davinci-resolve-mcp 2.213.3 → 2.214.0

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 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.214.0 — color_trace reads exported .drp files, and the trace is live-validated
+
+### Added
+
+- **`color_trace plan` takes `sourceDrp` / `targetDrp`.** The v2.213.0 matcher
+  read both timelines from `Project.db`, which a Postgres, network or cloud
+  library does not have. `ProjectManager.ExportProject` works on any project by
+  name without loading it, and the `.drp` it writes carries every field the
+  matcher keys on — name, record start, duration, in-point, media path, reel,
+  media ref, and the active grade version's body inline — so either side of a
+  plan can now be an exported `.drp`. The reader
+  (`resolve-advanced/server/drp-timeline-clips.mjs`) resolves a timeline name
+  through `MediaPool/**/MpFolder.xml` to its sequence id and reads the
+  `SeqContainer/<uuid>.xml` whose tracks reference it; it returns the same row
+  shape as the DB reader, active-version-first.
+- **`apply_trace_plan` writes its full report to a file.** A real conform is
+  800+ plan rows, and the first live run's per-clip tables (290k characters)
+  blew past what a tool response can carry. The full tables now go to
+  `report_path` (default `dry-run-report.json` / `apply-report.json` next to
+  the plan); the response keeps the summary, an `attention` list (ties,
+  partial overlaps, every skip that is not bulk `unmatched` /
+  `no-source-grade`) and the first `max_rows` rows (default 40, `verbose:
+  true` for everything). `failed` is never truncated.
+
+### Live-validated (Resolve Studio 19.1.3.7, Postgres library)
+
+- Source: a 659-clip picture-lock turnover with 263 graded clips. Target: an
+  878-clip conform of the next version, media on a different volume, reels
+  mostly empty, clip names carrying an extension the source names lack.
+- Plan: 613 matched (583 by file name + source-range overlap, 3 by reel, 27 by
+  name only), 265 unmatched (reference masters, offline screeners, clips not
+  in the source), 266 with a grade to carry. The 12 name-only matches sat
+  below the default 0.8 gate and were skipped.
+- Apply: 254 of 254 resolved clips graded, 0 failures, timeline archived as
+  `_archived_v01` first, a local version `traced V07 Sizing` added per clip.
+  Six sampled clips read back with exactly the node count their `.drx`
+  decodes to (9, 9, 8, 9, 5, 1) and the source's tools (Reduce Noise, a film
+  LUT, Halation, Glow, HDR wheels, hue curves).
+- Reported for review, not hidden: 70 applied clips span more source range
+  than the graded section they matched (lowest overlap 14 percent), 2 applied
+  on a tie between identical candidates.
+
+### Notes
+
+- Reading the Postgres library directly was not attempted: Resolve keeps the
+  connection password in plain text in `dblist.conf`, and the `.drp` route
+  needs no credential at all. `resolve-advanced/README.md` still says
+  `project_read` handles "SQLite or Postgres"; only SQLite is implemented.
+
 ## What's New in v2.213.3 — the capture docstring says what is restored and what is only reset
 
 ### Documentation

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.213.3-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.214.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-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.213.3-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.214.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-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.213.3 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.214.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/docs/kernels/color-grade-kernel.md

@@ -33,7 +33,7 @@ All actions are exposed through `timeline_item_color`.
 | `safe_set_cdl` | Validate and normalize CDL payloads before calling `SetCDL`; supports dry run. |
 | `safe_copy_grade` | Resolve target timeline item IDs before calling `CopyGrades`; supports dry run. |
 | `safe_apply_drx` | Validate DRX file existence and temp-path guard before calling `ApplyGradeFromDRX`. |
-| `apply_trace_plan` | Apply the advanced server's `color_trace` plan to the current timeline: resolve each entry to a live clip by (name, record start, duration), dry-run resolution table, one confirm_token for the batch, timeline archived first, then `ApplyGradeFromDRX` per clip; `version_name` adds a local version per clip so the previous grade survives. Unresolved entries are reported, never guessed. |
+| `apply_trace_plan` | Apply the advanced server's `color_trace` plan to the current timeline: resolve each entry to a live clip by (name, record start, duration), dry-run resolution table, one confirm_token for the batch, timeline archived first, then `ApplyGradeFromDRX` per clip; `version_name` adds a local version per clip so the previous grade survives. Unresolved entries are reported, never guessed; the full per-clip tables go to `report_path`, the response carries the summary, an `attention` list and the first `max_rows` rows. |
 | `safe_export_lut` | Resolve LUT export type aliases and require temp output paths by default. |
 | `grade_version_snapshot` | Read current, local, and remote grade version names. |
 | `grade_version_restore` | Safely load a named local/remote version after verifying it exists. |

package/docs/kernels/timeline-conform-interchange-kernel.md

@@ -139,7 +139,8 @@ files and the project DB.
   compared clear of its transition windows, and Resolve's own FCP7 export
   ingests with its `-1` edges resolved and its missing ticks tolerated).
 - **`color_trace`** — cross-project clip matching on media identity (pool id /
-  file path / reel / file name + source-range overlap; names last) → a trace
+  file path / reel / file name + source-range overlap; names last), from a
+  `Project.db` or an exported `.drp` (the Postgres/network-library route) → a trace
   plan with a lossless `.drx` per graded match and a `plan.json`. The live half
   is `timeline_item_color.apply_trace_plan` (dry-run resolution table → one
   confirm_token → ApplyGradeFromDRX per resolved clip, timeline archived first).

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.213.3"
+VERSION = "2.214.0"
 # 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.213.3",
+  "version": "2.214.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/resolve-advanced/README.md

@@ -86,9 +86,13 @@ Each dispatches on an `action`. Highlights:
   timeline (any two projects, from `Project.db`, read-only, no Resolve) on **media identity** —
   pool item id / file path / reel / file name plus source-range overlap, so a stringout cut into
   graded sections, a renamed clip, or relinked media still traces; clip names are the last resort.
-  Emits one lossless `.drx` per graded match plus a `plan.json`; the live server's
+  Either side is a `Project.db` (`…ProjectDb` / `…ProjectName`) **or an exported `.drp`**
+  (`sourceDrp` / `targetDrp`) — the `.drp` route is how a Postgres / network / cloud library
+  is read, since `ProjectManager.ExportProject` works on any project by name without loading
+  it. Emits one lossless `.drx` per graded match plus a `plan.json`; the live server's
   `timeline_item_color.apply_trace_plan` applies it (dry-run resolution table, one
-  confirm_token for the batch, timeline archived first).
+  confirm_token for the batch, timeline archived first, full per-clip report to a file).
+  Live-validated 2026-09-08: 878-clip conform, 254 grades carried, 0 failures.
 - **`project_read` / `project_db`** — read/patch the Resolve project DB (SQLite or Postgres).
   Includes `list_subtitle_styles` / `set_subtitle_style` — caption font family/size/weight/italic
   and normalised position, which the scripting API cannot touch at all. Whole-track (not

package/resolve-advanced/server/drp-timeline-clips.mjs

@@ -0,0 +1,155 @@
+/**
+ * Timeline clips from an exported .drp — the DB-agnostic twin of
+ * project_read.readTimelineClips. A Postgres / cloud / network library has no
+ * Project.db to open, but ProjectManager.ExportProject works on ANY project by
+ * name without loading it, and the .drp it writes carries every field the
+ * color_trace matcher keys on:
+ *
+ *   MediaPool/**\/MpFolder.xml   <Sm2Timeline><Name>…</Name><Sequence><Sm2Sequence DbId=SEQ>
+ *   SeqContainer/<uuid>.xml     <Sm2TiTrack><Type>0</Type><Sequence>SEQ</Sequence><Items>
+ *                                 <Sm2TiVideoClip DbId=…> Name/Start/Duration/In/MediaRef/
+ *                                 MediaFilePath/MediaReelNumber/pLmVerTable(pActive → LmVersion Body)
+ *
+ * Measured on Resolve 19.1.3.7 exports (DbPrjVer 14): one container per
+ * timeline, tracks reference their sequence by id, the grade body sits inline
+ * in the clip's version table. Row shape matches readTimelineClips so the
+ * matcher cannot tell the two sources apart.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const scalar = (xml, tag) => {
+  const m = xml.match(new RegExp(`<${tag}>([^<]*)</${tag}>`));
+  return m ? m[1].trim() : null;
+};
+const blank = (xml, tag) => new RegExp(`<${tag}/>`).test(xml);
+
+/** Walk every `<Sm2Timeline>` in the media-pool folder XMLs → [{name, timelineId, sequenceId}]. */
+export function listDrpTimelines(mpFolderXmls) {
+  const out = [];
+  for (const xml of mpFolderXmls) {
+    for (const m of xml.matchAll(/<Sm2Timeline DbId="([^"]+)">([\s\S]*?)<\/Sm2Timeline>/g)) {
+      const body = m[2];
+      const name = scalar(body, 'Name');
+      const seq = body.match(/<Sm2Sequence DbId="([^"]+)"/);
+      out.push({ name, timelineId: m[1], sequenceId: seq ? seq[1] : null });
+    }
+  }
+  return out;
+}
+
+/** Decode `<In>` the way project_read does: plain decimal, or the FIRST field of a
+ * pipe-joined composite ('47|0000eaffffffef3f'). Anything else → null, never 0. */
+function decodeIn(v) {
+  if (v === null || v === '') return null;
+  const head = String(v).split('|', 1)[0];
+  return /^-?\d+(\.\d+)?$/.test(head) ? Number(head) : null;
+}
+
+/** Active grade of one clip element: {gradeVersion, gradeBody} or nulls.
+ * pActive names the active version; fall back to the first corrected one. */
+function activeGrade(clipXml) {
+  const vt = clipXml.match(/<pLmVerTable>([\s\S]*?)<\/pLmVerTable>/);
+  if (!vt) return { gradeVersion: null, gradeBody: null };
+  const active = scalar(vt[1], 'pActive');
+  const versions = [...vt[1].matchAll(/<ListMgt::LmVersion DbId="([^"]+)">([\s\S]*?)<\/ListMgt::LmVersion>/g)].map((m) => {
+    const body = m[2];
+    const bodyHex = (body.match(/<Body>([0-9a-fA-F\s]*)<\/Body>/) || [null, ''])[1];
+    return {
+      id: m[1],
+      name: scalar(body, 'Name'),
+      corrected: /<HasCorrection>true<\/HasCorrection>/.test(body),
+      bodyHex: bodyHex ? bodyHex.replace(/[^0-9a-fA-F]/g, '').toLowerCase() : '',
+    };
+  });
+  const pick = versions.find((v) => v.id === active && v.corrected && v.bodyHex) || versions.find((v) => v.corrected && v.bodyHex);
+  return pick ? { gradeVersion: pick.name, gradeBody: pick.bodyHex } : { gradeVersion: null, gradeBody: null };
+}
+
+/** Clips of the tracks that belong to `sequenceId` inside one SeqContainer XML.
+ * trackType 0 = video (Sm2TiVideoClip), 1 = audio (Sm2TiAudioClip). */
+export function parseSeqContainerClips(containerXml, sequenceId, { includeGrade = false } = {}) {
+  const rows = [];
+  for (const t of containerXml.matchAll(/<Sm2TiTrack DbId="([^"]+)">([\s\S]*?)<\/Sm2TiTrack>/g)) {
+    const trackXml = t[2];
+    if (sequenceId && scalar(trackXml, 'Sequence') !== sequenceId) continue;
+    const trackType = Number(scalar(trackXml, 'Type') ?? 0);
+    const tag = trackType === 0 ? 'Sm2TiVideoClip' : 'Sm2TiAudioClip';
+    for (const c of trackXml.matchAll(new RegExp(`<${tag} DbId="([^"]+)">([\\s\\S]*?)</${tag}>`, 'g'))) {
+      const x = c[2];
+      const g = includeGrade ? activeGrade(x) : { gradeVersion: null, gradeBody: null };
+      rows.push({
+        itemId: c[1],
+        name: scalar(x, 'Name'),
+        trackType,
+        start: Number(scalar(x, 'Start')),
+        duration: Number(scalar(x, 'Duration')),
+        reel: blank(x, 'MediaReelNumber') ? '' : scalar(x, 'MediaReelNumber') || '',
+        mediaStart: scalar(x, 'MediaStartTime'),
+        sourceIn: decodeIn(scalar(x, 'In')),
+        mediaPath: blank(x, 'MediaFilePath') ? '' : scalar(x, 'MediaFilePath') || '',
+        poolId: scalar(x, 'MediaRef'), // per-project media ref; equal only inside one project
+        trackId: t[1],
+        gradeVersion: g.gradeVersion,
+        hasGrade: /<HasCorrection>true<\/HasCorrection>/.test(x),
+        ...(includeGrade ? { gradeBody: g.gradeBody } : {}),
+      });
+    }
+  }
+  rows.sort((a, b) => a.trackType - b.trackType || a.start - b.start);
+  return rows;
+}
+
+/** Unzip a .drp into a temp dir and return {dir, mpFolderXmls, containers:[{file, xml}]}. */
+export function openDrp(drpPath) {
+  if (!fs.existsSync(drpPath)) throw new Error(`.drp not found: ${drpPath}`);
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'drp-clips-'));
+  const r = spawnSync('unzip', ['-q', '-o', drpPath, '-d', dir], { encoding: 'utf8' });
+  if (r.status !== 0) throw new Error(`unzip failed for ${drpPath}: ${(r.stderr || '').slice(-200)}`);
+  const walk = (d, out = []) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p, out);
+      else out.push(p);
+    }
+    return out;
+  };
+  const files = walk(dir);
+  const read = (p) => fs.readFileSync(p, 'utf8');
+  return {
+    dir,
+    mpFolderXmls: files.filter((p) => /MpFolder\.xml$/.test(p)).map(read),
+    containers: files.filter((p) => /(^|\/)SeqContainer\/[^/]+\.xml$/.test(p)).map((p) => ({ file: p, xml: read(p) })),
+    close: () => {
+      try {
+        fs.rmSync(dir, { recursive: true, force: true });
+      } catch {
+        /* ignore */
+      }
+    },
+  };
+}
+
+/** readTimelineClips twin for a .drp: clips of the named timeline, video by default. */
+export function readTimelineClipsFromDrp(drpPath, timeline, trackType = 'video', includeGrade = false) {
+  const drp = openDrp(drpPath);
+  try {
+    const timelines = listDrpTimelines(drp.mpFolderXmls);
+    const tl = timelines.find((t) => t.name === timeline);
+    if (!tl) {
+      throw new Error(`timeline "${timeline}" not found in ${drpPath}. Timelines: ${timelines.map((t) => JSON.stringify(t.name)).join(', ') || '(none)'}`);
+    }
+    if (!tl.sequenceId) throw new Error(`timeline "${timeline}" has no <Sm2Sequence> in its media-pool entry`);
+    const holder = drp.containers.find((c) => c.xml.includes(`<Sequence>${tl.sequenceId}</Sequence>`));
+    if (!holder) throw new Error(`no SeqContainer references sequence ${tl.sequenceId} for timeline "${timeline}"`);
+    let rows = parseSeqContainerClips(holder.xml, tl.sequenceId, { includeGrade });
+    if (trackType === 'video') rows = rows.filter((r) => r.trackType === 0);
+    else if (trackType === 'audio') rows = rows.filter((r) => r.trackType !== 0);
+    return rows;
+  } finally {
+    drp.close();
+  }
+}

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

@@ -32,12 +32,28 @@ import crypto from 'node:crypto';
 import { z } from 'zod';
 import { resolveDbPath } from '../db-patch.mjs';
 import { readTimelineClips } from './project_read.mjs';
+import { readTimelineClipsFromDrp } from '../drp-timeline-clips.mjs';
 
 const side = (name) => ({
   [`${name}ProjectDb`]: z.string().optional(),
   [`${name}ProjectName`]: z.string().optional(),
+  [`${name}Drp`]: z
+    .string()
+    .optional()
+    .describe(
+      `An exported .drp of the ${name} project (ProjectManager.ExportProject / project_manager safe_project_export). The DB-agnostic route: use it when the project lives in a Postgres / network / cloud library that has no Project.db to open.`,
+    ),
   [`${name}Timeline`]: z.string(),
 });
+
+/** One side of the plan: a .drp when given, else a Project.db (path or name). */
+function sideClips(p, name, includeGrade) {
+  const drp = p[`${name}Drp`];
+  const timeline = p[`${name}Timeline`];
+  if (drp) return { origin: { drp, timeline }, clips: readTimelineClipsFromDrp(drp, timeline, 'video', includeGrade) };
+  const db = resolveDbPath({ projectDb: p[`${name}ProjectDb`], projectName: p[`${name}ProjectName`] });
+  return { origin: { projectDb: db, timeline }, clips: readTimelineClips(db, timeline, 'video', includeGrade) };
+}
 const planSchema = z.object({
   ...side('source'),
   ...side('target'),
@@ -274,14 +290,14 @@ const clipRef = (c) => ({
 export const colorTraceTool = {
   name: 'color_trace',
   description:
-    'Better ColorTrace — match clips between a SOURCE and TARGET timeline (cross-project, from Project.db, read-only, no Resolve) on media identity (pool id / file path / reel / file name + source-range overlap), names last → a trace plan with a lossless .drx per graded match and a plan.json for timeline_item_color.apply_trace_plan on the live server. Action: plan.',
+    'Better ColorTrace — match clips between a SOURCE and TARGET timeline (cross-project, from Project.db OR an exported .drp — the .drp route covers Postgres/network/cloud libraries — read-only, no Resolve) on media identity (pool id / file path / reel / file name + source-range overlap), names last → a trace plan with a lossless .drx per graded match and a plan.json for timeline_item_color.apply_trace_plan on the live server. Action: plan.',
   async handler({ action, args }) {
     if (action === 'plan') {
       const p = planSchema.parse(args);
-      const srcDb = resolveDbPath({ projectDb: p.sourceProjectDb, projectName: p.sourceProjectName });
-      const tgtDb = resolveDbPath({ projectDb: p.targetProjectDb, projectName: p.targetProjectName });
-      const srcClips = readTimelineClips(srcDb, p.sourceTimeline, 'video', true); // includeGrade
-      const tgtClips = readTimelineClips(tgtDb, p.targetTimeline, 'video');
+      const src = sideClips(p, 'source', true); // includeGrade
+      const tgt = sideClips(p, 'target', false);
+      const srcClips = src.clips;
+      const tgtClips = tgt.clips;
       if (!srcClips.length) throw new Error(`source timeline "${p.sourceTimeline}" has no video clips`);
       if (!tgtClips.length) throw new Error(`target timeline "${p.targetTimeline}" has no video clips`);
       if (p.emitDir) fs.mkdirSync(p.emitDir, { recursive: true });
@@ -330,8 +346,8 @@ export const colorTraceTool = {
       });
       const matched = matches.filter((m) => m.source).length;
       const result = {
-        source: { projectDb: srcDb, timeline: p.sourceTimeline, clips: srcClips.length, graded: srcClips.filter((c) => c.gradeBody).length },
-        target: { projectDb: tgtDb, timeline: p.targetTimeline, clips: tgtClips.length },
+        source: { ...src.origin, clips: srcClips.length, graded: srcClips.filter((c) => c.gradeBody).length },
+        target: { ...tgt.origin, clips: tgtClips.length },
         summary: { matched, unmatched: tgtClips.length - matched, gradesReady, ambiguous, belowThreshold, byMethod },
         emitDir: p.emitDir || null,
         planPath: null,

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.213.3"
+VERSION = "2.214.0"
 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.213.3"
+VERSION = "2.214.0"
 
 import base64
 import os
@@ -27093,6 +27093,33 @@ def _resolve_trace_plan(tl, plan: Dict[str, Any], p: Dict[str, Any]) -> List[Dic
     return rows
 
 
+_TRACE_MAX_ROWS_DEFAULT = 40
+
+
+def _trace_report(p: Dict[str, Any], plan: Dict[str, Any], kind: str, payload: Dict[str, Any]) -> Optional[str]:
+    """Write the full per-clip tables next to the plan (or to report_path) and
+    return the path. A real cut is 800+ rows — far past what a tool response
+    should carry — so the file is the durable artifact and the response stays
+    compact (see max_rows)."""
+    report_path = p.get("report_path")
+    if not report_path:
+        plan_path = p.get("plan_path")
+        base = os.path.dirname(os.path.abspath(plan_path)) if plan_path else tempfile.gettempdir()
+        report_path = os.path.join(base, f"{kind}-report.json")
+    try:
+        with open(report_path, "w", encoding="utf-8") as fh:
+            json.dump({"kind": f"color_trace.{kind}", "written_at": _time.time(),
+                       "plan_source": plan.get("source"), **payload}, fh, indent=1, default=str)
+        return report_path
+    except Exception as exc:
+        logger.warning("apply_trace_plan: could not write %s report: %s", kind, exc)
+        return None
+
+
+def _trace_compact(rows: List[Dict[str, Any]], max_rows: int) -> Dict[str, Any]:
+    return {"count": len(rows), "truncated": len(rows) > max_rows, "rows": rows[:max_rows]}
+
+
 def _apply_trace_plan(p: Dict[str, Any]) -> Dict[str, Any]:
     plan, err = _load_trace_plan(p)
     if err:
@@ -27126,12 +27153,25 @@ def _apply_trace_plan(p: Dict[str, Any]) -> Dict[str, Any]:
     public = [{k: v for k, v in r.items() if not k.startswith("_")} for r in rows]
     grade_mode = p.get("grade_mode", 0)
     version_name = p.get("version_name")
+    max_rows = p.get("max_rows", _TRACE_MAX_ROWS_DEFAULT)
+    max_rows = len(public) if p.get("verbose") else max(0, int(max_rows))
+    # Entries that deserve a human look: skipped for a reason other than the
+    # two bulk ones, or applied on a tie / a partial source-range overlap.
+    bulk = {"unmatched", "no-source-grade"}
+    attention = [r for r in public if (r["status"] != "apply" and r["reason"] not in bulk)
+                 or (r["status"] == "apply" and r["ambiguous"])]
 
     if p.get("dry_run"):
+        report_path = _trace_report(p, plan, "dry-run", {"summary": summary, "resolution": public})
         return _ok(dry_run=True, timeline=live_name, plan_source=plan.get("source"),
-                   summary=summary, resolution=public, grade_mode=grade_mode, version_name=version_name)
+                   summary=summary, report_path=report_path,
+                   attention=_trace_compact(attention, max_rows),
+                   resolution=_trace_compact(public, max_rows),
+                   grade_mode=grade_mode, version_name=version_name)
     if not to_apply:
-        return _ok(timeline=live_name, applied=[], failed=[], summary=summary, resolution=public,
+        report_path = _trace_report(p, plan, "apply", {"summary": summary, "resolution": public, "applied": [], "failed": []})
+        return _ok(timeline=live_name, applied=[], failed=[], summary=summary, report_path=report_path,
+                   attention=_trace_compact(attention, max_rows), resolution=_trace_compact(public, max_rows),
                    note="nothing to apply — every plan entry was skipped (see skipped_by_reason)")
     if "confirm_token" not in p and "confirmToken" not in p and _confirm_token_required():
         preview = {
@@ -27177,13 +27217,17 @@ def _apply_trace_plan(p: Dict[str, Any]) -> Dict[str, Any]:
         rec["status"] = "applied" if ok else "failed"
         (applied if ok else failed).append(rec)
     summary.update({"applied": len(applied), "failed": len(failed)})
+    skipped = [r for r in public if r["status"] != "apply"]
+    report_path = _trace_report(p, plan, "apply", {"summary": summary, "applied": applied, "failed": failed, "skipped": skipped})
     return {
         "success": not failed,
         "timeline": live_name,
         "plan_source": plan.get("source"),
-        "applied": applied,
-        "failed": failed,
-        "skipped": [r for r in public if r["status"] != "apply"],
+        "report_path": report_path,
+        "applied": _trace_compact(applied, max_rows),
+        "failed": failed,  # never truncated: every failure is actionable
+        "skipped": _trace_compact(skipped, max_rows),
+        "attention": _trace_compact(attention, max_rows),
         "summary": summary,
         "grade_mode": grade_mode,
         "version_name": version_name,
@@ -27311,8 +27355,8 @@ _ACTION_HELP: Dict[str, Dict[str, Dict[str, Any]]] = {
         },
         "apply_trace_plan": {
             "summary": "Apply a color_trace plan (advanced server) to the CURRENT timeline: one ApplyGradeFromDRX per resolved clip. REPLACES those graphs; gated by confirm_token; timeline archived first.",
-            "params": "plan_path: str (planPath from color_trace plan with emitDir) | plan: dict, dry_run?, min_confidence? (default 0.8), start_tolerance? (frames, default 0), grade_mode? (0=no keyframes, 1=source TC aligned, 2=start aligned), version_name? (AddVersion per clip before applying), require_temp_path? (default True), allow_timeline_mismatch?, confirm_token?",
-            "returns": "{success, timeline, applied: [...], failed: [...], skipped: [...], summary: {plan_matches, would_apply, applied, failed, skipped_by_reason, ambiguous_in_plan}}; dry_run → {resolution: [{target, source, method, confidence, status, reason, live}]}",
+            "params": "plan_path: str (planPath from color_trace plan with emitDir) | plan: dict, dry_run?, min_confidence? (default 0.8), start_tolerance? (frames, default 0), grade_mode? (0=no keyframes, 1=source TC aligned, 2=start aligned), version_name? (AddVersion per clip before applying), require_temp_path? (default True), allow_timeline_mismatch?, max_rows? (default 40; verbose=True returns every row), report_path? (default <plan dir>/dry-run-report.json | apply-report.json), confirm_token?",
+            "returns": "{success, timeline, report_path, summary: {plan_matches, would_apply, applied, failed, skipped_by_reason, ambiguous_in_plan}, attention: {count, truncated, rows}, applied: {count, truncated, rows}, failed: [...] (never truncated), skipped: {count, truncated, rows}}; dry_run → {resolution: {count, truncated, rows: [{target, source, method, confidence, status, reason, live}]}}",
             "example": (
                 '# 1. advanced server (no Resolve needed):\n'
                 '#    color_trace(action="plan", {sourceProjectName: "SHOW_v07", sourceTimeline: "REEL_01 v07",\n'
@@ -28147,13 +28191,15 @@ def timeline_item_color(action: str, params: Optional[Dict[str, Any]] = None) ->
       safe_apply_drx(path, source?, grade_mode?, require_temp_path?) -> {success}
         REPLACES the target graph. Captures a version snapshot first; require_temp_path defaults True.
         # example: action_help(name='<action_name>')
-      apply_trace_plan(plan_path|plan, dry_run?, min_confidence?=0.8, start_tolerance?=0, grade_mode?=0, version_name?, require_temp_path?=True, allow_timeline_mismatch?, confirm_token?) -> {success, applied, failed, skipped, summary}
+      apply_trace_plan(plan_path|plan, dry_run?, min_confidence?=0.8, start_tolerance?=0, grade_mode?=0, version_name?, require_temp_path?=True, allow_timeline_mismatch?, max_rows?=40, verbose?, report_path?, confirm_token?) -> {success, applied, failed, skipped, attention, summary, report_path}
         The live half of the advanced server's color_trace (a ColorTrace that matches on media
         identity, cross-project, from the project DB). Resolves each plan entry to a clip on the
         CURRENT timeline by (name, record start, duration), then ApplyGradeFromDRX per clip —
         one confirm_token for the batch, timeline archived first. dry_run returns the resolution
         table without a token. version_name adds a new local version per clip before applying so
         the previous grade stays intact. Never guesses: unresolved entries are reported, not applied.
+        The full per-clip tables go to report_path (default: next to the plan); the response carries
+        the summary, `attention` (ties, partial overlaps, non-bulk skips) and the first max_rows rows.
         # example: action_help(name='<action_name>')
       safe_export_lut(type?, path, require_temp_path?) -> {success, path, size}
         Sandboxed LUT export.