davinci-resolve-mcp 2.69.3 → 2.70.0

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.69.3"
+VERSION = "2.70.0"
 
 import base64
 import os
@@ -105,6 +105,7 @@ from src.utils.media_analysis_jobs import (
 )
 from src.utils.platform import get_resolve_paths, get_resolve_plugin_paths
 from src.utils.resolve_connection import connect_resolve
+from src.utils import resolve_runtime as _resolve_runtime
 from src.utils.lut_paths import master_lut_dir, ensure_lut_in_master
 from src.utils import fuse_templates, dctl_templates, script_templates
 from src.utils.timeline_title_text import (
@@ -855,18 +856,16 @@ def _try_connect():
             resolve = None
             return None
 
-#: macOS puts the two editions in different places, and only the first was ever
-#: checked — so an auto-launch on a machine with both would start Studio even
-#: when the free edition was the one in use. Ordered installer-first to keep the
-#: previous behaviour where Studio is present.
-_MACOS_RESOLVE_APPS = (
-    "/Applications/DaVinci Resolve/DaVinci Resolve.app",  # installer / Studio
-    "/Applications/DaVinci Resolve.app",                  # App Store, free
-)
-
+def _launch_resolve(headless: Optional[bool] = None):
+    """Launch DaVinci Resolve and wait for it to become available.
 
-def _launch_resolve():
-    """Launch DaVinci Resolve and wait for it to become available."""
+    `headless=None` defers to the DAVINCI_RESOLVE_HEADLESS environment variable.
+    A headless launch is capability-identical to a GUI one (see
+    docs/reference/headless-cli.md) and immune to the modal dialogs that
+    otherwise wedge an agent-driven session, so it is the better default for
+    unattended work — but it stays opt-in, because starting an invisible
+    application on a workstation is not something to do behind the user's back.
+    """
     if _bridge_requested():
         # Launching cannot produce a bridge. The listener only exists once
         # someone runs Workspace > Scripts > resolve_bridge inside an already
@@ -878,28 +877,17 @@ def _launch_resolve():
             "launching the application cannot start it."
         )
         return False
-    sys_name = platform.system().lower()
-    if sys_name == "darwin":
-        app_path = next((p for p in _MACOS_RESOLVE_APPS if os.path.exists(p)), None)
-        if app_path is None:
-            logger.error("DaVinci Resolve not found in %s", list(_MACOS_RESOLVE_APPS))
-            return False
-        subprocess.Popen(["open", app_path], stdin=subprocess.DEVNULL)
-    elif sys_name == "windows":
-        app_path = r"C:\Program Files\Blackmagic Design\DaVinci Resolve\Resolve.exe"
-        if not os.path.exists(app_path):
-            logger.error(f"DaVinci Resolve not found at {app_path}")
-            return False
-        subprocess.Popen([app_path], stdin=subprocess.DEVNULL)
-    elif sys_name == "linux":
-        app_path = "/opt/resolve/bin/resolve"
-        if not os.path.exists(app_path):
-            logger.error(f"DaVinci Resolve not found at {app_path}")
-            return False
-        subprocess.Popen([app_path], stdin=subprocess.DEVNULL)
-    else:
+    if headless is None:
+        headless = _resolve_runtime.prefers_headless()
+    command = _resolve_runtime.launch_command(bool(headless))
+    if command is None:
+        logger.error("DaVinci Resolve not found on this platform's known install paths")
         return False
-    logger.info("Launched DaVinci Resolve, waiting for it to respond...")
+    subprocess.Popen(command, stdin=subprocess.DEVNULL)
+    logger.info(
+        "Launched DaVinci Resolve (%s), waiting for it to respond...",
+        "headless" if headless else "with UI",
+    )
     for i in range(30):
         time.sleep(2)
         if _try_connect():
@@ -908,16 +896,6 @@ def _launch_resolve():
     logger.warning("Resolve did not respond within 60s after launch")
     return False
 
-#: Process names that mean a DaVinci Resolve application is already running.
-#: Deliberately not the full path: the App Store build lives at
-#: `/Applications/DaVinci Resolve.app` and the installer build inside
-#: `/Applications/DaVinci Resolve/`, and either one counts.
-_RESOLVE_PROCESS_PATTERNS = (
-    "DaVinci Resolve.app/Contents/MacOS/Resolve",   # macOS, both editions
-    "Resolve.exe",                                  # Windows
-    "/opt/resolve/bin/resolve",                     # Linux
-)
-
 
 def resolve_is_running() -> Optional[bool]:
     """Is a Resolve application already up? None when it cannot be determined.
@@ -926,17 +904,7 @@ def resolve_is_running() -> Optional[bool]:
     unanswerable question never silently becomes "nothing is running" — which is
     the answer that leads to launching something.
     """
-    try:
-        if platform.system().lower() == "windows":
-            out = subprocess.run(["tasklist"], capture_output=True, text=True, timeout=10, check=False)
-        else:
-            out = subprocess.run(["ps", "-Ao", "command="], capture_output=True, text=True, timeout=10, check=False)
-        if out.returncode != 0 and not out.stdout:
-            return None
-        listing = out.stdout or ""
-    except Exception:  # pragma: no cover - defensive; an unknown answer is None
-        return None
-    return any(pattern in listing for pattern in _RESOLVE_PROCESS_PATTERNS)
+    return _resolve_runtime.runtime_mode()["running"]
 
 
 def get_resolve():
@@ -1017,7 +985,11 @@ def _not_connected_error():
             remediation="On Studio: Preferences > General > 'External scripting using' = Local. "
                         "On the free edition: install the in-app bridge, run "
                         "Workspace > Scripts > resolve_bridge, and set DAVINCI_RESOLVE_BRIDGE=1.",
-            state={"resolve_running": True, "bridge_enabled": False},
+            # 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.
+            state={"resolve_running": True, "bridge_enabled": False,
+                   "headless": _resolve_runtime.is_headless()},
         )
     return _err(
         "DaVinci Resolve is not running and could not be started.",
@@ -13074,7 +13046,18 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     """App-level DaVinci Resolve operations.
 
     Actions:
-      launch() -> {success, message}  — Launch DaVinci Resolve if not running. Call this FIRST if any tool returns a 'Not connected' error.
+      launch(headless?) -> {success, message, running, headless, guidance}
+        — Launch DaVinci Resolve if not running. Call this FIRST if any tool returns
+          a 'Not connected' error. headless=true starts it with no UI (-nogui):
+          capability-identical to the GUI and immune to the modal dialogs that can
+          block a script indefinitely. Errors rather than starting a second instance
+          if one is already running in the other mode.
+      runtime_mode() -> {running, headless, instances, guidance}
+        — Is Resolve up, and does it have a UI? Answers with no connection needed.
+          headless is null when it cannot be determined — do NOT read that as false.
+          There is no way to tell from the scripting API itself; this reads the
+          process argv. Consult before any LoadProject/CloseProject: with a UI,
+          an unsaved outgoing project raises a dialog no script can dismiss.
       get_version() -> {product, version, version_string, mcp: {version, update, update_decision}}
         — mcp.update_decision piggybacks the cached update check: if its action is
           "notify" or "prompt", mention the available MCP update to the user ONCE
@@ -13172,11 +13155,58 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         clear_update_prompt_preferences(project_dir, env=_setup_update_env())
         return _ok(**_mcp_update_status_payload())
 
+    # runtime_mode reads the operating system, not Resolve, so it answers even
+    # when nothing is running — which is exactly when an agent needs it.
+    if action == "runtime_mode":
+        payload = _resolve_runtime.describe()
+        # If something IS running, add the one reading that distinguishes a
+        # healthy instance from a wedged one. A Resolve can come up attached to
+        # NO database: it answers GetProductName, GetVersionString and
+        # GetCurrentPage normally, so every liveness check passes, while
+        # CreateProject and LoadProject return False forever and SaveProject
+        # returns None. Observed after an unclean shutdown, and it does not
+        # recover on its own — only a restart clears it.
+        if payload.get("running"):
+            try:
+                r = _try_connect() and resolve
+                database = r.GetProjectManager().GetCurrentDatabase() if r else None
+            except Exception:
+                database = None
+            payload["database"] = database
+            payload["database_attached"] = bool(database)
+            if payload.get("determinable") and not database:
+                payload["guidance"] = (
+                    "WEDGED: Resolve is running and answers version queries, but no "
+                    "database is attached — CreateProject/LoadProject will return "
+                    "False indefinitely and SaveProject returns None. This does not "
+                    "recover; quit and restart Resolve before doing any work."
+                ) + " || " + payload["guidance"]
+        return _ok(**payload)
+
     # launch works even when Resolve is not connected
     if action == "launch":
+        headless = p.get("headless")
+        if headless is not None:
+            # An explicit request has to survive the "already running" shortcut
+            # in get_resolve: connecting to the GUI instance someone asked to
+            # replace with a headless one is not what was asked for.
+            mode = _resolve_runtime.runtime_mode()
+            if mode["running"] and bool(headless) != bool(mode["headless"]):
+                return _err(
+                    "DaVinci Resolve is already running in the other mode.",
+                    code="RESOLVE_MODE_CONFLICT", category="not_connected", retryable=False,
+                    reason="Only one Resolve can run at a time; a second instance fights the "
+                           "singleton and has been observed to crash-loop rather than fail cleanly.",
+                    remediation="Quit the running instance first (resolve_control quit), then "
+                                "launch again with the mode you want.",
+                    state=mode,
+                )
+            if not mode["running"]:
+                _launch_resolve(headless=bool(headless))
         r = get_resolve()  # auto-launches if not running
         if r is not None:
-            return _ok(message="DaVinci Resolve is running and connected.")
+            return _ok(message="DaVinci Resolve is running and connected.",
+                       **_resolve_runtime.describe())
         return _not_connected_error()
 
     r = get_resolve()  # auto-launches if not running
@@ -13228,7 +13258,7 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
             return missing
         r.DisableBackgroundTasksForCurrentResolveSession()
         return _ok()
-    return _unknown(action, ["launch","get_version","api_truth","verification_stats","job_status","list_jobs","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
+    return _unknown(action, ["launch","runtime_mode","get_version","api_truth","verification_stats","job_status","list_jobs","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
 
 
 # ─── V2 C4: Per-field corrections with provenance + changelog ────────────────
@@ -20440,7 +20470,7 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
       set_mark_in_out(mark_in, mark_out, type?) -> {success}
       clear_mark_in_out(type?) -> {success}
       convert_to_stereo() -> {success}
-      get_items_in_track(track_type, track_index|index) -> {items}  — full serialization of each item
+      get_items_in_track(track_type, track_index|index) -> {items}  — alias of get_items
       get_voice_isolation_state(track_index) -> {isEnabled, amount}
       set_voice_isolation_state(track_index, state) -> {success}
       extract_source_frame_ranges(handles?, gap_max?, skip_extensions?) -> {timeline_name, frame_ranges, occurrences, ...}
@@ -20645,7 +20675,7 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
         return {"name": tl.GetTrackName(p["track_type"], p["index"])}
     elif action == "set_track_name":
         return {"success": bool(tl.SetTrackName(p["track_type"], p["index"], p["name"]))}
-    elif action == "get_items":
+    elif action in {"get_items", "get_items_in_track"}:
         track_type, track_index, err = _track_selector(p)
         if err:
             return _err(err)
@@ -20884,11 +20914,6 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
         return {"success": bool(tl.ClearMarkInOut(p.get("type", "all")))}
     elif action == "convert_to_stereo":
         return {"success": bool(tl.ConvertTimelineToStereo())}
-    elif action == "get_items_in_track":
-        track_type, track_index, err = _track_selector(p)
-        if err:
-            return _err(err)
-        return {"items": _ser(tl.GetItemListInTrack(track_type, track_index))}
     elif action == "get_voice_isolation_state":
         missing = _requires_method(tl, "GetVoiceIsolationState", "20.1")
         if missing:
@@ -22235,9 +22260,9 @@ _ACTION_HELP: Dict[str, Dict[str, Dict[str, Any]]] = {
             "example": 'timeline(action="get_items", params={"track_type": "video", "index": 1})',
         },
         "get_items_in_track": {
-            "summary": "List items on one track with full per-item serialization.",
+            "summary": "Alias of get_items: list items on one track (name/id/start/end/duration).",
             "params": "track_type (video|audio|subtitle), track_index|index (1-based)",
-            "returns": "{items}",
+            "returns": "{items: [{name, id, start, end, duration}]}",
             "example": 'timeline(action="get_items_in_track", params={"track_type": "audio", "track_index": 1})',
         },
         "duplicate_clips": {

package/src/utils/api_truth.py

@@ -101,10 +101,233 @@ API_TRUTH: List[Dict[str, Any]] = [
         "reality": "Returns False (no deletion) when the target project is, or "
                    "recently was, the current project, and is flaky on the first "
                    "attempt — so a single bool() call leaves the project undeleted "
-                   "with no useful error.",
-        "recommended": "Load/close away from the target first, then retry; use "
-                       "src/utils/project_cleanup.py:delete_project_safely.",
-        "tags": ["unreliable-return", "project", "flaky"],
+                   "with no useful error. CloseProject reliably releases it: a "
+                   "delete that had failed six times in a row, a second apart, "
+                   "succeeded on the first attempt after one. Switching away with "
+                   "LoadProject is NOT reliable — it left the delete failing "
+                   "permanently after a heavily-used project, yet succeeded for a "
+                   "project that had only been created and loaded. Whatever "
+                   "distinguishes the two (modification? an open timeline?) is "
+                   "not established, so LoadProject-away cannot be depended on.",
+        "recommended": "CloseProject the target FIRST (that is what releases it), "
+                       "then LoadProject some named project so the session is not "
+                       "left on the unsaveable 'Untitled Project' fallback, then "
+                       "delete. Use src/utils/project_cleanup.py:delete_project_safely, "
+                       "which does exactly that.",
+        "tags": ["unreliable-return", "project", "flaky", "session-lock"],
+        "submit": "bug",
+    },
+    {
+        "symbol": "Project.SetSetting('timelinePlaybackFrameRate')",
+        "object": "Project",
+        "reality": "Returns False for every value form tried (string, int, "
+                   "float), both before and after a timeline exists, so the "
+                   "playback frame rate cannot be set from the API at all. "
+                   "Reported by a community contributor against Resolve Studio "
+                   "while assembling a vertical timeline (PR #99).",
+        "recommended": "Ask the user to set it in Project Settings > Master "
+                       "Settings > Playback frame rate as a SETUP step, before "
+                       "any timeline exists. Read it back to confirm; do not "
+                       "report it as set on the strength of the call alone.",
+        "tags": ["project-settings", "silent-failure", "timeline"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "ProjectManager.GetCurrentDatabase",
+        "object": "ProjectManager",
+        "signature": "() -> {DbType, DbName}",
+        "reality": "Returns None when Resolve has come up without attaching to a "
+                   "project database — a state it reaches after an unclean "
+                   "shutdown, and does not recover from on its own. In that state "
+                   "the application looks entirely healthy: it accepts scripting "
+                   "connections, and GetProductName, GetVersionString, "
+                   "GetCurrentPage and GetCurrentProject all answer normally. But "
+                   "CreateProject and LoadProject return False indefinitely, "
+                   "SaveProject returns None, and some calls block forever in "
+                   "the scripting transport rather than returning at all. "
+                   "Observed headless on Studio 19.1.3.7 after force-killing a "
+                   "wedged instance; the replacement took 2m05s to become "
+                   "scriptable and came up with no database.",
+        "recommended": "Treat a non-None GetCurrentDatabase() as the liveness "
+                       "check, not a successful connection — every cheaper check "
+                       "passes in the wedged state. `resolve_control "
+                       "runtime_mode` reports `database_attached` for exactly "
+                       "this. There is no repair: quit and restart Resolve.",
+        "tags": ["project", "database", "headless", "silent-failure", "startup"],
+        "mitigation": ["runtime_mode"],
+        "submit": "bug",
+    },
+    {
+        "symbol": "MediaPool.ImportTimelineFromFile",
+        "object": "MediaPool",
+        "signature": "(filePath, {importOptions}) -> Timeline",
+        "reality": "Returns None — no error, no exception — when the requested "
+                   "`timelineName` already exists. Measured: importing one file "
+                   "three times with the same name succeeded once and returned "
+                   "None twice. An iterative loop that reuses a fixed name "
+                   "therefore works exactly once and then silently does nothing. "
+                   "DRT ignores importOptions entirely (timelineName, "
+                   "importSourceClips and sourceClipsFolders are all invalid for "
+                   "it): the timeline is named after the FILE, repeats "
+                   "auto-uniquify ('iter', 'iter 2', 'iter 3'), and because "
+                   "importSourceClips cannot be disabled each DRT import adds "
+                   "another copy of the source media to the pool. OTIO is the one "
+                   "format that will NOT relink from the pool — with "
+                   "importSourceClips=False its timeline rebuilds with correct "
+                   "structure and every item OFFLINE, in both GUI and headless.",
+        "recommended": "For a repeatable loop use FCP7 XML or AAF with a UNIQUE "
+                       "timelineName per iteration plus importSourceClips=False "
+                       "and sourceClipsFolders=[root] — verified frame-exact over "
+                       "five consecutive imports with no media duplicated. Use DRT "
+                       "for one-shot hand-offs only. For OTIO, pass "
+                       "importSourceClips=True with a sourceClipsPath. See "
+                       "docs/guides/headless-edit-loop.md.",
+        "tags": ["timeline", "import", "interchange", "silent-failure", "conform"],
+        "submit": "bug",
+    },
+    {
+        "symbol": "Timeline.Export / ImportTimelineFromFile (format fidelity)",
+        "object": "Timeline",
+        "reality": "The formats are NOT interchangeable, and which one is right "
+                   "depends on the job — measured identically in GUI and "
+                   "headless. On a rich cut (2 video tracks, audio, per-item "
+                   "transform, colours, flags, item and timeline markers) only "
+                   "DRT kept everything. FCP7 XML kept the cut, tracks and most "
+                   "of the transform, losing only FlipX. AAF kept the cut and "
+                   "tracks but RESET THE WHOLE TRANSFORM to defaults. FCPXML 1.10 "
+                   "silently dropped an audio track (2v2a in, 2v1a out). OTIO "
+                   "lost the source association. EDL collapsed to 1v1a. "
+                   "But with media MOVED and sourceClipsPath given, the ranking "
+                   "inverts: FCP7 XML, AAF and FCPXML 1.10 relinked 3/3 and stayed "
+                   "frame-exact, while DRT relinked 0/3 (sourceClipsPath is not "
+                   "valid for DRT, so it cannot be told where the media went), EDL "
+                   "relinked 0/3, and OTIO's import returned None outright.",
+        "recommended": "Pick per job: DRT for full fidelity with media in place; "
+                       "FCP7 XML or AAF for an iterative loop or any conform where "
+                       "media may move; never DRT/OTIO/EDL for a relink. Note the "
+                       "cut stays frame-exact even when relinking fails, so a "
+                       "failed relink leaves a correct offline timeline rather "
+                       "than a wrong one. See docs/guides/headless-edit-loop.md.",
+        "tags": ["timeline", "export", "import", "interchange", "conform"],
+    },
+    {
+        "symbol": "BMD_RESOLVE_*_DIR environment variables",
+        "object": "Resolve",
+        "reality": "BMD_RESOLVE_CONFIG_DIR / SUPPORT_DIR / LUT_DIR genuinely "
+                   "isolate an instance — a launch with them set builds a private "
+                   "config.dat plus its own Resolve Project Library, Fairlight, "
+                   "DolbyVision and easyDCP trees, and the resulting instance sees "
+                   "ZERO of the machine's real projects. They do NOT defeat the "
+                   "single-instance guard: started while another Resolve was "
+                   "running, the second process created its private tree and then "
+                   "exited silently, logging nothing. So isolated instances are "
+                   "possible and PARALLEL instances are not. A fresh config also "
+                   "omits `System.Scripting.Mode = 1`, so an isolated instance is "
+                   "unreachable by scripting until that line is appended to its "
+                   "config.dat (plain ASCII) — until then it runs, opens no "
+                   "listener, and looks exactly like a hang. "
+                   "BMD_RESOLVE_LOGS_DIR only partly takes: LogArchive/ and "
+                   "gpudetect.bin appear there, the main log does not.",
+        "recommended": "Use for a CI/render worker that must not see or lock the "
+                       "operator's projects. Seed the scripting preference after "
+                       "the first boot. Do not expect to run two at once. Recipe "
+                       "in docs/reference/headless-cli.md.",
+        "tags": ["headless", "isolation", "singleton", "ci", "startup"],
+    },
+    {
+        "symbol": "Resolve -fastmode",
+        "object": "Resolve",
+        "reality": "Starts a process that stays alive at 0% CPU and never opens "
+                   "the scripting listener — port 15000 is not bound at all, and "
+                   "it was still unreachable after two minutes. Exercised in an "
+                   "isolated sandbox on Studio 19.1.3.7.",
+        "recommended": "Not usable for automation; do not pass it. (`-activate` "
+                       "and `-deactivate` remain deliberately unexercised: their "
+                       "adjacent strings show they mutate this machine's Studio "
+                       "licence activation.)",
+        "tags": ["headless", "cli-flags"],
+    },
+    {
+        "symbol": "Timeline.Export(EXPORT_FCPXML_1_10)",
+        "object": "Timeline",
+        "signature": "(fileName, EXPORT_FCPXML_1_10, EXPORT_NONE) -> bool",
+        "reality": "Returns True and creates a BUNDLE DIRECTORY at the given "
+                   "path containing `Info.fcpxml`, rather than a file — the "
+                   "`.fcpxmld` shape Final Cut uses. Two consequences bite "
+                   "immediately: a `stat().st_size` check reads the directory "
+                   "inode (96 bytes here) and concludes the export is empty, and "
+                   "ImportTimelineFromFile on that path fails because it is a "
+                   "directory. Every other EXPORT_* type in this build writes a "
+                   "plain file, so code that treats them uniformly gets this one "
+                   "wrong. Pointed at the inner member, the format round-trips "
+                   "frame-exactly in both modes.",
+        "recommended": "After exporting, check `Path(p).is_dir()` and import "
+                       "`next(Path(p).glob('*.fcpxml'))` instead. Do not size-"
+                       "check the export path itself.",
+        "tags": ["timeline", "export", "interchange", "fcpxml", "silent-failure"],
+        "submit": "bug",
+    },
+    {
+        "symbol": "MediaPool.CreateTimelineFromClips",
+        "object": "MediaPool",
+        "reality": "Fails with a bare 'Failed to create timeline from clip_infos' "
+                   "— naming nothing actionable — when the Media Pool's CURRENT "
+                   "folder is not the folder holding the clips, even though every "
+                   "clip_id passed is valid and resolvable. Reported against "
+                   "Resolve Studio in PR #99.",
+        "recommended": "Call MediaPool.SetCurrentFolder() to the clips' bin "
+                       "before creating the timeline (media_pool "
+                       "set_current_folder). Valid ids are not sufficient.",
+        "tags": ["media-pool", "timeline", "unhelpful-error"],
+        "submit": "bug",
+    },
+    {
+        "symbol": "TimelineItem.AddFusionComp / LoadFusionCompByName",
+        "object": "TimelineItem (media-backed clip)",
+        "reality": "A Fusion composition created on a media clip through the API "
+                   "is not applied at render WHEN MEDIAOUT HAS NO PATH FROM "
+                   "MEDIAIN. The original blanket form of this entry — 'never "
+                   "applied at render' — was too broad and was corrected on "
+                   "2026-08-02: a comp wired MediaIn -> Blur -> MediaOut, created "
+                   "entirely through the API on an ordinary media clip, DOES "
+                   "render. PSNR between the plain and Fusion renders of the same "
+                   "timeline was 22.7 dB (identical would be infinite), the file "
+                   "shrank 22.5 MB -> 14.8 MB as a blur should, and the output was "
+                   "frame-for-frame identical in GUI and headless. A first attempt "
+                   "that wired ONLY MediaOut -> Blur, leaving the Blur with no "
+                   "source, made the render job come back 'Failed' with an "
+                   "887-byte file — so an unrooted graph does not merely get "
+                   "bypassed, it can take the render down. "
+                   "What still stands is the original observation for the "
+                   "configuration it actually tested, which is retained below and "
+                   "has NOT been re-measured: AddFusionComp() returns the comp, "
+                   "AddTool/Connect/SetInput all succeed, and the whole graph "
+                   "reads back correctly (GetCompCount 1, MediaOut1.Input wired "
+                   "to the new tool, StyledText returning the value just set) — "
+                   "but the rendered output is byte-for-byte the untouched source "
+                   "media. Verified live on Studio 19.1.3.7 with the strongest "
+                   "form of the test: MediaOut1 fed ONLY by a Text+, with no path "
+                   "from MediaIn at all, still rendered the unmodified clip. "
+                   "LoadFusionCompByName on the sole comp does not activate it "
+                   "either. Contrast InsertFusionTitleIntoTimeline, whose comp "
+                   "DOES render — text set via SetInput('StyledText') appears in "
+                   "the output — so this is specific to comps attached to "
+                   "media-backed clips, not to Fusion through the API generally.",
+        "recommended": "Wire the graph so MediaOut descends from MediaIn — that "
+                       "is the difference between a comp that renders and one "
+                       "that is silently bypassed, and it is what made this look "
+                       "like 'Fusion never renders from the API'. Never leave a "
+                       "tool unrooted: a MediaOut fed by a tool with no source "
+                       "failed the render job outright. "
+                       "For text or effects over picture, insert a Fusion title/"
+                       "generator as its own timeline clip and set its Text+ "
+                       "(fusion_comp set_text_plus), rather than attaching a comp "
+                       "to the media clip. Note the destination track cannot be "
+                       "chosen from the API (see the Track Selector entry), so "
+                       "overlaying onto an existing clip's track is not currently "
+                       "reachable end-to-end. Building the comp in the Fusion page "
+                       "UI works; only the API-created comp is ignored.",
+        "tags": ["fusion", "silent-failure", "render"],
         "submit": "bug",
     },
     {
@@ -636,6 +859,81 @@ API_TRUTH: List[Dict[str, Any]] = [
         "tags": ["render", "deliver", "audio", "unsupported"],
         "submit": "missing",
     },
+    {
+        "symbol": "ProjectManager.SaveProject",
+        "object": "ProjectManager",
+        "signature": "() -> bool",
+        "reality": "On the default, never-saved project named 'Untitled Project' "
+                   "this call CANNOT succeed — the project has no location and "
+                   "there is no SaveProjectAs to give it one — and the two modes "
+                   "fail differently. In the GUI it returns False. HEADLESS IT "
+                   "BLOCKS FOREVER: measured on a cold -nogui boot with the "
+                   "database verified attached immediately beforehand, no return "
+                   "after 45s, the client parked in Fusion::RemoteApp::WaitPkt. "
+                   "Resolve wants a Save-As dialog and waits for an answer that "
+                   "cannot arrive. It also degrades the instance: after the hung "
+                   "call was interrupted, SaveProject began returning None "
+                   "instantly on that instance. On a named project it is fine in "
+                   "both modes.",
+        "recommended": "Guard it: only call SaveProject when "
+                       "GetCurrentProject().GetName() != 'Untitled Project'. "
+                       "There is nothing to save on the default project and the "
+                       "call cannot succeed, so skipping it loses nothing. Do NOT "
+                       "reach for headless to dodge the GUI's save dialog — "
+                       "headless turns that dialog into an unbounded hang that no "
+                       "human can clear.",
+        "tags": ["project", "modal", "headless", "hang", "silent-failure", "unreliable-return"],
+        "submit": "bug",
+        "mitigation": ["save_project_if_safe"],
+    },
+    {
+        "symbol": "Resolve.GetCurrentPage",
+        "object": "Resolve",
+        "signature": "() -> string",
+        "reality": "A headless (-nogui) instance answers with a real page name, "
+                   "not None, and OpenPage() succeeds and reads back for all "
+                   "seven pages with no UI present. Nothing on the scripting API "
+                   "distinguishes a headless Resolve from one with a window — "
+                   "product name, version, layout presets, Gallery handles and "
+                   "Fusion comps all behave identically (Studio 19.1.3.7, 238 "
+                   "paired observations, zero headless-only failures).",
+        "recommended": "Do not infer headlessness from any API reading. Use "
+                       "resolve_control runtime_mode, which reads -nogui out of "
+                       "the process argv — the only place it is visible.",
+        "tags": ["headless", "page", "detection"],
+        "mitigation": ["runtime_mode", "resolve_runtime.is_headless"],
+    },
+    {
+        "symbol": "GalleryStillAlbum.ExportStills",
+        "object": "GalleryStillAlbum",
+        "signature": "(galleryStills, folderPath, filePrefix, format) -> bool",
+        "reality": "PANEL-dependent, not mode-dependent — and the distinction "
+                   "took three revisions of this entry to pin down, so the "
+                   "evidence is recorded rather than summarised. Across four "
+                   "controlled 92-probe sweeps (2 GUI, 2 headless, 2026-08-01) it "
+                   "returned False and wrote nothing in ALL FOUR, while "
+                   "Timeline.GrabStill() succeeded in all four — so it is not "
+                   "being handed an empty still. In one earlier GUI session it "
+                   "DID work, returning True and writing 2 files. The variable "
+                   "that differed is not the mode: it is whether the Gallery "
+                   "panel was visible on the Color page, which depends on the "
+                   "restored workspace layout and which the harness does not "
+                   "control. A headless session can never satisfy it, so in "
+                   "practice the call never works headless; a GUI session "
+                   "satisfies it only sometimes. "
+                   "Project.ExportCurrentFrameAsStill worked in all four runs in "
+                   "both modes.",
+        "recommended": "Do not use ExportStills unattended in either mode — a "
+                       "GUI session is not sufficient, only a GUI session with "
+                       "the Gallery panel open. Use "
+                       "Project.ExportCurrentFrameAsStill for pixels (verified in "
+                       "both modes, four for four) or drp.extract_node_graphs for "
+                       "grades. If ExportStills must be used, have the user open "
+                       "Workspace > Gallery first and verify the written files "
+                       "rather than trusting the return.",
+        "tags": ["gallery", "stills", "headless", "unreliable-return"],
+        "submit": "bug",
+    },
 ]