davinci-resolve-mcp 2.208.0 → 2.209.0

package/CHANGELOG.md

@@ -2,6 +2,87 @@
 
 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.209.0 — safe operations policy
+
+### Added
+
+- **Destructive operations now carry explicit security metadata** — wrapped
+  destructive tool calls receive an `operation_id` plus a `security` block with
+  a `risk_level` (`low`, `medium`, `high`, or `critical`) and a
+  `risk_established` flag. The existing version-on-mutate and confirm-token
+  gates stay intact, but callers now have a stable policy surface to inspect
+  and display before or after a Resolve mutation.
+
+  Levels come from the same classifier that backs pre-flight
+  `inspect_operation`, so the gate and the inspection surface cannot disagree
+  about a call. `risk_established` is false when the classifier matched no rule
+  and the level is a name-based default rather than a finding — true today for
+  80 of the 108 registered destructive actions, which is a gap to close by
+  classifying them, not by gating them.
+- **Safe mode blocks high-risk destructive calls when enabled** —
+  `setup(action="set_defaults", params={"destructive": {"safe_mode": true}})`
+  blocks `high` and `critical` actions before the underlying Resolve handler
+  runs. Reviewed one-off calls can proceed with `allow_risky_operation=true`.
+  Unclassified actions are reported, not blocked.
+- **Security audit JSONL for destructive calls** — allowed, blocked, and
+  pending-confirmation destructive calls write audit events to
+  `logs/security-audit.jsonl` by default. Confirmation tokens are redacted in
+  the audit payload.
+
+### Changed
+
+- **Risk classification is now one table, not two** — the marker and
+  clip-colour actions classify as `low` instead of falling through the name
+  heuristic as unrecognised `medium`, and `timeline.lift_range`,
+  `timeline.overwrite_range`, `timeline.apply_cuts`, `timeline.delete_track`,
+  `media_pool.delete_folders` and `graph.reset_all_grades` are now classified
+  `high` wherever risk is reported, including pre-flight inspection.
+- **`setup` exposes destructive defaults** — `destructive.require_confirm_token`,
+  `destructive.safe_mode`, `destructive.audit_log`, and
+  `destructive.audit_log_path` are now visible through `schema`, persisted by
+  `set_defaults`, and reset by `clear_defaults`.
+
+## What's New in v2.208.1 — #188: variant item counts come from the timeline
+
+### Fixed
+
+- **A silence ripple under-reported what it built, by exactly half.**
+  `execute_silence_ripple` returned `variant_video_items: 250` and
+  `variant_audio_items: 250` for a variant that really held 432 of each. The
+  bridge's `ResolveOperations._encode` truncated every proxied container to
+  `max_items` (500) with no signal anywhere, and `plan_silence_ripple`
+  interleaves video and audio — so a 432-range plan became 864 clipInfos in one
+  `AppendToTimeline`, Resolve placed and returned all 864, and the first 500
+  encoded are precisely 250 video plus 250 audio. The same response's
+  `readback.after.clip_count` said 864 and was right the whole time, because it
+  re-reads per track: two numbers from two sources in one payload, one of them
+  silently short. "Planned 432, got 250" reads exactly like 182 ranges failing
+  to land, which on a silence ripple is the operator's central fear, and
+  establishing that it was benign cost a full review cycle of hand-auditing
+  both tracks. Reported and fixed in #188 by @mart0vip.
+- **Dropped elements are now reported, never silent.** `op_call` and
+  `op_get_attribute` carry a `truncated` block naming the count, limit and
+  containers; the client records it on `transport.truncations` and logs the
+  method. It warns rather than raises deliberately — the native call has
+  already run by the time the reply is encoded, so raising would turn a
+  completed 864-item assembly into an error and orphan the timeline. A short
+  list that looks complete was the failure mode; the bound itself is
+  legitimate.
+- **The item ceiling no longer exceeds the handle table.** `max_items` was
+  clamped to 5000 against a 4096-entry `MAX_HANDLES`, so a long enough list
+  evicted its own earliest handles while it was still being minted and handed
+  the client ids that were already `stale_handle`. It now clamps to
+  `MAX_HANDLES`, with the default raised 500 → 2000.
+- **Counts come from the timeline, not the append reply.**
+  `create_variant_from_ranges` reports `placed_item_counts` from the
+  post-assembly per-track re-read it was already taking for gap detection — no
+  extra Resolve calls — and `execute_silence_ripple` and `execute_tighten` now
+  share one accounting helper, tighten having carried the identical bug. A
+  planned-vs-placed disagreement is stated outright instead of left to a hand
+  audit.
+- Beyond reporting: under the old ceiling a `cdl` applied to a large variant
+  only reached the first 250 video items.
+
 ## What's New in v2.208.0 — agent execution lifecycle & pre-flight risk inspection
 
 Adapted from the design contributed in PR #187.

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.208.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.209.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.208.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.209.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.208.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.209.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 = "2.208.0"
+VERSION = "2.209.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.208.0",
+  "version": "2.209.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 = "2.208.0"
+VERSION = "2.209.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.208.0"
+VERSION = "2.209.0"
 
 import base64
 import os
@@ -1248,7 +1248,12 @@ def _ai_governance_gate(op: str, p: Dict[str, Any]) -> Optional[Dict[str, Any]]:
 def _destructive_preference_provider(key: str) -> Any:
     """Reader for C6 preferences out of the existing media-analysis prefs file."""
     try:
-        return _read_media_analysis_preferences().get(key)
+        prefs = _read_media_analysis_preferences()
+        if key.startswith("destructive."):
+            destructive = prefs.get("destructive")
+            if isinstance(destructive, dict):
+                return destructive.get(key.split(".", 1)[1])
+        return prefs.get(key)
     except Exception:
         return None
 
@@ -6606,6 +6611,26 @@ def _variant_item_placement(item) -> Dict[str, Any]:
     }
 
 
+def _snapshot_track_item_counts(snapshot: Dict[str, Any]) -> Dict[str, int]:
+    """Per-track-type item counts read from a conform snapshot of a live timeline.
+
+    This is the ONLY honest answer to "what did the assembly actually place".
+    The obvious alternative — counting what `MediaPool.AppendToTimeline`
+    returned — is a witness derived from the same call it would be checking, and
+    it lies in two measured ways: the in-app bridge caps any proxied list at
+    `max_items` (an 864-clipInfo append came back as 500 items, so a variant
+    holding 432 video + 432 audio was reported as 250 + 250), and Resolve drops
+    colliding records from the reply without an error (see the api_truth entry
+    "MediaPool.AppendToTimeline (overlapping records — earlier item wins)").
+    Re-reading the timeline per track cannot be fooled by either.
+    """
+    counts: Dict[str, int] = {}
+    for track_type, block in (snapshot.get("tracks") or {}).items():
+        rows = (block or {}).get("tracks") or []
+        counts[str(track_type)] = sum(int(row.get("item_count") or 0) for row in rows)
+    return counts
+
+
 def _variant_audio_summary(built):
     """Video/audio range counts for an assembled variant, warning when it carries
     no audio. create_variant_from_ranges places exactly the ranges given, so a
@@ -6618,6 +6643,61 @@ def _variant_audio_summary(built):
     return summary
 
 
+def _variant_audio_accounting(variant: Dict[str, Any], *, planned_video: int,
+                              planned_audio: int) -> Dict[str, Any]:
+    """The planned-vs-placed block on a tighten / silence-ripple readback.
+
+    Shared by execute_tighten and execute_silence_ripple so the two cannot
+    drift: they answer the same operator question, "did every range I planned
+    actually land in the variant".
+
+    Placed counts come from the assembler's post-assembly re-read of the
+    timeline, never from what `AppendToTimeline` returned — see
+    `_snapshot_track_item_counts` for why the append's reply is not evidence.
+    A count that is short for a *reporting* reason and a count that is short
+    because material was dropped must never look the same here: on a silence
+    ripple the operator's whole fear is dropped material, so a disagreement is
+    stated outright rather than left to be discovered by hand-auditing tracks.
+    """
+    placed = variant.get("placed_item_counts")
+    video = (placed or {}).get("video")
+    audio = (placed or {}).get("audio")
+    accounting: Dict[str, Any] = {
+        "planned_audio_ranges": planned_audio,
+        "planned_video_ranges": planned_video,
+        "variant_audio_items": audio,
+        "variant_video_items": video,
+        "counts_source": "post-assembly per-track read of the variant timeline",
+    }
+    if video is None or audio is None:
+        accounting["note"] = (
+            "Placed item counts are UNAVAILABLE — the variant could not be re-read "
+            "after assembly. Verify with timeline_item get_items_in_track before "
+            "using this variant."
+        )
+        return accounting
+    disagreements = []
+    if video != planned_video:
+        disagreements.append(f"video {video}/{planned_video}")
+    if audio != planned_audio:
+        disagreements.append(f"audio {audio}/{planned_audio}")
+    if disagreements:
+        accounting["note"] = (
+            "PLACED COUNT DISAGREES WITH THE PLAN (placed/planned: "
+            + ", ".join(disagreements)
+            + ") — ranges did not land. Resolve drops colliding records from an "
+            "append without erroring; check readback.gaps_overlaps and the "
+            "tracks themselves before using this variant."
+        )
+    elif planned_audio:
+        accounting["note"] = "Variant carries audio mirrored from the video cuts."
+    else:
+        accounting["note"] = (
+            "Variant is VIDEO-ONLY (silent) — re-plan with include_audio=True for sound."
+        )
+    return accounting
+
+
 def _timeline_create_variant_from_ranges(proj, source_tl, p: Dict[str, Any]) -> Dict[str, Any]:
     ranges = p.get("ranges") or p.get("clip_infos")
     if not isinstance(ranges, list) or not ranges:
@@ -6768,16 +6848,21 @@ def _timeline_create_variant_from_ranges(proj, source_tl, p: Dict[str, Any]) ->
     if p.get("cdl"):
         target_ids = [row.get("timeline_item_id") for row in items_out if row.get("timeline_item_id") and row.get("range", {}).get("media_type") == 1]
         look_result = _timeline_apply_look_to_items(new_tl, {"target_ids": target_ids, "cdl": p.get("cdl")})
+    # One snapshot, two consumers: gap detection and the placed-item counts.
+    # `items` above is only as complete as the append's REPLY, so it is not
+    # evidence of what landed — `placed_item_counts` re-reads the timeline.
+    snapshot = _timeline_conform_snapshot(new_tl, {})
     return {
         "success": True,
         "name": new_tl.GetName(),
         "id": new_tl.GetUniqueId(),
         "items": items_out,
+        "placed_item_counts": _snapshot_track_item_counts(snapshot),
         "placement_mismatches": placement_mismatches,
         "audio": _variant_audio_summary(built),
         "markers": marker_results,
         "look": look_result,
-        "gaps_overlaps": _detect_gaps_overlaps_from_snapshot(_timeline_conform_snapshot(new_tl, {}), {}),
+        "gaps_overlaps": _detect_gaps_overlaps_from_snapshot(snapshot, {}),
     }
 
 
@@ -15345,6 +15430,101 @@ def _setup_defaults_snapshot() -> Dict[str, Any]:
         "general": _setup_general_defaults(),
         "media_analysis": _setup_media_analysis_defaults(),
         "updates": _setup_updates_defaults(),
+        "destructive": _setup_destructive_defaults(),
+    }
+
+
+def _setup_destructive_defaults() -> Dict[str, Any]:
+    prefs = _read_media_analysis_preferences()
+    destructive = prefs.get("destructive") if isinstance(prefs.get("destructive"), dict) else {}
+    return {
+        "require_confirm_token": _setup_bool(destructive.get("require_confirm_token"), True),
+        "safe_mode": _setup_bool(destructive.get("safe_mode"), False),
+        "audit_log": _setup_bool(destructive.get("audit_log"), True),
+        "audit_log_path": destructive.get("audit_log_path") or os.path.join(project_dir, "logs", "security-audit.jsonl"),
+        "preferences_path": _media_analysis_preferences_path(),
+    }
+
+
+def _setup_set_destructive_defaults(destructive_defaults: Dict[str, Any], dry_run: bool) -> Dict[str, Any]:
+    if not destructive_defaults:
+        return {"changed": False, "recognized": False}
+
+    alias_to_key = {
+        "require_confirm_token": "require_confirm_token",
+        "requireconfirmtoken": "require_confirm_token",
+        "confirm_token": "require_confirm_token",
+        "confirmtoken": "require_confirm_token",
+        "safe_mode": "safe_mode",
+        "safemode": "safe_mode",
+        "audit_log": "audit_log",
+        "auditlog": "audit_log",
+        "audit_log_path": "audit_log_path",
+        "auditlogpath": "audit_log_path",
+    }
+    requested: Dict[str, Any] = {}
+    for key, value in destructive_defaults.items():
+        normalized_key = alias_to_key.get(_setup_text_key(key).replace("_", ""))
+        if not normalized_key:
+            normalized_key = alias_to_key.get(_setup_text_key(key))
+        if normalized_key:
+            requested[normalized_key] = value
+    if not requested:
+        return {"changed": False, "recognized": False}
+
+    try:
+        preferences = _read_media_analysis_preferences_strict()
+    except ConfigParseError as exc:
+        return _err(f"Refusing to update destructive defaults: {exc}. The preferences file exists but is unparseable; fix or delete it to avoid wiping saved settings.")
+
+    before = _setup_destructive_defaults()
+    next_preferences = dict(preferences)
+    destructive = dict(next_preferences.get("destructive") if isinstance(next_preferences.get("destructive"), dict) else {})
+    updates: Dict[str, Dict[str, Any]] = {}
+
+    def clear_requested(raw: Any) -> bool:
+        return raw is None or (not isinstance(raw, bool) and _setup_text_key(raw) in _SETUP_CHOICE_CLEAR_VALUES)
+
+    for key, raw_value in requested.items():
+        if clear_requested(raw_value):
+            destructive.pop(key, None)
+            updates[key] = {"before": before.get(key), "after": _setup_destructive_defaults().get(key), "cleared": True}
+        elif key in {"require_confirm_token", "safe_mode", "audit_log"}:
+            normalized = _setup_bool(raw_value, before.get(key, False))
+            destructive[key] = normalized
+            updates[key] = {"before": before.get(key), "after": normalized}
+        elif key == "audit_log_path":
+            path = os.path.realpath(os.path.abspath(os.path.expanduser(str(raw_value))))
+            destructive[key] = path
+            updates[key] = {"before": before.get(key), "after": path}
+
+    if dry_run:
+        return {
+            "changed": True,
+            "recognized": True,
+            "updates": updates,
+            "before": before,
+            "after": {**before, **{key: row.get("after") for key, row in updates.items()}},
+            "dry_run": True,
+        }
+
+    updated_at = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+    for key, row in updates.items():
+        if not row.get("cleared"):
+            destructive[f"{key}_updated_at"] = updated_at
+        else:
+            destructive.pop(f"{key}_updated_at", None)
+    next_preferences["destructive"] = destructive
+    _write_media_analysis_preferences(next_preferences)
+    after = _setup_destructive_defaults()
+    return {
+        "changed": before != after,
+        "recognized": True,
+        "updates": updates,
+        "before": before,
+        "after": after,
+        "updated_at": updated_at,
+        "preferences_path": _media_analysis_preferences_path(),
     }
 
 
@@ -15859,6 +16039,25 @@ def _setup_clear_defaults(keys: Any, dry_run: bool) -> Dict[str, Any]:
             return result["media_analysis"]
         result["cleared"].extend(media_clear_keys[key] for key in media_payload)
 
+    destructive_clear_keys = {
+        "require_confirm_token": "destructive.require_confirm_token",
+        "safe_mode": "destructive.safe_mode",
+        "audit_log": "destructive.audit_log",
+        "audit_log_path": "destructive.audit_log_path",
+    }
+    destructive_payload: Dict[str, Any] = {}
+    if clear_all or "destructive" in normalized_keys:
+        destructive_payload = {key: "clear" for key in destructive_clear_keys}
+    else:
+        for key, label in destructive_clear_keys.items():
+            if key in normalized_keys or label in normalized_keys:
+                destructive_payload[key] = "clear"
+    if destructive_payload:
+        result["destructive"] = _setup_set_destructive_defaults(destructive_payload, dry_run)
+        if result["destructive"].get("error"):
+            return result["destructive"]
+        result["cleared"].extend(destructive_clear_keys[key] for key in destructive_payload)
+
     if clear_all or normalized_keys & {"updates", "updates.mode", "update_mode", "mcp_update_policy"}:
         result["updates"] = _setup_set_updates_defaults({"mode": "prompt"}, dry_run)
         if result["updates"].get("error"):
@@ -15913,12 +16112,13 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
     Actions:
       schema() -> {defaults, actions}
       get_defaults() -> {defaults}
-      set_defaults(defaults?|media_analysis?|updates?|dry_run?) -> {defaults, changes}
+      set_defaults(defaults?|media_analysis?|updates?|destructive?|dry_run?) -> {defaults, changes}
       clear_defaults(keys?, dry_run?) -> {defaults, cleared}
 
     Current defaults:
       media_analysis.*: analysis, metadata, marker, reporting, and workflow defaults
       updates.*: MCP update policy, interval, and snooze defaults
+      destructive.*: confirm-token, safe-mode, and audit-log defaults
     """
     p = _params(params)
     if action in {"schema", "capabilities", "options"}:
@@ -15989,6 +16189,26 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
                     "current": _get_envelope_mode(),
                     "storage": _server_preferences_path(),
                 },
+                "destructive.require_confirm_token": {
+                    "description": "Require one-time confirmation tokens for registered high-risk destructive actions.",
+                    "values": [True, False],
+                    "storage": _media_analysis_preferences_path(),
+                },
+                "destructive.safe_mode": {
+                    "description": "When enabled, safe mode blocks high/dangerous destructive actions unless allow_risky_operation=true is passed.",
+                    "values": [True, False],
+                    "storage": _media_analysis_preferences_path(),
+                },
+                "destructive.audit_log": {
+                    "description": "Write JSONL security audit records for destructive operations.",
+                    "values": [True, False],
+                    "storage": _media_analysis_preferences_path(),
+                },
+                "destructive.audit_log_path": {
+                    "description": "Absolute path for the JSONL security audit log.",
+                    "values": "absolute or expandable path",
+                    "storage": _media_analysis_preferences_path(),
+                },
             },
         }
 
@@ -16017,6 +16237,7 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
                 for key, value in merged.items()
                 if key not in {"updates", "mcp_updates", "mcpUpdates", "dry_run", "dryRun"}
                 and key not in _general_keys
+                and key != "destructive"
             },
             **({
                 "timed_markers_default": _first_param(
@@ -16066,6 +16287,43 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
                 )
             } if any(key in merged for key in ("snooze_hours", "snoozeHours", "update_snooze_hours", "updateSnoozeHours")) else {}),
         }
+        destructive_defaults = {
+            **_setup_nested(merged, "destructive"),
+            **({
+                "require_confirm_token": _first_param(
+                    merged,
+                    "require_confirm_token",
+                    "requireConfirmToken",
+                    "confirm_token",
+                    "confirmToken",
+                    default=None,
+                )
+            } if any(key in merged for key in ("require_confirm_token", "requireConfirmToken", "confirm_token", "confirmToken")) else {}),
+            **({
+                "safe_mode": _first_param(
+                    merged,
+                    "safe_mode",
+                    "safeMode",
+                    default=None,
+                )
+            } if any(key in merged for key in ("safe_mode", "safeMode")) else {}),
+            **({
+                "audit_log": _first_param(
+                    merged,
+                    "audit_log",
+                    "auditLog",
+                    default=None,
+                )
+            } if any(key in merged for key in ("audit_log", "auditLog")) else {}),
+            **({
+                "audit_log_path": _first_param(
+                    merged,
+                    "audit_log_path",
+                    "auditLogPath",
+                    default=None,
+                )
+            } if any(key in merged for key in ("audit_log_path", "auditLogPath")) else {}),
+        }
 
         general_result = _setup_set_general_defaults(general_defaults, dry_run)
         if general_result.get("error"):
@@ -16076,9 +16334,16 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
         update_result = _setup_set_updates_defaults(update_defaults, dry_run)
         if update_result.get("error"):
             return update_result
-        recognized = (bool(general_result.get("recognized"))
-                      or bool(media_result.get("recognized"))
-                      or bool(update_result.get("recognized")))
+        destructive_result = _setup_set_destructive_defaults(destructive_defaults, dry_run)
+        if destructive_result.get("error"):
+            return destructive_result
+        recognized = (
+            bool(general_result.get("recognized"))
+            or
+            bool(media_result.get("recognized"))
+            or bool(update_result.get("recognized"))
+            or bool(destructive_result.get("recognized"))
+        )
         if not recognized:
             return _err("set_defaults did not receive a recognized default to set")
 
@@ -16088,6 +16353,7 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
                 "general": general_result,
                 "media_analysis": media_result,
                 "updates": update_result,
+                "destructive": destructive_result,
             },
             defaults=_setup_defaults_snapshot(),
         )
@@ -24172,24 +24438,11 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                     structural_diff if include_details
                     else _compact_structural_diff(structural_diff)
                 ),
-                "audio_accounting": {
-                    "planned_audio_ranges": audio_keep_ranges,
-                    "planned_video_ranges": video_keep_ranges,
-                    # variant_* count placed items; variant["audio"] counts requested ranges.
-                    "variant_audio_items": sum(
-                        1 for it in (variant.get("items") or [])
-                        if (it.get("range") or {}).get("media_type") == 2
-                    ),
-                    "variant_video_items": sum(
-                        1 for it in (variant.get("items") or [])
-                        if (it.get("range") or {}).get("media_type") == 1
-                    ),
-                    "note": (
-                        "Variant carries audio mirrored from the video cuts."
-                        if audio_keep_ranges
-                        else "Variant is VIDEO-ONLY (silent) — re-plan with include_audio=True for sound."
-                    ),
-                },
+                # variant_* count PLACED items, re-read from the variant;
+                # variant["audio"] counts requested ranges.
+                "audio_accounting": _variant_audio_accounting(
+                    variant, planned_video=video_keep_ranges, planned_audio=audio_keep_ranges,
+                ),
             },
             "plan_id": plan.get("plan_id"),
         }
@@ -24308,23 +24561,9 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                     structural_diff if include_details
                     else _compact_structural_diff(structural_diff)
                 ),
-                "audio_accounting": {
-                    "planned_audio_ranges": audio_keep_ranges,
-                    "planned_video_ranges": video_keep_ranges,
-                    "variant_audio_items": sum(
-                        1 for it in (variant.get("items") or [])
-                        if (it.get("range") or {}).get("media_type") == 2
-                    ),
-                    "variant_video_items": sum(
-                        1 for it in (variant.get("items") or [])
-                        if (it.get("range") or {}).get("media_type") == 1
-                    ),
-                    "note": (
-                        "Variant carries audio mirrored from the video cuts."
-                        if audio_keep_ranges
-                        else "Variant is VIDEO-ONLY (silent) — re-plan with include_audio=True for sound."
-                    ),
-                },
+                "audio_accounting": _variant_audio_accounting(
+                    variant, planned_video=video_keep_ranges, planned_audio=audio_keep_ranges,
+                ),
             },
             "plan_id": plan.get("plan_id"),
         }

package/src/utils/destructive_hook.py

@@ -25,14 +25,26 @@ every tool that owns destructive actions is decorated.
 from __future__ import annotations
 
 import functools
+import json
 import logging
+import os
+import time
+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.execution_lifecycle import RiskAssessment, RiskLevel, classify_operation_risk
 
 logger = logging.getLogger("resolve-mcp.destructive-hook")
 
 
+#: Risk levels safe mode refuses. Names come from `RiskLevel`; a second
+#: vocabulary here would let the gate and the reported level disagree.
+SAFE_MODE_BLOCKED_RISK_LEVELS: FrozenSet[str] = frozenset({
+    RiskLevel.HIGH.value, RiskLevel.CRITICAL.value,
+})
+
+
 # ── Destructive action registry ──────────────────────────────────────────────
 #
 # Tool name → frozenset of action strings that mutate the working timeline (or
@@ -300,6 +312,26 @@ def is_strict_required(tool_name: str, action: str, params: Optional[Dict[str, A
     return False
 
 
+def assess_action_risk(
+    tool_name: str, action: str, params: Optional[Dict[str, Any]] = None,
+) -> RiskAssessment:
+    """Classify a call for the safe-operations policy.
+
+    Classification lives in `execution_lifecycle`, which the pre-flight
+    inspection surface already uses. Deriving it a second time here would let
+    `inspect_operation` and the safe-mode gate disagree about the same call —
+    the gate blocking what inspection called reversible, or the reverse.
+    """
+    return classify_operation_risk(tool_name, action, params or {})
+
+
+def risk_level_for_action(
+    tool_name: str, action: str, params: Optional[Dict[str, Any]] = None,
+) -> str:
+    """Return the security risk level for a call, as a `RiskLevel` value."""
+    return assess_action_risk(tool_name, action, params).level.value
+
+
 # ── Provider hooks ───────────────────────────────────────────────────────────
 
 _ProjectRootProvider = Callable[[], Optional[Tuple[Any, Any, str, Optional[str]]]]
@@ -360,6 +392,163 @@ def _read_preference(key: str, default: Any = None) -> Any:
     return default if value is None else value
 
 
+def _coerce_bool(value: Any, default: bool = False) -> bool:
+    if value is None:
+        return default
+    if isinstance(value, str):
+        lowered = value.strip().lower()
+        if lowered in {"1", "true", "yes", "on"}:
+            return True
+        if lowered in {"0", "false", "no", "off"}:
+            return False
+        return default
+    return bool(value)
+
+
+def _safe_mode_enabled() -> bool:
+    return _coerce_bool(_read_preference("destructive.safe_mode", False), False)
+
+
+def _audit_enabled() -> bool:
+    return _coerce_bool(_read_preference("destructive.audit_log", True), True)
+
+
+def _audit_log_path() -> str:
+    configured = _read_preference("destructive.audit_log_path", None)
+    if configured:
+        return os.path.expanduser(str(configured))
+    project_dir = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    return os.path.join(project_dir, "logs", "security-audit.jsonl")
+
+
+def _safe_params_for_audit(params: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    if not isinstance(params, dict):
+        return None
+    redacted = dict(params)
+    for key in ("confirm_token", "confirmToken"):
+        if key in redacted:
+            redacted[key] = "<redacted>"
+    return redacted
+
+
+def _audit_security_event(
+    *,
+    operation_id: str,
+    tool_name: str,
+    action: str,
+    risk_level: str,
+    status: str,
+    params: Optional[Dict[str, Any]],
+    recognised: bool = True,
+    reason: Optional[str] = None,
+    project_root: Optional[str] = None,
+    analysis_run_id: Optional[str] = None,
+) -> None:
+    if not _audit_enabled():
+        return
+    event = {
+        "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "operation_id": operation_id,
+        "tool": tool_name,
+        "action": action,
+        "risk_level": risk_level,
+        "risk_established": recognised,
+        "status": status,
+        "reason": reason,
+        "analysis_run_id": analysis_run_id,
+        "project_root": project_root,
+        "params": _safe_params_for_audit(params),
+    }
+    path = _audit_log_path()
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "a", encoding="utf-8") as handle:
+            handle.write(json.dumps(event, sort_keys=True, default=str) + "\n")
+    except Exception as exc:
+        logger.warning("security audit log write failed: %s", exc)
+
+
+def _security_block_response(
+    *,
+    operation_id: str,
+    tool_name: str,
+    action: str,
+    risk_level: str,
+    recognised: bool = True,
+) -> Dict[str, Any]:
+    return {
+        "success": False,
+        "status": "blocked_by_security_policy",
+        "operation_id": operation_id,
+        "security": {
+            "risk_level": risk_level,
+            "risk_established": recognised,
+            "safe_mode": True,
+            "blocked": True,
+            "policy": "destructive.safe_mode",
+        },
+        "error": {
+            "message": (
+                f"Safe mode blocked {risk_level}-risk action "
+                f"'{tool_name}.{action}'. "
+                "Re-call with params.allow_risky_operation=true, or disable "
+                "destructive.safe_mode in setup defaults."
+            ),
+            "code": "SAFE_MODE_BLOCKED",
+            "category": "destructive_blocked",
+            "retryable": False,
+            "remediation": (
+                "Pass allow_risky_operation=true for this call after review, or "
+                "set destructive.safe_mode=false if this session should allow "
+                "high-risk destructive actions."
+            ),
+        },
+    }
+
+
+def _annotate_security(
+    result: Any,
+    *,
+    operation_id: str,
+    risk_level: str,
+    blocked: bool = False,
+    recognised: bool = True,
+) -> Any:
+    if isinstance(result, dict):
+        result.setdefault("operation_id", operation_id)
+        result.setdefault("security", {
+            "risk_level": risk_level,
+            "risk_established": recognised,
+            "safe_mode": _safe_mode_enabled(),
+            "blocked": blocked,
+        })
+    return result
+
+
+def _safe_mode_allows(
+    risk_level: str,
+    params: Optional[Dict[str, Any]],
+    recognised: bool = True,
+) -> bool:
+    """Whether safe mode lets this call through.
+
+    Only an established HIGH or CRITICAL is blocked. Failing closed on
+    `recognised=False` was measured and rejected: 80 of the 108 registered
+    destructive actions match no risk rule today, `timeline.add_track` and
+    `timeline.duplicate` among them, so it would block three quarters of all
+    edits and teach users to leave safe mode off — weaker in practice than a
+    narrow gate they keep on. The unclassified actions are reported via
+    `risk_established` instead, and want classifying rather than blanket-gating.
+    """
+    if not _safe_mode_enabled():
+        return True
+    if risk_level not in SAFE_MODE_BLOCKED_RISK_LEVELS:
+        return True
+    if isinstance(params, dict) and params.get("allow_risky_operation") is True:
+        return True
+    return False
+
+
 def _resolve_versioning_context() -> Optional[Tuple[Any, Any, str, Optional[str]]]:
     if _PROVIDER is None:
         return None
@@ -441,6 +630,29 @@ def destructive_op(tool_name: str) -> Callable[[Callable[..., Any]], Callable[..
             if not is_destructive(tool_name, action, params):
                 return fn(action, params, *args, **kwargs)
 
+            operation_id = f"op_{uuid.uuid4().hex[:12]}"
+            assessment = assess_action_risk(tool_name, action, params)
+            risk_level = assessment.level.value
+            risk_recognised = assessment.recognised
+            if not _safe_mode_allows(risk_level, params, risk_recognised):
+                _audit_security_event(
+                    operation_id=operation_id,
+                    tool_name=tool_name,
+                    action=action,
+                    risk_level=risk_level,
+                    status="blocked",
+                    params=params,
+                    reason="safe_mode",
+                    recognised=risk_recognised,
+                )
+                return _security_block_response(
+                    operation_id=operation_id,
+                    tool_name=tool_name,
+                    action=action,
+                    risk_level=risk_level,
+                    recognised=risk_recognised,
+                )
+
             # F4 — token-issuance calls don't mutate; skip the archive entirely
             # so that token preview/cancel paths don't litter the version chain.
             # The wrapper still annotates `_versioning` on the result so callers
@@ -453,30 +665,76 @@ def destructive_op(tool_name: str) -> Callable[[Callable[..., Any]], Callable[..
                     will_gate = False
                 if will_gate:
                     result = fn(action, params, *args, **kwargs)
+                    _audit_security_event(
+                        operation_id=operation_id,
+                        tool_name=tool_name,
+                        action=action,
+                        risk_level=risk_level,
+                        status="pending_confirmation",
+                        params=params,
+                        reason="confirm_token_required",
+                        recognised=risk_recognised,
+                    )
                     if isinstance(result, dict):
                         result.setdefault("_versioning", {
                             "analysis_run_id": None,
                             "archived": False,
                             "skipped_reason": "pending_confirm_token",
                         })
-                    return result
+                    return _annotate_security(
+                        result,
+                        operation_id=operation_id,
+                        risk_level=risk_level,
+                        recognised=risk_recognised,
+                    )
 
             strict = is_strict_required(tool_name, action, params)
 
             ctx = _resolve_versioning_context()
             if ctx is None:
                 if strict:
-                    return {
+                    _audit_security_event(
+                        operation_id=operation_id,
+                        tool_name=tool_name,
+                        action=action,
+                        risk_level=risk_level,
+                        status="blocked",
+                        params=params,
+                        reason="strict_missing_version_context",
+                        recognised=risk_recognised,
+                    )
+                    return _annotate_security({
                         "success": False,
                         "error": (
                             f"strict mode: '{tool_name}.{action}' refuses to run because the "
                             "version-on-mutate context (project_root) couldn't be resolved. "
                             "Open a project in Resolve, or pass strict=false to override."
                         ),
-                    }
+                    },
+                    operation_id=operation_id,
+                    risk_level=risk_level,
+                    blocked=True,
+                    recognised=risk_recognised,
+                )
                 # No Resolve / no project — let the underlying handler run; it
                 # will either succeed (e.g. in dry-run) or surface its own error.
-                return fn(action, params, *args, **kwargs)
+                result = fn(action, params, *args, **kwargs)
+                _audit_security_event(
+                    operation_id=operation_id,
+                    tool_name=tool_name,
+                    action=action,
+                    risk_level=risk_level,
+                    status="allowed",
+                    params=params,
+                    reason="no_version_context",
+                    recognised=risk_recognised,
+                )
+                return _annotate_security(
+                    result,
+                    operation_id=operation_id,
+                    risk_level=risk_level,
+                    recognised=risk_recognised,
+                )
 
             resolve_h, project_h, project_root, project_name = ctx
             run_id = _extract_analysis_run_id(params, project_root=project_root)
@@ -488,6 +746,17 @@ def destructive_op(tool_name: str) -> Callable[[Callable[..., Any]], Callable[..
             # wrapper only handles the timeline path.
             if tool_name == "media_pool":
                 result = fn(action, params, *args, **kwargs)
+                _audit_security_event(
+                    operation_id=operation_id,
+                    tool_name=tool_name,
+                    action=action,
+                    risk_level=risk_level,
+                    status="allowed",
+                    params=params,
+                    project_root=project_root,
+                    analysis_run_id=run_id,
+                    recognised=risk_recognised,
+                )
                 try:
                     media_pool_changes.log_media_pool_change(
                         project_root=project_root,
@@ -505,7 +774,12 @@ def destructive_op(tool_name: str) -> Callable[[Callable[..., Any]], Callable[..
                         "category": "media_pool",
                         "initiator": initiator,
                     })
-                return result
+                return _annotate_security(
+                    result,
+                    operation_id=operation_id,
+                    risk_level=risk_level,
+                    recognised=risk_recognised,
+                )
 
             before_value: Optional[float] = None
             timeline_before_name: Optional[str] = None
@@ -555,7 +829,19 @@ def destructive_op(tool_name: str) -> Callable[[Callable[..., Any]], Callable[..
                 if archive_exc is not None or (
                     not archive_result.get("archived") and not skipped_ok
                 ):
-                    return {
+                    _audit_security_event(
+                        operation_id=operation_id,
+                        tool_name=tool_name,
+                        action=action,
+                        risk_level=risk_level,
+                        status="blocked",
+                        params=params,
+                        reason="strict_archive_failed",
+                        project_root=project_root,
+                        analysis_run_id=run_id,
+                        recognised=risk_recognised,
+                    )
+                    return _annotate_security({
                         "success": False,
                         "error": (
                             f"strict mode: refused '{tool_name}.{action}' because the "
@@ -568,10 +854,26 @@ def destructive_op(tool_name: str) -> Callable[[Callable[..., Any]], Callable[..
                             "archived": False,
                             "strict_block": True,
                         },
-                    }
+                    },
+                    operation_id=operation_id,
+                    risk_level=risk_level,
+                    blocked=True,
+                    recognised=risk_recognised,
+                )
 
             # Run the underlying handler regardless of hook outcome.
             result = fn(action, params, *args, **kwargs)
+            _audit_security_event(
+                operation_id=operation_id,
+                tool_name=tool_name,
+                action=action,
+                risk_level=risk_level,
+                status="allowed",
+                params=params,
+                project_root=project_root,
+                analysis_run_id=run_id,
+                recognised=risk_recognised,
+            )
 
             after_value: Optional[float] = None
             timeline_after_name: Optional[str] = timeline_before_name
@@ -617,7 +919,12 @@ def destructive_op(tool_name: str) -> Callable[[Callable[..., Any]], Callable[..
                     "before_value": before_value,
                     "after_value": after_value,
                 })
-            return result
+            return _annotate_security(
+                result,
+                operation_id=operation_id,
+                risk_level=risk_level,
+                recognised=risk_recognised,
+            )
 
         wrapper.__wrapped_tool_name__ = tool_name  # type: ignore[attr-defined]
         wrapper.__is_destructive_wrapped__ = True  # type: ignore[attr-defined]

package/src/utils/execution_lifecycle.py

@@ -29,7 +29,7 @@ logger = logging.getLogger("resolve-mcp.execution-lifecycle")
 
 class RiskLevel(str, enum.Enum):
     """Categorized risk level for tool operations."""
-    LOW = "low"            # Read-only queries, info probes, status checks
+    LOW = "low"            # Read-only queries, info probes, and known-reversible edits
     MEDIUM = "medium"      # Reversible edits, markers, non-destructive properties
     HIGH = "high"          # Deletions, ripples, timeline restructuring, batch edits
     CRITICAL = "critical"  # Project deletion, database resets, permanent loss
@@ -139,6 +139,26 @@ class RiskClassificationHook(LifecycleHook):
         ("edit_engine", "auto_cut_silence"),
         ("edit_engine", "ripple_trim"),
         ("project_manager", "save_project_as"),
+        ("media_pool", "delete_folders"),
+        ("timeline", "delete_track"),
+        ("timeline", "lift_range"),
+        ("timeline", "overwrite_range"),
+        ("timeline", "apply_cuts"),
+        ("graph", "reset_all_grades"),
+    }
+
+    #: Mutating, but bounded and trivially reversible — a marker or a clip
+    #: colour. Without this table the name heuristic files them under MEDIUM
+    #: and flags them unrecognised, i.e. it warns that the risk is unestablished
+    #: for the actions whose risk is the best established of any we dispatch.
+    _LOW_RISK_ACTIONS: Set[Tuple[str, str]] = {
+        ("timeline_markers", "add"),
+        ("timeline_markers", "update_custom_data"),
+        ("timeline_item_markers", "add"),
+        ("timeline_item_markers", "add_flag"),
+        ("timeline_item_markers", "clear_flags"),
+        ("timeline_item_markers", "set_clip_color"),
+        ("timeline_item_markers", "clear_clip_color"),
     }
 
     _READ_ONLY_PREFIXES = ("get_", "list_", "query_", "probe_", "inspect_", "export_", "check_")
@@ -170,6 +190,11 @@ class RiskClassificationHook(LifecycleHook):
                 radius = BlastRadius.ITEM
             conf_required = True
             reasons.append(f"Destructive timeline edit: {action}")
+        elif pair in cls._LOW_RISK_ACTIONS:
+            level = RiskLevel.LOW
+            destructive = True
+            radius = BlastRadius.ITEM
+            reasons.append(f"Bounded reversible edit: {action}")
         elif any(action.startswith(p) for p in cls._READ_ONLY_PREFIXES) or action in {"read", "status", "info"}:
             level = RiskLevel.LOW
             destructive = False

package/src/utils/resolve_bridge_client.py

@@ -33,6 +33,18 @@ proxy deliberately does not.
   timeline item-by-item is the shape that bites.
 - **Bridge absence.** If the in-Resolve script is not running, construction fails
   with a clear message rather than pretending; there is nothing to fall back to.
+- **Incomplete replies.** A returned container longer than the surface's
+  `max_items` comes back short. That used to be invisible, and a short list is
+  indistinguishable from a genuinely short result — an 864-clipInfo
+  `AppendToTimeline` returned 500 items and a caller counted them as the whole
+  answer. The surface now reports every drop and `_BoundMethod` surfaces it
+  (`transport.truncations`, plus a warning naming the method).
+
+  It warns rather than raising, deliberately: the native call has already *run*
+  by the time the reply is encoded, so raising would turn completed Resolve work
+  — a placed 864-item assembly — into an error and orphan the result. The honest
+  handling is for the caller to stop treating a returned list as a count, which
+  is why the tools that report item counts re-read them from the timeline.
 """
 
 from __future__ import annotations
@@ -117,6 +129,31 @@ class BridgeTransport:
         # keeps request/response pairing simple and matches the _bridge_lock
         # discipline the rest of the server already follows.
         self._lock = threading.RLock()
+        #: Replies the surface reported as incomplete, newest last: one row per
+        #: (method, dropped, total). Kept so a caller that suspects a short
+        #: enumeration can prove it instead of inferring it from a count that
+        #: looks plausible. Bounded — this is a diagnostic, not a log.
+        self.truncations: List[Dict[str, Any]] = []
+
+    def note_truncation(self, method: str, truncated: Any) -> None:
+        """Record and announce a reply the surface could not carry in full."""
+        if not isinstance(truncated, dict):
+            return
+        row = {"method": method, **truncated}
+        with self._lock:
+            self.truncations.append(row)
+            del self.truncations[:-32]
+        # Shapes here come off the wire from a bridge that may be older than
+        # this client, so nothing is indexed or assumed present.
+        containers = truncated.get("containers")
+        first = containers[0] if isinstance(containers, list) and containers else {}
+        logger.warning(
+            "bridge reply for %s was TRUNCATED: %s of %s elements dropped (limit %s). "
+            "The returned list is not a count — re-read the object instead.",
+            method, truncated.get("dropped"),
+            first.get("total") if isinstance(first, dict) else None,
+            truncated.get("limit"),
+        )
 
     def request(self, operation: str, arguments: Dict[str, Any]) -> Any:
         payload = {
@@ -251,6 +288,7 @@ class _BoundMethod:
             {"target": self._handle, "method": self._name,
              "args": [_encode_argument(a) for a in args]},
         )
+        self._transport.note_truncation(self._name, (result or {}).get("truncated"))
         return _decode_value(self._transport, (result or {}).get("value"))
 
     def __repr__(self) -> str:  # pragma: no cover - debugging aid
@@ -345,6 +383,7 @@ class BridgeProxy:
                 probe = self._transport.request("get_attribute",
                                                 {"target": self._handle, "name": name}) or {}
                 if probe.get("kind") == "value":
+                    self._transport.note_truncation(name, probe.get("truncated"))
                     return _decode_value(self._transport, probe.get("value"))
                 if (name in _FUSION_UNENUMERATED_METHODS
                         and self._methods() & _FUSION_OBJECT_MARKERS):

package/src/utils/resolve_bridge_ops.py

@@ -174,13 +174,22 @@ class ResolveOperations:
     #: loses a handle gets a clear `stale_handle` error and can re-fetch.
     MAX_HANDLES = 4096
 
+    #: Elements carried out of one encoded return value. A timeline-scale
+    #: enumeration has to fit: the old 500 silently halved an 864-item
+    #: `AppendToTimeline` return, and the caller counted the 500 it got as the
+    #: whole truth (a 432+432 variant read back as 250+250, issue: silence-ripple
+    #: audio_accounting). Whatever the ceiling is, exceeding it is now REPORTED
+    #: — see `_encode` — because a short list that looks complete is the failure
+    #: mode, not the bound itself.
+    DEFAULT_MAX_ITEMS = 2000
+
     def __init__(
         self,
         resolve: Any,
         *,
         media_roots: List[str],
         output_roots: List[str],
-        max_items: int = 500,
+        max_items: int = DEFAULT_MAX_ITEMS,
         lifecycle: Optional[Callable[[str], Dict[str, Any]]] = None,
     ) -> None:
         if resolve is None:
@@ -191,7 +200,16 @@ class ResolveOperations:
         # pretending to stop something they have no handle on.
         self._lifecycle = lifecycle
         self.policy = PathPolicy(media_roots, output_roots)
-        self.max_items = max(1, min(int(max_items), 5000))
+        # Capped at MAX_HANDLES, not at some larger round number: every live
+        # object in an encoded list mints a handle, so a list longer than the
+        # table evicts its own earliest entries before the client can use them
+        # and hands back handles that are already `stale_handle`. A ceiling
+        # above the table would trade a short list for a poisoned one.
+        self.max_items = max(1, min(int(max_items), self.MAX_HANDLES))
+        #: Set by `_encode` when a return value did not fit, read by the ops
+        #: that encode. Not a counter across calls — it answers "was THIS reply
+        #: complete", which is the only question a caller can act on.
+        self._encode_truncation: List[Dict[str, Any]] = []
         self._routes: Dict[str, Callable[[Dict[str, Any]], Any]] = {
             name: getattr(self, f"op_{name}") for name in self.OPERATIONS
         }
@@ -507,21 +525,68 @@ class ResolveOperations:
         Every object produced by one call carries the same shape, including the
         elements of a returned list — a track's timeline items are homogeneous,
         which is exactly the case where sharing a cached method set pays.
+
+        **Dropping elements is recorded, never silent.** A container longer than
+        `max_items` used to come back shortened with nothing anywhere saying so,
+        and a short list is indistinguishable from a genuinely short result: an
+        864-clipInfo `AppendToTimeline` returned 500 items, the caller counted
+        them, and a variant holding 432 video + 432 audio was reported to the
+        operator as 250 + 250 — which reads exactly like 182 ranges failing to
+        land. The bound itself is legitimate (see `max_items`); hiding it is
+        not, so every drop is reported alongside the value.
         """
         if value is None or isinstance(value, (bool, int, float, str)):
             return value
         if depth > 6:
             return str(value)
         if isinstance(value, (list, tuple)):
-            return [self._encode(v, depth + 1, shape) for v in list(value)[: self.max_items]]
+            items = list(value)
+            self._note_truncation(len(items), "list", depth, shape)
+            return [self._encode(v, depth + 1, shape) for v in items[: self.max_items]]
         if isinstance(value, dict):
-            return {str(k): self._encode(v, depth + 1, shape) for k, v in list(value.items())[: self.max_items]}
+            pairs = list(value.items())
+            self._note_truncation(len(pairs), "dict", depth, shape)
+            return {str(k): self._encode(v, depth + 1, shape) for k, v in pairs[: self.max_items]}
         return {
             "__handle__": self._mint(value, shape),
             "__type__": type(value).__name__,
             "__shape__": shape,
         }
 
+    def _note_truncation(self, total: int, kind: str, depth: int, shape: str) -> None:
+        if total <= self.max_items:
+            return
+        self._encode_truncation.append({
+            "shape": shape, "kind": kind, "depth": depth,
+            "returned": self.max_items, "total": total,
+            "dropped": total - self.max_items,
+        })
+
+    def _encoded(self, value: Any, shape: str) -> Dict[str, Any]:
+        """Encode one return value into a reply, carrying any truncation with it.
+
+        The `truncated` block is the whole point: a caller that reads `value` as
+        a complete answer is wrong exactly when this key is present, and it
+        cannot know that from the value alone.
+        """
+        self._encode_truncation = []
+        encoded = self._encode(value, shape=shape)
+        reply: Dict[str, Any] = {"value": encoded}
+        if self._encode_truncation:
+            dropped = sum(row["dropped"] for row in self._encode_truncation)
+            reply["truncated"] = {
+                "dropped": dropped,
+                "limit": self.max_items,
+                "containers": self._encode_truncation[:8],
+                "hint": (
+                    "This reply is INCOMPLETE — the value is not evidence of how many "
+                    "items exist. Re-read in smaller pieces, or count from the object "
+                    "itself rather than from this list."
+                ),
+            }
+            self._encode_truncation = []
+        return reply
+
     def _decode(self, value: Any) -> Any:
         """Argument -> live object, rehydrating handles the bridge itself issued."""
         if isinstance(value, dict):
@@ -571,7 +636,7 @@ class ResolveOperations:
                 "resolve_raised",
                 f"Resolve raised while running {method}: {str(exc)[:200]}",
             )
-        return {"value": self._encode(result, shape=f"{self._shape_of(target_key)}.{method}")}
+        return self._encoded(result, shape=f"{self._shape_of(target_key)}.{method}")
 
     def op_list_methods(self, arguments: Dict[str, Any]) -> Dict[str, Any]:
         """The public attribute names on a target — what `hasattr` should answer.
@@ -690,7 +755,8 @@ class ResolveOperations:
             return {"kind": "none",
                     "note": "present-but-None; on Resolve objects this is indistinguishable "
                             "from absent, because getattr never raises"}
-        return {"kind": "value", "value": self._encode(value, shape=f"{self._shape_of(arguments.get('target', 'resolve'))}.{name}")}
+        encoded = self._encoded(value, shape=f"{self._shape_of(arguments.get('target', 'resolve'))}.{name}")
+        return {"kind": "value", **encoded}
 
     def op_release_handles(self, arguments: Dict[str, Any]) -> Dict[str, Any]:
         """Drop handles a client no longer needs, or all of them."""