davinci-resolve-mcp 2.204.0 → 2.205.0

package/CHANGELOG.md

@@ -2,6 +2,60 @@
 
 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.205.0 — a standard operation envelope on every tool result
+
+Adapted from the design contributed in PR #181.
+
+### Added
+
+- **`_operation` on every compound tool return.** Agents orchestrating
+  multi-turn edits had to answer the same three questions after every call —
+  did it happen, was it verified, what changed — in a different vocabulary per
+  tool (`readback.missing`, `succeeded`/`failed`, `partial`,
+  `status: "confirmation_required"`). Those are now normalized into one block:
+  `status` (`success` / `partial` / `blocked` / `failed`), `operation`,
+  `execution_id`, `verification`, `changes` and `warnings`.
+- **A contradiction stays its own verification status.** "Resolve reported
+  success and the readback disagrees" is a different thing for a caller to act
+  on than "the call failed", and this repo's most valuable reliability signal;
+  it does not collapse into a failure. `readback.as_verification_dict` renders
+  a `verify_by_readback` result in the same shape.
+- **`setup(action="set_defaults", params={"result_envelope": ...})`** — `dual`
+  (default), `pure`, or `legacy`, persisted to `logs/server-preferences.json`
+  and restored at startup. Override per call with `params={"envelope": ...}` or
+  per process with `RESOLVE_MCP_RESULT_ENVELOPE`.
+
+### Notes on the adaptation
+
+- **The envelope is namespaced, not flattened.** Five of its key names —
+  `status` (22 sites), `operation` (20), `warnings` (15), `result` (8),
+  `changes` (2) — are already domain keys on this server, so merging the
+  envelope into the top level silently rewrote them: `resolve_control`
+  `job_status` reported `"success"` instead of `"done"` (an agent polling a
+  job would never see it finish), a confirm gate's `"confirmation_required"`
+  became `"blocked"` — renaming the very signal the envelope exists to make
+  unambiguous — and a transcription's `"Transcribed"` was lost. The payload is
+  now passed through untouched and the envelope rides under `_operation`,
+  following the existing `_versioning` convention. A guard test fails the
+  suite if any module starts returning `_operation` as a domain key.
+- **An unreported delta is absent, not zero.** `changes: {}` reads as "this
+  operation changed nothing", which is false about an edit that simply never
+  declared its deltas — the silent-lie class this codebase treats as a bug.
+  The key is omitted instead, and `verification: "unverified"` likewise means
+  "no evidence reported", not "checked and clean".
+- **Status inference keys only on conventions this repo actually uses.**
+  `blocked` reads like a gate flag but is a domain key holding the *list of
+  targets that could not be resolved*; a successful `bulk_match_to_hero` dry
+  run carries a non-empty one. Reading it as a gate reported a confirmation
+  that was never requested.
+- **Semantic deltas are declared by the action, not guessed from key names.**
+  A mapping like `properties_restored_items` → `properties_updated` turns a
+  ripple insert's internal bookkeeping into an edit the caller never made.
+  `timeline.ripple_insert` declares its own; the rest report none rather than
+  a fabricated zero.
+- Verified through the real stdio JSON-RPC tool layer, not just at module
+  level: 36 tools register, the envelope arrives, the payload is intact.
+
 ## What's New in v2.204.0 — #179: the managed install can boot the advanced server
 
 ### Fixed

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.204.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.205.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)
@@ -231,6 +231,27 @@ The open-source servers are complete and fully functional on their own.
 | Extension authoring | Fuse, DCTL, ACES DCTL, and Resolve-page Lua/Python script lifecycle helpers with safe MCP-marked install/remove |
 | Craft guidance | The bundled editorial, colour, audio, and workflow guidance served as prose over MCP — indexed, searchable, and readable by any client, not just ones with this repository on disk |
 
+### Operation envelope
+
+Every compound tool return carries an `_operation` block beside its payload, so
+an agent reads one shape instead of a different key per tool: `status`
+(`success` / `partial` / `blocked` / `failed`), `verification` (with
+`contradiction` kept distinct — Resolve reported success and the readback
+disagreed), `changes` (the semantic delta), `warnings`, and an `execution_id`.
+
+Two absences are meaningful and deliberate. `verification.status: "unverified"`
+means *no evidence was reported*, not "checked and clean". A missing `changes`
+means the action did not report a delta, not that nothing changed — an empty
+`{}` there would be a confident, wrong answer about an edit that simply never
+declared one.
+
+The envelope is namespaced rather than merged into the top level because
+`status`, `operation`, `warnings`, `result` and `changes` are all already domain
+keys here; flattening would rewrite a background job's `status: "done"` and a
+confirm gate's `status: "confirmation_required"`. `setup(action="set_defaults",
+params={"result_envelope": "pure" | "legacy"})` changes the shape, per call via
+`params={"envelope": ...}`, per process via `RESOLVE_MCP_RESULT_ENVELOPE`.
+
 ## Optional Extras
 
 The core install is deliberately small: Python, ffmpeg, and the Resolve scripting

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.204.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.205.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.204.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.205.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -152,6 +152,14 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 | 渲染与交付 | 格式/编解码矩阵探测、渲染设置校验、队列任务生命周期检查、带护栏的快速导出 |
 | 扩展开发 | Fuse、DCTL、ACES DCTL 及 Resolve 页面 Lua/Python 脚本生命周期助手，带 MCP 标记的安全安装/移除 |
 
+### 操作信封（operation envelope）
+
+每个复合工具的返回值都会在原有 payload 旁边带一个 `_operation` 块，这样 agent 读的是同一种结构，而不是每个工具一套 key：`status`（`success` / `partial` / `blocked` / `failed`）、`verification`（其中 `contradiction` 单独成一档——Resolve 报告成功但回读结果不一致）、`changes`（语义增量）、`warnings`，以及一个 `execution_id`。
+
+有两种"缺失"是刻意保留其含义的。`verification.status: "unverified"` 表示*没有报告任何证据*，不等于"已检查且没问题"。`changes` 缺失表示这个动作没有报告增量，不等于什么都没改——在那里放一个空的 `{}`，等于对一次并未声明增量的剪辑给出一个自信而错误的回答。
+
+信封是带命名空间的，而不是平铺到顶层，因为 `status`、`operation`、`warnings`、`result` 和 `changes` 在这里本来就都是业务 key；平铺会改写后台任务的 `status: "done"` 和确认关卡的 `status: "confirmation_required"`。用 `setup(action="set_defaults", params={"result_envelope": "pure" | "legacy"})` 改变形态，单次调用用 `params={"envelope": ...}`，进程级用 `RESOLVE_MCP_RESULT_ENVELOPE`。
+
 ## 可选增强
 
 核心安装刻意保持精简：Python、ffmpeg 和 Resolve 脚本 API。有些功能需要更多依赖，且**每一项都会诚实拒绝并给出自己的安装命令，而不是退化成瞎猜**——编造的节拍或虚构的电平会产出自信但错误的结果，比没有这个功能更糟。

package/docs/SKILL.md

@@ -158,6 +158,59 @@ before mutating Resolve state.
 
 ---
 
+## Reading A Result: The Operation Envelope
+
+Every compound tool return carries an `_operation` block alongside its normal
+payload. It answers the three questions that otherwise need a different key per
+tool — did it happen, was it verified, what changed:
+
+```json
+{
+  "success": true,
+  "insert_frame_absolute": 86400,
+  "shift_frames": 48,
+
+  "_operation": {
+    "status": "success",
+    "operation": "timeline.ripple_insert",
+    "execution_id": "exec_d2c123817bee",
+    "verification": {
+      "status": "passed",
+      "checks": [{"check": "readback_verification", "passed": true, "missing_items": 0}],
+      "contradiction": false
+    },
+    "changes": {"items_added": 3, "items_moved": 17, "items_deleted": 0}
+  }
+}
+```
+
+- **`status`** — `success` | `partial` | `blocked` | `failed`. `blocked` means a
+  confirm gate is waiting; the payload still carries the `confirm_token` and
+  `preview` to act on.
+- **`verification.status`** — `passed` | `failed` | `partial` | `contradiction`
+  | `unverified`. **`contradiction` is the one to stop on**: Resolve reported
+  success and the readback disagrees. **`unverified` means no evidence was
+  reported, not that the operation was checked and found clean** — if you need
+  certainty there, go and read the state back.
+- **`changes`** — the semantic delta, present only when the action declared or
+  reported one. **Absent means "not reported", never "nothing changed"**, so do
+  not read a missing `changes` as a no-op.
+- **`warnings`** — present only when there are any.
+- **`execution_id`** — correlates one call across logs and transcripts.
+
+The envelope is namespaced under `_operation` rather than merged into the top
+level because `status`, `operation`, `warnings`, `result` and `changes` are all
+already domain keys on this server (a background job's `status` is `"done"`, a
+confirm gate's is `"confirmation_required"`). The payload is passed through
+untouched; read domain values where you always read them.
+
+Change the shape with `setup(action="set_defaults", params={"result_envelope": "pure" | "legacy" | "dual"})`,
+per call with `params={"envelope": "pure"}`, or per process with
+`RESOLVE_MCP_RESULT_ENVELOPE`. `pure` returns only the envelope with the payload
+nested under `result`; `legacy` adds nothing.
+
+---
+
 ## Two Server Modes
 
 | Mode | Entry point | Tool count | Use when |

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.204.0"
+VERSION = "2.205.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.204.0",
+  "version": "2.205.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.204.0"
+VERSION = "2.205.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.204.0"
+VERSION = "2.205.0"
 
 import base64
 import os
@@ -60,6 +60,12 @@ from src.utils.page_lock import (
 )
 from src.utils.proc import safe_run
 from src.utils.readback import verify_by_readback, verification_stats as _verification_stats
+from src.utils import operation_result as _operation_result
+from src.utils.operation_result import (
+    build_operation_envelope as _build_operation_envelope,
+    get_envelope_mode as _get_envelope_mode,
+    set_envelope_mode as _set_envelope_mode,
+)
 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,
@@ -1472,6 +1478,15 @@ def _guarded_action_name(args, kwargs) -> str:
     return str(args[0]) if args else "?"
 
 
+def _guarded_params(args, kwargs) -> Optional[Dict[str, Any]]:
+    """This call's `params` dict, wherever in the signature it was passed."""
+    if isinstance(kwargs.get("params"), dict):
+        return kwargs["params"]
+    if len(args) > 1 and isinstance(args[1], dict):
+        return args[1]
+    return None
+
+
 def _guard_missing_params(fn):
     """Tool decorator: report a missing parameter instead of leaking a KeyError.
 
@@ -1489,21 +1504,35 @@ def _guard_missing_params(fn):
     - **The signature is not (action, params).** `media_analysis` also takes
       `ctx: Optional[Context]`, so the wrapper forwards `*args, **kwargs` rather
       than naming parameters it does not know about.
+
+    It is also where the operation envelope is attached, for the same reason it
+    is where the missing-parameter guard lives: this is the one seam every tool
+    return passes through. In the default `dual` mode the payload is untouched
+    and the envelope rides under `_operation` — see `src/utils/operation_result`
+    for why it is namespaced rather than flattened.
     """
+    tool_name = getattr(fn, "__name__", "tool")
+
     if inspect.iscoroutinefunction(fn):
         @functools.wraps(fn)
         async def wrapper(*args, **kwargs):
+            action = _guarded_action_name(args, kwargs)
             try:
-                return await fn(*args, **kwargs)
+                result = await fn(*args, **kwargs)
             except _MissingParam as exc:
-                return _missing_param_error(exc, _guarded_action_name(args, kwargs))
+                result = _missing_param_error(exc, action)
+            return _build_operation_envelope(
+                tool_name, action, _guarded_params(args, kwargs), result)
     else:
         @functools.wraps(fn)
         def wrapper(*args, **kwargs):
+            action = _guarded_action_name(args, kwargs)
             try:
-                return fn(*args, **kwargs)
+                result = fn(*args, **kwargs)
             except _MissingParam as exc:
-                return _missing_param_error(exc, _guarded_action_name(args, kwargs))
+                result = _missing_param_error(exc, action)
+            return _build_operation_envelope(
+                tool_name, action, _guarded_params(args, kwargs), result)
 
     wrapper.__wrapped_by_missing_param_guard__ = True
     return wrapper
@@ -5238,6 +5267,15 @@ def _timeline_ripple_insert_impl(proj, tl, p: Dict[str, Any], *, resolve=None) -
         "readback": {"after_counts": after_counts, "missing": missing},
         "gap_frames_by_track": gap_by_track,
         "warnings": warnings,
+        # Semantic delta for the operation envelope. Declared rather than
+        # inferred: this action deletes and re-appends the tail to move it, so
+        # a reader counting raw API calls would see a deletion that the edit
+        # did not make.
+        "_changes": {
+            "items_added": len(built_inserts),
+            "items_moved": len(tail_rows),
+            "items_deleted": 0,
+        },
     }
     if failures:
         result["failures"] = failures
@@ -10215,6 +10253,63 @@ def _read_json_strict(path: str) -> Dict[str, Any]:
     return payload if isinstance(payload, dict) else {}
 
 
+_SERVER_PREFS_ENV = "RESOLVE_MCP_SERVER_PREFS"
+
+
+def _server_preferences_path() -> str:
+    """Where server-general defaults live.
+
+    Separate from the media-analysis preferences file: these are settings about
+    how the server answers, not about how it analyses media, and mixing them
+    would make either file's name a lie.
+    """
+    override = os.environ.get(_SERVER_PREFS_ENV)
+    if override:
+        return os.path.realpath(os.path.abspath(os.path.expanduser(override)))
+    return os.path.join(project_dir, "logs", "server-preferences.json")
+
+
+def _read_server_preferences() -> Dict[str, Any]:
+    try:
+        return _read_json_strict(_server_preferences_path())
+    except ConfigParseError:
+        return {}
+
+
+def _write_server_preferences(preferences: Dict[str, Any]) -> None:
+    # Same atomic replace as the other preference stores: a crash mid-write must
+    # not truncate a file whose reader falls back to {}, since the next save
+    # would then persist that empty state over the user's settings.
+    path = _server_preferences_path()
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    tmp_path = f"{path}.tmp-{os.getpid()}-{threading.get_ident()}-{time.time_ns()}"
+    try:
+        with open(tmp_path, "w", encoding="utf-8") as handle:
+            json.dump(preferences, handle, indent=2, sort_keys=True)
+            handle.write("\n")
+        os.replace(tmp_path, path)
+    finally:
+        try:
+            os.remove(tmp_path)
+        except OSError:
+            pass
+
+
+def _apply_persisted_envelope_mode() -> str:
+    """Restore the saved result_envelope default at startup.
+
+    An explicit RESOLVE_MCP_RESULT_ENVELOPE wins: a process-level override is a
+    deliberate act for this run, and a saved preference should not silently
+    outrank it.
+    """
+    if os.environ.get("RESOLVE_MCP_RESULT_ENVELOPE"):
+        return _get_envelope_mode()
+    saved = _read_server_preferences().get("result_envelope")
+    if isinstance(saved, str):
+        _set_envelope_mode(saved)
+    return _get_envelope_mode()
+
+
 def _read_media_analysis_preferences() -> Dict[str, Any]:
     path = _media_analysis_preferences_path()
     try:
@@ -15091,13 +15186,59 @@ def _setup_updates_defaults() -> Dict[str, Any]:
     }
 
 
+def _setup_general_defaults() -> Dict[str, Any]:
+    return {
+        "result_envelope": _get_envelope_mode(),
+        "options": {"result_envelope": list(_operation_result.MODES)},
+        "preferences_path": _server_preferences_path(),
+    }
+
+
 def _setup_defaults_snapshot() -> Dict[str, Any]:
     return {
+        "general": _setup_general_defaults(),
         "media_analysis": _setup_media_analysis_defaults(),
         "updates": _setup_updates_defaults(),
     }
 
 
+def _setup_set_general_defaults(general: Dict[str, Any], dry_run: bool) -> Dict[str, Any]:
+    """Persist server-general defaults. Currently just the result envelope."""
+    if not general:
+        return {"changed": False, "recognized": False}
+
+    mode = _first_param(
+        general, "result_envelope", "resultEnvelope", "envelope_mode", "envelopeMode",
+        default=None)
+    if mode is None:
+        return {"changed": False, "recognized": False}
+
+    cleaned = str(mode).strip().lower()
+    if cleaned not in _operation_result.MODES:
+        return _err(
+            f"result_envelope must be one of {', '.join(_operation_result.MODES)}",
+            code="INVALID_ENUM_VALUE", category="validation",
+            state={"result_envelope": mode})
+
+    if dry_run:
+        return {"changed": True, "recognized": True, "result_envelope": cleaned,
+                "current": _get_envelope_mode()}
+
+    # Persist before applying: a saved setting that does not survive a restart
+    # is a setting the caller was told they changed and did not.
+    try:
+        preferences = _read_json_strict(_server_preferences_path())
+    except ConfigParseError as exc:
+        return _err(
+            f"server preferences file is unreadable: {exc}",
+            code="CONFIG_UNREADABLE", category="state",
+            remediation=f"Repair or delete {_server_preferences_path()}, then retry.")
+    preferences["result_envelope"] = cleaned
+    _write_server_preferences(preferences)
+    _set_envelope_mode(cleaned)
+    return {"changed": True, "recognized": True, "result_envelope": _get_envelope_mode()}
+
+
 def _setup_set_media_analysis_defaults(media_defaults: Dict[str, Any], dry_run: bool) -> Dict[str, Any]:
     if not media_defaults:
         return {"changed": False, "recognized": False}
@@ -15691,6 +15832,17 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
                 },
                 "updates.check_interval_hours": {"values": "number >= 0.1", "storage": str(update_state_path(project_dir))},
                 "updates.snooze_hours": {"values": "number >= 0.1", "storage": str(update_state_path(project_dir))},
+                "general.result_envelope": {
+                    "description": (
+                        "Where the operation envelope goes. 'dual' (default) leaves the "
+                        "payload untouched and adds the envelope under '_operation'; "
+                        "'pure' returns only the envelope with the payload under 'result'; "
+                        "'legacy' adds nothing. Override per call with params={'envelope': ...}."
+                    ),
+                    "values": list(_operation_result.MODES),
+                    "current": _get_envelope_mode(),
+                    "storage": _server_preferences_path(),
+                },
             },
         }
 
@@ -15702,12 +15854,23 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
     if action in {"set_defaults", "set", "configure"}:
         defaults = p.get("defaults") if isinstance(p.get("defaults"), dict) else {}
         merged = {**defaults, **{k: v for k, v in p.items() if k != "defaults"}}
+        # media_analysis owns every unclaimed key, so anything another setter
+        # owns has to be named here or it lands in the wrong store.
+        _general_keys = {
+            "general", "result_envelope", "resultEnvelope",
+            "envelope_mode", "envelopeMode",
+        }
+        general_defaults = {
+            **_setup_nested(merged, "general"),
+            **{k: v for k, v in merged.items() if k in _general_keys and k != "general"},
+        }
         media_defaults = {
             **_setup_nested(merged, "media_analysis", "mediaAnalysis"),
             **{
                 key: value
                 for key, value in merged.items()
                 if key not in {"updates", "mcp_updates", "mcpUpdates", "dry_run", "dryRun"}
+                and key not in _general_keys
             },
             **({
                 "timed_markers_default": _first_param(
@@ -15758,19 +15921,25 @@ 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 {}),
         }
 
+        general_result = _setup_set_general_defaults(general_defaults, dry_run)
+        if general_result.get("error"):
+            return general_result
         media_result = _setup_set_media_analysis_defaults(media_defaults, dry_run)
         if media_result.get("error"):
             return media_result
         update_result = _setup_set_updates_defaults(update_defaults, dry_run)
         if update_result.get("error"):
             return update_result
-        recognized = bool(media_result.get("recognized")) or bool(update_result.get("recognized"))
+        recognized = (bool(general_result.get("recognized"))
+                      or bool(media_result.get("recognized"))
+                      or bool(update_result.get("recognized")))
         if not recognized:
             return _err("set_defaults did not receive a recognized default to set")
 
         return _ok(
             dry_run=dry_run,
             changes={
+                "general": general_result,
                 "media_analysis": media_result,
                 "updates": update_result,
             },
@@ -31310,6 +31479,9 @@ def _install_threaded_tool_dispatch(fastmcp) -> int:
 
 
 if __name__ == "__main__":
+    # Before any tool can answer: a saved result_envelope default has to be in
+    # force on the first call, not the second.
+    logger.info(f"Result envelope mode: {_apply_persisted_envelope_mode()}")
     start_background_update_check(VERSION, project_dir, logger, env=_setup_update_env())
     _install_threaded_tool_dispatch(mcp)
 

package/src/utils/operation_result.py

@@ -0,0 +1,377 @@
+"""A standard operation envelope over every compound tool's return value.
+
+Agents orchestrating multi-turn edits have to answer the same three questions
+after every call — did it actually happen, was it verified, and what changed —
+and today each tool answers them in its own vocabulary: ``readback.missing``,
+``succeeded``/``failed``, ``partial``, ``status: "confirmation_required"``.
+This module normalizes those into one shape so the answer is in the same place
+every time.
+
+Adapted from the design contributed in PR #181.
+
+**Where the envelope lives.** Its keys are namespaced under a single reserved
+key rather than merged into the top level, because half of them are already
+domain keys here and merging silently destroys them:
+
+    status       22 sites — a background job's "done", a transcription's
+                 "Transcribed", a confirm gate's "confirmation_required"
+    operation    20 sites
+    warnings     15 sites
+    result        8 sites
+    changes       2 sites
+
+Flattening the envelope over those rewrites `job_status`'s "done" to "success"
+(an agent polling a job then never sees it finish) and a confirm gate's
+"confirmation_required" to "blocked" — renaming the very signal the envelope
+exists to make unambiguous. So in the default ``dual`` mode the raw payload is
+passed through **untouched** and the envelope is added under ``_operation``,
+following the existing ``_versioning`` private-key convention. Nothing is
+shadowed, nothing is dropped, and there is still exactly one place to look.
+
+Modes:
+  ``dual``   (default) raw payload verbatim + ``_operation``.
+  ``pure``   only the envelope, domain payload nested under ``result``. Opt in
+             per call with ``params={"envelope": "pure"}``, per session with
+             ``setup(action="set_defaults", params={"result_envelope": "pure"})``,
+             or per process with ``RESOLVE_MCP_RESULT_ENVELOPE=pure``.
+  ``legacy`` no envelope at all.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import uuid
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger("resolve-mcp.operation-result")
+
+#: The reserved key the envelope hangs off in ``dual`` mode. Verified unused as
+#: a domain key across ``src/`` — ``test_envelope_key_stays_reserved`` keeps it
+#: that way, since the day a tool returns its own ``_operation`` is the day this
+#: mode starts destroying payloads the way the flat one did.
+ENVELOPE_KEY = "_operation"
+
+MODES = ("dual", "pure", "legacy")
+DEFAULT_MODE = "dual"
+
+
+def _clean_mode(mode: Any) -> Optional[str]:
+    if not isinstance(mode, str):
+        return None
+    candidate = mode.strip().lower()
+    return candidate if candidate in MODES else None
+
+
+_CURRENT_ENVELOPE_MODE = (
+    _clean_mode(os.environ.get("RESOLVE_MCP_RESULT_ENVELOPE")) or DEFAULT_MODE
+)
+
+
+def get_envelope_mode() -> str:
+    """The envelope mode applied when a call does not name one."""
+    return _CURRENT_ENVELOPE_MODE
+
+
+def set_envelope_mode(mode: str) -> str:
+    """Set the default envelope mode. Unknown values leave it unchanged."""
+    global _CURRENT_ENVELOPE_MODE
+    cleaned = _clean_mode(mode)
+    if cleaned:
+        _CURRENT_ENVELOPE_MODE = cleaned
+    return _CURRENT_ENVELOPE_MODE
+
+
+def new_execution_id() -> str:
+    """A compact id for correlating one tool call across logs and transcripts."""
+    return f"exec_{uuid.uuid4().hex[:12]}"
+
+
+# ─── Status ──────────────────────────────────────────────────────────────────
+
+def normalize_status(raw: Any) -> str:
+    """Reduce a result to 'success' | 'partial' | 'blocked' | 'failed'.
+
+    Deliberately narrow. Every rule below keys on a convention this repo
+    actually uses, checked against the call sites — a heuristic that guesses
+    from a plausible-looking key name produces exactly the confident-and-wrong
+    status the envelope is supposed to eliminate. The clearest example is
+    ``blocked``: it reads like a gate flag, but here it is a domain key holding
+    the *list of targets that could not be resolved* (`timeline` range delete,
+    `timeline_item_color.bulk_match_to_hero`), and a successful dry-run carries
+    a non-empty one. Keying on it would report a gate that never happened.
+    """
+    if not isinstance(raw, dict):
+        return "success" if bool(raw) else "failed"
+
+    # The confirm gate. `_issue_confirm_token` is the single producer of these
+    # responses and always stamps this exact status, so the check is exact
+    # rather than inferred.
+    if raw.get("status") == "confirmation_required" or raw.get("confirmation_required") is True:
+        return "blocked"
+
+    if raw.get("error"):
+        return "failed"
+    if raw.get("success") is False:
+        return "failed"
+
+    # Bulk operations set this explicitly when some units failed.
+    if raw.get("partial") is True:
+        return "partial"
+    succeeded, failed = raw.get("succeeded"), raw.get("failed")
+    if isinstance(succeeded, int) and isinstance(failed, int) and succeeded > 0 and failed > 0:
+        return "partial"
+
+    return "success"
+
+
+# ─── Warnings ────────────────────────────────────────────────────────────────
+
+def extract_warnings(raw: Any) -> List[str]:
+    """Every advisory the payload carries, as a flat list of strings."""
+    if not isinstance(raw, dict):
+        return []
+
+    out: List[str] = []
+
+    def add(value: Any) -> None:
+        if isinstance(value, str) and value.strip() and value.strip() not in out:
+            out.append(value.strip())
+
+    plural = raw.get("warnings")
+    if isinstance(plural, list):
+        for item in plural:
+            add(item if isinstance(item, str) else str(item) if item else None)
+    else:
+        add(plural)
+    add(raw.get("warning"))
+
+    ignored = raw.get("ignored_options")
+    if ignored:
+        add(f"Ignored unsupported options: {ignored}")
+
+    return out
+
+
+# ─── Verification ────────────────────────────────────────────────────────────
+
+def extract_verification(raw: Any) -> Dict[str, Any]:
+    """Normalize whatever verification evidence the payload carries.
+
+    'unverified' means *no evidence was reported*, which is not the same as
+    'checked and fine' — a caller that needs certainty should treat it as an
+    open question rather than a pass.
+    """
+    unverified = {"status": "unverified", "checks": [], "contradiction": False}
+    if not isinstance(raw, dict):
+        return unverified
+
+    # An impl that already speaks this shape wins outright.
+    existing = raw.get("verification")
+    if isinstance(existing, dict) and existing:
+        merged = dict(existing)
+        merged.setdefault(
+            "status", "passed" if existing.get("verified") else "unverified")
+        merged.setdefault("checks", [])
+        merged.setdefault("contradiction", False)
+        return merged
+
+    checks: List[Dict[str, Any]] = []
+    status = "unverified"
+    contradiction = False
+
+    readback = raw.get("readback")
+    if isinstance(readback, dict):
+        missing = readback.get("missing")
+        if isinstance(missing, list):
+            checks.append({
+                "check": "readback_verification",
+                "passed": not missing,
+                "missing_items": len(missing),
+            })
+            status = "passed" if not missing else "failed"
+
+    # verify_by_readback's own shape: a mutation that reported success while the
+    # post-state disagrees is a contradiction, this repo's single most valuable
+    # reliability signal — it must not be flattened into a plain failure.
+    if "verified" in raw:
+        verified = bool(raw["verified"])
+        contradiction = bool(raw.get("contradiction"))
+        checks.append({
+            "check": "readback_post_state",
+            "passed": verified,
+            "contradiction": contradiction,
+            "observed": raw.get("observed"),
+        })
+        status = "contradiction" if contradiction else ("passed" if verified else "failed")
+
+    if "property_restore_failures" in raw:
+        failures = _as_int(raw.get("property_restore_failures"))
+        checks.append({
+            "check": "property_restore",
+            "passed": failures == 0,
+            "restored_items": _as_int(raw.get("properties_restored_items")),
+            "failures": failures,
+        })
+        if failures and status in ("passed", "unverified"):
+            status = "partial"
+
+    succeeded, failed = raw.get("succeeded"), raw.get("failed")
+    if isinstance(succeeded, int) and isinstance(failed, int):
+        checks.append({
+            "check": "bulk_operations",
+            "passed": failed == 0,
+            "succeeded": succeeded,
+            "failed": failed,
+        })
+        if status == "unverified":
+            if failed == 0 and succeeded > 0:
+                status = "passed"
+            elif succeeded > 0:
+                status = "partial"
+            elif failed > 0:
+                status = "failed"
+
+    if not checks:
+        return unverified
+    return {"status": status, "checks": checks, "contradiction": contradiction}
+
+
+# ─── Changes ─────────────────────────────────────────────────────────────────
+
+def _as_int(value: Any) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return 0
+
+
+#: Domain key → semantic delta. Every entry is a key that exists in `src/` and
+#: means what the delta says it means; nothing is mapped on the strength of a
+#: suggestive name. `properties_restored_items`, for instance, is deliberately
+#: absent: a ripple insert restores clip properties it had to re-apply after
+#: moving items, which is bookkeeping, not an edit the user made.
+_COUNT_ALIASES = {
+    "items_added": ("inserted_clips",),
+    "items_moved": ("tail_items_shifted",),
+    "items_deleted": (),
+}
+
+
+def extract_changes(raw: Any) -> Optional[Dict[str, Any]]:
+    """The operation's semantic delta, or None when it did not report one.
+
+    None, not ``{}``. An empty dict reads as "this operation changed nothing",
+    which is a false statement about a ripple insert that simply never declared
+    its deltas — the silent-lie failure this codebase treats as a bug class. A
+    caller that needs a number and gets None knows to go and count.
+    """
+    if not isinstance(raw, dict):
+        return None
+
+    changes: Dict[str, Any] = {}
+
+    # An impl that declares its own deltas is authoritative.
+    declared = raw.get("_changes")
+    if isinstance(declared, dict):
+        changes.update(declared)
+
+    for canonical, aliases in _COUNT_ALIASES.items():
+        if canonical in raw:
+            changes[canonical] = _as_int(raw[canonical])
+            continue
+        for alias in aliases:
+            if alias in raw:
+                changes[canonical] = _as_int(raw[alias])
+                break
+
+    if "shift_frames" in raw:
+        changes["shift_frames"] = raw["shift_frames"]
+
+    versioning = raw.get("_versioning")
+    if isinstance(versioning, dict):
+        metric = versioning.get("metric")
+        before, after = versioning.get("before_value"), versioning.get("after_value")
+        if metric and before is not None and after is not None:
+            changes["metric"] = metric
+            changes["before_value"] = before
+            changes["after_value"] = after
+            try:
+                changes["delta"] = round(float(after) - float(before), 4)
+            except (TypeError, ValueError):
+                pass
+        if versioning.get("archived"):
+            changes["timeline_archived"] = True
+            if versioning.get("archived_version"):
+                changes["archived_version"] = versioning["archived_version"]
+
+    return changes or None
+
+
+# ─── Assembly ────────────────────────────────────────────────────────────────
+
+def is_passthrough(obj: Any) -> bool:
+    """MCP content objects (Image, TextContent, EmbeddedResource) go through as-is."""
+    return getattr(obj.__class__, "__name__", "") in {
+        "Image", "TextContent", "EmbeddedResource"
+    }
+
+
+def _requested_mode(params: Optional[Dict[str, Any]], fallback: Optional[str]) -> str:
+    if isinstance(params, dict):
+        for key in ("envelope", "_envelope"):
+            if key in params:
+                named = _clean_mode(params[key])
+                if named:
+                    return named
+                if isinstance(params[key], bool):
+                    return "pure" if params[key] else "legacy"
+    return _clean_mode(fallback) or get_envelope_mode()
+
+
+def build_operation_envelope(
+    tool_name: str,
+    action: str,
+    params: Optional[Dict[str, Any]],
+    raw_result: Any,
+    *,
+    execution_id: Optional[str] = None,
+    mode: Optional[str] = None,
+) -> Any:
+    """Attach the operation envelope to one action's return value."""
+    if is_passthrough(raw_result):
+        return raw_result
+
+    selected = _requested_mode(params, mode)
+    if selected == "legacy":
+        return raw_result
+
+    envelope: Dict[str, Any] = {
+        "status": normalize_status(raw_result),
+        "operation": f"{tool_name}.{action}",
+        "execution_id": execution_id or new_execution_id(),
+        "verification": extract_verification(raw_result),
+    }
+
+    changes = extract_changes(raw_result)
+    if changes is not None:
+        envelope["changes"] = changes
+
+    warnings = extract_warnings(raw_result)
+    if warnings:
+        envelope["warnings"] = warnings
+
+    versioning = raw_result.get("_versioning") if isinstance(raw_result, dict) else None
+    if isinstance(versioning, dict) and versioning.get("analysis_run_id"):
+        envelope["run_id"] = versioning["analysis_run_id"]
+
+    if selected == "pure":
+        return {**envelope, "result": raw_result}
+
+    # dual: the payload is passed through byte-for-byte and the envelope rides
+    # alongside it. A non-dict return has nowhere to carry the key, so it is
+    # handed back unchanged rather than being boxed into a shape callers of
+    # that action have never seen.
+    if not isinstance(raw_result, dict):
+        return raw_result
+    return {**raw_result, ENVELOPE_KEY: envelope}

package/src/utils/readback.py

@@ -89,3 +89,32 @@ def verify_by_readback(
             _STATS["unverified"] += 1
 
     return result
+
+
+def as_verification_dict(
+    readback_result: Dict[str, Any],
+    *,
+    check_name: str = "readback_verification",
+) -> Dict[str, Any]:
+    """Render a ``verify_by_readback`` result in the operation envelope's shape.
+
+    A contradiction stays a distinct status rather than collapsing into a plain
+    failure: "the API said yes and the post-state says no" is a different thing
+    for a caller to act on than "the call failed".
+    """
+    verified = bool(readback_result.get("verified"))
+    contradiction = bool(readback_result.get("contradiction"))
+    check: Dict[str, Any] = {
+        "check": check_name,
+        "passed": verified,
+        "contradiction": contradiction,
+        "success_raw": readback_result.get("success_raw"),
+        "observed": readback_result.get("observed"),
+    }
+    if "intent" in readback_result:
+        check["intent"] = readback_result["intent"]
+    return {
+        "status": "contradiction" if contradiction else ("passed" if verified else "failed"),
+        "checks": [check],
+        "contradiction": contradiction,
+    }