davinci-resolve-mcp 2.204.0 → 2.205.1

package/CHANGELOG.md

@@ -2,6 +2,101 @@
 
 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.1 — #182: the bridge preflight checks both halves of Resolve's Python lookup
+
+### Fixed
+
+- **A `PYTHON3HOME` prefix with a dylib but no `bin/python3` is no longer
+  reported as usable.** fusionscript.so does two things with the prefix — runs
+  `<prefix>/bin/python3` and dlopens `<prefix>/lib/libpython3.X.dylib`, whose
+  strings sit adjacent in the binary — and the preflight validated only the
+  second. It answered `python3_home.usable: true` and
+  `resolve_will_list_python_scripts: true` while Resolve listed **zero** Python
+  scripts and logged nothing, which is the worst shape this failure can take:
+  the user has been told the thing is configured correctly, so the real cause
+  is the last place they look. Reported in #182, with the root cause and the
+  fix both correct as filed.
+- **The interpreter has to be there under the unversioned name.** `python3` is
+  the literal name in the binary, and that is what makes this trap easy to hit:
+  a Homebrew framework prefix carries a perfectly good
+  `lib/libpython3.13.dylib` next to a `bin/` that has `python3.13` and no
+  `python3`. It is formula-dependent — `python@3.14` ships one, `python@3.11`
+  and `python@3.13` do not — so the same "Homebrew Python" advice works on one
+  machine and silently fails on the next. `framework_pythons()` has always
+  required `bin/python3`; this is the same rule applied to the route that
+  skipped it.
+- **A set-but-unusable `PYTHON3HOME` is now called out even when another
+  discovery route exists.** Resolve reads it first, and whether it falls back
+  after choosing a prefix it cannot use is inferred from string adjacency
+  rather than established — so resting a clean bill of health on a route
+  Resolve may never reach is the same false all-clear in a new place. The
+  preflight names the mismatch, prints the exact `ln -s` that repairs it, and
+  suggests `launchctl unsetenv` as the alternative.
+
+### Changed
+
+- **The advice says that `launchctl setenv` does not survive a reboot.** A
+  bridge that listed for weeks and then stopped, with no error anywhere, is
+  usually that, and nobody connects it back to a step they ran a month
+  earlier. `sudo ln -s "$(command -v python3)" /usr/local/bin/python3` is
+  offered as the persistent alternative, with the `PATH` caveat — presented
+  alongside the sudo-free route rather than replacing it, since avoiding a
+  system-wide install is the whole point of the #143 fix.
+
+## 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.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)
@@ -80,6 +80,20 @@ never sees your shell's environment. Restart Resolve afterwards. A Lua canary is
 installed alongside so you can tell "Python not detected" apart from a wrong
 folder.
 
+Two things that bite (#182). The prefix must contain **both**
+`lib/libpython3.X.dylib` and `bin/python3` under that exact **unversioned**
+name — Homebrew's framework builds often ship only `bin/python3.13`, which is
+half a Python as far as Resolve is concerned, and the installer's preflight now
+says so instead of reporting a usable prefix. And `launchctl setenv` **does not
+survive a reboot**; if scripts stop listing weeks later with no error, that is
+why. For something persistent, put an interpreter where Resolve already looks
+(this one needs `sudo`, and check that `/usr/local/bin` does not precede your
+normal Python on `PATH`):
+
+```bash
+sudo ln -s "$(command -v python3)" /usr/local/bin/python3
+```
+
 Validated on free 21.0.3.7 and Studio 19.1.3.7, both macOS. The Windows paths
 added in v2.70.1 (issue #106) shipped unverified; reports on free 21.0.1.11
 (issue #109) and free 21.0.3.7 (issue #112) have since shown the bridge
@@ -231,6 +245,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.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.204.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.205.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -61,6 +61,12 @@ launchctl setenv PYTHON3HOME "$(python3 -c 'import sys; print(sys.prefix)')"
 
 必须用 `launchctl setenv` 而不是 `export`——Resolve 从 Dock 启动，看不到你 shell 的环境变量。之后重启 Resolve。安装时会顺带装一个 Lua 金丝雀脚本，帮你区分"Python 未被检测到"和"目录放错"。
 
+有两个坑（#182）。前缀里必须**同时**有 `lib/libpython3.X.dylib` 和 `bin/python3`——而且是这个**不带版本号**的名字。Homebrew 的 framework 构建经常只提供 `bin/python3.13`，在 Resolve 眼里这只算半个 Python；安装器的预检现在会明说这一点，而不是报告前缀可用。另外，`launchctl setenv` **在重启后不会保留**；如果几周之后脚本又不列出来了且没有任何报错，通常就是这个原因。想要持久生效，就把解释器放到 Resolve 本来就会查的位置（这条需要 `sudo`，并且先确认 `/usr/local/bin` 没有排在你常用 Python 的 `PATH` 前面）：
+
+```bash
+sudo ln -s "$(command -v python3)" /usr/local/bin/python3
+```
+
 已在免费版 21.0.3.7 和 Studio 19.1.3.7 上验证（均为 macOS）。v2.70.1（issue #106）加入的 Windows 路径发布时未经验证；后续免费版 21.0.1.11（issue #109）和免费版 21.0.3.7（issue #112）的用户报告证实，Windows 11 上桥接在 `%PROGRAMDATA%` 和 `%APPDATA%` **两处**都能安装、列出并正常服务，这些路径现在是已证实而非假设。Linux 同样已获证实：免费版 20.3.2.9 的用户报告（issue #129，Fedora 43）显示桥接可安装到 `~/.local/share/DaVinciResolve/Fusion/Scripts/Utility`，用系统 Python 就能直接枚举脚本（Linux 完全没有这套查找问题），并能端到端正常服务。现在没有任何平台停留在假设上：macOS 为本项目直接验证，Windows 和 Linux 来自用户报告。
 
 注意：桥接在服务期间会一直占用端口。v2.70.3 之前，Windows 上的桥接可能在 Resolve 退出后存活，挡住下一个会话的监听器；如果你用的是旧版本且桥接不响应了，检查是否有残留的 `fuscript.exe` 还占着端口。
@@ -152,6 +158,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

@@ -41,6 +41,14 @@ Existing tool call sites work unchanged. Two things to know when diagnosing it:
   canary, which always lists, so "Python not detected" is distinguishable from
   "wrong folder". The preflight is macOS-only — off macOS Resolve finds Python
   by other means, and running the check there was a false alarm (#106).
+  Two follow-ups from #182 worth having in hand when a user says the menu is
+  empty despite a set `PYTHON3HOME`: the prefix needs **both**
+  `lib/libpython3.X.dylib` and `bin/python3` under that **unversioned** name
+  (Homebrew framework builds often ship only `python3.X`, so half the check
+  passes on the very interpreter people reach for), and `launchctl setenv` does
+  not survive a reboot — a bridge that listed for weeks and then stopped, with
+  no error anywhere, is usually that. `sudo ln -s "$(command -v python3)"
+  /usr/local/bin/python3` is the persistent alternative.
 - **Windows: both script folders confirmed.** `%PROGRAMDATA%` (#109) and
   `%APPDATA%` (#112) have each been shown serving the bridge on Windows 11 free
   builds. If a user reports the menu entry missing on Windows, ask whether the
@@ -158,6 +166,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.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.204.0",
+  "version": "2.205.1",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/scripts/install_resolve_bridge.py

@@ -286,10 +286,14 @@ _LUA_CANARY = """-- Installed by davinci-resolve-mcp as an enumeration canary.
 -- Resolve is listing Lua and silently skipping Python: it cannot find a Python 3.
 -- It looks at PYTHON3HOME, then /usr/local/bin/python3 -- and nowhere else, which
 -- is why Homebrew, pyenv, uv and conda interpreters go unseen. Either point it at
--- the one you have (no sudo):
+-- the one you have (no sudo, but does NOT survive a reboot):
 --   launchctl setenv PYTHON3HOME "$(python3 -c 'import sys; print(sys.prefix)')"
--- (launchctl, not export -- Resolve never sees your shell), or install a
--- python.org build, which creates /usr/local/bin/python3. Restart Resolve after.
+-- (launchctl, not export -- Resolve never sees your shell; and the prefix needs
+-- BOTH lib/libpython3.X.dylib and bin/python3 under that unversioned name --
+-- Homebrew framework builds often ship only python3.X), or put one where Resolve
+-- already looks, which persists:
+--   sudo ln -s "$(command -v python3)" /usr/local/bin/python3
+-- A python.org build creates that symlink for you. Restart Resolve after.
 print("Resolve is enumerating scripts. If the Python probe is missing, Resolve")
 print("cannot find a Python 3: set PYTHON3HOME with launchctl setenv, or install")
 print("a python.org build. Homebrew/pyenv/uv/conda are not looked at directly.")
@@ -335,12 +339,28 @@ def launchd_env(name: str) -> str | None:
 
 
 def python3_home_prefix() -> dict:
-    """Is PYTHON3HOME set for Resolve, and does it point at a loadable Python 3?
+    """Is PYTHON3HOME set for Resolve, and does it point at a usable Python 3?
 
-    "Loadable" means the `lib/libpython3.X.dylib` that fusionscript.so dlopens.
-    An interpreter that cannot supply one is reported as set-but-unusable rather
-    than counted, because the silent-non-enumeration symptom is identical and the
-    remedy is not.
+    Usable means BOTH halves of what fusionscript.so does with the prefix, whose
+    strings sit adjacent in the binary:
+
+        python3 -c 'import sys; ...sys.prefix...'   # run <prefix>/bin/python3
+        /libpython                                  # dlopen <prefix>/lib/libpython3.X.dylib
+
+    Checking only the dylib reported `usable: true` for a prefix Resolve cannot
+    run, and then Resolve listed zero Python scripts — the exact false all-clear
+    this function's docstring already warned about, since "the silent
+    non-enumeration symptom is identical and the remedy is not" (issue #182).
+
+    The interpreter must be there under the **unversioned** name. That is the
+    literal name in the binary, and it is what makes this trap so easy to hit:
+    a Homebrew framework prefix has `bin/python3.13` but no `bin/python3`
+    (formula-dependent — python@3.14 ships one, python@3.11 and python@3.13 do
+    not), while carrying a perfectly good `lib/libpython3.13.dylib`. Half the
+    check passes on exactly the interpreter most likely to be tried.
+
+    `framework_pythons()` has always required `bin/python3`; this is the same
+    rule applied to the route that skipped it.
     """
     value = launchd_env("PYTHON3HOME")
     result = {
@@ -348,20 +368,70 @@ def python3_home_prefix() -> dict:
         "in_launchd": value is not None,
         "in_this_shell": os.environ.get("PYTHON3HOME") or None,
         "dylib": None,
+        "interpreter": None,
+        "reason": None,
         "usable": False,
     }
     if not value:
         return result
+
+    prefix = Path(value)
     try:
-        dylibs = sorted(Path(value).glob("lib/libpython3.*.dylib"))
+        dylibs = sorted(prefix.glob("lib/libpython3.*.dylib"))
     except OSError:
         dylibs = []
+    interpreter = prefix / "bin" / "python3"
+    try:
+        # .exists() follows symlinks, so a dangling one reads as absent — which
+        # is what it is to a Resolve trying to execute it.
+        has_interpreter = interpreter.exists()
+    except OSError:
+        has_interpreter = False
+
     if dylibs:
         result["dylib"] = str(dylibs[0])
-        result["usable"] = True
+    if has_interpreter:
+        result["interpreter"] = str(interpreter)
+    result["usable"] = bool(dylibs) and has_interpreter
+
+    if result["usable"]:
+        return result
+    if dylibs and not has_interpreter:
+        versioned = sorted(
+            child.name for child in _safe_iterdir(prefix / "bin")
+            if child.name.startswith("python3.")
+            and not child.name.endswith("-config")
+        )
+        result["reason"] = (
+            f"{prefix}/lib has a libpython dylib but {interpreter} does not "
+            f"exist. Resolve runs the UNVERSIONED name `python3`"
+            + (f"; this prefix ships only {', '.join(versioned)}. " if versioned else ". ")
+            + "Homebrew framework builds are the common case. Either symlink it "
+            f"inside the prefix (ln -s {versioned[0] if versioned else 'python3.X'} "
+            f"{prefix}/bin/python3), or point PYTHON3HOME at a prefix that has both."
+        )
+    elif has_interpreter and not dylibs:
+        result["reason"] = (
+            f"{interpreter} exists but {prefix}/lib has no libpython3.X.dylib "
+            "for Resolve to dlopen. A static or non-shared build cannot be "
+            "embedded; point PYTHON3HOME at a prefix built with a shared library."
+        )
+    else:
+        result["reason"] = (
+            f"{prefix} has neither bin/python3 nor lib/libpython3.X.dylib. "
+            "Check the path — it should be a Python `sys.prefix`, which "
+            "`python3 -c 'import sys; print(sys.prefix)'` prints."
+        )
     return result
 
 
+def _safe_iterdir(directory: Path) -> list[Path]:
+    try:
+        return sorted(directory.iterdir())
+    except OSError:
+        return []
+
+
 def fallback_python3() -> dict:
     """`/usr/local/bin/python3` — the path baked into fusionscript.so.
 
@@ -414,7 +484,27 @@ def python_preflight() -> dict:
     # the order the binary's strings imply, and it is the one the user chose.
     found = home["usable"] or fallback["exists"] or bool(frameworks)
     advice = None
-    if not found:
+    if home["in_launchd"] and not home["usable"]:
+        # A set-but-broken PYTHON3HOME has to be said out loud even when another
+        # route exists. PYTHON3HOME is read FIRST, and whether Resolve falls
+        # back after choosing a prefix it cannot use is not established — the
+        # ordering here is inferred from string adjacency in fusionscript.so,
+        # not from decompiled control flow. Reporting a clean bill of health on
+        # the strength of a route Resolve may never reach is the failure this
+        # whole check exists to prevent (issue #182).
+        advice = (
+            "PYTHON3HOME is set for Resolve but does not point at a Python 3 it "
+            f"can use.\n{home['reason']}\n"
+            + ("Another discovery route is present on this machine, but Resolve "
+               "reads PYTHON3HOME first and it is NOT established that it falls "
+               "back after picking a prefix it cannot use. Fix the prefix or "
+               "unset it (launchctl unsetenv PYTHON3HOME) rather than relying "
+               "on the fallback.\n" if found else "")
+            + "Restart Resolve after changing it. The Lua canary installed "
+            "alongside lists regardless, so 'Python not detected' stays "
+            "distinguishable from 'wrong folder'."
+        )
+    elif not found:
         advice = (
             "Resolve cannot find a Python 3, so it will silently ignore every "
             ".py script in its Scripts folders — they will simply not appear in "
@@ -428,8 +518,16 @@ def python_preflight() -> dict:
             "print(sys.prefix)')\"\n"
             "     Use launchctl, NOT export — Resolve is launched from the Dock "
             "and never sees your shell's environment. The prefix must contain "
-            "lib/libpython3.X.dylib.\n"
-            "  2. Or install a python.org build, which creates "
+            "BOTH lib/libpython3.X.dylib and bin/python3 under that exact "
+            "unversioned name. Note that launchctl setenv does not survive a "
+            "reboot: if scripts stop listing weeks later with no error, this is "
+            "why.\n"
+            "  2. Or symlink an interpreter where Resolve already looks, which "
+            "is a file on disk and does persist (needs sudo):\n"
+            "       sudo ln -s \"$(command -v python3)\" /usr/local/bin/python3\n"
+            "     Check that /usr/local/bin does not precede your normal Python "
+            "on PATH before doing this.\n"
+            "  3. Or install a python.org build, which creates "
             "/usr/local/bin/python3 for you.\n"
             "Restart Resolve either way, then re-check. The Lua canary installed "
             "alongside will list regardless, so you can tell 'Python not "

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.204.0"
+VERSION = "2.205.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.204.0"
+VERSION = "2.205.1"
 
 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,
+    }