davinci-resolve-mcp 2.104.5 → 2.104.7

package/CHANGELOG.md

@@ -2,6 +2,77 @@
 
 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.104.7
+
+The DRT import thread, chased to ground by live bisection on Studio 19.1.3.7
+— and the tool had been giving instructions that could not work.
+
+**What a .drt import actually requires, measured.** A real Resolve export
+re-imports; the same archive minus ONLY project.xml is refused; removing
+MpFolder.xml or renaming the SeqContainer path changes nothing. Tool-authored
+DRTs fail on two counts: they omit project.xml AND use a flat template
+container schema (<StartFrame>/<StartTC> elements) that Resolve never wrote —
+its native containers are blob-based Sm2TiTrack/Sm2TiVideoClip structures.
+Worse: a refused .drt import can raise a modal error dialog that BLOCKS the
+scripting call indefinitely (observed live — the call neither returns nor
+times out until a human dismisses the dialog), and .drt import names the
+timeline after the FILE, not the container's internal name — a third naming
+authority beside FCP7 (internal name) and OTIO (timelineName option). All of
+it is now a submit-tagged api_truth entry.
+
+### Fixed
+
+- `import_timeline_checked` refuses tool-authored .drt/.drp BEFORE calling
+  Resolve — the shape is detectable from the zip alone, and refusing early is
+  what prevents the scripting-blocking dialog. The error names the actual
+  cause and points at routes that work (OTIO authoring; Resolve's own .drt
+  exports) instead of the old media/sanitize misdiagnosis.
+- `import_from_drp` no longer reports success:true when every selected
+  timeline failed to import (the discarded-outcome aggregation class); a
+  partial import is labeled partial with a warning.
+- Both extractors (`import_from_drp`'s and `drt.extract_from_drp`) now carry
+  the source archive's project.xml into the extracted .drt — measured as
+  necessary. NOT yet sufficient: a .drp-sourced native container repacked
+  with its project.xml was still refused on 19.1.3.7, so extraction-based
+  import remains unreliable on this build and is documented as such.
+
+### Documented
+
+- The .prproj refusal and offline-authoring guidance no longer tell users to
+  author a 'drt' and import it — that instruction could never work; they
+  point at 'otio'/'edl'. The drt tool and drt-builder docstrings state the
+  authored template's actual role (offline/DB workflows, injection, parsing)
+  and that real-Resolve exports are the only known-importable .drt files.
+
+## What's New in v2.104.6
+
+**A correction to the v2.104.2 StartFrame fix — measured against Resolve
+itself.** SMPTE non-drop timecode counts NOMINAL frames: the fields multiply
+by the integer base (30 for 29.97, 24 for 23.976), not the exact rate.
+Measured live on Studio 19.1.3.7: a 29.97 timeline at 01:00:00:00 reads
+GetStartFrame 108000 = 3600 x 30, and a 23.976 one reads 86400 = 3600 x 24.
+Issue #168's reporter expected round(3600 x 30000/1001) = 107892 — they said
+plainly they had patched defensively without verifying Resolve — and the
+v2.104.2 fix shipped that expectation. Both the original fractional product
+and the rounded 107892 were wrong; the Python converters (which always used
+nominal) and the Node converters now agree.
+
+Three Node converters move to nominal-base counting, with drop-frame
+handling (semicolon timecodes) matching the Python formula:
+
+- `drt.author`'s SeqContainer StartFrame (01:00:00:00 at 29.97 now writes
+  108000; at 23.976, 86400)
+- `editorial.tcToFrames` — the exact-rate product undercounted NTSC
+  timecode by 0.1% (108 frames per hour), which touched every EDL/AAF
+  source/record conversion at 29.97
+- `media-inventory.tcToFrames` — whose own framesToTc was already nominal,
+  so the tc->frames->tc round trip was asymmetric at NTSC rates until now
+
+The conform fixtures are integer-rate, which is how the exact-rate
+convention survived: nothing in the suite exercised an NTSC timecode
+conversion end to end. Regression tests now pin the measured nominal values
+and a drop-frame case.
+
 ## What's New in v2.104.5
 
 The recent bug classes, generalized into guards — and the sweeps found the

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.104.5-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.104.7-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-36%20(353%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.104.5-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.104.7-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-36%20(353%20full)-blue.svg)](#服务器模式)
@@ -12,7 +12,7 @@
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> 本翻译对应 v2.104.5 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.104.7 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 33 missing capabilities, 40 bugs / unreliable behaviors.
+**Totals:** 33 missing capabilities, 41 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -526,6 +526,14 @@ values, or automation-hostile modal prompts.
 - **Reference:** [issue #171](https://github.com/samuelgursky/davinci-resolve-mcp/issues/171)
 - **Tags:** timeline, import, silent-failure, unreliable-return
 
+### MediaPool.ImportTimelineFromFile (.drt requirements and filename naming)
+
+- **Object:** `MediaPool`
+- **Signature:** `(drtPath, {importSourceClips, ...}) -> Timeline`
+- **Behavior:** Measured by bisection on Studio 19.1.3.7 against a real .drt export: (1) the archive MUST contain project.xml — the same archive minus only that entry is refused, while removing MediaPool/MpFolder.xml or renaming the SeqContainer path changes nothing; (2) the container XML must be Resolve's native blob-based schema — a syntactic SeqContainer with flat template elements is refused even beside a genuine project.xml; (3) the imported timeline is named after the FILE (real_2997.drt -> 'real_2997'), not the container's internal name — a third naming authority beside FCP7 (internal name wins) and OTIO (timelineName option wins); and (4) a refused import can raise a modal error dialog that BLOCKS the scripting call until a human dismisses it — the call neither returns nor times out.
+- **Workaround / current handling:** Import only .drt files Resolve itself exported — the sufficient set is unmapped beyond that: even a .drp-sourced native container repacked WITH its project.xml was refused (measured 19.1.3.7), so extraction-based .drt import cannot be relied on either. Name the timeline by naming the FILE. Never batch speculative .drt imports unattended — one refusal can hold the whole session hostage behind its dialog. timeline.import_timeline_checked detects the authored template shape up front and refuses with this diagnosis instead of importing; for a reliable programmatic import use OTIO or FCP7 XML.
+- **Tags:** timeline, import, silent-failure, headless
+
 ### Timeline.DeleteClips (requires the Edit page; flaky first attempt)
 
 - **Object:** `Timeline`

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.104.5"
+VERSION = "2.104.7"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.104.5",
+  "version": "2.104.7",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/resolve-advanced/server/editorial.mjs

@@ -23,10 +23,21 @@ const require = createRequire(import.meta.url);
 // ── timecode ───────────────────────────────────────────────────────────
 const TC_RE = /^(\d{2}):(\d{2}):(\d{2})[:;](\d{2,3})$/;
 export function tcToFrames(tc, fps) {
-  const m = TC_RE.exec(String(tc).trim());
+  const raw = String(tc).trim();
+  const m = TC_RE.exec(raw);
   if (!m || !fps) return null;
   const [, h, mm, s, f] = m.map(Number);
-  return Math.round((h * 3600 + mm * 60 + s) * fps) + f;
+  // SMPTE timecode counts NOMINAL frames (base 30 for 29.97, 24 for 23.976) —
+  // measured against Resolve's own GetStartFrame (Studio 19.1.3.7). The
+  // previous exact-rate product undercounted NTSC by 0.1% (108 frames/hour).
+  const nominal = Math.round(fps);
+  let frames = (h * 3600 + mm * 60 + s) * nominal + f;
+  if (raw.includes(';')) {
+    const dropped = Math.round(nominal * 0.0666666667);
+    const totalMinutes = h * 60 + mm;
+    frames -= dropped * (totalMinutes - Math.floor(totalMinutes / 10));
+  }
+  return frames;
 }
 const isTc = (t) => TC_RE.test(t);
 

package/resolve-advanced/server/media-inventory.mjs

@@ -17,10 +17,21 @@ import { probeMedia } from './ffprobe-media.mjs';
 /** "HH:MM:SS:FF" (or ';' DF) → integer frames at fps. Returns null if unparseable. */
 export function tcToFrames(tc, fps) {
   if (typeof tc !== 'string' || !fps) return null;
-  const m = /^(\d{1,2}):(\d{2}):(\d{2})[:;](\d{2,3})$/.exec(tc.trim());
+  const raw = tc.trim();
+  const m = /^(\d{1,2}):(\d{2}):(\d{2})[:;](\d{2,3})$/.exec(raw);
   if (!m) return null;
   const [, h, mm, s, f] = m.map(Number);
-  return Math.round((h * 3600 + mm * 60 + s) * fps) + f;
+  // Nominal-base counting, matching framesToTc below and Resolve's own
+  // GetStartFrame (measured, Studio 19.1.3.7) — the exact-rate product made
+  // the tc->frames->tc round trip asymmetric at NTSC rates.
+  const nominal = Math.round(fps);
+  let frames = (h * 3600 + mm * 60 + s) * nominal + f;
+  if (raw.includes(';')) {
+    const dropped = Math.round(nominal * 0.0666666667);
+    const totalMinutes = h * 60 + mm;
+    frames -= dropped * (totalMinutes - Math.floor(totalMinutes / 10));
+  }
+  return frames;
 }
 
 export function framesToTc(frames, fps) {

package/resolve-advanced/server/tools/drt.mjs

@@ -2,7 +2,12 @@
  * drt tool — DaVinci Resolve Timeline (.drt) format. All actions local/offline.
  *
  * parse — .drt/.drp path → { timelines, metadata, seqContainers }
- * author — spec → .drt bytes written to outputPath
+ * author — spec → .drt bytes written to outputPath. TEMPLATE SCHEMA: the
+ *   output serves offline/DB workflows (inject_into_drp, parsing, diffing);
+ *   Resolve's ImportTimelineFromFile REFUSES it (measured 19.1.3.7 — the
+ *   native format is blob-based with a project.xml this shape lacks). For a
+ *   file Resolve imports, author OTIO, or extract a REAL container with
+ *   extract_from_drp.
  * validate — .drt path → { valid, errors }
  * inject_into_drp — graft a .drt's SeqContainers into an existing .drp
  * extract_from_drp — pull a SeqContainer out of a .drp as a .drt
@@ -154,6 +159,14 @@ export const drtTool = {
       const xml = await drpZip.file(seqEntries[idx]).async('string');
       const out = new JSZip();
       out.file('Primary1/SeqContainer1.xml', xml);
+      // ImportTimelineFromFile refuses a .drt without project.xml (measured
+      // by bisection on Studio 19.1.3.7), so carry the source's over.
+      const projectEntry = Object.keys(drpZip.files).find(
+        (n) => n === 'project.xml' || n.endsWith('/project.xml'),
+      );
+      if (projectEntry) {
+        out.file('project.xml', await drpZip.file(projectEntry).async('string'));
+      }
       out.file(
         'metadata.json',
         JSON.stringify(

package/resolve-advanced/vendor/drp-format/__tests__/framerate-encoding.test.js

@@ -34,14 +34,31 @@ test('the three formerly-wrong table rates never reappear', () => {
   assert.notStrictEqual(encodeFrameRate(59.94), '286b55e253f9ed3f');
 });
 
-test('StartFrame is an integer at fractional rates and startFrame wins', async () => {
+test('StartFrame counts NOMINAL frames and startFrame wins', async () => {
+  // Measured against Resolve itself (Studio 19.1.3.7): 01:00:00:00 at 29.97
+  // reads GetStartFrame 108000 = 3600 x 30, and 23.976 reads 86400 = 3600 x
+  // 24 — SMPTE NDF counts by the integer base, not the exact rate. Both the
+  // pre-#168 fractional product and its first rounded fix (107892) were wrong.
   const tl = { name: 'T', videoTracks: [], audioTracks: [] };
-  const fromTc = await buildSeqContainerFile(tl, {
+  const ntsc30 = await buildSeqContainerFile(tl, {
     frameRate: 30000 / 1001, startTimecode: '01:00:00:00',
   });
-  assert.match(fromTc, /<StartFrame>107892<\/StartFrame>/);
+  assert.match(ntsc30, /<StartFrame>108000<\/StartFrame>/);
+  const ntsc24 = await buildSeqContainerFile(tl, {
+    frameRate: 24000 / 1001, startTimecode: '01:00:00:00',
+  });
+  assert.match(ntsc24, /<StartFrame>86400<\/StartFrame>/);
   const explicit = await buildSeqContainerFile(tl, {
     frameRate: 30000 / 1001, startTimecode: '01:00:00:00', startFrame: 99999,
   });
   assert.match(explicit, /<StartFrame>99999<\/StartFrame>/);
 });
+
+test('drop-frame start timecode subtracts the dropped numbers', async () => {
+  // 00:01:00;02 DF at 29.97: minute 1 drops 2 numbers -> 1800 + 2 - 2 = 1800.
+  const tl = { name: 'T', videoTracks: [], audioTracks: [] };
+  const df = await buildSeqContainerFile(tl, {
+    frameRate: 30000 / 1001, startTimecode: '00:01:00;02',
+  });
+  assert.match(df, /<StartFrame>1800<\/StartFrame>/);
+});

package/resolve-advanced/vendor/drp-format/seq-container-builder.js

@@ -363,15 +363,27 @@ function buildMarkersFieldsBlob(markers, frameRate) {
 function timecodeToFrames(timecode, fps = 24) {
   if (!timecode || typeof timecode !== 'string') return 0;
 
-  const parts = timecode.split(':').map(Number);
-  if (parts.length !== 4) return 0;
+  const dropFrame = timecode.includes(';');
+  const parts = timecode.replace(/;/g, ':').split(':').map(Number);
+  if (parts.length !== 4 || parts.some(Number.isNaN)) return 0;
 
   const [hh, mm, ss, ff] = parts;
-  // A frame index is an integer. At fractional rates the seconds product is
-  // fractional (3600 x 30000/1001 = 107892.107...), and writing it raw put a
-  // fractional <StartFrame> in the XML (issue #168). Non-drop convention:
-  // round the seconds part, then add the frame component.
-  return Math.round(hh * 3600 * fps + mm * 60 * fps + ss * fps) + ff;
+  // SMPTE timecode counts NOMINAL frames: the fields multiply by the integer
+  // base (30 for 29.97, 24 for 23.976), not the exact rate. Measured against
+  // Resolve itself (Studio 19.1.3.7): a 29.97 timeline at 01:00:00:00 reads
+  // GetStartFrame 108000 = 3600 x 30, and a 23.976 one reads 86400 = 3600 x
+  // 24. Both the pre-#168 exact-rate product (107892.107...) and its rounded
+  // fix (107892) were wrong; nominal is what Resolve stores.
+  const nominal = Math.round(fps);
+  let frames = (hh * 3600 + mm * 60 + ss) * nominal + ff;
+  if (dropFrame) {
+    // Drop-frame skips 2 (or 4 at 59.94) TC numbers per minute except every
+    // tenth minute — same formula as the Python _timecode_to_frame_id.
+    const dropped = Math.round(nominal * 0.0666666667);
+    const totalMinutes = hh * 60 + mm;
+    frames -= dropped * (totalMinutes - Math.floor(totalMinutes / 10));
+  }
+  return frames;
 }
 
 // =============================================================================

package/resolve-advanced/vendor/drt-format/drt-builder.js

@@ -1,9 +1,14 @@
 /**
  * DRT builder — package a timeline-only Resolve archive.
  *
- * DRT and DRP share the SeqContainer/MpFolder schema; the only on-disk
- * difference is that DRT has no project.xml. This module reuses
- * drp-format's packageFullDRP with includeProjectXml: false.
+ * DRT and DRP share the SeqContainer/MpFolder schema. NOTE (measured on
+ * Studio 19.1.3.7): real Resolve .drt exports DO include a project.xml, and
+ * ImportTimelineFromFile refuses archives without one — and refuses this
+ * module's template-schema containers regardless (Resolve's native container
+ * is blob-based Sm2TiTrack/Sm2TiVideoClip, not the flat elements written
+ * here). buildDRT output therefore serves offline/DB workflows (injection,
+ * parsing, diffing), not direct live import. This module reuses drp-format's
+ * packageFullDRP with includeProjectXml: false.
  *
  * Spec shape — same as buildDRP minus the project shell:
  *   {

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.104.5"
+VERSION = "2.104.7"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 353-tool granular server instead
 """
 
-VERSION = "2.104.5"
+VERSION = "2.104.7"
 
 import base64
 import os
@@ -624,8 +624,10 @@ reverse-subclip repair, lineage, and grade tracing with no Resolve open.
 
 - Live: timeline probe_timeline_structure / detect_gaps_overlaps /
   source_range_report / conform_boundary_report; export_timeline_checked /
-  import_timeline_checked (drt is the only lossless project-native round-trip;
-  EDL/FCPXML drop relationships); detect_missing_media -> build_relink_plan
+  import_timeline_checked (a REAL-Resolve .drt — exported by Resolve or pulled
+  out with drt.extract_from_drp — is the only lossless project-native
+  round-trip; tool-AUTHORED .drt files use a template schema Resolve's import
+  refuses; EDL/FCPXML drop relationships); detect_missing_media -> build_relink_plan
   (read-only, bounded) -> media_pool.safe_relink with approved paths only.
 - XML import via the scripting API goes OFFLINE (missing-media/generators abort);
   use import_timeline_checked with media sanitize (FCP7/FCPXML), then exact-path
@@ -7016,11 +7018,14 @@ _PRPROJ_REFUSAL = (
     "XML, not an interchange). Two offline routes, no Premiere needed: (1) read it with the "
     "advanced MCP — editorial.list_sequences / editorial.parse_interchange (format 'prproj'); "
     "(2) convert it to an importable interchange — editorial.convert_to_interchange "
-    "(target 'otio'|'edl'|'drt') — then import that here with import_timeline_checked. "
+    "(target 'otio'|'edl') — then import that here with import_timeline_checked. "
     "Editorial timing/cuts/transitions carry over; per-clip effects/Lumetri color do not. "
-    "Speed/reverse carry on 'otio' and 'edl' ONLY — the DRT clip schema has no per-clip "
-    "speed field, so 'drt' flattens every retime to 100% forward and reports them in "
-    "`flattened`. Prefer 'otio' or 'edl' for a cut that carries retimes. "
+    "Speed/reverse carry on 'otio' and 'edl' ONLY. Do NOT pick target 'drt' for a live "
+    "import: tool-AUTHORED .drt files use a template schema that "
+    "ImportTimelineFromFile refuses (measured on 19.1.3.7 — Resolve's native "
+    "container format is blob-based and includes a project.xml the authored "
+    "shape lacks); authored DRTs are for offline/DB workflows, and 'drt' also "
+    "flattens every retime to 100% forward (reported in `flattened`). "
     "Alternatively export FCP7 XML / AAF / FCPXML from Premiere and conform that."
 )
 
@@ -7071,6 +7076,33 @@ def _rewrite_fcp7_sequence_name(xml_path: str, new_name: str):
     return out_path, True, None
 
 
+def _drt_looks_tool_authored(path: str) -> Optional[str]:
+    """Name the tell when a .drt/.drp is the authored TEMPLATE shape, else None.
+
+    Real Resolve archives carry a project.xml and blob-based SeqContainers
+    (Sm2TiTrack/FieldsBlob children, clip <Start> elements). The tool-authored
+    template instead writes flat container-level <StartFrame>/<StartTC>
+    elements and omits project.xml — and ImportTimelineFromFile refuses both
+    of those (measured: a real export re-imports; the same archive minus
+    project.xml, or with an authored container, does not).
+    """
+    import zipfile
+    try:
+        with zipfile.ZipFile(path) as zf:
+            names = zf.namelist()
+            has_project_xml = any(n == "project.xml" or n.endswith("/project.xml") for n in names)
+            for n in names:
+                if _SEQ_CONTAINER_RE.search(n or "") and n.endswith(".xml"):
+                    head = zf.read(n)[:4096].decode("utf-8", "replace")
+                    if "<StartFrame>" in head or "<StartTC>" in head:
+                        return "flat container-level <StartFrame>/<StartTC> elements"
+            if not has_project_xml:
+                return "no project.xml in the archive"
+    except Exception:
+        return None
+    return None
+
+
 def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
     path = p.get("path")
     if not path:
@@ -7080,6 +7112,31 @@ def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
     ext = os.path.splitext(path)[1].lower()
     if ext == ".prproj":
         return _err(_PRPROJ_REFUSAL, category="invalid_input")
+    if ext in {".drt", ".drp"}:
+        # Refuse BEFORE calling Resolve: a refused .drt import can raise a
+        # modal error dialog that blocks the scripting call indefinitely
+        # (measured live — the call neither returns nor times out until a
+        # human dismisses the dialog), so a post-failure diagnosis may never
+        # run. The authored template shape is detectable from the zip alone.
+        authored_shape = _drt_looks_tool_authored(path)
+        if authored_shape:
+            return _err(
+                f"This {ext} carries the tool-AUTHORED template schema "
+                f"({authored_shape}), which Resolve's ImportTimelineFromFile "
+                "refuses — the native format is blob-based and includes a "
+                "project.xml (measured on Studio 19.1.3.7). Worse, the refusal "
+                "raises a modal dialog that blocks all scripting until a human "
+                "dismisses it, so this import is not attempted at all.",
+                category="invalid_input",
+                remediation=(
+                    "Authored DRTs serve offline/DB workflows, not live import. "
+                    "For a live import, author OTIO instead "
+                    "(editorial.convert_to_interchange target 'otio' imports "
+                    "cleanly), or import a REAL Resolve .drt — one Resolve "
+                    "exported, or one pulled from a .drp with "
+                    "drt.extract_from_drp."
+                ),
+            )
     # ImportTimelineFromFile silently no-ops on the never-saved default project: it returns
     # nothing, creates no timeline, and reports no cause. The generic "Resolve created no
     # timeline" error that came back instead sent people to source-clip resolution and
@@ -7379,13 +7436,26 @@ def _drp_seq_containers(zf) -> List[Dict[str, Any]]:
 
 
 def _extract_seqcontainer_from_drp(drp_path: str, seq_entry: str, out_path: str) -> None:
-    """Write a minimal .drt (zip) holding one SeqContainer as Primary1/SeqContainer1.xml."""
+    """Write a .drt (zip) holding one SeqContainer plus the source's project.xml.
+
+    ImportTimelineFromFile refuses a .drt without project.xml (measured by
+    bisection on Studio 19.1.3.7: a real export minus only project.xml is
+    refused; project.xml + container with no MpFolder imports). The source
+    .drp/.drt carries one — copy it, or the extract cannot import.
+    """
     import zipfile
 
     with zipfile.ZipFile(drp_path, "r") as zf:
         xml = zf.read(seq_entry)
+        project_xml = None
+        for candidate in zf.namelist():
+            if candidate == "project.xml" or candidate.endswith("/project.xml"):
+                project_xml = zf.read(candidate)
+                break
     with zipfile.ZipFile(out_path, "w", zipfile.ZIP_DEFLATED) as out:
         out.writestr("Primary1/SeqContainer1.xml", xml)
+        if project_xml is not None:
+            out.writestr("project.xml", project_xml)
         out.writestr(
             "metadata.json",
             json.dumps(
@@ -7494,7 +7564,10 @@ def _import_from_drp(proj, mp, p: Dict[str, Any]):
             imported_count += 1
         results.append(entry)
 
-    return _ok(
+    # Top-level success must reflect the rows: _ok() over a result list whose
+    # every import failed read as a successful call (the #161 aggregation
+    # class — the wrapper reported what it meant to do, not what happened).
+    out = _ok(
         drpPath=drp_path,
         selected=len(selected),
         imported=imported_count,
@@ -7502,6 +7575,19 @@ def _import_from_drp(proj, mp, p: Dict[str, Any]):
         results=results,
         dry_run=bool(p.get("dry_run")),
     )
+    if not p.get("dry_run") and selected and imported_count == 0:
+        out["success"] = False
+        out["error"] = (
+            f"None of the {len(selected)} selected timeline(s) imported — "
+            "see results[].error for each cause."
+        )
+    elif not p.get("dry_run") and imported_count < len(selected):
+        out["partial"] = True
+        out["warning"] = (
+            f"{imported_count} of {len(selected)} selected timeline(s) "
+            "imported; see results[].error for the failures."
+        )
+    return out
 
 
 def _timeline_by_selector(proj, p: Dict[str, Any], *, prefix: str):
@@ -23761,7 +23847,12 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
         metric; a conflicting relink is VETOED — reverted and reported under
         `sanitize.flagged` for human review, never silently applied. verify_threshold
         (default 0.90) sets the structural-match bar.
-      import_from_drp(drpPath, timelineNames?|timelineIndexes?, import_source_clips?, dry_run?) -> {success, selected, imported, available, results}
+      import_from_drp(drpPath, timelineNames?|timelineIndexes?, import_source_clips?, dry_run?) -> {success, selected, imported, available, results, partial?}
+        CAVEAT (measured 19.1.3.7): Resolve refuses extracted containers even
+        repacked with the source's project.xml — the sufficient import set
+        beyond Resolve's own .drt exports is unmapped, so expect failures on
+        this build and read results[].error; success reflects the rows. For a
+        reliable programmatic import use OTIO or FCP7 XML.
         Extract chosen timelines from a .drp (offline zip surgery → temp .drt each) and
         import each into the running Resolve. Omit the selector to import ALL. Enumerate
         first with the advanced MCP drt.list_sequences / editorial.list_sequences to get

package/src/utils/api_truth.py

@@ -1879,6 +1879,39 @@ API_TRUTH: List[Dict[str, Any]] = [
         "submit": "bug",
         "issue": 171,
     },
+    {
+        "symbol": "MediaPool.ImportTimelineFromFile (.drt requirements and filename naming)",
+        "object": "MediaPool",
+        "signature": "(drtPath, {importSourceClips, ...}) -> Timeline",
+        "reality": "Measured by bisection on Studio 19.1.3.7 against a real "
+                   ".drt export: (1) the archive MUST contain project.xml — "
+                   "the same archive minus only that entry is refused, while "
+                   "removing MediaPool/MpFolder.xml or renaming the "
+                   "SeqContainer path changes nothing; (2) the container XML "
+                   "must be Resolve's native blob-based schema — a syntactic "
+                   "SeqContainer with flat template elements is refused even "
+                   "beside a genuine project.xml; (3) the imported timeline is "
+                   "named after the FILE (real_2997.drt -> 'real_2997'), not "
+                   "the container's internal name — a third naming authority "
+                   "beside FCP7 (internal name wins) and OTIO (timelineName "
+                   "option wins); and (4) a refused import can raise a modal "
+                   "error dialog that BLOCKS the scripting call until a human "
+                   "dismisses it — the call neither returns nor times out.",
+        "recommended": "Import only .drt files Resolve itself exported — "
+                       "the sufficient set is unmapped beyond that: even a "
+                       ".drp-sourced native container repacked WITH its "
+                       "project.xml was refused (measured 19.1.3.7), so "
+                       "extraction-based .drt import cannot be relied on "
+                       "either. Name the timeline by naming the FILE. Never "
+                       "batch speculative .drt imports unattended — one "
+                       "refusal can hold the whole session hostage behind "
+                       "its dialog. timeline.import_timeline_checked detects "
+                       "the authored template shape up front and refuses "
+                       "with this diagnosis instead of importing; for a "
+                       "reliable programmatic import use OTIO or FCP7 XML.",
+        "tags": ["timeline", "import", "silent-failure", "headless"],
+        "submit": "bug",
+    },
     {
         "symbol": "MediaPool.AppendToTimeline clipInfo recordFrame (timeline-absolute origin)",
         "object": "MediaPool",