davinci-resolve-mcp 2.37.3 → 2.39.0

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 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
+concurrency design for the stdio + networked two-instance setup.
+
+- **Added** cross-process registration for long synchronous Resolve calls
+  (timeline export/import, scene-cut detection, subtitle generation,
+  Dolby Vision analysis, folder/clip audio transcription). A tool call that
+  arrives while one is running now waits up to 5 seconds and then returns a
+  structured `RESOLVE_BUSY` error (new `busy` category, retryable, with
+  `state.busy_with` and `state.age_seconds`) instead of hanging silently
+  inside the scripting bridge. Stale registrations from crashed operations
+  are ignored automatically; an operation never gates its own thread.
+- Design decisions recorded: single-editor/multi-client is the supported
+  concurrency target; confirm tokens stay per-instance; actor identity is
+  deferred to the governance phase.
+
 ## What's New in v2.37.3
 
 Deep-audit fixes, rounds two and three: agent-facing action discovery,

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.37.3-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.37.3"
+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.37.3",
+  "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.37.3"
+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.37.3"
+VERSION = "2.39.0"
 
 import base64
 import os
@@ -84,6 +84,8 @@ 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 actor_identity, resolve_busy
+from src.utils.resolve_busy import long_resolve_op
 from src.utils.media_analysis_jobs import (
     MEDIA_EXTENSIONS,
     batch_job_status as media_analysis_batch_job_status,
@@ -714,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:
@@ -830,6 +880,7 @@ ERROR_CATEGORIES = (
     "wrong_page",            # action requires a specific page (Color, Edit, Fairlight…)
     "invalid_input",         # caller-side fixable (bad param shape, unknown enum)
     "resolve_api_failed",    # Resolve returned None/False for unclear reasons
+    "busy",                  # another long Resolve op holds the bridge; retry later
     "destructive_blocked",   # strict-mode/confirm-token refusal
     "pending_user_decision", # confirm_token required
     "unsupported",           # feature/version/method not available
@@ -846,6 +897,7 @@ _CATEGORY_RETRYABLE_DEFAULT: Dict[str, bool] = {
     "wrong_page":            True,   # trivial caller fix; retry after page switch
     "invalid_input":         False,  # caller fix required
     "resolve_api_failed":    True,   # often transient; retry once
+    "busy":                  True,   # another long Resolve op holds the bridge
     "destructive_blocked":   False,  # user decision required
     "pending_user_decision": False,  # confirm_token required
     "unsupported":           False,  # API/version mismatch
@@ -1028,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(
@@ -1671,6 +1726,19 @@ def _annotation_boundary_report(tl, p: Dict[str, Any]):
     }
 
 def _check():
+    busy = resolve_busy.wait_until_free()
+    if busy:
+        return None, None, _err(
+            f"Resolve is busy with a long operation: {busy['label']} "
+            f"(running for {busy['age_seconds']}s). Retry after it completes.",
+            code="RESOLVE_BUSY", category="busy",
+            remediation="Wait for the named operation to finish, then retry this call.",
+            state={
+                "busy_with": busy["label"],
+                "age_seconds": busy["age_seconds"],
+                "same_process": busy["same_process"],
+            },
+        )
     resolve = get_resolve()
     if resolve is None:
         return None, None, _err(
@@ -4916,7 +4984,8 @@ def _export_timeline_checked(tl, p: Dict[str, Any]):
     spec = _timeline_export_spec(p, resolve)
     if p.get("dry_run"):
         return _ok(path=path, would_export=True, spec={k: v for k, v in spec.items() if k != "export_type"})
-    success = bool(tl.Export(path, spec["export_type"], spec["export_subtype"]))
+    with long_resolve_op("timeline.export_timeline_checked"):
+        success = bool(tl.Export(path, spec["export_type"], spec["export_subtype"]))
     files = []
     primary_file = path
     if success and os.path.isdir(path):
@@ -4969,7 +5038,8 @@ def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
         tl_existing = proj.GetTimelineByIndex(index)
         if tl_existing:
             before_ids.add(str(tl_existing.GetUniqueId()))
-    imported = mp.ImportTimelineFromFile(path, options)
+    with long_resolve_op("timeline.import_timeline_checked"):
+        imported = mp.ImportTimelineFromFile(path, options)
     if not imported:
         return _err("Failed to import timeline")
     imported_id = str(imported.GetUniqueId())
@@ -5937,7 +6007,8 @@ def _subtitle_generation_probe(tl, p: Dict[str, Any]):
         return _ok(would_generate=True, settings=settings, note="Pass allow_generate=True to call CreateSubtitlesFromAudio.")
     if not _has_method(tl, "CreateSubtitlesFromAudio"):
         return _err("CreateSubtitlesFromAudio unavailable")
-    return {"success": bool(tl.CreateSubtitlesFromAudio(settings)), "settings": settings}
+    with long_resolve_op("timeline.create_subtitles_from_audio"):
+        return {"success": bool(tl.CreateSubtitlesFromAudio(settings)), "settings": settings}
 
 
 def _fairlight_boundary_report(proj, mp, tl, p: Dict[str, Any]):
@@ -12978,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",
@@ -13811,7 +13885,8 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
     elif action == "setup_multicam_timeline":
         return _setup_multicam_timeline(proj, mp, p)
     elif action == "import_timeline":
-        tl = mp.ImportTimelineFromFile(p["path"], p.get("options", {}))
+        with long_resolve_op("media_pool.import_timeline"):
+            tl = mp.ImportTimelineFromFile(p["path"], p.get("options", {}))
         return _ok(name=tl.GetName()) if tl else _err("Failed to import timeline")
     elif action == "delete_timelines":
         count = proj.GetTimelineCount()
@@ -14021,8 +14096,10 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
     elif action == "transcribe_audio":
         usd = _first_param(p, "use_speaker_detection", "useSpeakerDetection")
         if usd is None:
-            return {"success": bool(f.TranscribeAudio())}
-        return {"success": bool(f.TranscribeAudio(bool(usd)))}
+            with long_resolve_op("folder.transcribe_audio"):
+                return {"success": bool(f.TranscribeAudio())}
+        with long_resolve_op("folder.transcribe_audio"):
+            return {"success": bool(f.TranscribeAudio(bool(usd)))}
     elif action == "clear_transcription":
         return {"success": bool(f.ClearTranscription())}
     elif action == "perform_audio_classification":
@@ -14067,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",
@@ -14338,8 +14418,10 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     elif action == "transcribe_audio":
         usd = _first_param(p, "use_speaker_detection", "useSpeakerDetection")
         if usd is None:
-            return {"success": bool(clip.TranscribeAudio())}
-        return {"success": bool(clip.TranscribeAudio(bool(usd)))}
+            with long_resolve_op("media_pool_item.transcribe_audio"):
+                return {"success": bool(clip.TranscribeAudio())}
+        with long_resolve_op("media_pool_item.transcribe_audio"):
+            return {"success": bool(clip.TranscribeAudio(bool(usd)))}
     elif action == "clear_transcription":
         return {"success": bool(clip.ClearTranscription())}
     elif action == "get_transcription":
@@ -14400,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",
@@ -14583,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}
@@ -14767,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
@@ -15808,7 +15906,8 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
     elif action == "import_into_timeline":
         return {"success": bool(tl.ImportIntoTimeline(p["path"], p.get("options", {})))}
     elif action == "export":
-        return {"success": bool(tl.Export(p["path"], p["type"], p.get("subtype", "")))}
+        with long_resolve_op("timeline.export"):
+            return {"success": bool(tl.Export(p["path"], p["type"], p.get("subtype", "")))}
     elif action == "get_setting":
         return {"settings": _ser(tl.GetSetting(p.get("name", "")))}
     elif action == "set_setting":
@@ -16249,9 +16348,11 @@ def timeline_ai(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
         return err
 
     if action == "create_subtitles":
-        return {"success": bool(tl.CreateSubtitlesFromAudio(p.get("settings", {})))}
+        with long_resolve_op("timeline_ai.create_subtitles"):
+            return {"success": bool(tl.CreateSubtitlesFromAudio(p.get("settings", {})))}
     elif action == "detect_scene_cuts":
-        return {"success": bool(tl.DetectSceneCuts())}
+        with long_resolve_op("timeline_ai.detect_scene_cuts"):
+            return {"success": bool(tl.DetectSceneCuts())}
     elif action == "analyze_dolby_vision":
         clip_ids = p.get("clip_ids", [])
         items = []
@@ -16262,7 +16363,8 @@ def timeline_ai(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                         if it.GetUniqueId() in clip_ids:
                             items.append(it)
         analysis_type = p.get("analysis_type")
-        return {"success": bool(tl.AnalyzeDolbyVision(items, analysis_type))}
+        with long_resolve_op("timeline_ai.analyze_dolby_vision"):
+            return {"success": bool(tl.AnalyzeDolbyVision(items, analysis_type))}
     elif action == "grab_still":
         still = tl.GrabStill()
         return _ok() if still else _err("Failed to grab still")
@@ -21334,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/resolve_busy.py

@@ -0,0 +1,171 @@
+"""Cross-process visibility for long synchronous DaVinci Resolve operations.
+
+The Resolve scripting bridge executes one call at a time. Most calls return in
+milliseconds, but a handful block for seconds-to-minutes (timeline export and
+import, scene-cut detection, subtitle generation, audio transcription). A
+second tool call issued during one of those — from another thread of this
+server, or from the other instance when stdio and networked servers share one
+Resolve — simply hangs inside fusionscript with no feedback.
+
+This module gives those long operations a name and a presence that every
+instance can see, so the Resolve preflight can wait briefly and then return a
+structured "busy" answer instead of hanging:
+
+    with long_resolve_op("timeline.export"):
+        tl.Export(...)
+
+    op = wait_until_free(timeout_seconds=5.0)   # None when free
+    if op:
+        ... return a RESOLVE_BUSY error naming op["label"] ...
+
+Registration is advisory and best-effort: a sidecar JSON file in the temp dir
+(same approach as page_lock) carries {label, pid, thread, started_at}. Records
+are ignored when their pid is dead or they exceed MAX_OP_AGE_SECONDS, so a
+crashed operation can never wedge the server. The registering thread is exempt
+from its own gate — long operations call Resolve helpers internally.
+"""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import threading
+import time
+from contextlib import contextmanager
+from typing import Any, Dict, Optional
+
+_SIDECAR = os.path.join(tempfile.gettempdir(), "davinci_resolve_mcp_busy.json")
+# A long op that has run this long is presumed crashed/leaked and ignored.
+MAX_OP_AGE_SECONDS = 2 * 60 * 60
+# Default time a preflight will wait for the bridge to free up before
+# returning a busy error.
+DEFAULT_WAIT_SECONDS = 5.0
+_POLL_SECONDS = 0.25
+
+_lock = threading.Lock()
+_local_owner: Optional[int] = None  # thread ident of the in-process registrant
+
+
+def _pid_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except OSError:
+        return False
+
+
+def _read_record() -> Optional[Dict[str, Any]]:
+    try:
+        with open(_SIDECAR, "r", encoding="utf-8") as handle:
+            record = json.load(handle)
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(record, dict) or not record.get("label"):
+        return None
+    started_at = record.get("started_at")
+    if not isinstance(started_at, (int, float)):
+        return None
+    if time.time() - started_at > MAX_OP_AGE_SECONDS:
+        return None
+    pid = record.get("pid")
+    if not isinstance(pid, int) or not _pid_alive(pid):
+        return None
+    return record
+
+
+def _write_record(record: Dict[str, Any]) -> None:
+    tmp_path = f"{_SIDECAR}.tmp-{os.getpid()}-{threading.get_ident()}"
+    try:
+        with open(tmp_path, "w", encoding="utf-8") as handle:
+            json.dump(record, handle)
+        os.replace(tmp_path, _SIDECAR)
+    except OSError:
+        pass
+    finally:
+        try:
+            os.remove(tmp_path)
+        except OSError:
+            pass
+
+
+def _clear_record() -> None:
+    record = None
+    try:
+        with open(_SIDECAR, "r", encoding="utf-8") as handle:
+            record = json.load(handle)
+    except (OSError, json.JSONDecodeError):
+        pass
+    # Only the owning process removes the sidecar; never clobber another
+    # instance's registration.
+    if isinstance(record, dict) and record.get("pid") == os.getpid():
+        try:
+            os.remove(_SIDECAR)
+        except OSError:
+            pass
+
+
+def current_long_op() -> Optional[Dict[str, Any]]:
+    """The active long operation visible across instances, or None."""
+    record = _read_record()
+    if record is None:
+        return None
+    return {
+        "label": record.get("label"),
+        "pid": record.get("pid"),
+        "same_process": record.get("pid") == os.getpid(),
+        "started_at": record.get("started_at"),
+        "age_seconds": round(max(0.0, time.time() - float(record.get("started_at", 0.0))), 1),
+    }
+
+
+@contextmanager
+def long_resolve_op(label: str):
+    """Register a long synchronous Resolve call for its duration."""
+    global _local_owner
+    ident = threading.get_ident()
+    with _lock:
+        nested = _local_owner is not None
+        if not nested:
+            _local_owner = ident
+    if not nested:
+        _write_record({
+            "label": str(label),
+            "pid": os.getpid(),
+            "thread": ident,
+            "started_at": time.time(),
+        })
+    try:
+        yield
+    finally:
+        if not nested:
+            with _lock:
+                _local_owner = None
+            _clear_record()
+
+
+def wait_until_free(timeout_seconds: Optional[float] = None) -> Optional[Dict[str, Any]]:
+    """Wait briefly for any long op to finish.
+
+    Returns None when the bridge is free (or becomes free within the timeout),
+    otherwise the still-running operation's info. The thread that registered
+    the current in-process op is never gated by it. timeout_seconds defaults
+    to DEFAULT_WAIT_SECONDS, read at call time so callers/tests can tune it.
+    """
+    if timeout_seconds is None:
+        timeout_seconds = DEFAULT_WAIT_SECONDS
+    deadline = time.monotonic() + max(0.0, float(timeout_seconds))
+    while True:
+        op = current_long_op()
+        if op is None:
+            return None
+        if op["same_process"]:
+            record = _read_record() or {}
+            if record.get("thread") == threading.get_ident():
+                return None
+        if time.monotonic() >= deadline:
+            return op
+        time.sleep(_POLL_SECONDS)

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