davinci-resolve-mcp 2.207.0 → 2.208.1

package/CHANGELOG.md

@@ -2,6 +2,103 @@
 
 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.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.
+
+### Added
+
+- **Agent execution lifecycle pipeline & hooks:**
+  Tools passing through `_guard_missing_params` now execute within a structured
+  lifecycle pipeline, supporting pre-flight inspection (`before_tool_call`),
+  post-execution enrichment (`after_tool_call`), and failure handling (`on_error`).
+- **Pre-flight operation risk & blast radius assessment:**
+  `resolve_control(action="inspect_operation")` evaluates any tool and action
+  prior to execution, returning risk levels (`low`, `medium`, `high`, `critical`),
+  destructive flags, confirmation requirements, and blast radius scopes (`item`,
+  `track`, `timeline`, `project`, `system`).
+- **Lifecycle hooks introspection:**
+  `resolve_control(action="list_lifecycle_hooks")` exposes registered pipeline
+  hooks and their active states.
+
+### Notes on the adaptation
+
+- **The dry-run simulation interceptor is not included.** As contributed, any
+  call carrying `dry_run: true` outside a hardcoded four-entry allowlist was
+  short-circuited and answered with a synthesised `{"success": true,
+  "simulated": true}`. `src/server.py` has 273 `dry_run` references, so the
+  allowlist was not close: `setup.set_defaults` and
+  `resolve_control.clear_executions` both have real, tested dry-run paths and
+  were hijacked. It also answered `success: true` to
+  `set_defaults(result_envelope="banana")` — a dry run of an operation that
+  cannot succeed — and to adding a marker with no timeline in existence.
+  `dry_run` is the call an editor makes *because* they do not trust the next
+  one; a version of it that always succeeds is worse than none, because it is
+  believed. Nothing about dry-run behaviour changes in this release: every
+  `dry_run` reaches the handler that owns it.
+- **The pipeline can gate a call, but nothing shipped does.**
+  `HookDecision(proceed=False)` and the public `register_hook` remain, so a
+  deliberately registered hook can intercept. Every default hook only observes,
+  and `test_no_default_hook_short_circuits` keeps it that way.
+- **`inspect_operation` no longer contradicts itself about rollback.** It
+  reported `snapshot_available` two ways in one response — `false` inside
+  `risk`, and `true` at the top level whenever any pre-state could be read.
+  Reading a project name is not a restorable snapshot. It is now a single
+  `null`, meaning "not determined", with `pre_state_available` reporting
+  separately whether live state was read at all.
+- **An unrecognised operation is no longer assessed as safe.** Any action
+  matching no rule fell into a general-mutation bucket and returned `medium` /
+  `destructive: false` / `confirmation_required: false` — a confident answer
+  about an operation the classifier had never heard of, including ones that do
+  not exist. Responses now carry `recognised: false` and say in `reasons` that
+  the levels are name-based defaults rather than a finding. The guard exists
+  for hallucinated calls; answering one with reassurance was the failure it was
+  built to prevent.
+- The docs now state plainly that `inspect_operation` is a heuristic over
+  action names, not a simulation: it never touches the project and does not
+  validate parameters.
+
 ## What's New in v2.207.0 — execution audit report exports
 
 Contributed in PR #185.

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.207.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.208.1-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)
@@ -280,6 +280,17 @@ reviewable audit artifact with the same summary, defaulting to
 it instead — alongside a conform in a dated TransferFiles folder, say — and
 creates the directories to get there, so check the path before you send it.
 An existing file is never replaced without `overwrite: true`.
+`inspect_operation(tool?, target_action?, target_params?)` evaluates pre-flight
+risk level (`low`, `medium`, `high`, `critical`), destructive potential, and blast
+radius (`item`, `track`, `timeline`, `project`, `system`) before taking action, while
+`list_lifecycle_hooks()` inspects active execution interceptors.
+
+It is a heuristic over action names, not a simulation — it never touches the
+project and does not validate your parameters, so `recognised: false` means the
+levels are defaults rather than a finding, and `snapshot_available: null` means
+rollback availability was not determined rather than absent. Every shipped hook
+observes; none replaces a tool's result, so `dry_run` always reaches the real
+handler and nothing synthesises a preview for an action that has none.
 
 A report for a run where nothing was verified says **"not established — no
 checks recorded"**, not "passed". Absence of evidence is a question still open,

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.207.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.208.1-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.207.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.208.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -174,7 +174,9 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 ### 导出执行审计报告
 
-`export_execution_report(execution_id?, format="markdown"|"json")` 会把一条轨迹写成可供审阅的审计文件，默认落在 `logs/execution-reports/<execution_id>.md`。传 `path` 可以写到任何你想要的位置——比如跟着某次套底放进当天的 TransferFiles 文件夹——并且会自动创建沿途的目录，所以发出去之前请先确认路径。已存在的文件不会被覆盖，除非显式传 `overwrite: true`。
+`export_execution_report(execution_id?, format="markdown"|"json")` 会把一条轨迹写成可供审阅的审计文件，默认落在 `logs/execution-reports/<execution_id>.md`。传 `path` 可以写到任何你想要的位置——比如跟着某次套底放进当天的 TransferFiles 文件夹——并且会自动创建沿途的目录，所以发出去之前请先确认路径。已存在的文件不会被覆盖，除非显式传 `overwrite: true`。`inspect_operation(tool?, target_action?, target_params?)` 会在执行前评估操作的风险等级（`low`、`medium`、`high`、`critical`）、破坏性以及影响范围（`item`、`track`、`timeline`、`project`、`system`），而 `list_lifecycle_hooks()` 则可以查看当前生效的生命周期钩子。
+
+需要强调的是：这是一套基于动作名称的启发式判断，**不是模拟执行**——它完全不碰项目，也不会校验你传的参数。`recognised: false` 表示没有任何规则命中，那些等级只是按名字给出的默认值，而不是对这次操作的结论；`snapshot_available: null` 表示"是否能回滚未确定"，而不是"不能回滚"。所有随包启用的钩子都只做观察，没有任何一个会替换工具的返回值——因此 `dry_run` 永远会走到真正的处理函数，不会有人替一个本身不支持 dry-run 的动作凭空编一份预览出来。
 
 如果这次运行根本没有做过校验，报告里写的是**"not established — no checks recorded"（未确立——没有记录任何检查）**，而不是"通过"。没有证据是一个仍然悬而未决的问题；审计文件恰恰是最不该让读者把它读成"一切正常"的地方。
 

package/docs/SKILL.md

@@ -277,6 +277,24 @@ Example trace shape returned by `resolve_control(action="get_execution_trace")`:
   structured output, `include_steps: false` for a shorter summary, or
   `overwrite: true` to replace an existing report.
 - **`clear_executions(dry_run?)`**: Clears the in-memory execution trace buffer.
+- **`inspect_operation(tool?, target_action?, target_params?)`**: Evaluates operation risk
+  level (`low`, `medium`, `high`, `critical`), destructive potential, confirmation
+  requirements, and blast radius scope before executing an action.
+
+  **It is a heuristic over action names, not a simulation.** It does not touch
+  the project, does not validate your parameters, and cannot tell you whether
+  the clip ids you are holding exist. Read three fields before trusting it:
+  `recognised: false` means no rule matched and the levels are name-based
+  defaults rather than a finding; `snapshot_available: null` means rollback
+  availability was not determined, never that there is none; and
+  `pre_state_available` separates "no project open" from "state never read".
+  For an actual preview, use the action's own `dry_run` where it has one.
+- **`list_lifecycle_hooks()`**: Returns active execution lifecycle pipeline hooks
+  (`risk_classification`, `resolve_state_inspection`, `readback_verification`,
+  `drift_detection`, `provenance_trace`). All of them observe; none replaces a
+  tool result. `dry_run` therefore always reaches the real handler — a tool
+  either implements it or does not, and nothing synthesises a preview on its
+  behalf.
 
 Explicit correlation is also supported per-call: pass `params={"execution_id": ...}`
 or `params={"trace_id": ...}` in any tool call to associate it with a specific trace.

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.207.0"
+VERSION = "2.208.1"
 # 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.207.0",
+  "version": "2.208.1",
   "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.207.0"
+VERSION = "2.208.1"
 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.207.0"
+VERSION = "2.208.1"
 
 import base64
 import os
@@ -76,6 +76,11 @@ from src.utils.execution_trace import (
     clear_executions,
     export_execution_report,
 )
+from src.utils import execution_lifecycle as _execution_lifecycle
+from src.utils.execution_lifecycle import (
+    inspect_operation,
+    list_lifecycle_hooks,
+)
 from src.utils.render_ids import (
     render_codec_id_from_codecs as _render_codec_id_from_codecs,
     render_format_id_from_formats as _render_format_id_from_formats,
@@ -887,6 +892,37 @@ def _try_connect():
             resolve = None
             return None
 
+def _get_resolve_lifecycle_state() -> Optional[Dict[str, Any]]:
+    """Capture non-blocking pre-flight Resolve project and timeline metadata."""
+    global resolve
+    r = resolve
+    if r is None:
+        try:
+            r = _try_connect()
+        except Exception:
+            r = None
+    if r is None:
+        return None
+    try:
+        pm = r.GetProjectManager()
+        if not pm:
+            return None
+        proj = pm.GetCurrentProject()
+        if not proj:
+            return None
+        state: Dict[str, Any] = {"project_name": proj.GetName()}
+        tl = proj.GetCurrentTimeline()
+        if tl:
+            state["timeline_name"] = tl.GetName()
+            state["duration_frames"] = tl.GetEndFrame() - tl.GetStartFrame()
+            state["track_count_video"] = tl.GetTrackCount("video")
+            state["track_count_audio"] = tl.GetTrackCount("audio")
+        return state
+    except Exception:
+        return None
+
+_execution_lifecycle.get_lifecycle_pipeline().set_state_provider(_get_resolve_lifecycle_state)
+
 def _launch_resolve(headless: Optional[bool] = None):
     """Launch DaVinci Resolve and wait for it to become available.
 
@@ -1501,6 +1537,7 @@ _TRACE_OBSERVER_ACTIONS = {
     "get_execution_trace", "get_execution", "list_recent_executions",
     "clear_executions", "begin_execution", "end_execution",
     "export_execution_report",
+    "inspect_operation", "list_lifecycle_hooks",
 }
 
 
@@ -1573,14 +1610,29 @@ def _guard_missing_params(fn):
         async def wrapper(*args, **kwargs):
             action = _guarded_action_name(args, kwargs)
             params = _guarded_params(args, kwargs)
+            lifecycle = _execution_lifecycle.get_lifecycle_pipeline()
+            ctx = _execution_lifecycle.ToolCallContext(
+                tool_name=tool_name,
+                action=action,
+                params=params or {},
+            )
+            decision = lifecycle.run_before(ctx)
+            if decision and not decision.proceed and decision.short_circuit_result is not None:
+                return _build_operation_envelope(tool_name, action, params, decision.short_circuit_result, duration_ms=0)
+
             t0 = time.perf_counter()
             try:
                 result = await fn(*args, **kwargs)
             except _MissingParam as exc:
                 result = _missing_param_error(exc, action)
+            except Exception as exc:
+                duration_ms = max(0, int((time.perf_counter() - t0) * 1000))
+                lifecycle.run_on_error(ctx, exc, duration_ms)
+                raise
             duration_ms = max(0, int((time.perf_counter() - t0) * 1000))
             enveloped = _build_operation_envelope(
                 tool_name, action, params, result, duration_ms=duration_ms)
+            enveloped = lifecycle.run_after(ctx, enveloped, duration_ms)
             _record_execution_step(tool_name, action, params, result, enveloped, duration_ms)
             return enveloped
     else:
@@ -1588,14 +1640,29 @@ def _guard_missing_params(fn):
         def wrapper(*args, **kwargs):
             action = _guarded_action_name(args, kwargs)
             params = _guarded_params(args, kwargs)
+            lifecycle = _execution_lifecycle.get_lifecycle_pipeline()
+            ctx = _execution_lifecycle.ToolCallContext(
+                tool_name=tool_name,
+                action=action,
+                params=params or {},
+            )
+            decision = lifecycle.run_before(ctx)
+            if decision and not decision.proceed and decision.short_circuit_result is not None:
+                return _build_operation_envelope(tool_name, action, params, decision.short_circuit_result, duration_ms=0)
+
             t0 = time.perf_counter()
             try:
                 result = fn(*args, **kwargs)
             except _MissingParam as exc:
                 result = _missing_param_error(exc, action)
+            except Exception as exc:
+                duration_ms = max(0, int((time.perf_counter() - t0) * 1000))
+                lifecycle.run_on_error(ctx, exc, duration_ms)
+                raise
             duration_ms = max(0, int((time.perf_counter() - t0) * 1000))
             enveloped = _build_operation_envelope(
                 tool_name, action, params, result, duration_ms=duration_ms)
+            enveloped = lifecycle.run_after(ctx, enveloped, duration_ms)
             _record_execution_step(tool_name, action, params, result, enveloped, duration_ms)
             return enveloped
 
@@ -6539,6 +6606,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
@@ -6551,6 +6638,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:
@@ -6701,16 +6843,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, {}),
     }
 
 
@@ -16126,6 +16273,11 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         — Write a Markdown or JSON audit report for an execution trace (no connection needed).
       clear_executions(dry_run?) -> {success, cleared}
         — Clear the in-memory execution trace buffer.
+      inspect_operation(tool?, target_action?, target_params?) -> {tool, action, risk, destructive, blast_radius, confirmation_required, snapshot_available, recognised, reasons, pre_state, pre_state_available}
+        — Name-based heuristic, NOT a simulation: it never touches the project and does not validate params. recognised=false means no rule matched; snapshot_available=null means rollback was not determined, not that none exists.
+        — Pre-flight risk assessment and blast radius inspection for any tool action before execution (no connection needed).
+      list_lifecycle_hooks() -> {success, hooks, count}
+        — List active agent tool execution lifecycle hooks and their enabled status (no connection needed).
     """
     p = _params(params)
 
@@ -16286,6 +16438,14 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
             return {"success": True, "dry_run": True, "count": len(_execution_trace.list_recent_executions(100))}
         res = _execution_trace.clear_executions()
         return res
+    if action == "inspect_operation":
+        target_tool = p.get("tool") or p.get("tool_name") or "timeline"
+        target_action = p.get("target_action") or p.get("action") or p.get("op") or "delete_clips"
+        target_params = p.get("target_params") or p.get("params") or {}
+        return _execution_lifecycle.inspect_operation(target_tool, target_action, target_params)
+    if action == "list_lifecycle_hooks":
+        hooks = _execution_lifecycle.list_lifecycle_hooks()
+        return {"success": True, "hooks": hooks, "count": len(hooks)}
 
     # Control-panel actions don't require Resolve to be running.
     if action == "open_control_panel":
@@ -16501,7 +16661,7 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         if err:
             return _err(err)
         return {"success": bool(r.ExportUserPreferencesPreset(clean["name"], clean["path"]))}
-    return _unknown(action, ["launch","runtime_mode","get_version","api_truth","check_version_support","verification_stats","job_status","list_jobs","get_execution_trace","get_execution","list_recent_executions","begin_execution","end_execution","export_execution_report","clear_executions","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","list_user_preferences_presets","save_user_preferences_preset","load_user_preferences_preset","delete_user_preferences_preset","import_user_preferences_preset","export_user_preferences_preset","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
+    return _unknown(action, ["launch","runtime_mode","get_version","api_truth","check_version_support","verification_stats","job_status","list_jobs","get_execution_trace","get_execution","list_recent_executions","begin_execution","end_execution","export_execution_report","clear_executions","inspect_operation","list_lifecycle_hooks","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","list_user_preferences_presets","save_user_preferences_preset","load_user_preferences_preset","delete_user_preferences_preset","import_user_preferences_preset","export_user_preferences_preset","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
 
 
 # ─── V2 C4: Per-field corrections with provenance + changelog ────────────────
@@ -24092,24 +24252,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"),
         }
@@ -24228,23 +24375,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/execution_lifecycle.py

@@ -0,0 +1,496 @@
+"""Universal MCP Tool Execution Lifecycle and Hook Pipeline.
+
+Provides a pluggable, server-wide lifecycle middleware for all compound MCP tools.
+Every tool invocation (synchronous or asynchronous) passes through three distinct
+lifecycle phases:
+
+  1. Pre-flight (run_before):
+     - Risk classification and blast radius calculation (low -> critical)
+     - Resolve state inspection (pre-flight timeline duration, track count, project)
+     - Safe dry-run simulation interception for non-native dry-run actions
+  2. Execution / Error tracking (run_on_error):
+     - Catches exceptions, records duration, informs error observers
+  3. Post-flight (run_after):
+     - Readback verification and contradiction evaluation
+     - State drift detection (unintended timeline duration/structure shifts)
+     - Correlated execution trace aggregation
+"""
+
+from __future__ import annotations
+
+import enum
+import logging
+import threading
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional, Set, Tuple
+
+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
+    MEDIUM = "medium"      # Reversible edits, markers, non-destructive properties
+    HIGH = "high"          # Deletions, ripples, timeline restructuring, batch edits
+    CRITICAL = "critical"  # Project deletion, database resets, permanent loss
+
+
+class BlastRadius(str, enum.Enum):
+    """Scope of impact when an operation executes."""
+    ITEM = "item"          # Single clip, single marker, node
+    TRACK = "track"        # Single track or stem
+    TIMELINE = "timeline"  # Entire active timeline
+    PROJECT = "project"    # Entire Resolve project or Media Pool
+    SYSTEM = "system"      # System preferences, filesystem, host process
+
+
+@dataclass
+class RiskAssessment:
+    """Calculated risk evaluation for a tool action."""
+    level: RiskLevel = RiskLevel.LOW
+    destructive: bool = False
+    blast_radius: BlastRadius = BlastRadius.ITEM
+    confirmation_required: bool = False
+    #: None = not determined. The classifier reads action names; it does not
+    #: know whether timeline_versioning would archive a predecessor, and False
+    #: would assert "no rollback" as a finding it never made.
+    snapshot_available: Optional[bool] = None
+    #: False when no rule matched, i.e. the fields below are name-based
+    #: defaults rather than an assessment of this specific operation.
+    recognised: bool = True
+    reasons: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "level": self.level.value,
+            "destructive": self.destructive,
+            "blast_radius": self.blast_radius.value,
+            "confirmation_required": self.confirmation_required,
+            "snapshot_available": self.snapshot_available,
+            "recognised": self.recognised,
+            "reasons": list(self.reasons),
+        }
+
+
+@dataclass
+class ToolCallContext:
+    """Contextual metadata describing an in-flight tool invocation."""
+    tool_name: str
+    action: str
+    params: Dict[str, Any] = field(default_factory=dict)
+    execution_id: Optional[str] = None
+    risk: RiskAssessment = field(default_factory=RiskAssessment)
+    pre_state: Optional[Dict[str, Any]] = None
+    post_state: Optional[Dict[str, Any]] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class HookDecision:
+    """Decision returned by a pre-flight hook."""
+    proceed: bool = True
+    short_circuit_result: Optional[Dict[str, Any]] = None
+    reason: Optional[str] = None
+
+
+class LifecycleHook:
+    """Base class for all MCP tool lifecycle hooks."""
+    name: str = "base_hook"
+    enabled: bool = True
+
+    def before_tool_call(self, ctx: ToolCallContext) -> Optional[HookDecision]:
+        """Runs before tool invocation. Can short-circuit or modify context."""
+        return None
+
+    def after_tool_call(
+        self, ctx: ToolCallContext, result: Any, duration_ms: int
+    ) -> Optional[Dict[str, Any]]:
+        """Runs after successful tool execution. Can enrich result or emit telemetry."""
+        return None
+
+    def on_error(
+        self, ctx: ToolCallContext, exc: Exception, duration_ms: int
+    ) -> None:
+        """Runs when tool execution raises an unhandled exception."""
+        pass
+
+
+# ─── Built-in Hook Implementations ──────────────────────────────────────────
+
+
+class RiskClassificationHook(LifecycleHook):
+    """Evaluates tool + action + params to classify danger level and blast radius."""
+    name = "risk_classification"
+
+    _CRITICAL_ACTIONS: Set[Tuple[str, str]] = {
+        ("project_manager", "delete_project"),
+        ("project_manager", "close_project_without_saving"),
+        ("media_pool", "delete_timelines"),
+        ("media_pool", "delete_clips"),
+    }
+
+    _HIGH_RISK_ACTIONS: Set[Tuple[str, str]] = {
+        ("timeline", "delete_clips"),
+        ("timeline", "delete_clip_by_id"),
+        ("timeline", "delete_markers"),
+        ("timeline", "ripple_delete"),
+        ("timeline", "cut_clip"),
+        ("edit_engine", "execute_selects"),
+        ("edit_engine", "auto_cut_silence"),
+        ("edit_engine", "ripple_trim"),
+        ("project_manager", "save_project_as"),
+    }
+
+    _READ_ONLY_PREFIXES = ("get_", "list_", "query_", "probe_", "inspect_", "export_", "check_")
+
+    @classmethod
+    def classify(cls, tool_name: str, action: str, params: Dict[str, Any]) -> RiskAssessment:
+        reasons: List[str] = []
+        destructive = False
+        level = RiskLevel.LOW
+        radius = BlastRadius.ITEM
+        conf_required = False
+        recognised = True
+
+        pair = (tool_name, action)
+
+        if pair in cls._CRITICAL_ACTIONS:
+            level = RiskLevel.CRITICAL
+            destructive = True
+            radius = BlastRadius.PROJECT if "project" in tool_name else BlastRadius.TIMELINE
+            conf_required = True
+            reasons.append(f"Action '{action}' is permanently destructive across {radius.value}")
+        elif pair in cls._HIGH_RISK_ACTIONS or action.startswith("delete_") or action.startswith("remove_"):
+            level = RiskLevel.HIGH
+            destructive = True
+            if params.get("ripple", False):
+                radius = BlastRadius.TIMELINE
+                reasons.append("Ripple mode alters downstream timeline synchronization")
+            else:
+                radius = BlastRadius.ITEM
+            conf_required = True
+            reasons.append(f"Destructive timeline 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
+            radius = BlastRadius.ITEM
+        else:
+            # Everything the rules do not recognise. This is a heuristic over
+            # action NAMES, so "unrecognised" covers both a real action nobody
+            # listed and an action that does not exist — and it must not come
+            # back as a confident "medium, not destructive". The guard exists
+            # for hallucinated calls; answering one with reassurance is the
+            # failure it was built to prevent.
+            level = RiskLevel.MEDIUM
+            destructive = action.startswith("reset_") or action.startswith("clear_")
+            radius = BlastRadius.ITEM
+            recognised = False
+            reasons.append(
+                f"'{tool_name}.{action}' matches no risk rule. This assessment is a "
+                "name-based default, not a finding — treat the risk as unestablished "
+                "and check the tool's own documented behaviour before proceeding."
+            )
+
+        return RiskAssessment(
+            level=level,
+            destructive=destructive,
+            blast_radius=radius,
+            confirmation_required=conf_required,
+            snapshot_available=None,
+            reasons=reasons,
+            recognised=recognised,
+        )
+
+    def before_tool_call(self, ctx: ToolCallContext) -> Optional[HookDecision]:
+        ctx.risk = self.classify(ctx.tool_name, ctx.action, ctx.params)
+        return None
+
+
+class ResolveStateInspectionHook(LifecycleHook):
+    """Captures pre-flight Resolve project and timeline state non-blockingly."""
+    name = "resolve_state_inspection"
+
+    def __init__(self, state_provider: Optional[Callable[[], Optional[Dict[str, Any]]]] = None):
+        self._state_provider = state_provider
+
+    def before_tool_call(self, ctx: ToolCallContext) -> Optional[HookDecision]:
+        if self._state_provider is None:
+            return None
+        try:
+            state = self._state_provider()
+            if state:
+                ctx.pre_state = state
+                ctx.risk.snapshot_available = True
+        except Exception as exc:
+            logger.debug(f"Pre-flight state inspection skipped: {exc}")
+        return None
+
+
+class ReadbackVerificationHook(LifecycleHook):
+    """Evaluates readback verification data attached to operation results."""
+    name = "readback_verification"
+
+    def after_tool_call(
+        self, ctx: ToolCallContext, result: Any, duration_ms: int
+    ) -> Optional[Dict[str, Any]]:
+        if not isinstance(result, dict):
+            return None
+
+        # Check if result carries a verification block
+        verif = result.get("verification")
+        if isinstance(verif, dict):
+            contradiction = verif.get("contradiction", False)
+            verified = verif.get("verified", False)
+            if contradiction:
+                logger.warning(
+                    f"Readback contradiction detected on {ctx.tool_name}.{ctx.action}: {verif}"
+                )
+            return {
+                "readback_checked": True,
+                "verified": verified,
+                "contradiction": contradiction,
+            }
+
+        # Track unverified destructive operations
+        if ctx.risk.destructive and "verification" not in result:
+            return {
+                "readback_checked": False,
+                "status": "unverified",
+                "notice": f"Destructive operation {ctx.tool_name}.{ctx.action} completed without readback verification",
+            }
+        return None
+
+
+class DriftDetectionHook(LifecycleHook):
+    """Detects unexpected timeline duration or track structure drift."""
+    name = "drift_detection"
+
+    _DURATION_ALTERING_ACTIONS = {
+        "ripple_delete", "ripple_insert", "auto_cut_silence", "execute_selects",
+        "delete_clips", "cut_clip", "delete_item", "ripple_trim"
+    }
+
+    def __init__(self, state_provider: Optional[Callable[[], Optional[Dict[str, Any]]]] = None):
+        self._state_provider = state_provider
+
+    def after_tool_call(
+        self, ctx: ToolCallContext, result: Any, duration_ms: int
+    ) -> Optional[Dict[str, Any]]:
+        if not ctx.pre_state or self._state_provider is None:
+            return None
+
+        try:
+            post_state = self._state_provider()
+            if not post_state:
+                return None
+            ctx.post_state = post_state
+
+            pre_dur = ctx.pre_state.get("duration_frames")
+            post_dur = post_state.get("duration_frames")
+
+            # Check if duration changed on a non-duration-altering action
+            if (
+                pre_dur is not None
+                and post_dur is not None
+                and pre_dur != post_dur
+                and ctx.action not in self._DURATION_ALTERING_ACTIONS
+            ):
+                warning = (
+                    f"Timeline duration drifted unexpectedly from {pre_dur} to {post_dur} frames "
+                    f"during non-duration altering action '{ctx.action}'"
+                )
+                logger.warning(warning)
+                return {
+                    "drift_detected": True,
+                    "drift_warnings": [warning],
+                    "duration_delta_frames": post_dur - pre_dur,
+                }
+        except Exception as exc:
+            logger.debug(f"Drift detection evaluation skipped: {exc}")
+        return None
+
+
+class ProvenanceTraceHook(LifecycleHook):
+    """Correlates tool lifecycle events into the active execution trace."""
+    name = "provenance_trace"
+
+    def after_tool_call(
+        self, ctx: ToolCallContext, result: Any, duration_ms: int
+    ) -> Optional[Dict[str, Any]]:
+        return {
+            "execution_id": ctx.execution_id,
+            "duration_ms": duration_ms,
+            "risk_level": ctx.risk.level.value,
+        }
+
+
+# ─── Pipeline Coordinator ───────────────────────────────────────────────────
+
+
+class LifecyclePipeline:
+    """Thread-safe coordinator running registered lifecycle hooks."""
+
+    def __init__(self):
+        self._hooks: List[LifecycleHook] = []
+        self._lock = threading.RLock()
+        self._register_default_hooks()
+
+    def _register_default_hooks(self):
+        """The hooks that ship enabled. All of them OBSERVE; none short-circuit.
+
+        `HookDecision(proceed=False)` exists so a deliberately registered hook
+        can gate a call, and `register_hook` is public for that. Nothing
+        shipping uses it, on purpose: a hook that replaces a tool's result is
+        answering on behalf of code that never ran.
+
+        The original of this pipeline shipped a dry-run interceptor that did
+        exactly that — any `dry_run: true` call outside a four-entry allowlist
+        was short-circuited with a synthesised `success: true`. Against 273
+        `dry_run` references in `src/server.py` it hijacked actions with real
+        dry-run paths (`setup.set_defaults`, `resolve_control.clear_executions`),
+        and it answered `success: true` for an invalid enum value and for adding
+        a marker with no timeline in existence. `dry_run` is the one thing an
+        editor reaches for before a destructive edit; a version of it that
+        always succeeds is worse than none, because it is trusted.
+        `test_no_default_hook_short_circuits` keeps it that way.
+        """
+        self._hooks.append(RiskClassificationHook())
+        self._hooks.append(ResolveStateInspectionHook())
+        self._hooks.append(ReadbackVerificationHook())
+        self._hooks.append(DriftDetectionHook())
+        self._hooks.append(ProvenanceTraceHook())
+
+    def register_hook(self, hook: LifecycleHook) -> None:
+        with self._lock:
+            # Replace existing hook with same name if present
+            self._hooks = [h for h in self._hooks if h.name != hook.name]
+            self._hooks.append(hook)
+
+    def set_state_provider(self, provider: Callable[[], Optional[Dict[str, Any]]]) -> None:
+        """Configures state provider callable on inspection and drift hooks."""
+        with self._lock:
+            for hook in self._hooks:
+                if isinstance(hook, (ResolveStateInspectionHook, DriftDetectionHook)):
+                    hook._state_provider = provider
+
+    def run_before(self, ctx: ToolCallContext) -> HookDecision:
+        with self._lock:
+            hooks = list(self._hooks)
+
+        for hook in hooks:
+            if not hook.enabled:
+                continue
+            try:
+                decision = hook.before_tool_call(ctx)
+                if decision and not decision.proceed:
+                    return decision
+            except Exception as exc:
+                logger.error(f"Error in hook '{hook.name}.before_tool_call': {exc}", exc_info=True)
+        return HookDecision(proceed=True)
+
+    def run_after(self, ctx: ToolCallContext, result: Any, duration_ms: int) -> Any:
+        with self._lock:
+            hooks = list(self._hooks)
+
+        contributions: Dict[str, Any] = {}
+        for hook in hooks:
+            if not hook.enabled:
+                continue
+            try:
+                contrib = hook.after_tool_call(ctx, result, duration_ms)
+                if contrib and isinstance(contrib, dict):
+                    contributions[hook.name] = contrib
+            except Exception as exc:
+                logger.error(f"Error in hook '{hook.name}.after_tool_call': {exc}", exc_info=True)
+
+        # Attach telemetry into operation envelope or result if it's a dict
+        if isinstance(result, dict) and contributions:
+            if "_operation" in result and isinstance(result["_operation"], dict):
+                result["_operation"].setdefault("lifecycle", {}).update(contributions)
+        return result
+
+    def run_on_error(self, ctx: ToolCallContext, exc: Exception, duration_ms: int) -> None:
+        with self._lock:
+            hooks = list(self._hooks)
+
+        for hook in hooks:
+            if not hook.enabled:
+                continue
+            try:
+                hook.on_error(ctx, exc, duration_ms)
+            except Exception as hook_exc:
+                logger.error(f"Error in hook '{hook.name}.on_error': {hook_exc}", exc_info=True)
+
+    def list_hooks(self) -> List[Dict[str, Any]]:
+        with self._lock:
+            return [
+                {
+                    "name": h.name,
+                    "enabled": h.enabled,
+                    "class": h.__class__.__name__,
+                }
+                for h in self._hooks
+            ]
+
+    def inspect_operation(
+        self, tool_name: str, action: str, params: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """Inspects pre-flight risk, blast radius, and state before execution."""
+        p = params or {}
+        assessment = RiskClassificationHook.classify(tool_name, action, p)
+        pre_state = None
+        for hook in self._hooks:
+            if isinstance(hook, ResolveStateInspectionHook) and hook._state_provider:
+                try:
+                    pre_state = hook._state_provider()
+                except Exception:
+                    pass
+                break
+
+        return {
+            "success": True,
+            "tool": tool_name,
+            "action": action,
+            "risk": assessment.to_dict(),
+            "destructive": assessment.destructive,
+            "blast_radius": assessment.blast_radius.value,
+            "confirmation_required": assessment.confirmation_required,
+            # One value, from one place. This previously reported
+            # `assessment.snapshot_available or (pre_state is not None)` at the
+            # top level while `risk.snapshot_available` stayed False — the same
+            # response answering "can I roll this back?" both ways. Reading a
+            # project name is not a restorable snapshot, and the classifier
+            # never sets the flag, so the honest answer is "not determined".
+            "snapshot_available": assessment.snapshot_available,
+            "reasons": assessment.reasons,
+            "recognised": assessment.recognised,
+            "pre_state": pre_state,
+            # Whether pre_state reflects a live Resolve at all, so a caller can
+            # tell "no project open" from "never asked".
+            "pre_state_available": pre_state is not None,
+        }
+
+
+# Global singleton pipeline
+_GLOBAL_PIPELINE = LifecyclePipeline()
+
+
+def get_lifecycle_pipeline() -> LifecyclePipeline:
+    return _GLOBAL_PIPELINE
+
+
+def inspect_operation(
+    tool_name: str, action: str, params: Optional[Dict[str, Any]] = None
+) -> Dict[str, Any]:
+    return _GLOBAL_PIPELINE.inspect_operation(tool_name, action, params)
+
+
+def list_lifecycle_hooks() -> List[Dict[str, Any]]:
+    return _GLOBAL_PIPELINE.list_hooks()
+
+
+def classify_operation_risk(
+    tool_name: str, action: str, params: Optional[Dict[str, Any]] = None
+) -> RiskAssessment:
+    return RiskClassificationHook.classify(tool_name, action, params or {})
+

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."""