davinci-resolve-mcp 2.214.4 → 2.215.1

package/CHANGELOG.md

@@ -2,6 +2,81 @@
 
 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.215.1 — single-frame capture survives per-clip render mode and a vanished stills folder
+
+### Fixed
+
+- **`timeline_frame capture` forces Single-clip render mode and restores it.**
+  Measured 2026-09-09 on a project whose delivery preset was "Individual
+  clips": every single-frame capture reported success, wrote no file, and took
+  30+ seconds, because in that mode Resolve ignores `CustomName`, renders the
+  whole clip under its own naming, and the frame this helper waits for never
+  appears. The helper now reads `GetCurrentRenderMode()`, switches to single
+  clip (1) for the render, puts the mode back afterwards, and refuses with
+  `RENDER_MODE_REFUSED` before adding a job if the switch fails.
+- **The shared stills folder is recreated before every directory listing.**
+  Every sandbox path redirects to one `~/Documents/resolve-stills`, and the
+  helper's own cleanup removes it once it empties, so a concurrent capture (or
+  anything else) can take it away between the makedirs at the top and the
+  `os.listdir` that follows. Frame 81 of a 214-frame QC batch died on exactly
+  that. Recreate, do not assume.
+
+### Measured (not code)
+
+- A per-clip `.drx` carries the clip node graph losslessly (applying a clip's
+  own emitted grade back onto it re-renders bit-identically, PSNR 99 on 5/5),
+  but NOT colour-group pre/post grades, NOT Colour-page input sizing, and with
+  `grade_mode` 0 NOT keyframes. A traced conform whose source used groups needs
+  the group grades carried separately.
+## What's New in v2.215.0 — mutating operations write a structured operation log; the free-edition bridge is version-qualified for Resolve 21.1
+
+### Added
+
+- **Recognised mutating operations now write compact JSONL records** to
+  `logs/operation-log.jsonl`: operation id, tool, action, `tool.action`, risk
+  level and whether the classifier established it, blast radius, dry-run
+  flag, timestamp, final status, duration, and a short summary. When a result
+  already reports semantic changes through the `_operation` envelope those
+  changes are copied, never guessed. A mutating handler that raises before
+  returning still writes a `failed` record with the exception type and
+  message; a destructive attempt refused before mutation is logged as
+  `blocked`; read-only operations are skipped. Contributed in #202 by
+  @Rohitkanithi.
+- **Setup defaults for it:** `destructive.operation_log` (default on) and
+  `destructive.operation_log_path`; `RESOLVE_MCP_OPERATION_LOG_FILE` overrides
+  the path for deployments routing logs outside the repository. The offline
+  suite redirects the default path to a temporary file, the same way it
+  already redirects the security audit log.
+- **Why a third log.** Execution traces explain how a multi-step run
+  unfolded; the security audit records destructive gate decisions. This is
+  the plain chronological trail of what tried to change the project and how
+  it ended, with no parameters or file paths recorded.
+
+### Changed
+
+- **The free-edition bridge's claim is now version-qualified.** The README,
+  SKILL and the bridge module said the Workspace ▸ Scripts menu "is not gated
+  … on any edition". That was measured on free 21.0.3.7 only. Resolve 21.1
+  (2026-09-08) moved Python scripting to Studio, and the first field report
+  (#203, Fedora 44, free 21.1) shows the Scripts menu no longer listing any
+  `.py` file while a Lua script in the same folder lists normally. The docs
+  now say so, and the connection-failure remediation that sent free-edition
+  users to start the bridge now names the 21.1 change instead of promising a
+  path that may not exist. Whether the Console still runs Python on free 21.1
+  is unconfirmed and is the open question on #203.
+
+### Notes on the adaptation
+
+- The PR's bundled version bump and CHANGELOG entry were dropped, as with
+  the contributor's earlier PRs; everything else landed as authored, and the
+  offline-guard redirect it adds is what keeps the suite from writing a real
+  operation log.
+
+### Validation
+
+- The PR's seven tests plus the full offline suite, drift guards and the
+  advanced Node suite. No Resolve behavior changed; no live run required.
+
 ## What's New in v2.214.4 — the offline test suite no longer writes into the operator's server.log
 
 ### Fixed

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.214.4-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.215.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-36%20(353%20full)-blue.svg)](#server-modes)
@@ -42,10 +42,14 @@ The installer and server check the latest GitHub release for MCP updates. Checks
 
 Blackmagic gates *external* scripting to Studio: on the free edition
 `scriptapp("Resolve")` refuses a foreign process, whatever the preference says.
-The **Workspace ▸ Scripts** menu is not gated — a script launched from it is
-handed the live `resolve` object on any edition — so the server can reach the
-free edition through a small script that runs *inside* Resolve and re-exports it
-over an authenticated loopback listener.
+Through Resolve 21.0.x the **Workspace ▸ Scripts** menu was not gated — a script
+launched from it is handed the live `resolve` object (measured on free 21.0.3.7) —
+so the server can reach the free edition through a small script that runs *inside*
+Resolve and re-exports it over an authenticated loopback listener. **Resolve 21.1
+moved Python scripting to Studio.** On free 21.1 the Scripts menu no longer lists
+`.py` files at all (reported on Fedora 44 in #203; a Lua script in the same folder
+lists normally). Whether the Console still runs Python there is unconfirmed, so
+treat the bridge as a 21.0.x path until that is measured.
 
 ```bash
 python scripts/install_resolve_bridge.py

package/README.zh-CN.md

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

package/docs/SKILL.md

@@ -22,8 +22,10 @@ take up to 60 seconds.
 **Free edition.** Both of those preferences are Studio features; on the free
 edition `scriptapp("Resolve")` refuses a foreign process regardless. A third
 transport reaches it — a script run from **Workspace ▸ Scripts** is handed the
-live `resolve` object on any edition and re-exports it over an authenticated
-loopback listener. Install with `python scripts/install_resolve_bridge.py` and
+live `resolve` object (measured on free 21.0.3.7) and re-exports it over an
+authenticated loopback listener. Resolve 21.1 moved Python scripting to Studio:
+on free 21.1 the Scripts menu no longer lists `.py` files (#203), so on that
+build expect the bridge to have no launch path until the Console is checked. Install with `python scripts/install_resolve_bridge.py` and
 start it from that menu; once running it is used automatically when external
 scripting is unavailable, with no environment variable needed.
 `DAVINCI_RESOLVE_BRIDGE=1` *forces* it — the bridge becomes the only transport

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.214.4"
+VERSION = "2.215.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.214.4",
+  "version": "2.215.1",
   "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.4"
+VERSION = "2.215.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 353-tool granular server instead
 """
 
-VERSION = "2.214.4"
+VERSION = "2.215.1"
 
 import base64
 import os
@@ -61,6 +61,7 @@ from src.utils.page_lock import (
 from src.utils.proc import safe_run
 from src.utils.readback import verify_by_readback, verification_stats as _verification_stats
 from src.utils import operation_result as _operation_result
+from src.utils import operation_log as _operation_log
 from src.utils.operation_result import (
     build_operation_envelope as _build_operation_envelope,
     get_envelope_mode as _get_envelope_mode,
@@ -237,7 +238,9 @@ mcp = FastMCP(
         "reachable via the in-app bridge (Workspace > Scripts > resolve_bridge — it is "
         "used automatically when external scripting is unavailable; "
         "DAVINCI_RESOLVE_BRIDGE=1 only forces it), so a connection error does NOT mean "
-        "the free edition is unsupported."
+        "the free edition is unsupported — on Resolve 21.0.x. Resolve 21.1 moved Python "
+        "scripting to Studio and free 21.1 no longer lists Python scripts in that menu "
+        "(issue #203), so on 21.1+ a free-edition connection error may be final."
     ),
 )
 
@@ -1085,7 +1088,10 @@ def _not_connected_error():
                         "On the free edition: install the in-app bridge and run "
                         "Workspace > Scripts > resolve_bridge — once it is running it is used "
                         "automatically, no environment variable needed "
-                        "(DAVINCI_RESOLVE_BRIDGE=1 only forces it and disables this fallback).",
+                        "(DAVINCI_RESOLVE_BRIDGE=1 only forces it and disables this fallback). "
+                        "On free 21.1+ Blackmagic moved Python scripting to Studio and the "
+                        "Scripts menu no longer lists Python scripts (issue #203), so the bridge "
+                        "may have no launch path there.",
             # Which Resolve is refusing matters to the reader: a headless render
             # worker and the editor the user is looking at warrant different
             # responses, and the in-app bridge is not an option for the former.
@@ -1289,6 +1295,7 @@ def _destructive_preference_provider(key: str) -> Any:
 
 
 _destructive_hook.register_preference_provider(_destructive_preference_provider)
+_operation_log.register_preference_provider(_destructive_preference_provider)
 
 
 # Gated (tool, action) pairs routed through the destructive_hook wrapper that
@@ -14956,6 +14963,18 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
         original_fc = proj.GetCurrentRenderFormatAndCodec()
     except Exception:
         pass
+    # Render MODE is project state too, and it decides whether the capture can
+    # work at all. In "Individual clips" mode (0) Resolve ignores CustomName,
+    # renders the WHOLE clip under the frame's own file naming, and the
+    # single-frame file this helper waits for never appears — measured
+    # 2026-09-09 on a project whose delivery preset was per-clip: every capture
+    # reported success, wrote no file, and took 30+ s rendering the clip.
+    # Force single clip (1) for the capture and put the mode back afterwards.
+    original_mode = None
+    try:
+        original_mode = proj.GetCurrentRenderMode()
+    except Exception:
+        original_mode = None
     # Rendering pulls Resolve onto the Deliver page and moves the playhead;
     # measured leaving the user on Deliver at a different frame. Both are ours
     # to put back.
@@ -15007,6 +15026,16 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
 
     job = None
     try:
+        if original_mode is not None and original_mode != 1:
+            if not proj.SetCurrentRenderMode(1):
+                return _err(
+                    "Resolve refused to switch the render mode to single clip; in "
+                    "individual-clips mode a single-frame capture renders the whole clip "
+                    "under Resolve's own naming and the captured file never appears",
+                    code="RENDER_MODE_REFUSED", category="api_error",
+                    remediation="render(action='set_mode', params={'mode': 1}) then retry.",
+                    state={"render_mode": original_mode},
+                )
         codecs = proj.GetRenderCodecs("JPEG" if fmt == "jpg" else fmt.upper()) or {}
         codec = list(codecs.values())[0] if codecs else fmt
         if not proj.SetCurrentRenderFormatAndCodec(fmt, codec):
@@ -15033,6 +15062,13 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
         job = proj.AddRenderJob()
         if not job:
             return _err("AddRenderJob returned nothing", code="RENDER_JOB_FAILED", category="api_error")
+        # The folder is shared (every sandbox path redirects to one
+        # ~/Documents/resolve-stills) and the cleanup below removes it when it
+        # empties, so another capture — or anything else — can take it away
+        # between the makedirs above and here. Measured 2026-09-09: frame 81 of a
+        # 214-frame QC batch died in os.listdir on the missing folder. Recreate,
+        # don't assume.
+        os.makedirs(folder, exist_ok=True)
         before = set(os.listdir(folder))
         # Positional on purpose: the free-edition bridge proxies method calls
         # positionally, and a keyword argument dies inside _BoundMethod with
@@ -15080,6 +15116,19 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
                 proj.DeleteRenderJob(job)
             except Exception:
                 pass
+        if original_mode is not None and original_mode != 1:
+            # Same teardown contract as the format/codec restore below.
+            try:
+                restored_mode = bool(proj.SetCurrentRenderMode(original_mode))
+            except Exception as exc:
+                restored_mode, mode_exc = False, exc
+            else:
+                mode_exc = None
+            if not restored_mode:
+                logger.warning(
+                    "frame capture could not restore render mode %r: %s",
+                    original_mode, mode_exc or "SetCurrentRenderMode returned False",
+                )
         if original_fc:
             # A failed restore leaves the Deliver page on the capture's format
             # and codec, which the user's next render would silently inherit.
@@ -15560,6 +15609,8 @@ def _setup_destructive_defaults() -> Dict[str, Any]:
         "safe_mode": _setup_bool(destructive.get("safe_mode"), False),
         "audit_log": _setup_bool(destructive.get("audit_log"), True),
         "audit_log_path": destructive.get("audit_log_path") or os.path.join(project_dir, "logs", "security-audit.jsonl"),
+        "operation_log": _setup_bool(destructive.get("operation_log"), True),
+        "operation_log_path": destructive.get("operation_log_path") or os.path.join(project_dir, "logs", "operation-log.jsonl"),
         "preferences_path": _media_analysis_preferences_path(),
     }
 
@@ -15579,6 +15630,10 @@ def _setup_set_destructive_defaults(destructive_defaults: Dict[str, Any], dry_ru
         "auditlog": "audit_log",
         "audit_log_path": "audit_log_path",
         "auditlogpath": "audit_log_path",
+        "operation_log": "operation_log",
+        "operationlog": "operation_log",
+        "operation_log_path": "operation_log_path",
+        "operationlogpath": "operation_log_path",
     }
     requested: Dict[str, Any] = {}
     for key, value in destructive_defaults.items():
@@ -15607,11 +15662,11 @@ def _setup_set_destructive_defaults(destructive_defaults: Dict[str, Any], dry_ru
         if clear_requested(raw_value):
             destructive.pop(key, None)
             updates[key] = {"before": before.get(key), "after": _setup_destructive_defaults().get(key), "cleared": True}
-        elif key in {"require_confirm_token", "safe_mode", "audit_log"}:
+        elif key in {"require_confirm_token", "safe_mode", "audit_log", "operation_log"}:
             normalized = _setup_bool(raw_value, before.get(key, False))
             destructive[key] = normalized
             updates[key] = {"before": before.get(key), "after": normalized}
-        elif key == "audit_log_path":
+        elif key in {"audit_log_path", "operation_log_path"}:
             path = os.path.realpath(os.path.abspath(os.path.expanduser(str(raw_value))))
             destructive[key] = path
             updates[key] = {"before": before.get(key), "after": path}
@@ -16162,6 +16217,8 @@ def _setup_clear_defaults(keys: Any, dry_run: bool) -> Dict[str, Any]:
         "safe_mode": "destructive.safe_mode",
         "audit_log": "destructive.audit_log",
         "audit_log_path": "destructive.audit_log_path",
+        "operation_log": "destructive.operation_log",
+        "operation_log_path": "destructive.operation_log_path",
     }
     destructive_payload: Dict[str, Any] = {}
     if clear_all or "destructive" in normalized_keys:
@@ -16327,6 +16384,16 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
                     "values": "absolute or expandable path",
                     "storage": _media_analysis_preferences_path(),
                 },
+                "destructive.operation_log": {
+                    "description": "Write compact JSONL records for every recognised mutating operation.",
+                    "values": [True, False],
+                    "storage": _media_analysis_preferences_path(),
+                },
+                "destructive.operation_log_path": {
+                    "description": "Absolute path for the mutating-operation JSONL log.",
+                    "values": "absolute or expandable path",
+                    "storage": _media_analysis_preferences_path(),
+                },
             },
         }
 
@@ -16441,6 +16508,22 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
                     default=None,
                 )
             } if any(key in merged for key in ("audit_log_path", "auditLogPath")) else {}),
+            **({
+                "operation_log": _first_param(
+                    merged,
+                    "operation_log",
+                    "operationLog",
+                    default=None,
+                )
+            } if any(key in merged for key in ("operation_log", "operationLog")) else {}),
+            **({
+                "operation_log_path": _first_param(
+                    merged,
+                    "operation_log_path",
+                    "operationLogPath",
+                    default=None,
+                )
+            } if any(key in merged for key in ("operation_log_path", "operationLogPath")) else {}),
         }
 
         general_result = _setup_set_general_defaults(general_defaults, dry_run)

package/src/utils/execution_lifecycle.py

@@ -24,6 +24,8 @@ import threading
 from dataclasses import dataclass, field
 from typing import Any, Callable, Dict, List, Optional, Set, Tuple
 
+from src.utils import operation_log
+
 logger = logging.getLogger("resolve-mcp.execution-lifecycle")
 
 
@@ -542,6 +544,45 @@ class ProvenanceTraceHook(LifecycleHook):
         }
 
 
+class OperationLogHook(LifecycleHook):
+    """Writes a compact append-only record for each mutating operation."""
+    name = "operation_log"
+
+    def after_tool_call(
+        self, ctx: ToolCallContext, result: Any, duration_ms: int
+    ) -> Optional[Dict[str, Any]]:
+        if not ctx.risk.destructive:
+            return None
+        record = operation_log.build_record(
+            tool_name=ctx.tool_name,
+            action=ctx.action,
+            params=ctx.params,
+            result=result,
+            risk=ctx.risk.to_dict(),
+        )
+        operation_log.write_record(record)
+        return {
+            "logged": operation_log.operation_log_enabled(),
+            "operation_id": record["operation_id"],
+            "path": operation_log.operation_log_path(),
+        }
+
+    def on_error(
+        self, ctx: ToolCallContext, exc: Exception, duration_ms: int
+    ) -> None:
+        if not ctx.risk.destructive:
+            return
+        record = operation_log.build_exception_record(
+            tool_name=ctx.tool_name,
+            action=ctx.action,
+            params=ctx.params,
+            exc=exc,
+            risk=ctx.risk.to_dict(),
+            duration_ms=duration_ms,
+        )
+        operation_log.write_record(record)
+
+
 # ─── Pipeline Coordinator ───────────────────────────────────────────────────
 
 
@@ -577,6 +618,7 @@ class LifecyclePipeline:
         self._hooks.append(ReadbackVerificationHook())
         self._hooks.append(DriftDetectionHook())
         self._hooks.append(ProvenanceTraceHook())
+        self._hooks.append(OperationLogHook())
 
     def register_hook(self, hook: LifecycleHook) -> None:
         with self._lock:
@@ -711,4 +753,3 @@ def classify_operation_risk(
     tool_name: str, action: str, params: Optional[Dict[str, Any]] = None
 ) -> RiskAssessment:
     return RiskClassificationHook.classify(tool_name, action, params or {})
-

package/src/utils/operation_log.py

@@ -0,0 +1,206 @@
+"""Structured operation log for mutating tool calls.
+
+This log is deliberately narrower than execution traces and separate from the
+security audit log. It records the user-visible mutation attempt: which tool
+action ran, its risk, whether it was a dry run, a compact summary, and the
+final status.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional
+
+from src.utils import operation_result
+
+logger = logging.getLogger("resolve-mcp.operation-log")
+
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+_PreferenceProvider = Callable[[str], Any]
+_PREFERENCE_PROVIDER: Optional[_PreferenceProvider] = None
+
+
+def register_preference_provider(fn: _PreferenceProvider) -> None:
+    global _PREFERENCE_PROVIDER
+    _PREFERENCE_PROVIDER = fn
+
+
+def _read_preference(key: str, default: Any = None) -> Any:
+    if _PREFERENCE_PROVIDER is None:
+        return default
+    try:
+        value = _PREFERENCE_PROVIDER(key)
+    except Exception:
+        return default
+    return default if value is None else value
+
+
+def _coerce_bool(value: Any, default: bool = False) -> bool:
+    if value is None:
+        return default
+    if isinstance(value, str):
+        lowered = value.strip().lower()
+        if lowered in {"1", "true", "yes", "on"}:
+            return True
+        if lowered in {"0", "false", "no", "off"}:
+            return False
+        return default
+    return bool(value)
+
+
+def operation_log_enabled() -> bool:
+    return _coerce_bool(_read_preference("destructive.operation_log", True), True)
+
+
+def operation_log_path() -> str:
+    configured = (
+        os.environ.get("RESOLVE_MCP_OPERATION_LOG_FILE")
+        or _read_preference("destructive.operation_log_path", None)
+    )
+    if configured:
+        return os.path.realpath(os.path.abspath(os.path.expanduser(str(configured))))
+    return str(_REPO_ROOT / "logs" / "operation-log.jsonl")
+
+
+def _now_iso() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def _dry_run_requested(params: Optional[Dict[str, Any]], result: Any) -> bool:
+    if isinstance(params, dict):
+        if "dry_run" in params:
+            return bool(params["dry_run"])
+        if "dryRun" in params:
+            return bool(params["dryRun"])
+    return bool(isinstance(result, dict) and result.get("dry_run") is True)
+
+
+def _envelope(result: Any) -> Dict[str, Any]:
+    if not isinstance(result, dict):
+        return {}
+    nested = result.get(operation_result.ENVELOPE_KEY)
+    if isinstance(nested, dict):
+        return nested
+    if {"operation", "execution_id", "status"}.intersection(result):
+        return result
+    return {}
+
+
+def _operation_id(result: Any, envelope: Dict[str, Any]) -> str:
+    if isinstance(result, dict) and result.get("operation_id"):
+        return str(result["operation_id"])
+    execution_id = envelope.get("execution_id")
+    if execution_id:
+        return str(execution_id)
+    return f"op_{uuid.uuid4().hex[:12]}"
+
+
+def _status(result: Any, envelope: Dict[str, Any]) -> str:
+    raw_status = result.get("status") if isinstance(result, dict) else None
+    error = result.get("error") if isinstance(result, dict) else None
+    category = error.get("category") if isinstance(error, dict) else None
+    if raw_status in {
+        "blocked_by_security_policy",
+        "dry_run_unavailable",
+        "confirmation_required",
+    }:
+        return "blocked"
+    if category in {
+        "destructive_blocked",
+        "dry_run_unavailable",
+        "pending_user_decision",
+    }:
+        return "blocked"
+    return str(envelope.get("status") or operation_result.normalize_status(result))
+
+
+def _summary(tool_name: str, action: str, status: str, envelope: Dict[str, Any]) -> str:
+    operation = f"{tool_name}.{action}"
+    changes = envelope.get("changes")
+    if isinstance(changes, dict) and changes:
+        parts = [f"{key}={value}" for key, value in sorted(changes.items())[:4]]
+        return f"{operation} {status}; " + ", ".join(parts)
+    if status == "blocked":
+        return f"{operation} blocked before mutation"
+    return f"{operation} {status}"
+
+
+def build_record(
+    *,
+    tool_name: str,
+    action: str,
+    params: Optional[Dict[str, Any]],
+    result: Any,
+    risk: Dict[str, Any],
+) -> Dict[str, Any]:
+    env = _envelope(result)
+    status = _status(result, env)
+    record = {
+        "operation_id": _operation_id(result, env),
+        "tool": tool_name,
+        "action": action,
+        "operation": f"{tool_name}.{action}",
+        "risk_level": risk.get("level", "unknown"),
+        "risk_established": risk.get("recognised"),
+        "dry_run": _dry_run_requested(params, result),
+        "timestamp": _now_iso(),
+        "summary": _summary(tool_name, action, status, env),
+        "status": status,
+    }
+    if env.get("execution_id") and env.get("execution_id") != record["operation_id"]:
+        record["execution_id"] = env["execution_id"]
+    if risk.get("blast_radius"):
+        record["blast_radius"] = risk["blast_radius"]
+    if env.get("duration_ms") is not None:
+        record["duration_ms"] = env["duration_ms"]
+    if env.get("changes") is not None:
+        record["changes"] = env["changes"]
+    return record
+
+
+def build_exception_record(
+    *,
+    tool_name: str,
+    action: str,
+    params: Optional[Dict[str, Any]],
+    exc: Exception,
+    risk: Dict[str, Any],
+    duration_ms: int,
+) -> Dict[str, Any]:
+    exception_type = exc.__class__.__name__
+    operation = f"{tool_name}.{action}"
+    return {
+        "operation_id": f"op_{uuid.uuid4().hex[:12]}",
+        "tool": tool_name,
+        "action": action,
+        "operation": operation,
+        "risk_level": risk.get("level", "unknown"),
+        "risk_established": risk.get("recognised"),
+        "dry_run": _dry_run_requested(params, None),
+        "timestamp": _now_iso(),
+        "summary": f"{operation} failed with {exception_type}",
+        "status": "failed",
+        "blast_radius": risk.get("blast_radius"),
+        "duration_ms": max(0, int(duration_ms)),
+        "exception": {
+            "type": exception_type,
+            "message": str(exc),
+        },
+    }
+
+
+def write_record(record: Dict[str, Any]) -> None:
+    if not operation_log_enabled():
+        return
+    path = operation_log_path()
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "a", encoding="utf-8") as handle:
+            handle.write(json.dumps(record, sort_keys=True, default=str) + "\n")
+    except Exception as exc:
+        logger.warning("operation log write failed: %s", exc)

package/src/utils/resolve_bridge.py

@@ -1,11 +1,14 @@
 """Authenticated loopback bridge that runs *inside* DaVinci Resolve.
 
 External scripting is a Studio feature: `fusionscript` refuses a connection from
-a foreign process on the free edition. The in-app path is not gated — Blackmagic's
-own README documents the Workspace ▸ Scripts menu with no edition qualifier, and a
-script launched from it is handed the same `resolve` object Studio exposes. This
-module is that script: it re-exports a *named, allowlisted* operation surface over
-127.0.0.1 so the MCP server can drive Resolve on any edition.
+a foreign process on the free edition. Through 21.0.x the in-app path was not gated —
+Blackmagic's README documented the Workspace ▸ Scripts menu with no edition
+qualifier, and a script launched from it is handed the same `resolve` object Studio
+exposes (measured on free 21.0.3.7). This module is that script: it re-exports a
+*named, allowlisted* operation surface over 127.0.0.1 so the MCP server can drive
+Resolve on any edition that still runs Python scripts in-app. Resolve 21.1 moved
+Python scripting to Studio; on free 21.1 the Scripts menu no longer lists `.py`
+files (#203, Fedora 44), and whether the Console still runs Python is unconfirmed.
 
 This is the documented in-app path, not a circumvention of the licence check —
 but Blackmagic could close it, so treat this tier as supported-until-it-isn't.