davinci-resolve-mcp 4.2.0 → 4.3.0

package/CHANGELOG.md

@@ -2,6 +2,72 @@
 
 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.3.0 — the granular grade-copy stops replacing grades on clips nobody named
+
+v4.2.0 gated the compound `timeline_item_color copy_grades`. Its granular twin,
+`ti_copy_grades` on the `--full` server, reached the identical
+`TimelineItem.CopyGrades` with no guard at all — and on a surface that addresses
+clips by bare 0-based index rather than by unique ID, which made it the more
+dangerous of the two.
+
+### Fixed
+
+- **`ti_copy_grades` accepted negative indices as valid targets.** The bounds check
+  was `i < len(items)`, which every negative integer passes, so `-1` reached
+  `items[-1]` and confidently graded the **last clip in the track**. An off-by-one
+  did not fail; it replaced the node graph of a clip the caller never named, and
+  `CopyGrades` leaves no version to restore. Indices are now range-checked at both
+  ends, and `bool` is refused explicitly — `True` is an `int` subclass and would
+  otherwise have indexed item 1.
+
+- **Out-of-range indices were silently dropped.** `[i for i in indices if i < len(items)]`
+  discarded anything past the end and reported `success: true` for a copy that
+  reached fewer clips than asked for. They are now refused, with the track's real
+  item count in the response.
+
+### Added
+
+- **`ti_copy_grades` requires `acknowledge_trap`, then a `confirm_token`.** The same
+  two-step gate the compound action got in v4.2.0: the first call refuses with the
+  verified fact about `CopyGrades`, and the second returns a preview naming the
+  source and every resolved target — index, clip name, unique ID and start frame —
+  with a one-time token bound to those exact targets. Change the target list and the
+  token no longer matches.
+
+  **This is a breaking change for existing `ti_copy_grades` callers**, deliberately:
+  a call that used to replace grades now refuses until the caller says twice that it
+  means to. It is versioned as a minor to match v4.2.0, which made the identical
+  change to the compound action.
+
+- **`ti_copy_grades` is now annotated `destructiveHint=True`.** Granular tools infer
+  their MCP safety hint from a name prefix, and `ti_` matches none of the read,
+  write or destructive prefix lists, so every `ti_*` tool falls through to the plain
+  write default. A client that gates on that hint was being told this tool was safe.
+
+### Changed
+
+- **One confirm-token implementation, in `src/utils/confirm_tokens.py`.** The
+  compound and granular servers are separate processes and each holds its own token
+  table — a token from one is not honoured by the other, which is what the
+  `CONFIRM_TOKEN_INVALID` message already said. What is now shared is the mechanism
+  and the on/off policy, rather than a second hand-rolled copy of both. `src/server.py`
+  keeps every private name it had and delegates; the error builder is injected,
+  because the granular tools return plain dicts and the compound server an envelope.
+
+### Validation
+
+- Full offline suite: **3,635 passed, 1 skipped, 0 failed**, 1,257 subtests — the
+  same 3,620 as v4.2.0 plus the 15 new tests, so the token extraction cost no
+  coverage. All release drift guards green.
+- **Live on Studio 19.1.3.7**, against real `TimelineItem` objects: every refusal and
+  preview path — negative index, out-of-range index, `bool` index, empty target list,
+  source listed as its own target — plus the clip-summary reads that build the
+  preview. None of these reach `CopyGrades`, and nothing in the project was mutated.
+- **Not validated live: the accepted-token path itself**, where a valid token is
+  redeemed and `CopyGrades` runs. That needs a disposable two-clip project and was
+  covered offline only. The call it makes is byte-for-byte the one v4.2.0 shipped;
+  what is unproven live is the redemption in front of it.
+
 ## What's New in v4.2.0 — the raw grade-copy asks before it overwrites, and an injected grade shows as graded
 
 Contributed by [@Rohitkanithi](https://github.com/Rohitkanithi) in

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-4.2.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.3.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)

package/README.zh-CN.md

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

package/install.py

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

package/src/granular/common.py

@@ -28,6 +28,11 @@ from src.utils.app_control import (
     restart_resolve_app,
 )
 from src.utils.cdl import normalize_cdl_payload
+from src.utils.confirm_tokens import (
+    ConfirmTokenStore,
+    gate_required_from,
+    plain_error as plain_confirm_error,
+)
 from src.utils.cloud_operations import (
     create_cloud_project,
     import_cloud_project,
@@ -87,7 +92,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.2.0"
+VERSION = "4.3.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")
@@ -797,4 +802,50 @@ def _ai_result_payload(returned):
         payload["error"] = message
     return payload
 
+
+# ── Confirmation gate ────────────────────────────────────────────────────────
+#
+# The granular server is a separate process from the compound one, so it holds its
+# own token table; a token minted here is not honoured there and vice versa. What
+# is shared is the implementation and the on/off policy, from
+# src/utils/confirm_tokens.py — the granular tools return plain dicts rather than
+# the compound envelope, so the error builder is the plain one.
+
+_MEDIA_ANALYSIS_PREFS_ENV = "DAVINCI_RESOLVE_MCP_MEDIA_ANALYSIS_PREFS"
+
+
+def _media_analysis_preferences():
+    """Read the same preferences file the compound server and setup write."""
+    import json
+
+    override = os.environ.get(_MEDIA_ANALYSIS_PREFS_ENV)
+    if override:
+        path = os.path.realpath(os.path.abspath(os.path.expanduser(override)))
+    else:
+        path = os.path.join(PROJECT_DIR, "logs", "media-analysis-preferences.json")
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            payload = json.load(handle)
+        return payload if isinstance(payload, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def _confirm_token_required() -> bool:
+    """Honor the setup default destructive.require_confirm_token (default True)."""
+    try:
+        prefs = _media_analysis_preferences()
+    except Exception:
+        prefs = {}
+    return gate_required_from(prefs)
+
+
+CONFIRM_TOKENS = ConfirmTokenStore(
+    err=plain_confirm_error,
+    # Resolved per call so the preference can be changed without a server restart,
+    # and so tests can patch the module-level function.
+    required=lambda: _confirm_token_required(),
+)
+
+
 __all__ = [name for name in globals() if not name.startswith("__")]

package/src/granular/timeline_item.py

@@ -24,6 +24,28 @@ def _has_audio_type(item):
             or _item_type(item, "GetMediaType") == "audio")
 
 
+def _copy_grade_item_summary(item, index):
+    """Name a clip well enough that a caller can recognise it in a confirmation.
+
+    Every read is guarded: Resolve fabricates a callable for ANY attribute name on
+    its objects, so `getattr(item, "Whatever")` is never absent and a bad call
+    raises rather than returning None. Absent detail degrades the preview; it must
+    not break the gate that the preview exists to serve.
+    """
+    summary = {"index": index}
+    for key, method in (("name", "GetName"), ("id", "GetUniqueId"), ("start", "GetStart")):
+        getter = getattr(item, method, None)
+        if not callable(getter):
+            continue
+        try:
+            value = getter()
+        except Exception:
+            continue
+        if value is not None:
+            summary[key] = value
+    return summary
+
+
 @mcp.resource("resolve://timeline-item/{timeline_item_id}")
 def get_timeline_item_properties(timeline_item_id: str) -> Dict[str, Any]:
     """Get properties of a specific timeline item by ID.
@@ -1891,30 +1913,106 @@ def ti_finalize_take(item_index: int = 0, track_type: str = "video", track_index
     return {"success": bool(item.FinalizeTake())}
 
 
-@mcp.tool()
-def ti_copy_grades(target_item_indices: List[int], track_type: str = "video", track_index: int = 1, source_item_index: int = 0) -> Dict[str, Any]:
-    """Copy grades from one timeline item to others.
+@mcp.tool(annotations=DESTRUCTIVE_TOOL)
+def ti_copy_grades(
+    target_item_indices: List[int],
+    track_type: str = "video",
+    track_index: int = 1,
+    source_item_index: int = 0,
+    acknowledge_trap: bool = False,
+    confirm_token: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Copy grades from one timeline item to others. DESTRUCTIVE — gated.
+
+    `TimelineItem.CopyGrades` replaces each target's ENTIRE node graph with the
+    source's and creates no version to go back to, so a target's hand grade is gone
+    with no way to recover it. Two acknowledgements are required, in order:
+    `acknowledge_trap=true` (you know what the API does), then `confirm_token` from
+    the preview this returns (you have seen which clips it resolved).
 
     Args:
         target_item_indices: List of 0-based indices of target items.
         track_type: 'video' or 'audio'. Default: 'video'.
         track_index: 1-based track index. Default: 1.
         source_item_index: 0-based source item index. Default: 0.
+        acknowledge_trap: Must be true — confirms you accept that target grades are
+            replaced unrecoverably.
+        confirm_token: Token from this tool's own confirmation_required response.
     """
     _, tl, err = _get_timeline()
     if err:
         return err
-    items = tl.GetItemListInTrack(track_type, track_index)
+    items = tl.GetItemListInTrack(track_type, track_index) or []
     if not items:
         return {"error": "No items in track"}
-    source = items[source_item_index] if source_item_index < len(items) else None
-    if not source:
-        return {"error": "Source item not found"}
-    targets = [items[i] for i in target_item_indices if i < len(items)]
-    if not targets:
-        return {"error": "No target items found"}
-    result = source.CopyGrades(targets)
-    return {"success": bool(result)}
+    if not isinstance(target_item_indices, list) or not target_item_indices:
+        return {"error": "target_item_indices must be a non-empty list of 0-based indices"}
+
+    # A negative index is a real Python index: `items[-1]` silently grades the LAST
+    # clip in the track. The old bounds check (`i < len(items)`) let every negative
+    # through, so an off-by-one produced a confident success on the wrong clip.
+    out_of_range = sorted({i for i in target_item_indices
+                           if not isinstance(i, int) or isinstance(i, bool)
+                           or i < 0 or i >= len(items)})
+    if out_of_range:
+        return {"error": f"target_item_indices out of range for {len(items)} items in "
+                         f"{track_type} track {track_index}: {out_of_range}",
+                "track_item_count": len(items)}
+    if not isinstance(source_item_index, int) or isinstance(source_item_index, bool) \
+            or source_item_index < 0 or source_item_index >= len(items):
+        return {"error": f"source_item_index {source_item_index} out of range for "
+                         f"{len(items)} items in {track_type} track {track_index}",
+                "track_item_count": len(items)}
+
+    source = items[source_item_index]
+    # De-duplicate while keeping caller order: grading one clip twice is never what
+    # was meant, and it would double-count the preview the caller confirms against.
+    seen = set()
+    ordered = [i for i in target_item_indices if not (i in seen or seen.add(i))]
+    if source_item_index in seen:
+        return {"error": "source_item_index is also listed in target_item_indices; "
+                         "copying a grade onto its own source is a no-op that would "
+                         "still consume a confirmation"}
+    targets = [items[i] for i in ordered]
+
+    gate_params = {
+        "target_item_indices": ordered,
+        "track_type": track_type,
+        "track_index": track_index,
+        "source_item_index": source_item_index,
+    }
+    if not acknowledge_trap:
+        return {
+            "success": False,
+            "error": "'ti_copy_grades' is refused: TimelineItem.CopyGrades replaces "
+                     "each target's entire node graph and leaves no version to "
+                     "restore. Re-send with acknowledge_trap=true if that is "
+                     "genuinely what you want.",
+            "known_limitation": [
+                "TimelineItem.CopyGrades replaces the target grade wholesale and "
+                "creates no recovery version (measured on Studio 19.1.3.7; "
+                "reconfirmed on Studio 21.1.0.14, issue #207)."
+            ],
+            "retry_with": {"acknowledge_trap": True},
+        }
+    if confirm_token is None and CONFIRM_TOKENS.required():
+        return CONFIRM_TOKENS.issue(
+            action="ti_copy_grades",
+            params=gate_params,
+            preview={
+                "operation": "ti_copy_grades",
+                "warning": "Replaces the entire node graph on every target item.",
+                "source": _copy_grade_item_summary(items[source_item_index], source_item_index),
+                "target_count": len(targets),
+                "targets": [_copy_grade_item_summary(items[i], i) for i in ordered],
+            },
+        )
+    blocked = CONFIRM_TOKENS.consume(action="ti_copy_grades", params={
+        **gate_params, "confirm_token": confirm_token})
+    if blocked:
+        return blocked
+    return {"success": bool(source.CopyGrades(targets)),
+            "target_count": len(targets)}
 
 
 @mcp.tool()

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 377-tool granular server instead
 """
 
-VERSION = "4.2.0"
+VERSION = "4.3.0"
 
 import base64
 import os
@@ -73,6 +73,10 @@ from src.utils.readback import verify_by_readback, verification_stats as _verifi
 from src.utils import operation_result as _operation_result
 from src.utils import operation_log as _operation_log
 from src.utils.bool_params import explicit_bool_param as _explicit_bool_param
+from src.utils.confirm_tokens import (
+    ConfirmTokenStore as _ConfirmTokenStore,
+    gate_required_from as _gate_required_from,
+)
 from src.utils.operation_result import (
     build_operation_envelope as _build_operation_envelope,
     get_envelope_mode as _get_envelope_mode,
@@ -1838,78 +1842,47 @@ import time as _time
 import uuid as _uuid
 
 
-_CONFIRM_TOKENS: Dict[str, Dict[str, Any]] = {}
-# The control panel runs on a threaded HTTP server, so issue/consume/gc of the
-# token table run on concurrent threads. Guard every access so a GC iteration
-# can't race a write and validate-then-pop stays atomic (EX4).
-_CONFIRM_TOKENS_LOCK = threading.RLock()
-_CONFIRM_TTL_SECONDS = 300
+def _confirm_token_required() -> bool:
+    """Honor setup default destructive.require_confirm_token (default True)."""
+    try:
+        prefs = _read_media_analysis_preferences() if "_read_media_analysis_preferences" in globals() else {}
+    except Exception:
+        prefs = {}
+    return _gate_required_from(prefs)
+
+
+#: The token machinery itself lives in src/utils/confirm_tokens.py so the granular
+#: server can run the same gate in its own process — both surfaces reach
+#: TimelineItem.CopyGrades, and a second hand-rolled copy would drift. The names
+#: below stay module-level because callers and tests reach for them directly.
+#:
+#: `required` is a lambda, not `_confirm_token_required` itself, so the global is
+#: resolved on every call: tests patch `_confirm_token_required` on this module, and
+#: binding the function object here would capture the original and make that patch
+#: invisible to the store.
+_CONFIRM_TOKEN_STORE = _ConfirmTokenStore(
+    err=_err,
+    required=lambda: _confirm_token_required(),
+    ttl_seconds=300,
+)
+_CONFIRM_TOKENS: Dict[str, Dict[str, Any]] = _CONFIRM_TOKEN_STORE.tokens
+_CONFIRM_TOKENS_LOCK = _CONFIRM_TOKEN_STORE.lock
+_CONFIRM_TTL_SECONDS = _CONFIRM_TOKEN_STORE.ttl_seconds
 
 
 def _confirm_token_fingerprint(action: str, params: Optional[Dict[str, Any]]) -> str:
     """Stable hash of (action, params) that identifies one specific mutation request."""
-    payload = {"action": action, "params": params or {}}
-    # Strip the confirm_token itself if the caller is echoing it back to us.
-    if isinstance(payload["params"], dict) and "confirm_token" in payload["params"]:
-        payload["params"] = {k: v for k, v in payload["params"].items() if k != "confirm_token"}
-    try:
-        blob = json.dumps(payload, sort_keys=True, default=str)
-    except Exception:
-        blob = repr(payload)
-    return _hashlib.sha256(blob.encode("utf-8")).hexdigest()[:16]
+    return _CONFIRM_TOKEN_STORE.fingerprint(action, params)
 
 
 def _confirm_token_gc():
-    """Drop expired tokens; called on every issue/validate. Caller may already
-    hold _CONFIRM_TOKENS_LOCK (RLock makes re-entry safe)."""
-    now = _time.time()
-    with _CONFIRM_TOKENS_LOCK:
-        expired = [t for t, rec in _CONFIRM_TOKENS.items() if rec.get("expires_at", 0) < now]
-        for t in expired:
-            _CONFIRM_TOKENS.pop(t, None)
-
-
-def _confirm_token_required() -> bool:
-    """Honor setup default destructive.require_confirm_token (default True)."""
-    try:
-        prefs = _read_media_analysis_preferences() if "_read_media_analysis_preferences" in globals() else {}
-    except Exception:
-        prefs = {}
-    destructive = prefs.get("destructive") if isinstance(prefs.get("destructive"), dict) else {}
-    val = destructive.get("require_confirm_token", True)
-    if isinstance(val, str):
-        return val.strip().lower() not in {"0", "false", "no", "off"}
-    return bool(val)
+    """Drop expired tokens; called on every issue/validate."""
+    _CONFIRM_TOKEN_STORE.gc()
 
 
 def _issue_confirm_token(*, action: str, params: Optional[Dict[str, Any]], preview: Dict[str, Any]) -> Dict[str, Any]:
     """Mint a token. Returns the pending_user_decision response shape."""
-    token = _uuid.uuid4().hex
-    fp = _confirm_token_fingerprint(action, params)
-    expires_at = _time.time() + _CONFIRM_TTL_SECONDS
-    with _CONFIRM_TOKENS_LOCK:
-        _confirm_token_gc()
-        _CONFIRM_TOKENS[token] = {
-            "action": action,
-            "fingerprint": fp,
-            "expires_at": expires_at,
-            "issued_at": _time.time(),
-        }
-    body = _err(
-        f"This action is destructive. Re-call with confirm_token to proceed.",
-        code="CONFIRMATION_REQUIRED",
-        category="pending_user_decision",
-        retryable=False,
-        remediation=f"Re-call {action} with params.confirm_token={token!r}; token expires in {_CONFIRM_TTL_SECONDS}s.",
-    )
-    body.update({
-        "status": "confirmation_required",
-        "confirm_token": token,
-        "preview": preview,
-        "expires_at_epoch": expires_at,
-        "ttl_seconds": _CONFIRM_TTL_SECONDS,
-    })
-    return body
+    return _CONFIRM_TOKEN_STORE.issue(action=action, params=params, preview=preview)
 
 
 def _consume_confirm_token(*, action: str, params: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
@@ -1917,41 +1890,7 @@ def _consume_confirm_token(*, action: str, params: Optional[Dict[str, Any]]) ->
     If missing/expired/mismatched, return a destructive_blocked error.
     If gating is disabled, return None (proceed).
     """
-    if not _confirm_token_required():
-        return None
-    token = (params or {}).get("confirm_token") or (params or {}).get("confirmToken")
-    if not token:
-        return None  # Caller is expected to call _issue_confirm_token in this case.
-    with _CONFIRM_TOKENS_LOCK:
-        _confirm_token_gc()
-        rec = _CONFIRM_TOKENS.pop(token, None)  # one-time use, atomic with gc
-    if rec is None:
-        return _err(
-            "confirm_token is invalid, expired, or was issued by a different "
-            "server instance (tokens are valid only on the instance that "
-            "issued them — e.g. a stdio-server token is not honored by the "
-            "networked server).",
-            code="CONFIRM_TOKEN_INVALID",
-            category="destructive_blocked",
-            retryable=False,
-            remediation=f"Re-call {action} without confirm_token on this instance to receive a fresh token.",
-        )
-    if rec.get("action") != action:
-        return _err(
-            f"confirm_token issued for {rec.get('action')!r}, not {action!r}",
-            code="CONFIRM_TOKEN_ACTION_MISMATCH",
-            category="destructive_blocked",
-            retryable=False,
-        )
-    if rec.get("fingerprint") != _confirm_token_fingerprint(action, params):
-        return _err(
-            "confirm_token does not match the current params",
-            code="CONFIRM_TOKEN_FINGERPRINT_MISMATCH",
-            category="destructive_blocked",
-            retryable=False,
-            remediation="Either re-issue the token with current params or roll back the params change.",
-        )
-    return None  # OK to proceed
+    return _CONFIRM_TOKEN_STORE.consume(action=action, params=params)
 
 
 def _activate_resolve_window() -> Dict[str, Any]:

package/src/utils/confirm_tokens.py

@@ -0,0 +1,222 @@
+"""One confirm-token implementation, shared by the compound and granular servers.
+
+A confirm token is the last barrier in front of a mutation that cannot be undone:
+the first call mints a token and returns a preview *instead of acting*, and only a
+second call carrying that token is allowed through. Tokens are short-lived,
+single-use, bound to one action name, and bound to a fingerprint of the params, so
+a token issued for one target set is refused when the targets change.
+
+Tokens live in the process that issued them. The compound server and the granular
+(`--full`) server are separate processes and therefore hold separate stores; a
+token from one is not honoured by the other, which is what the CONFIRM_TOKEN_INVALID
+message says out loud. Sharing this module shares the *implementation*, never the
+state.
+
+That distinction is the reason this file exists. Both servers reach
+`TimelineItem.CopyGrades`, which replaces a target's whole node graph and leaves no
+version to go back to, so both need the same gate — and a second hand-rolled copy of
+it would drift from this one exactly the way seventeen copies of the live-harness
+stub installer drifted before v4.1.3. The error builder differs between the two
+surfaces (the compound server has a structured envelope, the granular server returns
+plain dicts), so it is injected rather than assumed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import threading
+import time
+import uuid
+from typing import Any, Callable, Dict, Optional
+
+#: Long enough for a human to read a preview and decide, short enough that a token
+#: left lying around in a transcript is not a standing authorisation.
+DEFAULT_TTL_SECONDS = 300
+
+
+#: Preference key that switches the gate off, and the file both servers read it from.
+PREFERENCE_KEY = "require_confirm_token"
+PREFERENCE_SECTION = "destructive"
+
+
+def gate_required_from(preferences: Optional[Dict[str, Any]]) -> bool:
+    """Read `destructive.require_confirm_token` out of a preferences payload.
+
+    The policy — default on, and the exact set of strings that count as off — is
+    shared even though each server reads the preferences file for itself, because
+    the default is the part that must never drift. A surface that defaulted this to
+    False would silently have no gate at all while still looking gated in code.
+    """
+    if not isinstance(preferences, dict):
+        return True
+    section = preferences.get(PREFERENCE_SECTION)
+    if not isinstance(section, dict):
+        return True
+    value = section.get(PREFERENCE_KEY, True)
+    if isinstance(value, str):
+        return value.strip().lower() not in {"0", "false", "no", "off"}
+    return bool(value)
+
+
+def plain_error(message: str, **fields: Any) -> Dict[str, Any]:
+    """Error builder for surfaces with no structured envelope (the granular server).
+
+    Keeps the diagnostic fields the confirm flow relies on — `code` above all, since
+    that is what a caller branches on — without inventing an envelope the granular
+    tools do not otherwise emit.
+    """
+    body: Dict[str, Any] = {"success": False, "error": message}
+    for key, value in fields.items():
+        if value is not None:
+            body[key] = value
+    return body
+
+
+class ConfirmTokenStore:
+    """Mint, hold and redeem one-time confirmation tokens.
+
+    `required` and `err` are callables rather than values so that a caller can swap
+    either at runtime: the compound server's preference lookup is patched by tests
+    on the module object, and resolving it per call is what makes that patch visible
+    here instead of being captured once at construction.
+    """
+
+    def __init__(
+        self,
+        *,
+        err: Callable[..., Dict[str, Any]],
+        required: Optional[Callable[[], bool]] = None,
+        ttl_seconds: int = DEFAULT_TTL_SECONDS,
+    ) -> None:
+        self._err = err
+        self._required = required if required is not None else (lambda: True)
+        self.ttl_seconds = ttl_seconds
+        self.tokens: Dict[str, Dict[str, Any]] = {}
+        # The control panel runs on a threaded HTTP server, so issue/consume/gc can
+        # run on concurrent threads. Guard every access so a GC pass cannot race a
+        # write and so validate-then-pop stays atomic.
+        self.lock = threading.RLock()
+
+    # ── internals ────────────────────────────────────────────────────────────
+
+    def required(self) -> bool:
+        """Is the gate switched on right now?"""
+        return bool(self._required())
+
+    def fingerprint(self, action: str, params: Optional[Dict[str, Any]]) -> str:
+        """Stable hash of (action, params) identifying one specific mutation request."""
+        payload = {"action": action, "params": params or {}}
+        # Strip the token itself if the caller is echoing it back to us, so the
+        # fingerprint of "the request" is the same before and after issuance.
+        if isinstance(payload["params"], dict) and "confirm_token" in payload["params"]:
+            payload["params"] = {
+                k: v for k, v in payload["params"].items() if k != "confirm_token"
+            }
+        try:
+            blob = json.dumps(payload, sort_keys=True, default=str)
+        except Exception:
+            blob = repr(payload)
+        return hashlib.sha256(blob.encode("utf-8")).hexdigest()[:16]
+
+    def gc(self) -> None:
+        """Drop expired tokens. Callers may already hold the lock; RLock re-entry is safe."""
+        now = time.time()
+        with self.lock:
+            expired = [t for t, rec in self.tokens.items() if rec.get("expires_at", 0) < now]
+            for token in expired:
+                self.tokens.pop(token, None)
+
+    # ── the gate ─────────────────────────────────────────────────────────────
+
+    def issue(
+        self,
+        *,
+        action: str,
+        params: Optional[Dict[str, Any]],
+        preview: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        """Mint a token and return the pending_user_decision response shape."""
+        token = uuid.uuid4().hex
+        expires_at = time.time() + self.ttl_seconds
+        with self.lock:
+            self.gc()
+            self.tokens[token] = {
+                "action": action,
+                "fingerprint": self.fingerprint(action, params),
+                "expires_at": expires_at,
+                "issued_at": time.time(),
+            }
+        body = self._err(
+            "This action is destructive. Re-call with confirm_token to proceed.",
+            code="CONFIRMATION_REQUIRED",
+            category="pending_user_decision",
+            retryable=False,
+            remediation=(
+                f"Re-call {action} with params.confirm_token={token!r}; "
+                f"token expires in {self.ttl_seconds}s."
+            ),
+        )
+        body.update({
+            "status": "confirmation_required",
+            "confirm_token": token,
+            "preview": preview,
+            "expires_at_epoch": expires_at,
+            "ttl_seconds": self.ttl_seconds,
+        })
+        return body
+
+    def consume(
+        self,
+        *,
+        action: str,
+        params: Optional[Dict[str, Any]],
+    ) -> Optional[Dict[str, Any]]:
+        """Redeem a token.
+
+        Returns None when the call may proceed — which covers three distinct cases:
+        gating is switched off, no token was supplied (the caller is expected to
+        call `issue` in that case), or the token was valid and has now been spent.
+        Returns an error body when a token was supplied but is not good.
+        """
+        if not self.required():
+            return None
+        token = (params or {}).get("confirm_token") or (params or {}).get("confirmToken")
+        if not token:
+            return None  # Caller is expected to call issue() in this case.
+        with self.lock:
+            self.gc()
+            rec = self.tokens.pop(token, None)  # one-time use, atomic with gc
+        if rec is None:
+            return self._err(
+                "confirm_token is invalid, expired, or was issued by a different "
+                "server instance (tokens are valid only on the instance that "
+                "issued them — e.g. a stdio-server token is not honored by the "
+                "networked server).",
+                code="CONFIRM_TOKEN_INVALID",
+                category="destructive_blocked",
+                retryable=False,
+                remediation=(
+                    f"Re-call {action} without confirm_token on this instance to "
+                    "receive a fresh token."
+                ),
+            )
+        if rec.get("action") != action:
+            return self._err(
+                f"confirm_token issued for {rec.get('action')!r}, not {action!r}",
+                code="CONFIRM_TOKEN_ACTION_MISMATCH",
+                category="destructive_blocked",
+                retryable=False,
+            )
+        if rec.get("fingerprint") != self.fingerprint(action, params):
+            return self._err(
+                "confirm_token does not match the current params",
+                code="CONFIRM_TOKEN_FINGERPRINT_MISMATCH",
+                category="destructive_blocked",
+                retryable=False,
+                remediation=(
+                    "Either re-issue the token with current params or roll back "
+                    "the params change."
+                ),
+            )
+        return None  # OK to proceed