davinci-resolve-mcp 2.104.6 → 2.104.8

package/CHANGELOG.md

@@ -2,6 +2,82 @@
 
 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.8
+
+More laps: the aggregation class swept to completion, and the dependency
+stack brought to zero known vulnerabilities.
+
+**Four more envelope lies fixed.** An AST sweep for per-op result lists under
+success-shaped envelopes (the class import_from_drp exposed) found four bulk
+tools whose top level ignored their rows: `bulk_set_title_text`,
+`fusion_comp.bulk_set_expressions`, and `bulk_set_inputs` returned bare
+{results, op_count} — all-failed and all-succeeded calls indistinguishable
+without reading every row — and `fusion_comp.add_mask` hard-coded
+success:true over failable input writes, so a mask whose every parameter
+failed to apply read as configured while sitting default-shaped on the clip.
+All four now report success/succeeded/failed with partial warnings, through
+one shared summarizer. Also swept and clean: flow-prescribing remediation
+texts (every named action exists), absolute-belief comments in tests and
+source, and the Python tree for further aggregation suspects (the remaining
+hits are read-only listers).
+
+**Dependency stack: 15 advisories to zero.** `npm audit fix` cleared the
+non-breaking set (hono, fast-xml-parser, fast-uri, ip-address, js-yaml and
+friends); adm-zip moved to 0.6.0; the `uuid` dependency is GONE (three call
+sites now use Node's built-in crypto.randomUUID); and sharp moved to 0.35.4,
+which clears four libvips CVEs in the image-decode paths that media QC feeds
+untrusted files into.
+
+**Node floor: >=20.9 (warn-don't-block).** sharp 0.35 requires Node 20.9+,
+and Node 18 has been end-of-life since April 2025 — on an 18.20 interpreter
+npm silently produced a BROKEN install (engines-skipped platform binding,
+"up to date", no sharp module, 57 tests gone from the count). Both
+package.json engines now say >=20.9, which warns older interpreters without
+blocking, matching the Python floor policy. CI publishes on Node 24; the
+full Node suite runs green on 20.19 (823 tests, sharp included).
+
+## 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

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.104.6-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.104.8-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.6-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.104.8-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.6 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.104.8 版 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.6"
+VERSION = "2.104.8"
 # 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.6",
+  "version": "2.104.8",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",
@@ -66,7 +66,7 @@
     "post-production"
   ],
   "engines": {
-    "node": ">=18.17"
+    "node": ">=20.9"
   },
   "publishConfig": {
     "access": "public"

package/resolve-advanced/package.json

@@ -3,9 +3,9 @@
   "version": "0.0.0-dev",
   "private": true,
   "license": "MIT",
-  "description": "Beyond-the-API DaVinci Resolve MCP — offline .drp/.drt/.drx authoring/editing. Sibling Node server to the Python davinci-resolve-mcp. Dev-local package.json; deps promote to the repo root at packaging.",
-  "comment_commonjs": "Intentionally NO \"type\": \"module\" — the vendored libs are CommonJS (require()). The repo root is type:module, so this nested manifest scopes resolve-advanced/**/*.js back to CommonJS.",
-  "comment_exports": "Public library surface so a downstream consumer can import the codec/grading/pipeline API, not just spawn the MCP bin. `.` = the lib barrel; `./mcp` = the stdio server entry. Still private:true — publish name/registry + un-privating are a parked decision.",
+  "description": "Beyond-the-API DaVinci Resolve MCP \u2014 offline .drp/.drt/.drx authoring/editing. Sibling Node server to the Python davinci-resolve-mcp. Dev-local package.json; deps promote to the repo root at packaging.",
+  "comment_commonjs": "Intentionally NO \"type\": \"module\" \u2014 the vendored libs are CommonJS (require()). The repo root is type:module, so this nested manifest scopes resolve-advanced/**/*.js back to CommonJS.",
+  "comment_exports": "Public library surface so a downstream consumer can import the codec/grading/pipeline API, not just spawn the MCP bin. `.` = the lib barrel; `./mcp` = the stdio server entry. Still private:true \u2014 publish name/registry + un-privating are a parked decision.",
   "main": "./server/lib.mjs",
   "exports": {
     ".": "./server/lib.mjs",
@@ -20,11 +20,10 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "adm-zip": "^0.5.16",
+    "adm-zip": "^0.6.0",
     "fast-xml-parser": "^5.7.3",
     "fzstd": "^0.1.1",
     "jszip": "^3.10.1",
-    "uuid": "^9.0.0",
     "zod": "^3.25.76",
     "zstd-codec": "^0.1.5"
   },
@@ -32,10 +31,10 @@
     "better-sqlite3": "^11.10.0",
     "js-yaml": "^4.3.0",
     "pg": "^8.22.0",
-    "sharp": "^0.33.0"
+    "sharp": "^0.35.4"
   },
   "peerDependenciesMeta": {
-    "_comment": "audio (split/trim/convert) + conform frame ops need system ffmpeg/ffprobe on PATH (NOT bundled — FFmpeg binaries are GPL; this package stays MIT). Install ffmpeg yourself: brew install ffmpeg."
+    "_comment": "audio (split/trim/convert) + conform frame ops need system ffmpeg/ffprobe on PATH (NOT bundled \u2014 FFmpeg binaries are GPL; this package stays MIT). Install ffmpeg yourself: brew install ffmpeg."
   },
   "scripts": {
     "test": "node --test vendor/drp-format/__tests__/*.test.js vendor/drt-format/__tests__/*.test.js vendor/drx-codec/__tests__/*.test.js test/*.test.mjs",
@@ -43,7 +42,7 @@
     "test:server": "node --test test/*.test.mjs"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.9"
   },
   "devDependencies": {
     "prettier": "^3.9.4"

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/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/resolve-advanced/vendor/drx-codec/drx-generator.js

@@ -34,7 +34,7 @@ try {
 } catch {
   ZstdCodec = null;
 }
-const { v4: uuidv4 } = require('uuid');
+const { randomUUID: uuidv4 } = require('node:crypto');
 
 // Import shared DRX parameter library
 const drxParams = require('../drx-parameters');
@@ -1859,7 +1859,7 @@ async function generateMultiNodeDRX(nodes, connections, metadata = {}) {
   const bodyHex = body.toString('hex');
 
   // Generate UUIDs
-  const { v4: uuidv4 } = require('uuid');
+  const { randomUUID: uuidv4 } = require('node:crypto');
   const stillId = uuidv4();
   const clipVersionId = uuidv4();
 
@@ -1873,7 +1873,7 @@ async function generateMultiNodeDRX(nodes, connections, metadata = {}) {
  ${pTrackVerXml}`;
   } else {
     // Generate default pTrackVer body
-    const trackVersionId = require('uuid').v4();
+    const trackVersionId = require('node:crypto').randomUUID();
     const trackBodyHex = await generatePTrackVerBody(width, height);
     pTrackVerSection = `
  <pTrackVer>

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.104.6"
+VERSION = "2.104.8"
 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.6"
+VERSION = "2.104.8"
 
 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
@@ -5785,6 +5787,35 @@ def _timeline_set_title_text(tl, p: Dict[str, Any]) -> Dict[str, Any]:
     }
 
 
+def _summarize_bulk_results(results: List[Dict[str, Any]], op_count: int) -> Dict[str, Any]:
+    """Envelope for per-op result lists whose top level must reflect the rows.
+
+    A bare {results, op_count} envelope made all-failed and all-succeeded
+    calls indistinguishable to a caller reading only the top level (the same
+    aggregation class as import_from_drp reporting success over failed rows).
+    """
+    succeeded = sum(1 for row in results if row.get("success"))
+    failed = op_count - succeeded
+    out: Dict[str, Any] = {
+        "results": results,
+        "op_count": op_count,
+        "succeeded": succeeded,
+        "failed": failed,
+        "success": failed == 0,
+    }
+    if failed and succeeded:
+        out["partial"] = True
+        out["warning"] = (
+            f"{succeeded} of {op_count} ops succeeded; see results[].error "
+            "for the failures."
+        )
+    elif failed:
+        out["error"] = (
+            f"All {op_count} op(s) failed — see results[].error for each cause."
+        )
+    return out
+
+
 def _timeline_bulk_set_title_text(tl, p: Dict[str, Any]) -> Dict[str, Any]:
     ops = p.get("ops")
     if not isinstance(ops, list) or not ops:
@@ -5799,7 +5830,7 @@ def _timeline_bulk_set_title_text(tl, p: Dict[str, Any]) -> Dict[str, Any]:
         out = _timeline_set_title_text(tl, merged)
         out["index"] = index
         results.append(out)
-    return {"results": results, "op_count": len(ops)}
+    return _summarize_bulk_results(results, len(ops))
 
 
 _TIMELINE_CONFORM_KERNEL_ACTIONS = [
@@ -7016,11 +7047,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 +7105,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 +7141,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 +7465,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 +7593,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 +7604,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 +23876,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
@@ -27494,7 +27614,7 @@ def _fusion_comp_bulk_set_expressions(p: Dict[str, Any]) -> Dict[str, Any]:
             results.append({"index": index, "error": error_message})
         elif keep_undo:
             results.append({"index": index, "success": True, "expression": op["expression"]})
-    return {"results": results, "op_count": len(ops)}
+    return _summarize_bulk_results(results, len(ops))
 
 
 def _fusion_probe_group_published_inputs(comp, p: Dict[str, Any]) -> Dict[str, Any]:
@@ -27619,7 +27739,7 @@ def _fusion_comp_bulk_set_inputs(p: Dict[str, Any]) -> Dict[str, Any]:
         elif keep_undo:
             results.append({"index": index, "success": True})
 
-    return {"results": results, "op_count": len(ops)}
+    return _summarize_bulk_results(results, len(ops))
 
 
 _FUSION_KERNEL_ACTIONS = [
@@ -28024,12 +28144,28 @@ def _fusion_add_mask(comp, p: Dict[str, Any]) -> Dict[str, Any]:
             rec["error"] = str(exc)
         results.append(rec)
 
+    failed_inputs = [row for row in results if not row.get("success")]
     out: Dict[str, Any] = {
-        "success": True,
+        # The tool was added either way, but success must mean "the mask that
+        # was asked for": an unconditional True over failed input rows left a
+        # default-shaped mask reading as configured.
+        "success": not failed_inputs or len(failed_inputs) < len(results),
         "tool_name": tool_name,
         "tool_type": attrs.get("TOOLS_RegID", tool_type),
         "inputs_set": results,
     }
+    if failed_inputs and len(failed_inputs) == len(results):
+        out["success"] = False
+        out["error"] = (
+            f"The {tool_name} tool was added but all {len(results)} input "
+            "write(s) failed — the mask is default-shaped; see inputs_set[].error."
+        )
+    elif failed_inputs:
+        out["partial"] = True
+        out["warning"] = (
+            f"{len(failed_inputs)} of {len(results)} mask input(s) failed to "
+            "apply; see inputs_set[].error."
+        )
 
     # Optional wiring: connect this mask into a tool's mask input.
     connect_to = p.get("connect_to")
@@ -28051,6 +28187,12 @@ def _fusion_add_mask(comp, p: Dict[str, Any]) -> Dict[str, Any]:
                 }
             except Exception as exc:
                 out["connection"] = {"success": False, "error": str(exc)}
+        if isinstance(out.get("connection"), dict) and not out["connection"].get("success"):
+            out["success"] = False
+            out.setdefault(
+                "error",
+                "The mask was added but could not be connected — see `connection`.",
+            )
     return out
 
 

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",