davinci-resolve-mcp 3.4.0 → 4.0.0

package/CHANGELOG.md

@@ -2,6 +2,90 @@
 
 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 v4.0.0 — verified API facts reach the caller, and one of them refuses
+
+Contributed by @Grimthereapper (#217). **Major**, because a call that previously
+returned `{"success": true}` from `copy_grades` or `apply_look_to_items` can now
+refuse.
+
+### Breaking
+
+- **Actions that call `TimelineItem.CopyGrades` refuse until the caller passes
+  `acknowledge_trap: true`.** That symbol replaces the target's grade wholesale
+  rather than merging, returns `True` while doing it, and creates no grade
+  version — so applied to a clip carrying hand-work it is unrecoverable loss
+  reported as success. `copy_grades` and `apply_look_to_items` refuse;
+  `safe_copy_grade` and `bulk_match_to_hero` do not, because each already owns a
+  confirmation path (see *Why two actions are exempt* below). The refusal names
+  the behaviour, carries the recommendation, and tells the caller what to
+  re-send. Dry runs are exempt — a preview destroys nothing.
+- **`RESOLVE_MCP_DISABLE_TRAP_GUARD=1` turns the whole mechanism off**, refusal
+  and advisory push alike.
+
+### Added
+
+- **`api_truth` became a push, not only a pull.** The ledger answered
+  `resolve_control(action="api_truth")` and was otherwise a file nobody greps
+  mid-job; exactly one callsite pushed proactively. An action mapped to a symbol
+  with a recorded fact now carries a compact `known_limitation` on its result —
+  symbol, reality, recommendation, nothing else, because response weight is a
+  real cost on a long session and the full entry is one lookup away.
+- **`ACTION_SYMBOLS`** declares which Resolve symbols each compound `(tool,
+  action)` actually calls, matched on exact symbol equality only. Nothing is
+  inferred from a similar name: an unrelated explanation stapled to a failure
+  reads as a diagnosis, and a wrong diagnosis is worse than none.
+- **Four new `api_truth` entries**, in the places the ledger was thinnest —
+  `TimelineItem.CopyGrades` (replaces wholesale, no version),
+  `TimelineItem.ApplyGradeFromStill` (does not exist on `TimelineItem` or
+  `Graph`; `Graph.ApplyGradeFromDRX` is the real symbol),
+  `TimelineItem.ExportLUT` (Color-page gated, bare `False` elsewhere, no stale
+  file written) and `Timeline.DuplicateTimeline` (silently moves the
+  current-timeline pointer). The existing `ProjectManager.DeleteProject` entry
+  was reconfirmed rather than duplicated. Each carries a per-entry
+  `verified_on`; the stale module-level `VERIFIED_ON` constant was deliberately
+  left alone rather than globally bumped to assert 113 re-measurements that did
+  not happen.
+- **`color_grade_live_probe`** re-derives three of these against a live build
+  and records `drifted` when Resolve stops agreeing. A fact nobody can
+  re-measure decays into folklore the moment Blackmagic ships a build — and one
+  of these now refuses calls, so a stale entry would block legitimate work
+  rather than merely mislead.
+
+### Why two actions are exempt
+
+`destroys_prior_work` is a property of the symbol, but four actions call
+`CopyGrades` and two already make the caller confirm. Refusing those too would
+cost a caller two acknowledgements discovered serially — add `acknowledge_trap`,
+retry, then find a `confirm_token` is also needed — and it would land hardest on
+`safe_copy_grade`, whose name promises it is the careful route. Making the
+careful route the most irritating to call pushes people toward the raw
+`copy_grades` the guard exists to protect them from. The confirm-token flow is
+older and more specific, so it wins and the guard stands down; those actions
+still get the advisory `known_limitation`.
+
+### Guards
+
+- Every mapped symbol is a real `API_TRUTH` entry, and every mapped action a
+  real handler.
+- Every `destroys_prior_work` entry is reachable from some action, or the
+  refusal it powers can never fire.
+- Every `destroys_prior_work` entry is named by a live probe, or it becomes a
+  superstition.
+- An exempt action's handler still mentions `confirm_token`, so deleting that
+  gate fails loudly instead of silently becoming no confirmation at all.
+- No still-refusing action defaults `dry_run` to `True`.
+
+### Measurement provenance
+
+The four new entries were measured by the contributor on **DaVinci Resolve
+Studio 21.1.0.14** and are recorded with that `verified_on`. They were **not**
+re-measured for this release — no 21.1 machine was available — so they are this
+server's record of a contributor's measurement, not a maintainer reconfirmation.
+The `ExportLUT` page-gating finding is independently consistent with this
+repository's own recorded behaviour of grade calls off the Color page on Studio
+19.1.3.7. `color_grade_live_probe` exists precisely so anyone on 21.1 can
+re-derive them and see `drifted` if Resolve has changed.
+
 ## What's New in v3.4.0 — review a bin one frame at a time in the control panel
 
 Contributed by @tpellet (#230), their first contribution here.

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-3.4.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.0.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-37%20(387%20full)-blue.svg)](#server-modes)
@@ -312,6 +312,51 @@ file paths. The one free-text field is the `request` you pass to
 `begin_execution`, so treat it the way you would a commit message on a client
 project.
 
+## Verified-Trap Guard
+
+`src/utils/api_truth.py` records behaviours of the Resolve API that were measured
+against a live build rather than read off a signature — calls that return `True`
+having done nothing, settings keys silently rejected, methods that are not there
+at all. That ledger used to be **pull-only**: it answered
+`resolve_control(action="api_truth")` and was otherwise a file nobody greps in
+the middle of a job.
+
+It now reaches the caller at the callsite. An action mapped to a symbol with a
+recorded fact carries a compact `known_limitation` on its result — symbol,
+reality, recommendation, and nothing else, because response weight is a real cost
+on a long grading session and the full entry is one lookup away.
+
+A fact is only attached when the mapping names that exact symbol. Nothing is
+inferred from a similar name: an unrelated explanation stapled to a failure reads
+as a diagnosis, and a wrong diagnosis is worse than none.
+
+**One behaviour refuses rather than warns.** `TimelineItem.CopyGrades` replaces
+the target's grade wholesale — measured by baking each state to a 33-point LUT
+and comparing bytes — returns `True` while doing it, and creates no version to go
+back to. Applied to clips carrying hand-work, that is unrecoverable loss reported
+as success. So actions that call it refuse until the caller passes
+`acknowledge_trap: true`:
+
+```json
+{
+  "success": false,
+  "error": "'timeline_item_color.copy_grades' is refused: its verified behaviour destroys existing work that cannot be recovered afterwards.",
+  "known_limitation": [{"symbol": "TimelineItem.CopyGrades", "reality": "...", "recommended": "..."}],
+  "retry_with": {"acknowledge_trap": true}
+}
+```
+
+The intent is not to forbid the operation — it is to make the caller say out loud
+that they know what it does. Dry runs are exempt: a preview destroys nothing.
+
+Set `RESOLVE_MCP_DISABLE_TRAP_GUARD=1` to turn both the refusal and the advisory
+push off. This is a behaviour change for callers that previously received a bare
+`{"success": true}` from a destructive copy.
+
+Facts that power a refusal must stay re-measurable, so a live probe re-derives
+each one and records `drifted` when Resolve stops agreeing; a test fails if a
+`destroys_prior_work` entry has no probe.
+
 ## Optional Extras
 
 The core install is deliberately small: Python, ffmpeg, and the Resolve scripting

package/README.zh-CN.md

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

package/docs/SKILL.md

@@ -674,6 +674,7 @@ specific pages. Always confirm or switch pages before calling page-sensitive too
 | Operation category | Required page | How to switch |
 |---|---|---|
 | Color grading, node graphs, CDL | Color | `resolve_control(action="open_page", params={"page": "color"})` |
+| LUT export (`export_lut`, `safe_export_lut`) | Color — measured `False` from media, edit, fusion, fairlight and deliver | `resolve_control(action="open_page", params={"page": "color"})` |
 | Gallery stills export, `grab_and_export` | Color, Gallery panel open | `resolve_control` + open Gallery panel in Workspace menu |
 | Fusion compositions (page comp) | Fusion | `resolve_control(action="open_page", params={"page": "fusion"})` |
 | Timeline editing, track operations | Edit or Cut | `resolve_control(action="open_page", params={"page": "edit"})` |
@@ -2332,6 +2333,24 @@ Resolve API returned `False`. This usually means a precondition was not met
 
 ## Known Gotchas
 
+### `copy_grades` refuses until you acknowledge it
+
+`TimelineItem.CopyGrades` **replaces** the target's grade — it does not merge —
+returns `True` while doing it, and creates no version to roll back to. Measured on
+Studio 21.1.0.14 by baking each state to a 33-point LUT: after the copy the
+target's LUT is byte-identical to the source's. Pointed at clips someone graded by
+hand, that is unrecoverable loss reported as success.
+
+So `copy_grades`, `safe_copy_grade`, `bulk_match_to_hero` and
+`timeline.apply_look_to_items` refuse until you pass `acknowledge_trap: true`. The
+refusal carries the measured fact in `known_limitation`. Before acknowledging,
+confirm the targets are actually uniform — export each one's LUT on the Color page
+and compare — rather than assuming a group shares a grade.
+
+Other recorded traps ride along on results as `known_limitation` without blocking.
+`RESOLVE_MCP_DISABLE_TRAP_GUARD=1` disables both behaviours.
+
+
 **Resolve API object lifetimes** — Objects like timelines, clips, and color groups
 returned by the API are live references that can become stale if the project state
 changes (e.g., the user deletes a timeline). Always re-fetch IDs after any

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 41 missing capabilities, 52 bugs / unreliable behaviors.
+**Totals:** 41 missing capabilities, 53 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -768,3 +768,11 @@ values, or automation-hostile modal prompts.
 - **Behavior:** Reported by @legionsound (issue #207) from Studio 21.1.0.14 on macOS; NOT reproduced here (no 21.1 install). The documented success result is None. A minimal identity transform written across several lines — `__DEVICE__ float3 transform(...)` with the body on its own lines — validates (None). The SAME function collapsed onto one line consistently returns 'DCTL Error: main DCTL function does not have return value.', which is false: the return statement is there. A genuinely invalid source returns 'cannot find main DCTL function.', so the validator does distinguish; it is the single-line layout it misreads. An earlier multi-line timeout did not reproduce after a Resolve restart with a 30-second limit. Nothing establishes a GPU compiler or render defect — this is the validator's parse, not the DCTL's execution. EncryptDCTL untested.
 - **Workaround / current handling:** Any wrapper around ValidateDCTL must pass the native diagnostic through verbatim and must not reflow or rewrite the user's source to dodge it; ship the multi-line identity fixture as the known-good control. A 'no return value' error on a one-line function is this quirk, not a missing return — re-run the validation with the function laid out across lines before believing it. This server's own `dctl validate` is a static, offline check (entry point, brace balance, float suffixes) and does not call ValidateDCTL at all. The separate `dctl validate_native` and granular `validate_dctl_native` now expose the native validator without changing source or diagnostics. Both interfaces were contributor-validated against the three fixtures on Studio 21.1.0.14; see resolve211-dctl-validation.md.
 - **Tags:** dctl, validation, unreliable-return, version-gated, reported
+
+### TimelineItem.ExportLUT
+
+- **Object:** `TimelineItem`
+- **Signature:** `(exportType, path) -> bool`
+- **Behavior:** Gated on the Color page. Measured on all six pages: returns False from media, edit, fusion, fairlight and deliver, and True only from color. The refusal is a bare False with no reason. It does at least fail cleanly - no file is written on the failing pages, so there is no stale-file trap here.
+- **Workaround / current handling:** resolve.OpenPage('color') before the call and restore the prior page afterwards. Treat a False as 'you were on the wrong page' before suspecting the path.
+- **Tags:** page-gated, silent-failure, lut

package/install.py

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

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "3.4.0"
+VERSION = "4.0.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 377-tool granular server instead
 """
 
-VERSION = "3.4.0"
+VERSION = "4.0.0"
 
 import base64
 import os

package/src/utils/api_truth.py

@@ -24,7 +24,7 @@ When you add or change a ``submit``-tagged entry, regenerate the report
 (``venv/bin/python scripts/gen_api_limitations.py``) or the
 ``tests.test_api_limitations_doc`` drift guard fails.
 """
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Tuple
 
 VERIFIED_ON = "DaVinci Resolve Studio 21.0.2"
 
@@ -116,6 +116,10 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "which does exactly that.",
         "tags": ["unreliable-return", "project", "flaky", "session-lock"],
         "submit": "bug",
+        "verified_on": "DaVinci Resolve Studio 21.1.0.14",
+        "reconfirmed": "2026-09-09: still true on 21.1.0.14. Delete with another "
+                       "project current returned False; CloseProject on the target "
+                       "then delete returned True, first attempt.",
     },
     {
         "symbol": "Project.SetSetting('timelinePlaybackFrameRate')",
@@ -3272,6 +3276,76 @@ API_TRUTH: List[Dict[str, Any]] = [
         "tags": ["dctl", "validation", "unreliable-return", "version-gated", "reported"],
         "submit": "bug",
     },
+    # ── Measured on Studio 21.1.0.14, 2026-09-09 (trap-aware execution work) ──
+    {
+        "symbol": "TimelineItem.CopyGrades",
+        "object": "TimelineItem",
+        "signature": "(tgtTimelineItems) -> bool",
+        "reality": "REPLACES the target's grade wholesale; it does not merge. "
+                   "Measured by exporting a 33-point LUT from the target before "
+                   "and after: after the copy the target's LUT is byte-identical "
+                   "to the source's and differs from the grade the target had. "
+                   "Returns True while doing it. It creates NO grade version - "
+                   "GetVersionNameList is unchanged across the call - so the "
+                   "overwritten grade cannot be recovered.",
+        "recommended": "Never call this on clips carrying hand-work. Prove the "
+                       "targets are uniform first by exporting each one's LUT "
+                       "(Color page) and comparing bytes. If the prior grade has "
+                       "any value, call TimelineItem.AddVersion() first - the "
+                       "copy will not make a restore point for you.",
+        "tags": ["destructive", "unrecoverable", "grade", "no-version"],
+        "destroys_prior_work": True,
+        "verified_on": "DaVinci Resolve Studio 21.1.0.14",
+    },
+    {
+        "symbol": "TimelineItem.ApplyGradeFromStill",
+        "object": "TimelineItem",
+        "reality": "Does not exist. There is no ApplyGradeFromStill on "
+                   "TimelineItem or on Graph in 21.1, and it is absent from the "
+                   "typed stubs. Code calling it raises AttributeError, and any "
+                   "wrapper that swallows that reports success for a grade it "
+                   "never applied.",
+        "recommended": "Use Graph.ApplyGradeFromDRX(path, gradeMode) against a "
+                       "'.drx' (gradeMode 0=no keyframes, 1=source-timecode "
+                       "aligned, 2=start-frame aligned).",
+        "tags": ["missing-method", "grade"],
+        "verified_on": "DaVinci Resolve Studio 21.1.0.14",
+    },
+    {
+        "symbol": "TimelineItem.ExportLUT",
+        "object": "TimelineItem",
+        "signature": "(exportType, path) -> bool",
+        "reality": "Gated on the Color page. Measured on all six pages: returns "
+                   "False from media, edit, fusion, fairlight and deliver, and "
+                   "True only from color. The refusal is a bare False with no "
+                   "reason. It does at least fail cleanly - no file is written "
+                   "on the failing pages, so there is no stale-file trap here.",
+        "recommended": "resolve.OpenPage('color') before the call and restore "
+                       "the prior page afterwards. Treat a False as 'you were on "
+                       "the wrong page' before suspecting the path.",
+        "tags": ["page-gated", "silent-failure", "lut"],
+        "submit": "bug",
+        "verified_on": "DaVinci Resolve Studio 21.1.0.14",
+    },
+    {
+        "symbol": "Timeline.DuplicateTimeline",
+        "object": "Timeline",
+        "signature": "(timelineName) -> Timeline",
+        "reality": "Silently moves the project's current-timeline pointer to the "
+                   "new duplicate. The return value is the duplicate and nothing "
+                   "signals that 'current' changed, so every subsequent mutation "
+                   "lands in the copy while the caller believes it is still "
+                   "editing the original.",
+        "recommended": "Capture GetCurrentTimeline() before the call and "
+                       "SetCurrentTimeline() back after it, checking the return "
+                       "- SetCurrentTimeline restores it and returns True. "
+                       "Never discard that boolean. "
+                       "src/utils/timeline_versioning.py:archive_current_timeline "
+                       "already does this and fails loudly if the restore fails.",
+        "tags": ["side-effect", "silent-failure", "timeline"],
+        "verified_on": "DaVinci Resolve Studio 21.1.0.14",
+    },
+
 ]
 
 
@@ -3308,3 +3382,64 @@ def submittable_limitations() -> Dict[str, List[Dict[str, Any]]]:
         if kind in groups:
             groups[kind].append(e)
     return groups
+
+
+# ── Action → Resolve symbol registry ─────────────────────────────────────────
+#
+# Which Resolve symbols a compound (tool, action) actually calls. Used to push
+# the relevant fact to the caller at the moment of the call instead of waiting
+# for someone to think to query this file.
+#
+# Every mapping is declared explicitly and matched by exact symbol equality.
+# Substring or fuzzy matching is forbidden here for the reason given in
+# `server._setting_limitation`: attaching an unrelated explanation to a call
+# reads as a diagnosis, and a wrong diagnosis is worse than none. A guard
+# (`tests/test_action_symbol_registry.py`) asserts every symbol named below is a
+# real API_TRUTH entry and every action is a real handler.
+ACTION_SYMBOLS: Dict[Tuple[str, str], List[str]] = {
+    ("timeline_item_color", "copy_grades"): ["TimelineItem.CopyGrades"],
+    ("timeline_item_color", "safe_copy_grade"): ["TimelineItem.CopyGrades"],
+    ("timeline_item_color", "bulk_match_to_hero"): ["TimelineItem.CopyGrades"],
+    ("timeline", "apply_look_to_items"): ["TimelineItem.CopyGrades"],
+    ("timeline_item_color", "export_lut"): ["TimelineItem.ExportLUT"],
+    ("timeline_item_color", "safe_export_lut"): ["TimelineItem.ExportLUT"],
+    ("timeline", "duplicate"): ["Timeline.DuplicateTimeline"],
+}
+
+
+def _entry_for_symbol(symbol: str) -> Optional[Dict[str, Any]]:
+    """The single entry whose `symbol` is exactly `symbol`."""
+    for entry in API_TRUTH:
+        if entry.get("symbol") == symbol:
+            return entry
+    return None
+
+
+def traps_for(tool: str, action: str) -> List[Dict[str, Any]]:
+    """Verified facts for the symbols this (tool, action) actually calls.
+
+    Exact matches only — an action with no declared mapping returns nothing
+    rather than guessing.
+    """
+    out: List[Dict[str, Any]] = []
+    for symbol in ACTION_SYMBOLS.get((tool, action), ()):
+        entry = _entry_for_symbol(symbol)
+        if entry is not None:
+            out.append(entry)
+    return out
+
+
+def trap_notice(entry: Dict[str, Any]) -> Dict[str, str]:
+    """The compact push form: what it does, what to do instead.
+
+    Deliberately three fields. A full entry carries signature, tags, submit
+    status and mitigation lists that cost tokens on every single call and tell
+    the caller nothing they can act on at the callsite. Response weight is a
+    real cost on long grading sessions, so the push stays small and the full
+    entry stays one `resolve_control(action="api_truth")` away.
+    """
+    return {
+        "symbol": entry.get("symbol", ""),
+        "reality": entry.get("reality", ""),
+        "recommended": entry.get("recommended", ""),
+    }

package/src/utils/color_grade_live_probe.py

@@ -3,6 +3,7 @@
 
 from __future__ import annotations
 
+import hashlib
 import json
 import os
 import platform
@@ -141,6 +142,192 @@ def _redact_file_payloads(result: Dict[str, Any]) -> Dict[str, Any]:
     return redacted
 
 
+
+# ── api_truth re-verification ────────────────────────────────────────────────
+#
+# The entries these confirm were measured on Studio 21.1.0.14. A fact nobody can
+# re-measure decays into folklore the moment Blackmagic ships a build, so each
+# check below re-derives the behaviour and records `drifted` when what it sees
+# stops matching what api_truth claims. The point is not to pass; it is to
+# notice when the answer changes.
+
+_LUT_PAGES = ("media", "edit", "fusion", "fairlight", "deliver", "color")
+
+
+def _lut_digest(path: Path) -> Optional[str]:
+    try:
+        return hashlib.md5(path.read_bytes()).hexdigest()
+    except OSError:
+        return None
+
+
+def _verify_copygrades_replaces_wholesale(recorder, resolve, items, work_dir: Path) -> None:
+    """TimelineItem.CopyGrades: does it still replace, and still leave no version?
+
+    Measured by baking each state to a 33-point LUT and comparing bytes. There is
+    no GetCDL to read back, and GetToolsInNode reports only which tools exist —
+    it returns the same list either way — so the exported LUT is the only handle
+    on what the grade actually became.
+    """
+    if len(items) < 2:
+        recorder.record("api_truth", "CopyGrades_replaces_wholesale", "not_applicable",
+                        details={"reason": "probe timeline has fewer than two items"})
+        return
+
+    src, tgt = items[0], items[1]
+    lut_type = resolve.EXPORT_LUT_33PTCUBE
+    hand = work_dir / "trap_target_handwork.cube"
+    source = work_dir / "trap_source_grade.cube"
+    after = work_dir / "trap_target_after_copy.cube"
+
+    # Every return here is checked. SetCDL and ExportLUT both report refusal as a
+    # bare False, and a probe that grades nothing, exports nothing, and then
+    # compares two identical empty LUTs would conclude "no replacement" with
+    # total confidence. A measurement built on unchecked setup is worse than no
+    # measurement, because it gets written down as a fact.
+    setup: Dict[str, bool] = {}
+    try:
+        setup["target_reset"] = bool(tgt.GetNodeGraph().ResetAllGrades())
+        setup["target_setcdl"] = bool(tgt.SetCDL(
+            {"NodeIndex": "1", "Slope": "0.5 0.5 1.5", "Offset": "0.1 0.1 0.1",
+             "Power": "1.0 1.0 1.0", "Saturation": "0.3"}))
+        versions_before = list(tgt.GetVersionNameList(0) or [])
+        setup["export_handwork"] = bool(tgt.ExportLUT(lut_type, str(hand)))
+
+        setup["source_reset"] = bool(src.GetNodeGraph().ResetAllGrades())
+        setup["source_setcdl"] = bool(src.SetCDL(
+            {"NodeIndex": "1", "Slope": "2.0 1.0 1.0", "Offset": "0.0 0.0 0.0",
+             "Power": "1.0 1.0 1.0", "Saturation": "1.0"}))
+        setup["export_source"] = bool(src.ExportLUT(lut_type, str(source)))
+
+        returned = bool(src.CopyGrades([tgt]))
+        setup["export_after"] = bool(tgt.ExportLUT(lut_type, str(after)))
+        versions_after = list(tgt.GetVersionNameList(0) or [])
+    except Exception as exc:  # noqa: BLE001 - a probe reports, it does not raise
+        recorder.record_exception("api_truth", "CopyGrades_replaces_wholesale", exc)
+        return
+
+    # Only the calls the measurement actually depends on can abort it. The two
+    # resets are best-effort tidying: the stubs type ResetAllGrades as -> bool,
+    # but "nothing to reset" plausibly returns False on an already-clean graph,
+    # and gating on that would abort every run. Their returns are still recorded
+    # rather than dropped.
+    required = ("target_setcdl", "export_handwork",
+                "source_setcdl", "export_source", "export_after")
+    failed_setup = sorted(k for k in required if not setup.get(k))
+    if failed_setup:
+        recorder.record(
+            "api_truth", "CopyGrades_replaces_wholesale", "error",
+            details={"setup": setup, "failed_setup": failed_setup,
+                     "reason": "probe setup did not take, so nothing below would be "
+                               "a measurement of CopyGrades"},
+        )
+        _cleanup_exported_files([{"path": str(f)} for f in (hand, source, after)])
+        return
+
+    d_hand, d_source, d_after = _lut_digest(hand), _lut_digest(source), _lut_digest(after)
+    replaced = d_after is not None and d_after == d_source and d_after != d_hand
+    made_version = versions_after != versions_before
+
+    details = {
+        "setup": setup,
+        "copygrades_returned": returned,
+        "handwork_digest": d_hand,
+        "source_digest": d_source,
+        "target_after_copy_digest": d_after,
+        "target_became_byte_identical_to_source": replaced,
+        "versions_before": versions_before,
+        "versions_after": versions_after,
+        "created_a_recovery_version": made_version,
+        "api_truth_claims": "replaces wholesale, returns True, creates no version",
+    }
+    # api_truth says: replaced and unrecoverable. Anything else is news.
+    if replaced and not made_version:
+        recorder.record("api_truth", "CopyGrades_replaces_wholesale", "supported", details=details)
+    else:
+        details["drifted"] = (
+            "CopyGrades no longer matches its api_truth entry — re-read the entry "
+            "and the destroys_prior_work flag before trusting either."
+        )
+        recorder.record("api_truth", "CopyGrades_replaces_wholesale", "error", details=details)
+
+    _cleanup_exported_files([{"path": str(f)} for f in (hand, source, after)])
+
+
+def _verify_exportlut_page_gate(recorder, server, resolve, items, work_dir: Path) -> None:
+    """TimelineItem.ExportLUT: still Color-page only, still no stale file?"""
+    if not items:
+        recorder.record("api_truth", "ExportLUT_page_gated", "not_applicable",
+                        details={"reason": "no timeline items"})
+        return
+
+    item = items[0]
+    lut_type = resolve.EXPORT_LUT_33PTCUBE
+    by_page = {}
+    written = []
+    try:
+        for page in _LUT_PAGES:
+            server.resolve_control("open_page", {"page": page})
+            out = work_dir / f"trap_lut_{page}.cube"
+            returned = bool(item.ExportLUT(lut_type, str(out)))
+            exists = out.exists()
+            by_page[page] = {"returned": returned, "wrote_file": exists}
+            if exists:
+                written.append({"path": str(out)})
+        server.resolve_control("open_page", {"page": "color"})
+    except Exception as exc:  # noqa: BLE001
+        recorder.record_exception("api_truth", "ExportLUT_page_gated", exc)
+        return
+
+    off_page = [p for p in _LUT_PAGES if p != "color"]
+    gated = (
+        by_page.get("color", {}).get("returned") is True
+        and all(by_page[p]["returned"] is False for p in off_page)
+    )
+    stale = [p for p in off_page if by_page[p]["wrote_file"]]
+
+    details = {"by_page": by_page, "stale_files_written_on_failure": stale,
+               "api_truth_claims": "True only on color; no file written elsewhere"}
+    if gated and not stale:
+        recorder.record("api_truth", "ExportLUT_page_gated", "version_or_page_dependent", details=details)
+    else:
+        details["drifted"] = "ExportLUT page behaviour no longer matches its api_truth entry."
+        recorder.record("api_truth", "ExportLUT_page_gated", "error", details=details)
+
+    _cleanup_exported_files(written)
+
+
+def _verify_duplicatetimeline_moves_pointer(recorder, project, timeline) -> None:
+    """Timeline.DuplicateTimeline: does it still silently steal `current`?"""
+    try:
+        before_id = timeline.GetUniqueId()
+        dup = timeline.DuplicateTimeline("Trap Probe Duplicate")
+        if dup is None:
+            recorder.record("api_truth", "DuplicateTimeline_moves_current", "error",
+                            details={"reason": "DuplicateTimeline returned None"})
+            return
+        current = project.GetCurrentTimeline()
+        moved = bool(current) and current.GetUniqueId() != before_id
+        restored, _ = set_current_timeline(project, timeline)
+    except Exception as exc:  # noqa: BLE001
+        recorder.record_exception("api_truth", "DuplicateTimeline_moves_current", exc)
+        return
+
+    details = {
+        "current_moved_to_duplicate": moved,
+        "setcurrenttimeline_restored_it": bool(restored),
+        "api_truth_claims": "the pointer moves to the duplicate; SetCurrentTimeline restores it",
+    }
+    if moved and restored:
+        recorder.record("api_truth", "DuplicateTimeline_moves_current", "supported", details=details)
+    else:
+        details["drifted"] = (
+            "DuplicateTimeline pointer behaviour changed — timeline_versioning "
+            "compensates for it, so check that code too."
+        )
+        recorder.record("api_truth", "DuplicateTimeline_moves_current", "error", details=details)
+
+
 def run_probe(server, output_dir: Path, keep_open: bool = False) -> Dict[str, Any]:
     output_dir.mkdir(parents=True, exist_ok=True)
     work_dir = Path(tempfile.mkdtemp(prefix="mcp_color_grade_probe_"))
@@ -415,6 +602,12 @@ def run_probe(server, output_dir: Path, keep_open: bool = False) -> Dict[str, An
             server.timeline_item_color("grade_boundary_report", {**scope, "include_timeline_graph": True}),
         )
 
+        # Re-measure the api_truth entries this probe is the home for. Runs last:
+        # it deliberately overwrites grades on the probe clips.
+        _verify_copygrades_replaces_wholesale(recorder, resolve, items, work_dir)
+        _verify_exportlut_page_gate(recorder, server, resolve, items, work_dir)
+        _verify_duplicatetimeline_moves_pointer(recorder, project, timeline)
+
         if keep_open:
             server.project_manager("save")
             print(f"LEFT PROJECT OPEN FOR INSPECTION: {project_name}")

package/src/utils/destructive_hook.py

@@ -33,6 +33,7 @@ import uuid
 from typing import Any, Callable, Dict, FrozenSet, Optional, Tuple
 
 from src.utils import analysis_runs, brain_edits, media_pool_changes, timeline_versioning
+from src.utils.api_truth import traps_for, trap_notice
 from src.utils.execution_lifecycle import RiskAssessment, RiskLevel, classify_operation_risk
 
 logger = logging.getLogger("resolve-mcp.destructive-hook")
@@ -793,6 +794,79 @@ def _extract_metric(params: Optional[Dict[str, Any]]) -> Tuple[Optional[str], Op
 # ── Decorator ────────────────────────────────────────────────────────────────
 
 
+#: Set truthy to disable the trap guard entirely (both the refusal and the
+#: advisory push). Exists because the refusal is a behaviour change for callers
+#: that previously got a bare `{"success": true}` from a destructive copy.
+TRAP_GUARD_ENV = "RESOLVE_MCP_DISABLE_TRAP_GUARD"
+
+
+def _trap_guard_disabled() -> bool:
+    return os.environ.get(TRAP_GUARD_ENV, "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+#: Actions that already make the caller confirm, so the trap guard must NOT also
+#: refuse them.
+#:
+#: `destroys_prior_work` is a property of the SYMBOL (TimelineItem.CopyGrades),
+#: but four actions call that symbol and two of them already own a confirmation
+#: path. Refusing those means the caller is told to add `acknowledge_trap`, and
+#: only after retrying discovers they also need a confirm token — two
+#: acknowledgements for one operation, found serially. Worse, it lands hardest on
+#: `safe_copy_grade`, whose whole name promises it is the careful route; making
+#: it the most irritating to call pushes people toward the raw `copy_grades` the
+#: guard exists to protect them from.
+#:
+#: Two mechanisms enforcing one rule drift apart. The confirm-token flow is older
+#: and more specific, so it wins and this guard stands down. These actions still
+#: get the advisory `known_limitation` — the fact is worth having, the second
+#: refusal is not.
+TRAP_REFUSAL_EXEMPT_ACTIONS: FrozenSet[Tuple[str, str]] = frozenset({
+    # Issues a confirm_token whose preview names the exact risk: "Replaces the
+    # entire node graph on every successfully resolved target item."
+    ("timeline_item_color", "safe_copy_grade"),
+    # Dry-run-by-default in the handler (`p.get("dry_run", True)`), then
+    # confirm_token to execute. A first call with no params mutates nothing.
+    ("timeline_item_color", "bulk_match_to_hero"),
+})
+
+
+def _trap_acknowledged(params: Optional[Dict[str, Any]]) -> bool:
+    """Did the caller explicitly accept a known-destructive behaviour?"""
+    return bool(isinstance(params, dict) and params.get("acknowledge_trap"))
+
+
+def _trap_block_response(
+    tool_name: str, action: str, blocking: list,
+) -> Dict[str, Any]:
+    """Refuse a call whose verified behaviour destroys unrecoverable work.
+
+    The point is not to forbid the operation — it is to make the caller say out
+    loud that they know what it does. `CopyGrades` returns True while replacing
+    a hand-built grade wholesale and leaving no version to go back to, so a
+    caller who did not know that cannot tell success from loss.
+    """
+    return {
+        "success": False,
+        "error": (
+            f"'{tool_name}.{action}' is refused: its verified behaviour destroys "
+            "existing work that cannot be recovered afterwards. Read "
+            "`known_limitation`, then re-send with acknowledge_trap=true if that "
+            "is genuinely what you want."
+        ),
+        "known_limitation": [trap_notice(e) for e in blocking],
+        "retry_with": {"acknowledge_trap": True},
+        "override_env": TRAP_GUARD_ENV,
+    }
+
+
+def _attach_trap_notices(result: Any, traps: list) -> Any:
+    """Ride the verified fact along on the result, without overwriting one."""
+    if not traps or not isinstance(result, dict):
+        return result
+    result.setdefault("known_limitation", [trap_notice(e) for e in traps])
+    return result
+
+
 def destructive_op(tool_name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
     """Wrap a top-level tool function with the version-on-mutate hook.
 
@@ -802,8 +876,7 @@ def destructive_op(tool_name: str) -> Callable[[Callable[..., Any]], Callable[..
     """
 
     def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
-        @functools.wraps(fn)
-        def wrapper(action: str, params: Optional[Dict[str, Any]] = None, *args, **kwargs) -> Any:
+        def _inner(action: str, params: Optional[Dict[str, Any]] = None, *args, **kwargs) -> Any:
             if lacks_native_dry_run(tool_name, action, params):
                 # An explicit dry-run request this handler would silently
                 # execute for real. Refuse before archive, state lookup, or the
@@ -1151,6 +1224,29 @@ def destructive_op(tool_name: str) -> Callable[[Callable[..., Any]], Callable[..
                 recognised=risk_recognised,
             )
 
+        @functools.wraps(fn)
+        def wrapper(action: str, params: Optional[Dict[str, Any]] = None, *args, **kwargs) -> Any:
+            # Trap push. `_inner` has a dozen return paths (dry-run refusal,
+            # safe-mode block, pending-confirm, strict/no-context, normal); one
+            # outer attach point covers all of them and cannot drift as those
+            # paths change.
+            traps = traps_for(tool_name, action)
+            if traps and not _trap_guard_disabled():
+                blocking = [t for t in traps if t.get("destroys_prior_work")]
+                # A dry run destroys nothing, so there is nothing to acknowledge
+                # — and preempting `_inner` here would swallow its
+                # DRY_RUN_UNAVAILABLE refusal, which is the more important
+                # answer: it tells the caller this action cannot be previewed
+                # at all. The advisory push still rides along on that refusal.
+                if (
+                    blocking
+                    and (tool_name, action) not in TRAP_REFUSAL_EXEMPT_ACTIONS
+                    and not _trap_acknowledged(params)
+                    and not _explicit_dry_run_requested(params)
+                ):
+                    return _trap_block_response(tool_name, action, blocking)
+            return _attach_trap_notices(_inner(action, params, *args, **kwargs), traps)
+
         wrapper.__wrapped_tool_name__ = tool_name  # type: ignore[attr-defined]
         wrapper.__is_destructive_wrapped__ = True  # type: ignore[attr-defined]
         return wrapper