davinci-resolve-mcp 2.212.4 → 2.213.0

package/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 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.213.0 — a ColorTrace that matches on media, then applies
+
+### Added
+
+- **`color_trace` matches on media identity, names last.** Native ColorTrace
+  keys on timecode, clip name and order inside one project, so a renamed clip,
+  a reordered cut, or a stringout cut into graded sections defeats it. The
+  advanced server's `color_trace plan` now reads both timelines from their
+  `Project.db` (any two projects, read-only, no Resolve) and matches in tiers:
+  same media (pool item id or file path) with the same in-point and duration;
+  same media with overlapping source range (the best overlap wins, so each
+  section of a stringout finds its own grade); same reel plus overlap; same
+  file name plus overlap (relocated media); then, only as a fallback, exact and
+  normalised clip names. Every match reports its `method`, `confidence`,
+  `sourceOverlap` and an `ambiguous` flag when two candidates tie.
+- **`plan.json` + a lossless `.drx` per graded match.** With `emitDir` set the
+  plan writes one `.drx` per match by copying the source clip's grade body
+  byte for byte (no decode/re-encode, so OFX/ResolveFX nodes survive) and a
+  `plan.json` that names each target clip by (name, record start, duration).
+- **`timeline_item_color.apply_trace_plan` — the live half.** Resolves every
+  plan entry to a clip on the CURRENT timeline, returns a dry-run resolution
+  table (`apply` or `skip` with a reason: `live_item_not_found`,
+  `ambiguous_live_item`, `below_min_confidence`, `drx_missing`,
+  `drx_path_not_temp`, `no-source-grade`, `unmatched`), then behind one
+  `confirm_token` for the whole batch runs `ApplyGradeFromDRX` per clip.
+  Registered as a destructive action (timeline archived to the Archive bin
+  first, rated with the other whole-grade replacements, native dry-run).
+  `version_name` adds a local version per clip before applying so the previous
+  grade stays intact; `min_confidence` (default 0.8) gates the name-only tiers
+  out unless you lower it. Unresolved entries are reported, never guessed.
+
+### Changed
+
+- **`project_read.timeline_clips` reads the ACTIVE grade version.** The clip
+  join now follows the version table's `pActive` and dedupes to one row per
+  item, so a clip carrying several corrected versions no longer reads back as
+  several clips. Rows also carry the pool item id (`poolId`) and `hasGrade`.
+- **Name normalisation only strips `v`-prefixed version tokens.** Stripping any
+  trailing number folded `SHOT_010` and `SHOT_020` onto one key, so a
+  name-tier match could cross shots.
+
+### What was checked
+
+- Offline: 11 new match-engine tests (stringout sections by overlap, straddling
+  ranges, ties → ambiguous, pool-id vs path, reel and basename tiers,
+  unreadable in-point degrading to `media-only`, name fallbacks, active-version
+  dedupe) and 9 driver tests (resolution reasons, stacked clips disambiguated
+  by duration, ambiguous live items skipped, token → apply with `version_name`,
+  partial failure reported, dispatch without an item). Both full suites green.
+- **Not yet live-validated:** the end-to-end trace onto a real target timeline
+  with a render check afterwards. The plan step was live-verified against a
+  scratch DB in v2.136; the apply step is unit-tested against stubs only.
+
 ## What's New in v2.212.4 — both dependency manifests move together again
 
 ### Changed

package/README.md

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

package/docs/SKILL.md

@@ -1857,7 +1857,8 @@ Key actions:
 Color / Grade kernel actions (v2.11.0+) add safer grade inspection and
 boundary helpers: `grade_capabilities`, `probe_grade_item`,
 `probe_node_graph`, `safe_set_cdl`, `safe_copy_grade`, `safe_apply_drx`,
-`safe_export_lut`, `grade_version_snapshot`, `grade_version_restore`,
+`apply_trace_plan` (the live half of the advanced server's identity-matched
+`color_trace`), `safe_export_lut`, `grade_version_snapshot`, `grade_version_restore`,
 `color_group_capabilities`, `gallery_capabilities`, and
 `grade_boundary_report`. See `docs/kernels/color-grade-kernel.md` for the live-tested
 support map, and `docs/guides/color-decision-guide.md` for the practical distinction

package/docs/kernels/README.md

@@ -14,7 +14,7 @@ Current kernel coverage: **136 actions** across **9 compound MCP tools**.
 | Media Pool / ingest | `media_pool` | `ingest_capabilities`, `setup_multicam_timeline`, `probe_ingest_item`, `probe_media_pool`, `safe_import_media`, `safe_import_sequence`, `safe_import_folder`, `organize_clips`, `copy_metadata`, `normalize_metadata`, `probe_clip_properties`, `metadata_field_inventory`, `safe_relink`, `safe_unlink`, `link_proxy_checked`, `link_full_resolution_checked`, `set_clip_marks`, `clear_clip_marks`, `copy_clip_annotations`, `media_pool_boundary_report` |
 | Render / Deliver | `render` | `render_capabilities`, `probe_render_matrix`, `probe_render_settings`, `validate_render_settings`, `safe_set_render_settings`, `prepare_render_job`, `render_job_lifecycle_probe`, `quick_export_capabilities`, `safe_quick_export`, `export_render_boundary_report` |
 | Review annotations | `timeline_markers` | `annotation_capabilities`, `probe_annotations`, `normalize_marker_payload`, `copy_annotations`, `move_annotations`, `sync_marker_custom_data`, `clear_annotations_by_scope`, `export_review_report`, `annotation_boundary_report` |
-| Color / Grade | `timeline_item_color` | `grade_capabilities`, `probe_grade_item`, `probe_node_graph`, `safe_set_cdl`, `safe_copy_grade`, `safe_apply_drx`, `safe_export_lut`, `grade_version_snapshot`, `grade_version_restore`, `color_group_capabilities`, `gallery_capabilities`, `grade_boundary_report` |
+| Color / Grade | `timeline_item_color` | `grade_capabilities`, `probe_grade_item`, `probe_node_graph`, `safe_set_cdl`, `safe_copy_grade`, `safe_apply_drx`, `apply_trace_plan`, `safe_export_lut`, `grade_version_snapshot`, `grade_version_restore`, `color_group_capabilities`, `gallery_capabilities`, `grade_boundary_report` |
 | Fusion composition | `fusion_comp` | `fusion_graph_capabilities`, `probe_fusion_comp`, `probe_fusion_tool`, `safe_add_tool`, `safe_set_inputs`, `safe_connect_tools`, `fusion_boundary_report` |
 | Conform / interchange | `timeline` | `conform_capabilities`, `probe_timeline_structure`, `detect_gaps_overlaps`, `source_range_report`, `export_timeline_checked`, `import_timeline_checked`, `compare_timelines`, `probe_interchange_roundtrip`, `detect_missing_media`, `build_relink_plan`, `conform_boundary_report` |
 | Audio / Fairlight | `timeline` | `audio_capabilities`, `probe_audio_item`, `probe_audio_track`, `safe_set_audio_properties`, `audio_mix_capability_report`, `voice_isolation_capabilities`, `audio_mapping_report`, `safe_auto_sync_audio`, `transcription_capabilities`, `subtitle_generation_probe`, `fairlight_boundary_report` |

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

@@ -33,6 +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. |
 | `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. |
@@ -114,7 +115,8 @@ The live actions above drive a *running* Resolve. The companion advanced server
 (`davinci-resolve-advanced`, see `resolve-advanced/README.md`) *computes* grades
 offline from extracted frames and reads/writes `.drx`/`.drp` grades with **no
 Resolve running**. It emits an apply-ready `.drx`; **applying it is this kernel's
-job** (`safe_apply_drx`). Node never drives Resolve.
+job** (`safe_apply_drx` for one clip, `apply_trace_plan` for a whole `color_trace`
+plan). Node never drives Resolve.
 
 `drx` grading/QC actions (frame-stats → arithmetic → `.drx`, all local,
 deterministic, guarded — they refuse to fabricate a match rather than emit a

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

@@ -138,8 +138,12 @@ files and the project DB.
   reference-render, scale-corrected, red/yellow/cyan verdicts; each cut is
   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 → a trace plan for carrying
-  grades across a re-conform (pairs with the color kernel's `drx grade_transfer`).
+- **`color_trace`** — cross-project clip matching 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`. The live half
+  is `timeline_item_color.apply_trace_plan` (dry-run resolution table → one
+  confirm_token → ApplyGradeFromDRX per resolved clip, timeline archived first).
+  Pairs with the color kernel's `drx grade_transfer` for single looks.
 - **`offline_ref`** — offline-reference clips have **no scripting API** but live
   inside `.drp`/`.drt` as `<OfflineClip>` entries; patch them here.
 - **`editorial`** — `parse_interchange` (EDL/OTIO/XMEML natively; **AAF via pyaaf2**,

package/docs/reference/readwrite-symmetry.md

@@ -2,7 +2,7 @@
 
 # Read/Write Symmetry Audit
 
-- write-style action occurrences scanned: **116**
+- write-style action occurrences scanned: **117**
 - write-style action occurrences with a matching read: **71**
 - distinct high-signal `set_` actions without a direct/known readback: **4**
 
@@ -13,6 +13,6 @@
 - `set_keyframe_interpolation`
 - `set_node_enabled`
 
-## Low-signal (create/add/insert/apply/import — usually expected): 40 distinct names
+## Low-signal (create/add/insert/apply/import — usually expected): 41 distinct names
 
-`add_clip_mattes`, `add_comp`, `add_fusion_mask`, `add_subfolder`, `add_sync_event_markers`, `add_timeline_mattes`, `add_track`, `add_version`, `apply_arri_cdl_lut`, `apply_cuts`, `apply_fairlight_preset`, `apply_grade_from_drx`, `apply_look_to_items`, `apply_spec`, `create_compound_clip`, `create_fusion_clip`, `create_magic_mask`, `create_stereo_clip`, `create_subtitles`, `create_timeline`, `create_timeline_from_clips`, `create_variant_from_ranges`, `import_comp`, `import_folder`, `import_from_drp`, `import_into_timeline`, `import_media`, `import_preset`, `import_project`, `import_render`, `import_timeline`, `import_timeline_checked`, `import_to_pool`, `insert_audio`, `insert_fusion_composition`, `insert_fusion_generator`, `insert_fusion_title`, `insert_generator`, `insert_ofx_generator`, `insert_title`
+`add_clip_mattes`, `add_comp`, `add_fusion_mask`, `add_subfolder`, `add_sync_event_markers`, `add_timeline_mattes`, `add_track`, `add_version`, `apply_arri_cdl_lut`, `apply_cuts`, `apply_fairlight_preset`, `apply_grade_from_drx`, `apply_look_to_items`, `apply_spec`, `apply_trace_plan`, `create_compound_clip`, `create_fusion_clip`, `create_magic_mask`, `create_stereo_clip`, `create_subtitles`, `create_timeline`, `create_timeline_from_clips`, `create_variant_from_ranges`, `import_comp`, `import_folder`, `import_from_drp`, `import_into_timeline`, `import_media`, `import_preset`, `import_project`, `import_render`, `import_timeline`, `import_timeline_checked`, `import_to_pool`, `insert_audio`, `insert_fusion_composition`, `insert_fusion_generator`, `insert_fusion_title`, `insert_generator`, `insert_ofx_generator`, `insert_title`

package/install.py

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

package/resolve-advanced/README.md

@@ -82,7 +82,13 @@ Each dispatches on an `action`. Highlights:
 - **`conform`** — offline conform/relink QC engine (frame-oracle math, not filename matching),
   reverse-clip DB repair, sequence lineage store + diff, per-cut frame QC (sampled clear of
   transition windows; ingests Resolve's own FCP7 export — `-1` edges → junctions, no ticks needed).
-- **`color_trace`** — cross-project clip matching → a trace plan for carrying grades across a re-conform.
+- **`color_trace`** — a ColorTrace that works: matches a graded SOURCE timeline against a TARGET
+  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
+  `timeline_item_color.apply_trace_plan` applies it (dry-run resolution table, one
+  confirm_token for the batch, timeline archived first).
 - **`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/tools/color_trace.mjs

@@ -1,18 +1,29 @@
 /**
  * color_trace tool — a better ColorTrace. Match clips between a SOURCE and
- * TARGET timeline (cross-project, content-key-aware) → a trace plan mapping each
- * target clip to the source clip whose grade should carry over.
+ * TARGET timeline (cross-project, identity-aware) → a trace plan mapping each
+ * target clip to the source clip whose grade should carry over, plus a lossless
+ * .drx per graded match and a plan.json the live server's
+ * `timeline_item_color.apply_trace_plan` consumes.
  *
  * Resolve's native ColorTrace matches by TC/name/order within a project and breaks
  * on renames/reorders/retimes. This reads clip lists from ANY project's Project.db
- * (READ-only, no Resolve, even cross-project) and matches with a layered key.
+ * (READ-only, no Resolve, even cross-project) and matches on MEDIA IDENTITY first,
+ * names last:
  *
- * plan — source timeline + target timeline → { matches[], summary }
+ *   media-exact     same media (pool id or file path), same in-point + duration   1.00
+ *   media-overlap   same media, overlapping source range (best overlap wins)      0.95
+ *   reel-overlap    same reel name, overlapping source range                      0.90
+ *   basename-overlap same file name (relocated media), overlapping source range  0.85
+ *   media-only      same media, source range unreadable or disjoint              0.70
+ *   exact-name      clip name identical                                          0.75
+ *   normalized-name clip name identical after version/separator normalisation    0.60
  *
- * NOTE (current scope): this is the MATCH engine. The grade read + apply
- * (drx-codec decode → ApplyGradeFromDRX) is the next layer — it needs graded source
- * data + the live API; each match carries a `gradeApply` stub describing what would
- * be traced.
+ * A stringout — one long file cut into many graded sections — is the case native
+ * ColorTrace loses: every section shares a name and a file. media-overlap picks
+ * the section whose source range covers the target's, and flags `ambiguous`
+ * when two candidates tie.
+ *
+ * plan — source timeline + target timeline → { matches[], summary, planPath? }
  */
 
 import fs from 'node:fs';
@@ -30,7 +41,20 @@ const side = (name) => ({
 const planSchema = z.object({
   ...side('source'),
   ...side('target'),
-  emitDir: z.string().optional().describe('If set, write a .drx per matched+graded clip here (for ApplyGradeFromDRX via the live API)'),
+  emitDir: z
+    .string()
+    .optional()
+    .describe(
+      'If set, write a .drx per matched+graded clip here plus plan.json (for timeline_item_color.apply_trace_plan on the live server). Use a temp-dir path: the live apply refuses .drx files outside the system temp dir by default.',
+    ),
+  minConfidence: z
+    .number()
+    .min(0)
+    .max(1)
+    .optional()
+    .describe(
+      'Matches below this confidence get no .drx and status below-threshold (default 0 — everything is emitted, confidence is reported per match; the live apply has its own gate, default 0.8)',
+    ),
 });
 
 const xmlEscape = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
@@ -77,41 +101,180 @@ export const drxEnvelope = (label, bodyHex) => {
 };
 
 // Normalize a clip name to a match key: drop path + extension, lowercase,
-// collapse separators, strip trailing version tokens (_v2,.01, etc.).
-function normalize(name) {
+// collapse separators, strip a trailing VERSION token (_v2, -V12). Only a
+// v-prefixed token is a version: stripping any trailing number folded
+// SHOT_010 and SHOT_020 onto one key and let a name-tier match cross shots.
+export function normalize(name) {
   let n = String(name || '')
     .split('/')
     .pop()
     .replace(/\.[^.]+$/, '')
     .toLowerCase();
   n = n.replace(/[_\-.\s]+/g, ' ').trim();
-  n = n.replace(/\s+v?\d{1,3}$/, '').trim();
+  n = n.replace(/\s+v\d{1,3}$/, '').trim();
   return n;
 }
 
+const num = (v) => {
+  if (v === null || v === undefined || v === '') return null;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+};
+const lower = (v) => (v === null || v === undefined ? '' : String(v).trim().toLowerCase());
+const basename = (p) => lower(p).split(/[\\/]/).pop();
+
+/** Source-frame range of a clip, or null when the in-point is unreadable. */
+function sourceRange(c) {
+  const a = num(c.sourceIn);
+  const d = num(c.duration);
+  if (a === null || d === null || d <= 0) return null;
+  return [a, a + d];
+}
+function overlapFrames(r1, r2) {
+  if (!r1 || !r2) return 0;
+  return Math.max(0, Math.min(r1[1], r2[1]) - Math.max(r1[0], r2[0]));
+}
+
+const TIERS = [
+  // [method, confidence, key(clip) → string|null, needsOverlap]
+  ['media-exact', 1.0, null, 'exact'],
+  ['media-overlap', 0.95, null, 'overlap'],
+  ['reel-overlap', 0.9, (c) => lower(c.reel) || null, 'overlap'],
+  ['basename-overlap', 0.85, (c) => basename(c.mediaPath) || null, 'overlap'],
+  ['exact-name', 0.75, (c) => (c.name ? String(c.name) : null), 'none'],
+  ['media-only', 0.7, null, 'none'],
+  ['normalized-name', 0.6, (c) => normalize(c.name) || null, 'none'],
+];
+
+/** Media identity keys a clip answers to: its pool item id and its file path.
+ * Either equal on both sides means "the same media". */
+function mediaKeys(c) {
+  const keys = [];
+  if (c.poolId) keys.push(`pool:${lower(c.poolId)}`);
+  if (c.mediaPath) keys.push(`path:${lower(c.mediaPath)}`);
+  return keys;
+}
+
 function buildIndex(clips) {
-  const exact = new Map();
-  const norm = new Map();
+  const idx = { media: new Map(), tiers: new Map() };
+  const add = (map, k, c) => {
+    if (!k) return;
+    if (!map.has(k)) map.set(k, []);
+    map.get(k).push(c);
+  };
   for (const c of clips) {
-    if (!c.name) continue;
-    if (!exact.has(c.name)) exact.set(c.name, c);
-    const k = normalize(c.name);
-    if (k && !norm.has(k)) norm.set(k, c);
+    for (const k of mediaKeys(c)) add(idx.media, k, c);
+    for (const [method, , keyFn] of TIERS) {
+      if (!keyFn) continue;
+      if (!idx.tiers.has(method)) idx.tiers.set(method, new Map());
+      add(idx.tiers.get(method), keyFn(c), c);
+    }
+  }
+  return idx;
+}
+
+/** Candidates that share media identity with the target (deduped). */
+function mediaCandidates(target, idx) {
+  const seen = new Set();
+  const out = [];
+  for (const k of mediaKeys(target)) {
+    for (const c of idx.media.get(k) || []) {
+      const id = c.itemId || c;
+      if (seen.has(id)) continue;
+      seen.add(id);
+      out.push(c);
+    }
+  }
+  return out;
+}
+
+/** Pick the best candidate by source-range overlap. Ties (identical overlap)
+ * fall to the nearest record start and are flagged ambiguous. */
+function bestByOverlap(target, candidates) {
+  const tr = sourceRange(target);
+  if (!tr) return null;
+  let best = null;
+  let bestOv = 0;
+  let ties = 0;
+  for (const c of candidates) {
+    const ov = overlapFrames(tr, sourceRange(c));
+    if (ov <= 0) continue;
+    if (ov > bestOv) {
+      best = c;
+      bestOv = ov;
+      ties = 0;
+    } else if (ov === bestOv) {
+      ties += 1;
+      const d = (x) => Math.abs(num(x.start) - num(target.start));
+      if (d(c) < d(best)) best = c;
+    }
   }
-  return { exact, norm };
+  if (!best) return null;
+  return { src: best, overlap: bestOv, fraction: bestOv / (tr[1] - tr[0]), ambiguous: ties > 0, candidates: candidates.length };
 }
 
-function matchClip(target, idx) {
-  if (target.name && idx.exact.has(target.name)) return { src: idx.exact.get(target.name), method: 'exact-name', confidence: 1.0 };
-  const k = normalize(target.name);
-  if (k && idx.norm.has(k)) return { src: idx.norm.get(k), method: 'normalized-name', confidence: 0.85 };
-  return { src: null, method: null, confidence: 0 };
+/** Match ONE target clip against the source index. Returns
+ * { src, method, confidence, ambiguous, candidates, sourceOverlap? } — src null when unmatched. */
+export function matchClip(target, idx) {
+  const tr = sourceRange(target);
+  const tDur = num(target.duration);
+  const media = mediaCandidates(target, idx);
+
+  for (const [method, confidence, keyFn, mode] of TIERS) {
+    let candidates;
+    if (keyFn) candidates = idx.tiers.get(method)?.get(keyFn(target)) || [];
+    else candidates = media;
+    if (!candidates.length) continue;
+
+    if (mode === 'exact') {
+      const hits = candidates.filter((c) => tr && num(c.sourceIn) === tr[0] && num(c.duration) === tDur);
+      if (!hits.length) continue;
+      const src =
+        hits.length === 1 ? hits[0] : hits.reduce((a, b) => (Math.abs(num(b.start) - num(target.start)) < Math.abs(num(a.start) - num(target.start)) ? b : a));
+      return { src, method, confidence, ambiguous: hits.length > 1, candidates: hits.length, sourceOverlap: { frames: tDur, fraction: 1 } };
+    }
+    if (mode === 'overlap') {
+      const b = bestByOverlap(target, candidates);
+      if (!b) continue;
+      return {
+        src: b.src,
+        method,
+        confidence,
+        ambiguous: b.ambiguous,
+        candidates: b.candidates,
+        sourceOverlap: { frames: b.overlap, fraction: Number(b.fraction.toFixed(4)) },
+      };
+    }
+    // mode 'none' — first candidate, nearest record start on ties.
+    const src =
+      candidates.length === 1
+        ? candidates[0]
+        : candidates.reduce((a, b) => (Math.abs(num(b.start) - num(target.start)) < Math.abs(num(a.start) - num(target.start)) ? b : a));
+    return { src, method, confidence, ambiguous: candidates.length > 1, candidates: candidates.length };
+  }
+  return { src: null, method: null, confidence: 0, ambiguous: false, candidates: 0 };
+}
+
+/** Match every target clip against the source clips (pure; no DB). */
+export function matchClips(srcClips, tgtClips) {
+  const idx = buildIndex(srcClips);
+  return tgtClips.map((t) => ({ target: t, ...matchClip(t, idx) }));
 }
 
+const clipRef = (c) => ({
+  name: c.name,
+  start: num(c.start),
+  duration: num(c.duration),
+  sourceIn: num(c.sourceIn),
+  reel: c.reel || null,
+  mediaPath: c.mediaPath || null,
+  poolId: c.poolId || null,
+});
+
 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) → a trace plan for carrying grades across a re-conform. Action: plan.',
+    '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.',
   async handler({ action, args }) {
     if (action === 'plan') {
       const p = planSchema.parse(args);
@@ -122,43 +285,63 @@ export const colorTraceTool = {
       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 });
+      const minConfidence = p.minConfidence ?? 0;
 
-      const idx = buildIndex(srcClips);
-      const byMethod = { 'exact-name': 0, 'normalized-name': 0, unmatched: 0 };
+      const byMethod = { unmatched: 0 };
+      for (const [m] of TIERS) byMethod[m] = 0;
       let gradesReady = 0;
-      const matches = tgtClips.map((t, i) => {
-        const m = matchClip(t, idx);
+      let ambiguous = 0;
+      let belowThreshold = 0;
+      const matches = matchClips(srcClips, tgtClips).map((m, i) => {
+        const t = m.target;
         byMethod[m.method || 'unmatched'] += 1;
+        if (m.ambiguous) ambiguous += 1;
         let gradeApply = null;
-        if (m.src && m.src.gradeBody) {
+        if (m.src && m.confidence < minConfidence) {
+          belowThreshold += 1;
+          gradeApply = { status: 'below-threshold', sourceClip: m.src.name, confidence: m.confidence, minConfidence };
+        } else if (m.src && m.src.gradeBody) {
           gradesReady += 1;
-          gradeApply = { status: 'ready', sourceClip: m.src.name };
+          gradeApply = { status: 'ready', sourceClip: m.src.name, sourceVersion: m.src.gradeVersion || null };
           if (p.emitDir) {
             // emit a .drx (lossless source-grade pass-through) for ApplyGradeFromDRX onto the target clip.
             const drxPath = path.join(p.emitDir, `trace-${String(i).padStart(4, '0')}.drx`);
             fs.writeFileSync(drxPath, drxEnvelope(m.src.name, m.src.gradeBody));
             gradeApply.drxPath = drxPath;
-            gradeApply.applyVia = { api: 'timeline_item_color.safe_apply_drx', target: { timeline: p.targetTimeline, clipName: t.name, start: t.start } };
+            gradeApply.applyVia = {
+              api: 'timeline_item_color.apply_trace_plan',
+              target: { timeline: p.targetTimeline, clipName: t.name, start: num(t.start), duration: num(t.duration) },
+            };
           }
         } else if (m.src) {
           gradeApply = { status: 'no-source-grade', sourceClip: m.src.name };
         }
         return {
-          target: { name: t.name, start: t.start },
-          source: m.src ? { name: m.src.name, start: m.src.start } : null,
+          index: i,
+          target: clipRef(t),
+          source: m.src ? clipRef(m.src) : null,
           method: m.method,
           confidence: m.confidence,
+          ambiguous: m.ambiguous,
+          candidates: m.candidates,
+          sourceOverlap: m.sourceOverlap || null,
           gradeApply,
         };
       });
       const matched = matches.filter((m) => m.source).length;
-      return {
-        source: { timeline: p.sourceTimeline, clips: srcClips.length },
-        target: { timeline: p.targetTimeline, clips: tgtClips.length },
-        summary: { matched, unmatched: tgtClips.length - matched, gradesReady, byMethod },
+      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 },
+        summary: { matched, unmatched: tgtClips.length - matched, gradesReady, ambiguous, belowThreshold, byMethod },
         emitDir: p.emitDir || null,
+        planPath: null,
         matches,
       };
+      if (p.emitDir) {
+        result.planPath = path.join(p.emitDir, 'plan.json');
+        fs.writeFileSync(result.planPath, JSON.stringify({ kind: 'color_trace.plan', createdAt: new Date().toISOString(), ...result }, null, 2));
+      }
+      return result;
     }
     throw new Error(`Unknown color_trace action: ${action}`);
   },

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

@@ -35,16 +35,28 @@ const timelineClipsSchema = z.object({ ...dbTarget, timeline: z.string().describ
 // column: file-relative source frames, calibrated frame-EXACT against a real
 // turnover's AAF ground truth (A005C004 run: 36069/8863/8919/12804, through-
 // edit continuity intact). Emitted as sourceIn.
+// Identity columns for color_trace (2026-09-08): MediaRef → Sm2MpMedia gives the
+// pool item's UniqueMediaPoolItemId (poolId); the version table's pActive names
+// the ACTIVE grade version, so an item carrying several corrected versions
+// reads back ONE row — the active one (or the first corrected one when the
+// active version has no correction). Measured on a 21k-item show DB: no item
+// held two corrected versions, but the dedupe below is what keeps that from
+// becoming a duplicate-clip bug the day one does.
 const TIMELINE_CLIPS_SQL = `
- SELECT i.Name AS name, t.Type AS trackType, i.Start AS start, i.Duration AS duration,
+ SELECT i.Sm2TiItem_id AS itemId, i.Name AS name, t.Type AS trackType, i.Start AS start, i.Duration AS duration,
  i.MediaReelNumber AS reel, i.MediaStartTime AS mediaStart, i."In" AS sourceIn,
  i.MediaFilePath AS mediaPath,
+ m.UniqueMediaPoolItemId AS poolId,
  i.Sm2TiTrack_id AS trackId,
+ v.Name AS gradeVersion,
+ CASE WHEN vt.pActive IS NOT NULL AND v."ListMgt::LmVersion_id" = vt.pActive THEN 1 ELSE 0 END AS gradeIsActive,
  lower(hex(v.Body)) AS gradeBody
  FROM Sm2TiItem i
  JOIN Sm2TiTrack t ON i.Sm2TiTrack_id = t.Sm2TiTrack_id
  JOIN Sm2Sequence s ON t.Sequence = s.Sm2Sequence_id
  JOIN Sm2Timeline tl ON s.Sm2Timeline_id = tl.Sm2Timeline_id
+ LEFT JOIN Sm2MpMedia m ON m.Sm2MpMedia_id = i.MediaRef
+ LEFT JOIN "ListMgt::LmVersionTable" vt ON vt."ListMgt::LmVersionTable_id" = i.pLmVerTable
  LEFT JOIN "ListMgt::LmVersion" v ON v."ListMgt::LmVersionTable_id" = i.pLmVerTable AND v.HasCorrection = '1'
  WHERE tl.Name = ?`;
 const tablesSchema = z.object({ ...dbTarget, withRowCounts: z.boolean().optional() });
@@ -107,12 +119,15 @@ export function readTimelineClips(dbPath, timeline, trackType = 'all', includeGr
   const db = openGuarded(dbPath, { writable: false });
   try {
     let rows = db.prepare(TIMELINE_CLIPS_SQL).all(timeline);
+    rows = dedupeVersionRows(rows);
     if (trackType === 'video') rows = rows.filter((r) => r.trackType === 0);
     else if (trackType === 'audio') rows = rows.filter((r) => r.trackType !== 0);
     rows.sort((a, b) => a.trackType - b.trackType || Number(a.start) - Number(b.start));
     // grade Body is large + only needed for ColorTrace — strip it by default to avoid bloat.
     for (const r of rows) {
+      r.hasGrade = !!r.gradeBody;
       if (!includeGrade) delete r.gradeBody;
+      delete r.gradeIsActive;
       r.sourceIn = decodeItemIn(r.sourceIn);
     }
     return rows;
@@ -121,6 +136,18 @@ export function readTimelineClips(dbPath, timeline, trackType = 'all', includeGr
   }
 }
 
+/** One row per timeline item: an item with several corrected grade versions
+ * joins to several rows — keep the ACTIVE version's row, else the first. */
+export function dedupeVersionRows(rows) {
+  const byItem = new Map();
+  for (const r of rows) {
+    const key = r.itemId || `${r.trackId}|${r.start}|${r.name}`;
+    const prev = byItem.get(key);
+    if (!prev || (!prev.gradeIsActive && r.gradeIsActive)) byItem.set(key, r);
+  }
+  return [...byItem.values()];
+}
+
 export const projectReadTool = {
   name: 'project_read',
   description:

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.212.4"
+VERSION = "2.213.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.212.4"
+VERSION = "2.213.0"
 
 import base64
 import os
@@ -1281,6 +1281,8 @@ _TOKEN_GATED_DESTRUCTIVE_ACTIONS = frozenset({
     ("edit_engine", "execute_swap"),
     ("graph", "apply_grade_from_drx"),
     ("graph", "reset_all_grades"),
+    # Batch grade carry-over from a color_trace plan: plan → confirm → apply.
+    ("timeline_item_color", "apply_trace_plan"),
     # 21.0 AI ops that render/generate NEW media files (additive, but expensive
     # and irreversible without manual cleanup) — gated so they never run by
     # surprise. They never modify source media.
@@ -26386,6 +26388,7 @@ _COLOR_GRADE_KERNEL_ACTIONS = [
     "safe_set_cdl",
     "safe_copy_grade",
     "safe_apply_drx",
+    "apply_trace_plan",
     "safe_export_lut",
     "grade_version_snapshot",
     "grade_version_restore",
@@ -26861,6 +26864,232 @@ def _safe_apply_drx(proj, item, p: Dict[str, Any]):
     return {"success": success, "path": path, "source": source}
 
 
+# ── color_trace apply driver ─────────────────────────────────────────────────
+#
+# The advanced (Node) server's `color_trace plan` matches a graded SOURCE
+# timeline against a TARGET timeline from the project DB (no Resolve needed),
+# writes one lossless .drx per graded match and a plan.json naming each target
+# clip by (name, record start, duration). This driver is the live half: it
+# resolves every plan entry to a clip on the CURRENT timeline, reports what it
+# would touch, and — behind a confirm_token, with the timeline archived first —
+# runs ApplyGradeFromDRX on each resolved clip. Every clip the plan could not
+# place on the live timeline is reported, never guessed.
+
+_TRACE_SKIP_REASONS = (
+    "unmatched", "no-source-grade", "below-threshold", "below_min_confidence",
+    "drx_missing", "drx_path_not_temp", "live_item_not_found", "ambiguous_live_item",
+)
+
+
+def _load_trace_plan(p: Dict[str, Any]):
+    plan = p.get("plan")
+    plan_path = p.get("plan_path")
+    if plan is None:
+        if not plan_path:
+            return None, _err(
+                "plan_path (or an inline plan) is required",
+                code="MISSING_PLAN", category="invalid_input",
+                remediation="Run the advanced server's color_trace plan with emitDir set "
+                            "(a temp-dir path) and pass its planPath here.",
+            )
+        if not os.path.isfile(plan_path):
+            return None, _err(f"plan not found: {plan_path}", code="PLAN_NOT_FOUND", category="invalid_input")
+        try:
+            with open(plan_path, encoding="utf-8") as fh:
+                plan = json.load(fh)
+        except Exception as exc:
+            return None, _err(f"plan is not valid JSON: {exc}", code="PLAN_INVALID", category="invalid_input")
+    if not isinstance(plan, dict) or not isinstance(plan.get("matches"), list):
+        return None, _err("plan has no matches list (expected color_trace.plan output)",
+                          code="PLAN_INVALID", category="invalid_input")
+    return plan, None
+
+
+def _live_video_items(tl) -> List[Dict[str, Any]]:
+    """Every video-track item on the timeline with the fields the plan keys on."""
+    out: List[Dict[str, Any]] = []
+    try:
+        track_count = int(tl.GetTrackCount("video") or 0)
+    except Exception as exc:
+        logger.warning("apply_trace_plan: GetTrackCount(video) failed: %s", exc)
+        track_count = 0
+    for track_index in range(1, track_count + 1):
+        for item_index, it in enumerate(tl.GetItemListInTrack("video", track_index) or []):
+            try:
+                out.append({
+                    "item": it,
+                    "track_index": track_index,
+                    "item_index": item_index,
+                    "id": it.GetUniqueId(),
+                    "name": it.GetName(),
+                    "start": int(it.GetStart()),
+                    "duration": int(it.GetDuration()),
+                })
+            except Exception as exc:
+                logger.warning("apply_trace_plan: skipping unreadable item on V%s: %s", track_index, exc)
+    return out
+
+
+def _resolve_trace_plan(tl, plan: Dict[str, Any], p: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """Map each plan match onto a live clip. status: apply | skip (+reason)."""
+    min_conf = float(p.get("min_confidence", 0.8))
+    tol = int(p.get("start_tolerance", 0))
+    require_temp = p.get("require_temp_path", True)
+    live = _live_video_items(tl)
+    rows: List[Dict[str, Any]] = []
+    for m in plan["matches"]:
+        tgt = m.get("target") or {}
+        src = m.get("source") or {}
+        ga = m.get("gradeApply") or {}
+        drx = ga.get("drxPath")
+        row: Dict[str, Any] = {
+            "index": m.get("index"),
+            "target": {"name": tgt.get("name"), "start": tgt.get("start"), "duration": tgt.get("duration")},
+            "source": src.get("name"),
+            "method": m.get("method"),
+            "confidence": m.get("confidence"),
+            "ambiguous": bool(m.get("ambiguous")),
+            "drx_path": drx,
+            "status": "skip",
+            "reason": None,
+            "live": None,
+        }
+        conf = row["confidence"] if isinstance(row["confidence"], (int, float)) else 0.0
+        if not src:
+            row["reason"] = "unmatched"
+        elif ga.get("status") != "ready":
+            row["reason"] = ga.get("status") or "no-source-grade"
+        elif conf < min_conf:
+            row["reason"] = "below_min_confidence"
+        elif not drx or not os.path.isfile(drx):
+            row["reason"] = "drx_missing"
+        elif require_temp and not _grade_temp_path_ok(drx):
+            row["reason"] = "drx_path_not_temp"
+        else:
+            name = tgt.get("name")
+            start = tgt.get("start")
+            cands = [
+                x for x in live
+                if x["name"] == name and isinstance(start, (int, float)) and abs(x["start"] - int(start)) <= tol
+            ]
+            if len(cands) > 1:
+                same_dur = [x for x in cands if x["duration"] == tgt.get("duration")]
+                if len(same_dur) == 1:
+                    cands = same_dur
+            if not cands:
+                row["reason"] = "live_item_not_found"
+            elif len(cands) > 1:
+                row["reason"] = "ambiguous_live_item"
+                row["live_candidates"] = [
+                    {"track_index": x["track_index"], "item_index": x["item_index"], "id": x["id"], "duration": x["duration"]}
+                    for x in cands
+                ]
+            else:
+                hit = cands[0]
+                row["status"] = "apply"
+                row["live"] = {k: hit[k] for k in ("track_index", "item_index", "id", "start", "duration")}
+                row["_item"] = hit["item"]
+        rows.append(row)
+    return rows
+
+
+def _apply_trace_plan(p: Dict[str, Any]) -> Dict[str, Any]:
+    plan, err = _load_trace_plan(p)
+    if err:
+        return err
+    _, tl, err = _get_tl()
+    if err:
+        return err
+    live_name = tl.GetName()
+    plan_tl = (plan.get("target") or {}).get("timeline")
+    if plan_tl and plan_tl != live_name and not p.get("allow_timeline_mismatch"):
+        return _err(
+            f"plan targets timeline {plan_tl!r} but the current timeline is {live_name!r}",
+            code="TIMELINE_MISMATCH", category="invalid_input",
+            remediation=f"timeline(action='set_current', params={{'name': {plan_tl!r}}}) first, "
+                        "or pass allow_timeline_mismatch=True if the plan was built for this cut under another name.",
+        )
+    rows = _resolve_trace_plan(tl, plan, p)
+    to_apply = [r for r in rows if r["status"] == "apply"]
+    skipped_by_reason: Dict[str, int] = {}
+    for r in rows:
+        if r["status"] != "apply":
+            skipped_by_reason[r["reason"] or "unknown"] = skipped_by_reason.get(r["reason"] or "unknown", 0) + 1
+    summary = {
+        "plan_matches": len(rows),
+        "would_apply": len(to_apply),
+        "skipped": len(rows) - len(to_apply),
+        "skipped_by_reason": skipped_by_reason,
+        "ambiguous_in_plan": sum(1 for r in rows if r["ambiguous"]),
+        "min_confidence": float(p.get("min_confidence", 0.8)),
+    }
+    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")
+
+    if p.get("dry_run"):
+        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)
+    if not to_apply:
+        return _ok(timeline=live_name, applied=[], failed=[], summary=summary, resolution=public,
+                   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 = {
+            "operation": "apply_trace_plan",
+            "warning": "REPLACES the node graph of every listed target clip (ApplyGradeFromDRX has "
+                       "no append mode). The current timeline is archived to the Archive bin first.",
+            "timeline": live_name,
+            "will_apply": len(to_apply),
+            "summary": summary,
+            "targets": [
+                {"name": r["target"]["name"], "start": r["target"]["start"], "source": r["source"],
+                 "method": r["method"], "confidence": r["confidence"], "ambiguous": r["ambiguous"]}
+                for r in to_apply[:50]
+            ],
+            "grade_mode": grade_mode,
+            "version_name": version_name,
+        }
+        return _issue_confirm_token(action="apply_trace_plan", params=p, preview=preview)
+    blocked = _consume_confirm_token(action="apply_trace_plan", params=p)
+    if blocked:
+        return blocked
+
+    applied: List[Dict[str, Any]] = []
+    failed: List[Dict[str, Any]] = []
+    for r in to_apply:
+        item = r["_item"]
+        rec = {k: v for k, v in r.items() if not k.startswith("_")}
+        ok = False
+        try:
+            if version_name:
+                # AddVersion switches the item to the NEW version, so the apply
+                # lands there and the previous version stays intact.
+                rec["version_added"] = bool(item.AddVersion(version_name, 0))
+            graph = item.GetNodeGraph()
+            if not _has_method(graph, "ApplyGradeFromDRX"):
+                rec["error"] = "item graph does not expose ApplyGradeFromDRX"
+            else:
+                ok = bool(graph.ApplyGradeFromDRX(r["drx_path"], grade_mode))
+                if not ok:
+                    rec["error"] = "ApplyGradeFromDRX returned False"
+        except Exception as exc:
+            rec["error"] = str(exc)
+        rec["status"] = "applied" if ok else "failed"
+        (applied if ok else failed).append(rec)
+    summary.update({"applied": len(applied), "failed": len(failed)})
+    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"],
+        "summary": summary,
+        "grade_mode": grade_mode,
+        "version_name": version_name,
+    }
+
+
 def _grade_version_restore(item, p: Dict[str, Any]):
     name = p.get("name")
     if not name:
@@ -26980,6 +27209,25 @@ _ACTION_HELP: Dict[str, Dict[str, Dict[str, Any]]] = {
                 '   # re-call with confirm_token to apply'
             ),
         },
+        "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}]}",
+            "example": (
+                '# 1. advanced server (no Resolve needed):\n'
+                '#    color_trace(action="plan", {sourceProjectName: "SHOW_v07", sourceTimeline: "REEL_01 v07",\n'
+                '#                                targetProjectName: "SHOW_v08", targetTimeline: "REEL_01 v08",\n'
+                '#                                emitDir: "/tmp/trace-reel01"})  → planPath\n'
+                '# 2. open the TARGET project + timeline in Resolve, then:\n'
+                'timeline_item_color(action="apply_trace_plan", params={\n'
+                '  "plan_path": "/tmp/trace-reel01/plan.json", "dry_run": True\n'
+                '})  # read resolution: every entry is apply | skip(reason)\n'
+                'timeline_item_color(action="apply_trace_plan", params={\n'
+                '  "plan_path": "/tmp/trace-reel01/plan.json", "version_name": "traced v07"\n'
+                '})  # first call returns {status: "confirmation_required", confirm_token}\n'
+                '   # re-call with confirm_token to apply'
+            ),
+        },
         "grade_evidence_base": {
             "summary": "PREFERRED pre-flight read. Composes version_snapshot + node_graph + color_group + coverage_report.",
             "params": "include_coverage?, max_nodes?, min_source_trust? (medium|high), track_type?, track_index?, item_index?",
@@ -27757,6 +28005,7 @@ def timeline_item_color(action: str, params: Optional[Dict[str, Any]] = None) ->
     safe_set_cdl        -> {success, validation, normalized, node_preflight, diagnosis?}
     safe_copy_grade     -> {success, targets, missing}
     safe_apply_drx      -> {success, path, source}  # first call may return confirm_token
+    apply_trace_plan    -> {success, timeline, applied, failed, skipped, summary}  # dry_run → {resolution}; first live call returns confirm_token
     grade_capabilities  -> {item_methods, graph_sources, lut_export_types, guards}
     grade_boundary_report -> {capabilities, item, color_groups, gallery}
     All actions may return {"error": {code, category, retryable, message, remediation, reason?}}.
@@ -27798,6 +28047,14 @@ 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}
+        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.
+        # example: action_help(name='<action_name>')
       safe_export_lut(type?, path, require_temp_path?) -> {success, path, size}
         Sandboxed LUT export.
       grade_version_restore(name, type?, dry_run?, ...) -> {success}
@@ -27837,6 +28094,9 @@ def timeline_item_color(action: str, params: Optional[Dict[str, Any]] = None) ->
     p = _params(params)
     if action == "action_help":
         return _action_help("timeline_item_color", p)
+    if action == "apply_trace_plan":
+        # Timeline-scoped (walks every video track); does not need an item.
+        return _apply_trace_plan(p)
     _, item, err = _get_item(p)
     if err:
         return err

package/src/utils/destructive_hook.py

@@ -169,6 +169,7 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
     "timeline_item_color": frozenset({
         "set_cdl",
         "copy_grades",
+        "apply_trace_plan",
         "reset_all_node_colors",
         "assign_color_group",
         "remove_from_color_group",
@@ -277,6 +278,7 @@ DRY_RUN_DEFAULT_TRUE_ACTIONS: frozenset = frozenset({
 
 NATIVE_DRY_RUN_ACTIONS: frozenset = frozenset({
     ("media_pool", "clear_clip_marks"),
+    ("timeline_item_color", "apply_trace_plan"),
     ("media_pool", "set_clip_marks"),
     ("media_pool", "setup_multicam_timeline"),
     ("timeline", "apply_cuts"),

package/src/utils/execution_lifecycle.py

@@ -169,6 +169,9 @@ class RiskClassificationHook(LifecycleHook):
         # CopyGrades overwrites each target's grade.
         ("graph", "apply_grade_from_drx"),
         ("timeline_item_color", "copy_grades"),
+        # apply_trace_plan runs ApplyGradeFromDRX over every clip a color_trace
+        # plan resolved — one confirm_token, N replaced graphs.
+        ("timeline_item_color", "apply_trace_plan"),
         # Takes. delete removes one; finalize collapses the item to the selected
         # take and discards the rest.
         ("timeline_item_takes", "delete"),