davinci-resolve-mcp 2.69.3 → 2.70.0

package/CHANGELOG.md

@@ -2,6 +2,91 @@
 
 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.70.0
+
+Headless (`-nogui`) Resolve, measured rather than assumed — and the finding
+reverses this project's working belief about it.
+
+### The measurement
+
+A GUI run and a `-nogui` run of the same Resolve Studio 19.1.3.7 were probed
+identically and differenced: 139 read-only API probes plus 13 write scenarios
+covering pages, media pool, timeline editing, colour, Fusion comps, Gallery,
+render-to-disk, interchange export, layout presets, playhead and project
+settings. 238 paired observations.
+
+**Zero capabilities worked with a UI and failed without one.** Render to disk,
+AAF/EDL/FCPXML/DRT/OTIO export, `ExportCurrentFrameAsStill`, `GrabStill`, Fusion
+comp create/delete, colour groups, and even UI layout presets all behave
+identically headless.
+
+**Scope, stated up front:** that is a result about *capability* and about
+modals. It is **not** a stability result. The probe's render was 2 seconds of
+640×360 H.264; long renders, JPEG 2000 decode out of DCP MXF, ProRes-into-MXF
+writes and repeated jobs in one session are all untested, and there is a field
+report of headless crashing *on completion of writes* for exactly that class of
+job. The docs and the runtime guidance say so rather than letting the matrix
+be read as a blanket endorsement.
+
+The one difference actually found runs the other way, and it is the one an agent
+cares about: **a GUI Resolve can raise a modal dialog no script can dismiss;
+headless cannot.** The trigger is project switching, and the obvious defence fails —
+`ProjectManager.SaveProject()` returns `False` for the default never-saved
+`Untitled Project`, which is exactly the project that raises the prompt.
+Headless returns the same `False` and switches anyway.
+
+Two earlier notes are corrected: `ExportCurrentFrameAsStill` was recorded as a
+headless-only failure and works headless; `ExportStills` was recorded the same
+way and fails in *both* modes (its documented cause is Gallery panel visibility,
+which no headless session and no panel-closed GUI session can satisfy).
+
+### Fixed
+
+- **`timeline(action="get_items_in_track")` returned object reprs, not items.**
+  The handler passed `GetItemListInTrack`'s result to `_ser`, which has no
+  TimelineItem branch and falls through to `str(obj)`, so callers got
+  `["<PyRemoteObject at 0x…>", …]` instead of clip data. The docstring's claim of
+  "full serialization of each item" was never true. The sibling `get_items`
+  takes the same params through the same `_track_selector` and calls the same API
+  method, so the two are now one handler and `get_items_in_track` is documented
+  as its alias — there was no richer per-item serializer to preserve. Thanks
+  [@billcarroll](https://github.com/billcarroll) (#105).
+
+### Added
+
+- `resolve_control(action="runtime_mode")` — is Resolve up, and does it have a
+  UI? Answers with no connection needed, and carries the mode-specific guidance
+  with it. **There is no API tell**: a headless instance returns a real page from
+  `GetCurrentPage()` and identical product/version strings, so this reads the
+  process argv, which is the only place `-nogui` appears. `headless` is `null`
+  when undeterminable — never read that as `false`.
+- `resolve_control(action="launch", params={"headless": true})`, plus
+  `DAVINCI_RESOLVE_HEADLESS=1` to make auto-launch headless. Launching the other
+  mode while an instance is running returns `RESOLVE_MODE_CONFLICT` instead of
+  starting a second one that would fight the singleton.
+- `src/utils/resolve_runtime.py` — mode detection and launch-command
+  construction. Headless launch runs the binary inside the app bundle, because
+  `open -a` hands the argument list to LaunchServices, which discards `-nogui`
+  and gives you a window with no error.
+- `scripts/resolve_headless.py` — batch/CI entry point: `status`, `guard`,
+  `start`, `stop`, and `run -- <cmd>` which only stops what it started.
+- `scripts/headless_differential.py` + `src/utils/headless_differential.py` —
+  the harness that produced the above, rerunnable after a Resolve upgrade.
+- `docs/reference/headless-cli.md` — verified flags, environment variables,
+  launch/teardown recipes, singleton rules, and the flags found in the
+  application binary but deliberately *not* exercised.
+- `docs/reference/headless-capability-matrix.md` — the generated differential.
+- Three `api_truth` entries: the `SaveProject`/modal trap, the absence of any
+  headless API tell, and the corrected `ExportStills` reality.
+
+### Validation
+
+- Offline suite 2280 → 2305 (`tests/test_headless_runtime.py`, 25 tests).
+- Live: full differential recorded in both modes on Resolve Studio 19.1.3.7,
+  scratch project created and deleted per run, GUI session restored afterwards.
+  Measured teardown 2.1s via `Quit()`, headless boot to scriptable under 3s,
+  scripting listener on TCP 15000 in both modes.
+
 ## What's New in v2.69.3
 
 Ships the v2.69.2 bundle, which never reached npm. Same fixes, plus the one that

package/README.md

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

package/docs/SKILL.md

@@ -218,6 +218,81 @@ respect this hint pass it as `tool_choice={type:"tool", name:"media_analysis"}`
 on the next API turn, hard-locking the agent into the correct next call. Hosts
 that don't recognize the field ignore it — the flow is unchanged for them.
 
+## Headless Resolve (`-nogui`)
+
+Resolve runs without a UI, and it is **capability-identical** to a GUI session.
+Measured across 238 paired observations on Studio 19.1.3.7 (see
+`docs/reference/headless-cli.md` and the regenerable
+`docs/reference/headless-capability-matrix.md`): **zero** capabilities work with
+a UI and fail without one. Pages, render-to-disk, AAF/EDL/XML/DRT/OTIO export,
+`ExportCurrentFrameAsStill`, Fusion comps, colour groups, layout presets and all
+ordinary editorial behave identically.
+
+**Capability is not stability, but stability is now partly measured too.** Ten
+consecutive ProRes 422 HQ renders in one headless session, from a JPEG 2000 /
+MXF OP1A source, completed with no crash, no death and no leak — marginally
+faster and ~95 MB lighter than the same ten renders with a UI. What remains
+untested is *sustained* encode over hours and the operator's own footage and
+codec settings. Use headless freely for orchestration, edit, conform, analysis
+and renders of that scale; qualify it on real footage before promising a
+long-form or professional-container delivery, and keep a GUI fallback there.
+
+**Headless is NOT immune to modal dialogs — it is worse.** It cannot *display* a
+dialog, but Resolve still tries to raise one, and the call then never returns.
+
+The canonical case, measured on a cold `-nogui` boot:
+`ProjectManager.SaveProject()` on the default never-saved project named
+`Untitled Project` **blocks forever** headless (no return after 45s, client
+parked in `Fusion::RemoteApp::WaitPkt`), where the GUI merely returns `False`.
+The project has no location and there is no `SaveProjectAs`, so Resolve wants a
+Save-As dialog and waits for an answer that can never arrive. In the GUI a human
+clears it in one click; headless nothing can.
+
+**Never call `SaveProject()` without checking the project name first:**
+
+```python
+project = pm.GetCurrentProject()
+if project is not None and project.GetName() != "Untitled Project":
+    pm.SaveProject()      # safe: it has a location
+# else: nothing to save, and headless this call blocks forever
+```
+
+`src/utils/project_cleanup.py:save_project_if_safe(pm)` does exactly this — use
+it rather than calling `SaveProject` directly. And do **not** reach for headless
+to dodge the GUI's save dialog; that trade makes a one-click interruption into a
+dead session.
+
+Rules:
+
+- **Check the mode before any project switch.** `resolve_control(action="runtime_mode")`
+  → `{running, headless, instances, database_attached, guidance}`. It needs no
+  connection.
+- **`database_attached: false` means the instance is WEDGED — stop and restart it.**
+  Resolve can come up with no project database attached. It accepts connections
+  and answers product, version, page and current-project queries normally, so
+  every ordinary liveness check passes, while `CreateProject`/`LoadProject`
+  return False forever, `SaveProject` returns None, and some calls never return
+  at all. It does not recover on its own. Do not retry; quit and relaunch.
+- **`headless` may be `null`.** That means "cannot be determined", not "has a UI".
+  Treat `null` like `false` — take the careful path — but do not report it as fact.
+- **There is no API tell.** A headless instance returns a real page from
+  `GetCurrentPage()` and identical product/version strings. Anything that
+  inspects the `resolve` handle to guess the mode is guessing. `runtime_mode`
+  reads the process argv, which is the only place `-nogui` appears.
+- **Launching:** `resolve_control(action="launch", params={"headless": true})`,
+  or set `DAVINCI_RESOLVE_HEADLESS=1` to make auto-launch headless. Launching
+  the other mode while an instance is already running returns
+  `RESOLVE_MODE_CONFLICT` rather than starting a second one — two Resolves fight
+  the singleton and have been observed to crash-loop rather than fail cleanly.
+- **`instances` > 1 is a fault to report**, not a state to work around. Check for
+  a render node before starting anything.
+- Teardown is `resolve_control(action="quit")`; it discards the open project
+  without prompting, which is what a batch process wants.
+
+The one thing headless genuinely cannot do is anything that needs a *visible
+panel* — `ExportStills` being the known case, and it fails in a panel-closed GUI
+too.
+
 ## Local Control Panel
 
 If the user asks to open, launch, or inspect the Resolve MCP control panel, run
@@ -1850,7 +1925,9 @@ timeline item returns `False` in Resolve. Use `get_node_graph` without a
 
 **Gallery export requires the Gallery panel visible** — `ExportStills` only works
 if the Gallery panel is open in the Resolve UI on the Color page. Instruct the
-user to open it via Workspace menu if export fails.
+user to open it via Workspace menu if export fails. Measured to fail in *both*
+GUI (panel closed) and headless sessions, so a failure is not a reason to switch
+modes. For pixels use `Project.ExportCurrentFrameAsStill`, which works in both.
 
 **Python version** — the only hard requirement is Python **3.10+** (the MCP SDK
 floor). There is no upper cap: 3.13/3.14 are accepted, and Python 3.14 is verified

package/docs/guides/headless-edit-loop.md

@@ -0,0 +1,238 @@
+# Building edits headless: the iterative loop
+
+How to drive Resolve entirely from the command line to import media, link it,
+assemble a cut, and then round-trip that cut repeatedly — with the format and
+option choices justified by measurement rather than habit.
+
+Everything here was measured on Resolve Studio 19.1.3.7 in **both** GUI and
+`-nogui` sessions on 2026-08-01. Regenerate with `scripts/roundtrip_matrix.py`;
+the raw runs are in `docs/reference/evidence/`.
+
+## The short answer
+
+**Mode does not matter.** Every result below is byte-identical between GUI and
+`-nogui` — the flat round trip, the complex-cut round trip, and the moved-media
+relink. Choose a format on its properties, never on whether you have a UI.
+
+**There is no single best format.** Three measurements pull in different
+directions, and the right choice depends on which one you are up against:
+
+| what you need | format | why |
+| --- | --- | --- |
+| **Full fidelity**, media staying put | **DRT** | the only format that kept *everything*: transforms, colours, flags, item and timeline markers |
+| **Iterative loop**, media staying put | **FCP7 XML** or AAF | no media duplication, controllable timeline name — DRT has neither |
+| **Media has MOVED** (real conform) | **FCP7 XML**, AAF, FCPXML 1.10 | the only three that relink. **DRT, OTIO and EDL all fail** |
+
+The trap is that DRT looks like the obvious choice — it is native and it is the
+only format that survives a rich cut intact — and it is the *worst* choice for
+both of the other two jobs. It re-imports its media every time, and it cannot
+relink media that has moved at all.
+
+**For an iterative loop, use FCP7 XML (or AAF) with:**
+
+```python
+options = {
+    "timelineName": f"CUT_v{iteration:03d}",   # MUST be unique per import
+    "importSourceClips": False,                 # reuse the pool, do not re-import
+    "sourceClipsFolders": [pool.GetRootFolder()],
+}
+timeline = pool.ImportTimelineFromFile(path, options)
+```
+
+Verified: five consecutive imports, all succeeded, source in-points preserved
+exactly, and **no media duplicated** — the media pool grew by exactly one item
+per import, which is the imported timeline itself, not another copy of the
+footage.
+
+## The traps, each measured
+
+### A repeated `timelineName` silently stops working
+
+Importing the same file three times with the *same* `timelineName`:
+
+| import | result |
+| --- | --- |
+| 1 | succeeded, timeline `ITER_FIXED` |
+| 2 | **returned None** |
+| 3 | **returned None** |
+
+No error, no exception — `ImportTimelineFromFile` just returns None once the
+name is taken. An iterative loop that reuses one name works exactly once and
+then quietly does nothing, which is the worst possible failure for an automated
+edit cycle. Make the name unique per iteration.
+
+### DRT ignores `timelineName` and re-imports the media
+
+DRT is the native format and the obvious first choice, but it behaves
+differently on import, in ways the documentation states but that are easy to
+miss:
+
+- `timelineName`, `importSourceClips` and `sourceClipsFolders` are **all invalid
+  for DRT**. Passing them gets you a failure that says nothing about the format.
+- The imported timeline is named after the **file**, not the timeline inside it,
+  and repeated imports auto-uniquify: `iter`, `iter 2`, `iter 3`.
+- Because `importSourceClips` cannot be set to False, each DRT import **adds
+  another copy of the source media** to the pool. Measured: three DRT imports
+  grew the pool by four items, against one per import for the XML route.
+
+So DRT is excellent for a one-shot hand-off and wrong for a loop that runs a
+hundred times.
+
+### FCPXML 1.10 exports a *directory*, not a file
+
+`Timeline.Export(path, EXPORT_FCPXML_1_10, EXPORT_NONE)` returns True and
+creates a **bundle directory** at `path` containing `Info.fcpxml` — the
+`.fcpxmld` shape Final Cut uses. Consequences:
+
+- `path.stat().st_size` reports the directory inode (96 bytes here), so a
+  size check reads it as a near-empty export.
+- `ImportTimelineFromFile(path)` fails, because the path is a directory.
+
+Point the import at the member instead, and the format round-trips exactly:
+
+```python
+inner = next(Path(export_path).glob("*.fcpxml"))     # Info.fcpxml
+pool.ImportTimelineFromFile(str(inner), options)
+```
+
+This is why the first round-trip run reported FCPXML 1.10 as import-failed in
+both modes. It was the harness, not the format.
+
+### OTIO with `importSourceClips: False` arrives fully offline
+
+Every other format relinks against the existing pool. OTIO does not: with
+`reuse_pool` the timeline rebuilds with correct structure and **all four items
+offline**, in both modes. With `importSourceClips: True` and a `sourceClipsPath`
+it links correctly. If you want OTIO, re-import the sources.
+
+## What each format actually keeps
+
+The flat single-track round trip found every format frame-exact — because a flat
+cut of untouched clips gives them nothing to disagree about. On a real cut (two
+video tracks, audio, a per-item transform, clip colours, flags, item and timeline
+markers) they diverge sharply. Identical in both modes:
+
+| format | cut | tracks | transform | colour | flags | item markers | timeline markers |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| **drt** | kept | kept | **kept** | **kept** | kept | **kept** | kept |
+| fcpxml_1_10 | kept | **lost an audio track** | kept | lost | kept | lost | lost |
+| fcp7xml | kept | kept | lost **only FlipX** | lost | kept | lost | lost |
+| aaf | kept | kept | **lost: all reset to defaults** | lost | kept | lost | kept |
+| otio | **lost: source** | kept | kept | lost | lost | kept | kept |
+| edl | **lost** | **1v1a** | n/a | lost | lost | lost | lost |
+
+Two details worth having:
+
+- **AAF resets the entire transform to defaults**, while **FCP7 XML preserves
+  zoom, pan and rotation exactly** and drops only `FlipX`. A whole-dict
+  comparison called both "lost", which is the same word for "carries geometry"
+  and "does not". Crop comes back as 39.999936 against 40.0 — that is unit
+  round-tripping, not loss.
+- **FCPXML 1.10 silently drops an audio track** (2v2a in, 2v1a out).
+
+## Relinking media that has moved
+
+The test that matters for conform: build the cut, export it, **rename the media
+directory** so every baked-in path is dead, then import in a fresh project with
+`sourceClipsPath` pointing at the new location. Identical in both modes:
+
+| format | relinked | cut still frame-exact |
+| --- | --- | --- |
+| fcp7xml | **3/3** | yes |
+| aaf | **3/3** | yes |
+| fcpxml_1_10 | **3/3** | yes |
+| drt | **0/3** — items stay pointing at the dead path | yes (but offline) |
+| edl | **0/3** | yes (but offline) |
+| otio | **import returned None** — fails outright | — |
+
+`sourceClipsPath` is not valid for DRT, so DRT has no mechanism to be told where
+the media went. EDL carries reel names rather than paths and did not resolve
+either. OTIO did not merely fail to relink — the import returned `None`.
+
+Note that "frame-exact" stays true even where nothing relinked: the *cut*
+survives offline. That is worth knowing, because it means a failed relink leaves
+a correct timeline you can relink by other means, rather than a wrong one.
+
+## Format selection
+
+All are frame-exact in both modes; these are the tie-breakers. Payload sizes are
+for the same four-item test timeline.
+
+| format | size | links from pool | name controllable | notes |
+| --- | --- | --- | --- | --- |
+| **fcp7xml** | 42 KB | yes | yes | the recommended loop format |
+| **aaf** | 315 KB | yes | yes | same behaviour, 7x the payload |
+| **edl** | 512 B | yes | yes | astonishingly, frame-exact — see below |
+| drt | 19 KB | n/a (always re-imports) | no | native; one-shot hand-off |
+| otio | 85 KB | **no — offline** | yes | needs `importSourceClips: True` |
+| fcpxml_1_10 | 3 KB | yes | yes | writes a bundle directory |
+
+**On EDL:** 512 bytes round-tripped frame-exactly with media linked, which is not
+what EDL's reputation suggests. It works here because the test media carries
+embedded timecode (`-timecode 01:00:00:00`) and the sources relink by name. EDL
+carries no effects, no multiple tracks, and no speed changes — so this result
+means "EDL is sufficient for a flat single-track conform of timecoded media",
+not "EDL is a good interchange format". Do not generalise it to a real cut.
+
+## The whole loop, headless
+
+```bash
+# 1. one Resolve, no UI, and confirm nothing else holds the singleton
+python scripts/resolve_headless.py guard
+python scripts/resolve_headless.py start
+```
+
+```python
+# 2. import media and build the initial cut through the API, not a file.
+#    AppendToTimeline with explicit clipInfo dicts is frame-exact and needs no
+#    interchange format at all.
+clips = resolve.GetMediaStorage().AddItemListToMediaPool(paths)
+timeline = pool.CreateEmptyTimeline("CUT_v001")
+project.SetCurrentTimeline(timeline)
+pool.AppendToTimeline([
+    {"mediaPoolItem": clips[0], "startFrame": 0,  "endFrame": 191},
+    {"mediaPoolItem": clips[1], "startFrame": 24, "endFrame": 71},
+])
+```
+
+Two things about that call, both measured and both able to waste a session:
+
+- **`endFrame` is inclusive-of-the-last-frame here** — pass `frames` rather than
+  `frames - 1` and you append nothing.
+- **Do not build a repeated clip with `CreateTimelineFromClips([clip] * n)`.** It
+  deduplicates identical MediaPoolItem references: fifteen copies produced a
+  one-copy timeline, returned a valid Timeline, and reported no error. Use
+  `AppendToTimeline` with one dict per instance, and assert the resulting frame
+  count.
+
+```python
+# 3. iterate: export, mutate outside Resolve, re-import under a NEW name
+timeline.Export(str(path), resolve.EXPORT_FCP_7_XML, resolve.EXPORT_NONE)
+...                                            # edit the XML however you like
+pool.ImportTimelineFromFile(str(path), {
+    "timelineName": f"CUT_v{n:03d}",
+    "importSourceClips": False,
+    "sourceClipsFolders": [pool.GetRootFolder()],
+})
+```
+
+```bash
+# 4. done
+python scripts/resolve_headless.py stop
+```
+
+## Rules that apply to the whole loop
+
+- **Never call `SaveProject()` without checking the project name.** On the
+  never-saved `Untitled Project` it blocks the entire application — in both
+  modes — and needs a force-kill. Use
+  `src/utils/project_cleanup.py:save_project_if_safe`.
+- **Verify structure, not return values.** Every finding above involved a call
+  that returned success. After building or importing a cut, read the item count
+  and each item's `GetLeftOffset()` back and compare against what you intended.
+- **Teardown order is `CloseProject` → `LoadProject(something named)` →
+  `DeleteProject`.** `CloseProject` is what releases the session lock, and
+  landing on the unsaveable default project is what raises the next modal.
+- Capability is identical headless, but **stability under long renders is not
+  established** — see the limits section in
+  [headless-cli.md](../reference/headless-cli.md).

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.0
 
-**Totals:** 20 missing capabilities, 13 bugs / unreliable behaviors.
+**Totals:** 21 missing capabilities, 20 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -41,6 +41,13 @@ Python bridge fabricates a callable for any attribute name (see the
 Functionality that exists in the Resolve UI but has no scripting API
 equivalent, blocking full automation.
 
+### Project.SetSetting('timelinePlaybackFrameRate')
+
+- **Object:** `Project`
+- **Behavior:** 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).
+- **Workaround / current handling:** 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
+
 ### Timeline.GetTimelineByName
 
 - **Object:** `Project`
@@ -226,9 +233,47 @@ values, or automation-hostile modal prompts.
 
 - **Object:** `ProjectManager`
 - **Signature:** `(projectName) -> bool`
-- **Behavior:** 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.
-- **Workaround / current handling:** Load/close away from the target first, then retry; use src/utils/project_cleanup.py:delete_project_safely.
-- **Tags:** unreliable-return, project, flaky
+- **Behavior:** 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. 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.
+- **Workaround / current handling:** 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
+
+### ProjectManager.GetCurrentDatabase
+
+- **Object:** `ProjectManager`
+- **Signature:** `() -> {DbType, DbName}`
+- **Behavior:** 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.
+- **Workaround / current handling:** 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
+
+### MediaPool.ImportTimelineFromFile
+
+- **Object:** `MediaPool`
+- **Signature:** `(filePath, {importOptions}) -> Timeline`
+- **Behavior:** 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.
+- **Workaround / current handling:** 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
+
+### Timeline.Export(EXPORT_FCPXML_1_10)
+
+- **Object:** `Timeline`
+- **Signature:** `(fileName, EXPORT_FCPXML_1_10, EXPORT_NONE) -> bool`
+- **Behavior:** 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.
+- **Workaround / current handling:** 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
+
+### MediaPool.CreateTimelineFromClips
+
+- **Object:** `MediaPool`
+- **Behavior:** 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.
+- **Workaround / current handling:** 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
+
+### TimelineItem.AddFusionComp / LoadFusionCompByName
+
+- **Object:** `TimelineItem (media-backed clip)`
+- **Behavior:** 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.
+- **Workaround / current handling:** 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
 
 ### Composition.Paste
 
@@ -291,3 +336,19 @@ values, or automation-hostile modal prompts.
 - **Workaround / current handling:** Normalize both arguments through the live maps before calling: src.utils.render_ids.render_format_id_from_formats and render_codec_id_from_codecs accept a description or an id and return the id.
 - **Reference:** [issue #59](https://github.com/samuelgursky/davinci-resolve-mcp/issues/59)
 - **Tags:** render, deliver, silent-failure, id-vs-label
+
+### ProjectManager.SaveProject
+
+- **Object:** `ProjectManager`
+- **Signature:** `() -> bool`
+- **Behavior:** 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.
+- **Workaround / current handling:** 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
+
+### GalleryStillAlbum.ExportStills
+
+- **Object:** `GalleryStillAlbum`
+- **Signature:** `(galleryStills, folderPath, filePrefix, format) -> bool`
+- **Behavior:** 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.
+- **Workaround / current handling:** 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

package/docs/reference/headless-capability-matrix.md

@@ -0,0 +1,56 @@
+# GUI vs headless probe matrix
+
+105 probes, 2 GUI run(s) x 2 headless run(s).
+
+| verdict | count |
+| --- | --- |
+| parity | 86 |
+| flaky | 0 |
+| hang_headless | 0 |
+| hang_gui | 0 |
+| headless_degraded | 2 |
+| gui_degraded | 0 |
+| both_hang | 0 |
+| both_failed | 14 |
+| divergent | 3 |
+| untested | 0 |
+
+## Coverage by category
+
+| category | probes | parity | hang_headless | headless_degraded | gui_degraded | divergent | untested |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| app | 8 | 6 | 0 | 0 | 0 | 0 | 0 |
+| audio | 3 | 3 | 0 | 0 | 0 | 0 | 0 |
+| color | 9 | 9 | 0 | 0 | 0 | 0 | 0 |
+| editorial | 5 | 0 | 0 | 2 | 0 | 1 | 0 |
+| fusion | 2 | 2 | 0 | 0 | 0 | 0 | 0 |
+| gallery | 4 | 3 | 0 | 0 | 0 | 0 | 0 |
+| interchange | 5 | 5 | 0 | 0 | 0 | 0 | 0 |
+| layout | 4 | 4 | 0 | 0 | 0 | 0 | 0 |
+| lifecycle | 3 | 3 | 0 | 0 | 0 | 0 | 0 |
+| longop | 4 | 1 | 0 | 0 | 0 | 0 | 0 |
+| media_pool | 8 | 5 | 0 | 0 | 0 | 0 | 0 |
+| pages | 7 | 7 | 0 | 0 | 0 | 0 | 0 |
+| project_manager | 8 | 8 | 0 | 0 | 0 | 0 | 0 |
+| project_settings | 5 | 5 | 0 | 0 | 0 | 0 | 0 |
+| projectlevel | 4 | 0 | 0 | 0 | 0 | 2 | 0 |
+| render | 6 | 6 | 0 | 0 | 0 | 0 | 0 |
+| timeline | 12 | 11 | 0 | 0 | 0 | 0 | 0 |
+| timeline_item | 8 | 8 | 0 | 0 | 0 | 0 | 0 |
+
+## Mode-dependent findings
+
+> **Re-verify every row below in isolation before believing it.** Probes run in catalogue order against one shared fixture, so a probe near the end has ~90 destructive probes' worth of accumulated state behind it, and the two modes can drift apart for reasons that have nothing to do with the mode. Measured: five findings here — nested timelines, clip linking, take selectors, multi-job queues and render presets — all reproduced as mode differences in a full sweep and all came out **identical** when re-run with `--only`. Isolation is the test:
+
+> ```
+> python scripts/mode_matrix.py run --mode gui      --out iso_gui.jsonl  --only <probe>
+> python scripts/mode_matrix.py run --mode headless --out iso_hl.jsonl   --only <probe>
+> ```
+
+| probe | verdict | GUI | headless | note |
+| --- | --- | --- | --- | --- |
+| `editorial.nested_timeline` | headless_degraded | ok: 'True/1' | raised | succeeded with a UI, failed without one |
+| `editorial.set_clips_linked` | headless_degraded | ok: True | none: None | succeeded with a UI, failed without one |
+| `editorial.take_selector` | divergent | ok: 'False/0/None/None' | ok: 'None/None/None/None' | both returned, values differ |
+| `projectlevel.multi_job_queue` | divergent | ok: '3/3' | ok: '0/0' | both returned, values differ |
+| `projectlevel.render_preset_roundtrip` | divergent | ok: 'True/True' | ok: 'None/None' | both returned, values differ |