davinci-resolve-mcp 2.69.3 → 2.70.1

package/CHANGELOG.md

@@ -2,6 +2,177 @@
 
 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.1
+
+Windows support for the free-edition in-app bridge, and the end of doctor.py's
+macOS-only path assumptions. Reported in issue #106 by @kacemmosbah8-afk.
+
+### The bug
+
+`script_targets()` in `scripts/install_resolve_bridge.py` enumerated macOS and
+Linux candidates only. There was no Windows branch at all, so the candidate list
+came back empty on every Windows machine and the installer exited with:
+
+```
+No writable DaVinci Resolve Scripts/Utility folder found. Is Resolve installed?
+```
+
+on installs where Resolve was demonstrably present. Since the in-app bridge is
+the *only* route to the free edition — external scripting is Studio-gated by
+Blackmagic — Windows free-edition users had no working path to this server at
+all. The bridge shipped in v2.68.0; it has been macOS/Linux-only that whole time.
+
+Windows now targets the two Scripts/Utility trees Blackmagic documents, per-user
+first because `%PROGRAMDATA%` typically needs an elevated prompt:
+
+- `%APPDATA%\Blackmagic Design\DaVinci Resolve\Support\Fusion\Scripts\Utility`
+- `%PROGRAMDATA%\Blackmagic Design\DaVinci Resolve\Fusion\Scripts\Utility`
+
+Three traps came out of implementing that, each now pinned by a test:
+
+- **The per-user tree carries a `Support` segment the all-users tree does not.**
+  They are not one layout under two roots; deriving either from the other lands
+  in a folder Resolve never scans.
+- **Blackmagic's own README writes the per-user root as `%APPDATA%\Roaming\...`,
+  which is wrong** — `%APPDATA%` already *is* `...\AppData\Roaming`. Transcribing
+  it verbatim yields `AppData\Roaming\Roaming\...`: a real, creatable folder that
+  is silently never read.
+- **Resolve does not create its `Fusion\Scripts` tree until a script is
+  installed**, so gating on that tree existing — or on its parent being writable
+  — skips a fresh free-edition install, the exact build the bridge exists for.
+  The candidates are gated on Resolve's product folder instead, mirroring how the
+  macOS sandbox container is handled.
+
+`install()` no longer aborts when one target is unwritable. The `%PROGRAMDATA%`
+tree needs elevation, and Windows `os.access(W_OK)` reports the read-only flag
+rather than the ACL, so it cannot be screened out in advance — without this, the
+newly added candidate would have crashed the installer on every non-elevated
+Windows account *after* it had already succeeded into the per-user tree. Skips
+are reported in `warnings`; only a clean sweep is fatal, and that error now names
+the folders and the reason instead of asking whether Resolve is installed.
+
+### The macOS framework-Python alarm was firing off macOS
+
+`python_preflight()` looked for a framework Python under `/Library/Frameworks`,
+a path that cannot exist on Windows or Linux — so it always found nothing and
+emitted the macOS remediation, telling the reporter (running a working python.org
+3.12.9) to install the Python they already had. Linux had the same false alarm.
+The check is now macOS-only. The Lua canary still ships everywhere, so a genuine
+enumeration failure stays diagnosable.
+
+### doctor.py was macOS-only too
+
+`scripts/doctor.py` hardcoded macOS defaults for `RESOLVE_APP`,
+`RESOLVE_SCRIPT_API` and `RESOLVE_SCRIPT_LIB`. Run standalone — that is, without
+the environment variables the npm/`install.py` flow injects — it reported four
+`[FAIL]` lines naming a `.app` bundle and `fusionscript.so` on a Windows 11
+machine that had neither, while `install.py` detected that same install
+correctly. Two tables describing one thing, one of them platform-blind. Linux was
+equally affected.
+
+doctor now selects per-platform candidates, and picks the first that exists so
+the reported path matches reality. macOS values are byte-identical to before.
+A new `tests/test_doctor_paths.py` drift guard asserts every path doctor names
+also appears in `install.py`'s `RESOLVE_PATHS`, so the two cannot diverge again.
+Claude Desktop's config path is now MSIX-aware on Windows as well, matching the
+issue #93 fix that `install.py` already had.
+
+### Scope — what is and is not verified
+
+The path construction is unit-tested, and a simulated Windows run exercises the
+installer end to end. **No Windows hardware has confirmed that Resolve actually
+lists the bridge from these folders.** The reporter verified the folders exist
+and are writable; issue #104 is precedent that "the folder exists" and "Resolve
+reads it" are different claims. The README and `docs/SKILL.md` say so plainly
+rather than implying Windows is a supported, tested tier.
+
+Suite: 2312 → 2336.
+
+## 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.1-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)
@@ -51,15 +51,21 @@ python scripts/install_resolve_bridge.py
 export DAVINCI_RESOLVE_BRIDGE=1      # opt-in; unset changes nothing
 ```
 
-Requires a **framework Python** (python.org). Resolve enumerates `.py` scripts
-only when it finds one — Homebrew, pyenv and conda interpreters are not
-detected, and the script silently never appears in the menu. A Lua canary is
-installed alongside so you can tell that apart from a wrong folder.
-
-Validated on free 21.0.3.7 and Studio 19.1.3.7. This is the documented in-app
-path, not a licence circumvention, but Blackmagic could close it — treat it as a
-supported-until-it-is-not tier. Loopback only, HMAC-signed requests, one-use
-nonces.
+On **macOS**, this requires a **framework Python** (python.org). Resolve
+enumerates `.py` scripts only when it finds one — Homebrew, pyenv and conda
+interpreters are not detected, and the script silently never appears in the
+menu. A Lua canary is installed alongside so you can tell that apart from a
+wrong folder.
+
+Validated on free 21.0.3.7 and Studio 19.1.3.7, both macOS. **Windows paths were
+added in v2.70.1 (issue #106) and have not yet been confirmed on Windows
+hardware** — the installer targets the `%APPDATA%` and `%PROGRAMDATA%` script
+folders Blackmagic documents, but whether Resolve lists the bridge from them is
+unverified. Reports welcome.
+
+This is the documented in-app path, not a licence circumvention, but Blackmagic
+could close it — treat it as a supported-until-it-is-not tier. Loopback only,
+HMAC-signed requests, one-use nonces.
 
 ## Local Control Panel
 

package/docs/SKILL.md

@@ -27,11 +27,17 @@ loopback listener. Install with `python scripts/install_resolve_bridge.py`, star
 it from that menu, and set `DAVINCI_RESOLVE_BRIDGE=1`. Existing tool call sites
 work unchanged. Two things to know when diagnosing it:
 
-- Resolve lists `.py` scripts only when it can find a **framework Python**
-  (python.org). Homebrew/pyenv/conda are not detected and the script simply never
-  appears, with no error. The installer preflights this and ships a Lua canary,
-  which always lists, so "Python not detected" is distinguishable from "wrong
-  folder".
+- On macOS, Resolve lists `.py` scripts only when it can find a **framework
+  Python** (python.org). Homebrew/pyenv/conda are not detected and the script
+  simply never appears, with no error. The installer preflights this and ships a
+  Lua canary, which always lists, so "Python not detected" is distinguishable
+  from "wrong folder". The preflight is macOS-only — off macOS Resolve finds
+  Python by other means, and running the check there was a false alarm (#106).
+- **Windows is unconfirmed.** The `%APPDATA%`/`%PROGRAMDATA%` script folders are
+  targeted as of v2.70.1, but no Windows machine has verified that Resolve lists
+  the bridge from them. If a user reports the menu entry missing on Windows, ask
+  whether the Lua canary lists — that separates "wrong folder" from "Python not
+  detected" there too.
 - The in-Resolve runtime is a **copy taken at install time**. After changing the
   repository, re-run the installer and then ask the running bridge to reload —
   it re-imports from disk in place, so Resolve does not need restarting.
@@ -218,6 +224,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 +1931,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).