davinci-resolve-mcp 2.214.3 → 2.215.0

package/CHANGELOG.md

@@ -2,6 +2,84 @@
 
 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.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
+
+- **The unit suite was appending to `logs/server.log`.** Importing
+  `src/server.py` attaches the root logger's FileHandler to that file, and the
+  suite imports the server, so every MagicMock "connection" the bridge tests
+  provoke and every lifecycle warning about a MagicMock timeline landed in the
+  operator's real log — the file a live debugging session reads. On the
+  maintainer's machine that log had grown to 128 MB with 240 such lines in it.
+  The log target is now `RESOLVE_MCP_LOG_FILE`: unset means `logs/server.log`
+  as before, a path means that file, empty means no file. `tests/__init__.py`
+  sets it to a temporary file before any test module imports the server, on
+  both the `unittest` and `pytest` paths, and `tests/test_log_isolation.py`
+  fails the suite if a handler on the root or `resolve-mcp` logger ever targets
+  the real log during a run. The live server's behaviour is unchanged, and the
+  transport-token redaction test, which builds its own root FileHandler, still
+  passes.
+- **The existing log is untouched.** The 128 MB file is the operator's; this
+  change only stops adding to it. Rotate or trim it by hand if wanted.
+
+### Validation
+
+- `tests/test_log_isolation.py` (four tests, including the unset-means-real-log
+  case that pins the live behaviour). Proven with an audited full run — a
+  `sys.addaudithook` on every `open` of the operator's log — that recorded zero
+  opens across 3371 tests. Full offline suite, drift guards and the advanced
+  Node suite green.
+
 ## What's New in v2.214.3 — the advanced launcher heals a wrong-Node registration
 
 ### Fixed

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.214.3-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.215.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-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
@@ -298,7 +302,9 @@ and an audit document is the last place to let a reader read it as an all-clear.
 
 Traces live in a 100-entry in-memory ring and are appended to
 `logs/execution-traces.jsonl` beside `server.log` — `RESOLVE_MCP_TRACE_FILE`
-moves it. `list_recent_executions` reports that path and whether it is
+moves it, and `RESOLVE_MCP_LOG_FILE` moves `server.log` itself (a path, or empty
+for no file; the offline test suite points it at a temporary file so it never
+writes into the operator's log). `list_recent_executions` reports that path and whether it is
 writable, so "the log is empty" and "nothing is being written" are
 distinguishable without reading the source. What is recorded is tool name,
 action, timing, status, semantic deltas and verification — no parameters and no

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.214.3-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.215.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-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.3 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.215.0 版 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.3"
+VERSION = "2.215.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.214.3",
+  "version": "2.215.0",
   "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.3"
+VERSION = "2.215.0"
 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.3"
+VERSION = "2.215.0"
 
 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,
@@ -185,10 +186,40 @@ if RESOLVE_MODULES_PATH not in sys.path:
 
 log_dir = os.path.join(project_dir, "logs")
 os.makedirs(log_dir, exist_ok=True)
+
+#: Where this process logs. Unset: `logs/server.log` under the repository, as
+#: always. A path: that file (its directory is created). Empty: no file at all.
+#:
+#: The variable exists because importing this module attaches the file handler,
+#: and the offline unit suite imports this module. Without it the suite's
+#: MagicMock "connections" and lifecycle warnings landed in the operator's real
+#: server.log — 240 such lines in a 128 MB log on the maintainer's machine —
+#: which is the file every live debugging session reads. `tests/__init__.py`
+#: points it at a temporary file before any test module runs.
+ENV_LOG_FILE = "RESOLVE_MCP_LOG_FILE"
+
+
+def _log_file_from_env(env=None) -> str:
+    """The log path this process should use, or "" for none."""
+    values = os.environ if env is None else env
+    value = values.get(ENV_LOG_FILE)
+    if value is None:
+        return os.path.join(log_dir, "server.log")
+    return os.path.expanduser(value.strip())
+
+
+def _log_handlers():
+    target = _log_file_from_env()
+    if not target:
+        return [logging.NullHandler()]
+    os.makedirs(os.path.dirname(target) or ".", exist_ok=True)
+    return [logging.FileHandler(target)]
+
+
 logging.basicConfig(
     level=logging.INFO,
     format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-    handlers=[logging.FileHandler(os.path.join(log_dir, "server.log"))]
+    handlers=_log_handlers(),
 )
 logger = logging.getLogger("resolve-mcp")
 
@@ -207,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."
     ),
 )
 
@@ -1055,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.
@@ -1259,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
@@ -15530,6 +15567,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(),
     }
 
@@ -15549,6 +15588,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():
@@ -15577,11 +15620,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}
@@ -16132,6 +16175,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:
@@ -16297,6 +16342,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(),
+                },
             },
         }
 
@@ -16411,6 +16466,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.