davinci-resolve-mcp 2.38.0 → 2.39.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 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.39.0
+
+Governance enforce mode and actor identity — the staged Phase 3 of the
+Resolve 21 AI-ops work.
+
+- **Added** governance `mode` for the media-creating AI ops (motion deblur,
+  speech generation): `advisory` (default, unchanged — confirm-preview
+  warnings only) or `enforce`, where an over-tier run is blocked with
+  `GOVERNANCE_BLOCKED` before token issuance, naming the exceeded dimensions.
+  Escape hatches: raise the tier, relax the mode, or pass
+  `override_governance=true` to consciously exceed the tier once.
+  `set_ai_governance` accepts `mode` (preset now optional);
+  `get_ai_governance` reports it.
+- **Added** instance-level actor identity (per the recorded concurrency
+  design): each entry point declares itself — `stdio`, `network-sse`,
+  `network-http`, `control-panel`, `batch-cli` — and AI-ops ledger rows,
+  brain edits, and timeline versions now carry `actor` (`<instance>:<pid>`)
+  alongside `initiator`. Schema v8 (additive columns); migration verified
+  against a copy of a real project DB with all rows preserved.
+
 ## What's New in v2.38.0
 
 Busy gate for long DaVinci Resolve operations — the first piece of the

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.38.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.39.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-33%20(341%20full)-blue.svg)](#server-modes)

package/docs/SKILL.md

@@ -694,7 +694,13 @@ The two media-creating ops also have **soft governance tiers**
 deblur/speech runs, bytes, and render time. It is advisory — the confirm dialog
 warns when near/over the tier but never blocks (the ops are confirm-gated).
 Inspect/set with `media_analysis(action="get_ai_governance")` and
-`media_analysis(action="set_ai_governance", preset=…, overrides={...})`; the AI
+`media_analysis(action="set_ai_governance", preset=…, mode=…, overrides={...})`.
+Governance `mode` is `advisory` by default (preview warnings only); `enforce`
+blocks an over-tier run with `GOVERNANCE_BLOCKED` until the tier is raised, the
+mode is relaxed, or the op is re-called with `override_governance=true`. Ledger
+rows, brain edits, and timeline versions record the acting instance
+(`stdio` / `network-sse` / `network-http` / `control-panel` / `batch-cli` + pid)
+in an `actor` field; the AI
 Console's Governance section offers a tier picker + consumption gauges.
 
 The caps layer:

package/install.py

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

package/src/analysis_dashboard.py

@@ -14678,6 +14678,8 @@ def _warm_inventory_cache(project_root: str) -> None:
 
 
 def main() -> None:
+    from src.utils import actor_identity
+    actor_identity.set_instance("control-panel")
     args = parse_args()
     state = DashboardState(args.project_name, args.project_id, args.analysis_root)
     Handler.state = state

package/src/batch_cli.py

@@ -526,6 +526,8 @@ _HANDLERS = {
 
 
 def main(argv: Optional[List[str]] = None) -> int:
+    from src.utils import actor_identity
+    actor_identity.set_instance("batch-cli")
     parser = _build_parser()
     args = parser.parse_args(argv)
     if not hasattr(args, "json"):

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.38.0"
+VERSION = "2.39.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 341-tool granular server instead
 """
 
-VERSION = "2.38.0"
+VERSION = "2.39.0"
 
 import base64
 import os
@@ -84,7 +84,7 @@ from src.utils.media_analysis import (
     summarize_reports as summarize_media_analysis_reports,
 )
 from src.utils.sync_detection import detect_sync_events_for_records as detect_media_sync_events
-from src.utils import resolve_busy
+from src.utils import actor_identity, resolve_busy
 from src.utils.resolve_busy import long_resolve_op
 from src.utils.media_analysis_jobs import (
     MEDIA_EXTENSIONS,
@@ -716,6 +716,54 @@ def _ai_governance_check(op: str) -> Dict[str, Any]:
         return {"applies": False}
 
 
+_AI_GOVERNANCE_MODES = ("advisory", "enforce")
+
+
+def _ai_governance_mode() -> str:
+    try:
+        raw = str(_read_media_analysis_preferences().get("resolve_ai_governance_mode") or "").strip().lower()
+        return raw if raw in _AI_GOVERNANCE_MODES else "advisory"
+    except Exception:
+        return "advisory"
+
+
+def _ai_governance_gate(op: str, p: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """Hard gate for a governed AI render op when governance mode is 'enforce'.
+
+    Returns None to proceed (advisory mode, within tier, or explicit
+    override_governance=True), otherwise a destructive_blocked error naming
+    the exceeded dimensions. Checked before token issuance so the agent
+    learns about the block without burning a confirm round-trip.
+    """
+    if _ai_governance_mode() != "enforce":
+        return None
+    if p.get("override_governance") or p.get("overrideGovernance"):
+        return None
+    check = _ai_governance_check(op)
+    if not check.get("applies") or not check.get("exceeded"):
+        return None
+    return _err(
+        f"Governance tier '{check.get('tier')}' blocks this {op} run: "
+        + " ".join(check.get("warnings") or ["over threshold."]),
+        code="GOVERNANCE_BLOCKED",
+        category="destructive_blocked",
+        retryable=False,
+        remediation=(
+            "Raise the tier or thresholds via media_analysis(action='set_ai_governance'), "
+            "switch governance mode back to 'advisory', or re-call with override_governance=true "
+            "to consciously exceed the tier this once."
+        ),
+        state={
+            "op": op,
+            "mode": "enforce",
+            "tier": check.get("tier"),
+            "usage": check.get("usage"),
+            "projected": check.get("projected"),
+            "thresholds": check.get("thresholds"),
+        },
+    )
+
+
 def _destructive_preference_provider(key: str) -> Any:
     """Reader for C6 preferences out of the existing media-analysis prefs file."""
     try:
@@ -1032,11 +1080,14 @@ def _consume_confirm_token(*, action: str, params: Optional[Dict[str, Any]]) ->
     rec = _CONFIRM_TOKENS.pop(token, None)  # one-time use
     if rec is None:
         return _err(
-            "confirm_token is invalid or expired",
+            "confirm_token is invalid, expired, or was issued by a different "
+            "server instance (tokens are valid only on the instance that "
+            "issued them — e.g. a stdio-server token is not honored by the "
+            "networked server).",
             code="CONFIRM_TOKEN_INVALID",
             category="destructive_blocked",
             retryable=False,
-            remediation=f"Re-call {action} without confirm_token to receive a fresh token.",
+            remediation=f"Re-call {action} without confirm_token on this instance to receive a fresh token.",
         )
     if rec.get("action") != action:
         return _err(
@@ -12998,6 +13049,9 @@ def project_settings(action: str, params: Optional[Dict[str, Any]] = None) -> Di
             return _err("generate_speech requires speech_generation_settings with a 'TextInput' string. "
                         "Optional keys: VoiceModel, CustomVoiceFile, Speed, Variation, Pitch, GenerationID, Filename, AddToTimeline, AudioTrack.")
         timecode = _first_param(p, "timecode", default="") or ""
+        gate = _ai_governance_gate("generate_speech", p)
+        if gate:
+            return gate
         if "confirm_token" not in p and "confirmToken" not in p and _confirm_token_required():
             return _issue_confirm_token(
                 action="project_settings.generate_speech",
@@ -14090,6 +14144,9 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
         if missing:
             return missing
         deblur = _first_param(p, "deblur_option", "deblurOption", default=None) or {}
+        gate = _ai_governance_gate("remove_motion_blur", p)
+        if gate:
+            return gate
         if "confirm_token" not in p and "confirmToken" not in p and _confirm_token_required():
             return _issue_confirm_token(
                 action="folder.remove_motion_blur",
@@ -14425,6 +14482,9 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         if missing:
             return missing
         deblur = _first_param(p, "deblur_option", "deblurOption", default=None) or {}
+        gate = _ai_governance_gate("remove_motion_blur", p)
+        if gate:
+            return gate
         if "confirm_token" not in p and "confirmToken" not in p and _confirm_token_required():
             return _issue_confirm_token(
                 action="media_pool_item.remove_motion_blur",
@@ -14608,8 +14668,8 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
       set_caps_preset(preset, overrides?) -> {success, preset, overrides} — preset is minimal | standard | generous | unlimited. Overrides is a dict of {field: int|"unlimited"} that wins over the preset.
       get_usage(scope?, scope_key?, clip_id?, job_id?) -> {scope, usage} — raw usage rollup for one scope (clip | job | day).
       get_resolve_ai_usage(session_only?, op?, limit?) -> {summary, recent} — ledger of Resolve 21 local AI ops (audio classification, IntelliSearch, slate, motion-deblur, speech). Tracks invocations, wall-clock, and files/bytes created by the two media-creating ops. Separate from get_caps/get_usage (those meter Claude-side tokens; these ops don't spend them).
-      get_ai_governance() -> {tier, thresholds, usage, tiers_available} — soft governance tier (off|lenient|standard|strict) for the media-creating AI ops vs this session's render usage. Advisory; surfaced in the confirm preview + panel, never blocks.
-      set_ai_governance(preset, overrides?) -> {success, tier, overrides} — set the governance tier. Overrides keys: deblur_runs, speech_runs, render_bytes, render_wall_clock_ms (int or "unlimited").
+      get_ai_governance() -> {tier, mode, thresholds, usage, tiers_available} — governance tier (off|lenient|standard|strict) for the media-creating AI ops vs this session's render usage. mode is advisory (default; preview warnings only) or enforce (over-tier runs are blocked).
+      set_ai_governance(preset?, mode?, overrides?) -> {success, tier, mode, overrides} — set the tier, the mode (advisory|enforce), and/or overrides (deblur_runs, speech_runs, render_bytes, render_wall_clock_ms; int or "unlimited"). In enforce mode a blocked run returns GOVERNANCE_BLOCKED; pass override_governance=true on the op to consciously exceed the tier once.
       resolve_output_root(analysis_root?, source_paths?) -> {project_root}
       plan(target, depth?, analysis_root?, transcription?, vision?, dry_run?) -> {clips, artifacts}
       analyze_file(path|file_path, dry_run?, session_only?, persist?) -> {clips, manifest}
@@ -14792,19 +14852,32 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
                 project_root=project_root, session_id=_AI_LEDGER_SESSION_ID,
                 preset=_ai_governance_preset(), overrides=_ai_governance_overrides(),
             )
-            return {"success": True, "session_id": _AI_LEDGER_SESSION_ID, **st}
+            return {"success": True, "session_id": _AI_LEDGER_SESSION_ID, "mode": _ai_governance_mode(), **st}
         except Exception as exc:
             return _err(f"{type(exc).__name__}: {exc}")
     if action == "set_ai_governance":
         preset = (p.get("preset") or "").strip().lower()
-        if preset not in _resolve_ai_governance.VALID_TIERS:
+        mode = (p.get("mode") or "").strip().lower()
+        if not preset and not mode and not isinstance(p.get("overrides"), dict):
+            return _err("set_ai_governance requires at least one of: preset, mode, overrides")
+        if preset and preset not in _resolve_ai_governance.VALID_TIERS:
             return _err(f"unknown tier '{preset}'. Valid: {sorted(_resolve_ai_governance.VALID_TIERS)}")
+        if mode and mode not in _AI_GOVERNANCE_MODES:
+            return _err(f"unknown mode '{mode}'. Valid: {list(_AI_GOVERNANCE_MODES)}")
         prefs = _read_media_analysis_preferences()
-        prefs["resolve_ai_governance_preset"] = preset
+        if preset:
+            prefs["resolve_ai_governance_preset"] = preset
+        if mode:
+            prefs["resolve_ai_governance_mode"] = mode
         if isinstance(p.get("overrides"), dict):
             prefs["resolve_ai_governance_overrides"] = p["overrides"]
         _write_media_analysis_preferences(prefs)
-        return {"success": True, "tier": preset, "overrides": prefs.get("resolve_ai_governance_overrides") or {}}
+        return {
+            "success": True,
+            "tier": prefs.get("resolve_ai_governance_preset") or _resolve_ai_governance.DEFAULT_TIER,
+            "mode": prefs.get("resolve_ai_governance_mode") or "advisory",
+            "overrides": prefs.get("resolve_ai_governance_overrides") or {},
+        }
     if action == "set_caps_preset":
         preset = (p.get("preset") or "").strip().lower()
         from src.utils import analysis_caps as _ac
@@ -21363,6 +21436,7 @@ if __name__ == "__main__":
             del sys.argv[_i:_i + 2]
     if transport in ("sse", "streamable-http"):
         from src.utils.mcp_transport import run_networked
+        actor_identity.set_instance("network-sse" if transport == "sse" else "network-http")
         logger.info(f"Starting DaVinci Resolve MCP Server ({transport} transport)")
         run_networked(mcp, transport)
         sys.exit(0)

package/src/utils/actor_identity.py

@@ -0,0 +1,46 @@
+"""Instance-level actor identity for ledger and destructive-op records.
+
+Design decision (2026-06-09): the supported concurrency target is a single
+editor running multiple clients — a stdio server, a networked server, the
+control panel, and the batch CLI may all drive one Resolve. Records therefore
+identify the INSTANCE that performed an op, not a per-request client; finer
+per-client fingerprints can layer on in a multi-user future without changing
+this surface.
+
+Each entry point declares itself once at startup via set_instance():
+
+    stdio          — the default MCP server over stdio
+    network-sse    — the networked server (SSE transport)
+    network-http   — the networked server (streamable-http transport)
+    control-panel  — the analysis dashboard process
+    batch-cli      — the headless batch runner
+
+actor_string() is the compact form persisted in DB columns: "<instance>:<pid>".
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, Dict
+
+_instance = "stdio"
+
+KNOWN_INSTANCES = ("stdio", "network-sse", "network-http", "control-panel", "batch-cli")
+
+
+def set_instance(kind: str) -> None:
+    """Declare what kind of process this is. Unknown kinds are kept verbatim."""
+    global _instance
+    kind = str(kind or "").strip() or "stdio"
+    _instance = kind
+
+
+def get_instance() -> str:
+    return _instance
+
+
+def current_actor() -> Dict[str, Any]:
+    return {"instance": _instance, "pid": os.getpid()}
+
+
+def actor_string() -> str:
+    return f"{_instance}:{os.getpid()}"

package/src/utils/brain_edits.py

@@ -24,7 +24,7 @@ import os
 import time
 from typing import Any, Callable, Dict, List, Optional
 
-from src.utils import timeline_brain_db
+from src.utils import actor_identity, timeline_brain_db
 
 logger = logging.getLogger("resolve-mcp.brain-edits")
 
@@ -220,14 +220,15 @@ def log_brain_edit(
                 analysis_run_id, timeline_before, timeline_after, edit_type,
                 tool_name, action_name, target_metric, metric_direction,
                 before_value, after_value, rationale, params_json,
-                result_summary_json, created_at, initiator
-            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                result_summary_json, created_at, initiator, actor
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
             """,
             (
                 analysis_run_id, timeline_before, timeline_after, edit_type,
                 tool_name, action_name, target_metric, metric_direction,
                 before_value, after_value, rationale, params_json,
                 result_json, created_at, initiator,
+                actor_identity.actor_string(),
             ),
         )
         row_id = cursor.lastrowid

package/src/utils/resolve_ai_ledger.py

@@ -22,7 +22,7 @@ import logging
 import time
 from typing import Any, Dict, List, Optional
 
-from src.utils import timeline_brain_db
+from src.utils import actor_identity, timeline_brain_db
 
 logger = logging.getLogger("resolve-mcp.resolve-ai-ledger")
 
@@ -64,6 +64,7 @@ def record_op(
     output_path: Optional[str] = None,
     output_bytes: Optional[int] = None,
     error: Optional[str] = None,
+    actor: Optional[str] = None,
 ) -> Optional[int]:
     """Persist one ledger row. Returns the row id, or None on any failure.
 
@@ -81,8 +82,8 @@ def record_op(
                 INSERT INTO resolve_ai_op_usage(
                     op, op_class, clip_id, session_id, success, wall_clock_ms,
                     output_path, output_bytes, extra_required, error,
-                    occurred_at, day_bucket
-                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                    occurred_at, day_bucket, actor
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                 """,
                 (
                     op, meta["op_class"], clip_id, session_id, 1 if success else 0,
@@ -90,6 +91,7 @@ def record_op(
                     int(output_bytes) if output_bytes is not None else None,
                     meta["extra_required"], error,
                     _iso(now), _day_bucket(now),
+                    actor or actor_identity.actor_string(),
                 ),
             )
             return cursor.lastrowid
@@ -177,7 +179,7 @@ def get_usage(
         rows = conn.execute(
             f"""
             SELECT op, op_class, clip_id, session_id, success, wall_clock_ms,
-                   output_path, output_bytes, extra_required, error, occurred_at
+                   output_path, output_bytes, extra_required, error, occurred_at, actor
             FROM resolve_ai_op_usage{where}
             ORDER BY id DESC LIMIT ?
             """,

package/src/utils/timeline_brain_db.py

@@ -29,7 +29,7 @@ from typing import Callable, Dict, Iterator, Optional, Tuple
 
 logger = logging.getLogger("resolve-mcp.timeline-brain-db")
 
-SCHEMA_VERSION = 7
+SCHEMA_VERSION = 8
 DB_FILENAME = "timeline_brain.sqlite"
 SOUL_DIRNAME = "_soul"
 
@@ -464,6 +464,20 @@ def _migrate_v7_resolve_ai_op_usage(conn: sqlite3.Connection) -> None:
     )
 
 
+@register_migration(8)
+def _migrate_v8_actor_identity(conn: sqlite3.Connection) -> None:
+    """Instance-level actor provenance (design decision 2026-06-09).
+
+    Stamps which process kind performed an op — "<instance>:<pid>" where
+    instance is stdio / network-sse / network-http / control-panel /
+    batch-cli. Complements `initiator` (auto vs manual) on the versioning
+    tables: initiator says WHY a row exists, actor says WHO wrote it.
+    """
+    for table in ("resolve_ai_op_usage", "brain_edits", "timeline_versions"):
+        if not _column_exists(conn, table, "actor"):
+            conn.execute(f"ALTER TABLE {table} ADD COLUMN actor TEXT")
+
+
 @register_migration(5)
 def _migrate_v5_analysis_token_usage(conn: sqlite3.Connection) -> None:
     """Track real vendor token + frame upload usage so caps can enforce budgets.

package/src/utils/timeline_versioning.py

@@ -32,7 +32,7 @@ import time
 import uuid
 from typing import Any, Dict, List, Optional, Tuple
 
-from src.utils import timeline_brain_db
+from src.utils import actor_identity, timeline_brain_db
 
 logger = logging.getLogger("resolve-mcp.timeline-versioning")
 
@@ -159,8 +159,8 @@ def archive_current_timeline(
             """
             INSERT INTO timeline_versions(
                 timeline_name, version, created_at, analysis_run_id,
-                archived_timeline_name, archived_bin_path, reason, initiator
-            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                archived_timeline_name, archived_bin_path, reason, initiator, actor
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
             """,
             (
                 working_name,
@@ -171,6 +171,7 @@ def archive_current_timeline(
                 _archive_bin_path(media_pool),
                 reason,
                 initiator,
+                actor_identity.actor_string(),
             ),
         )
         row_id = cursor.lastrowid