davinci-resolve-mcp 2.203.0 → 2.205.0

package/CHANGELOG.md

@@ -2,6 +2,106 @@
 
 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
+
+- **The managed install now contains the tree the advanced bin imports.**
+  `setup` registered `davinci-resolve-advanced` in every generated client
+  config, pointing at `<managed root>/bin/davinci-resolve-advanced-mcp.mjs` —
+  but the bootstrapper's sync list never copied `resolve-advanced/`, which
+  that bin imports. The process died with `ERR_MODULE_NOT_FOUND` before the
+  MCP handshake, and every client reported the same uninformative "subprocess
+  closed stdout before responding". `resolve-advanced/` is now synced, and a
+  regression test drives the real sync into a temp root rather than restating
+  the list, so dropping it again fails the suite. Reported in #179.
+- **Its Node dependencies are installed there too.** Syncing the tree alone
+  was only half the fix: the managed root has no `node_modules`, so
+  `@modelcontextprotocol/sdk`, `zod`, `jszip`, `fzstd` and `zstd-codec` still
+  failed to resolve. `setup` now runs `npm install --omit=dev --omit=optional`
+  under the managed `resolve-advanced/` before install.py writes any config.
+  Optional native deps (`better-sqlite3`, `sharp`, `pg`) stay optional — the
+  server already reports those gaps itself through `capabilities`, and a
+  failed native build must not take the whole setup down. Verified end to
+  end: a fresh managed install now completes the MCP handshake and registers
+  all 18 advanced tools.
+- **A config is only written for a layout that can boot.** When
+  `resolve-advanced/` or its deps are absent, `build_advanced_entry` now emits
+  an `npx -y --package davinci-resolve-mcp@<version>` command instead of a
+  managed bin path that cannot start. `resolve-advanced/package.json` is the
+  single source of truth for which deps have to be present — install.py and
+  the bin both read it rather than restating the list.
+- **An unbootable advanced server names its own fix.** The bin preflights its
+  server tree and dependencies and exits with what is missing and how to
+  repair it, instead of an `ERR_MODULE_NOT_FOUND` stack. The diagnostic goes
+  to stderr — stdout is the JSON-RPC channel, where it would corrupt the
+  handshake rather than explain it. `--version` and `--help` keep answering
+  from a broken install, since those are what a user reaches for when the
+  server will not start.
+
+### Added
+
+- **`davinci-resolve-mcp sync`** — refresh the managed install and provision
+  the advanced server's Node deps without running the full interactive setup.
+  `--no-deps` syncs files only. Re-syncing preserves the provisioned
+  `node_modules`; a dev checkout's own `node_modules` is never copied into a
+  managed install, since its optional native deps are built for the
+  developer's platform and ABI.
+
 ## What's New in v2.203.0 — E151: verify_roundtrip fits a source offset from the majority
 
 ### Fixed

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.203.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)
@@ -160,6 +160,12 @@ Add it alongside the live server (both ship in one `npm install`):
 need user-installed tools (ffmpeg for `audio`, `sharp`/`better-sqlite3` for some paths) — call the
 `capabilities` tool for live status and install hints.
 
+Unlike the Python server, this one has Node dependencies. `npx davinci-resolve-mcp setup` installs them
+into the managed install (`npm install --omit=dev --omit=optional` under `resolve-advanced/`) and only
+then registers the bin. If that install could not run — offline, or npm unavailable — setup registers
+an `npx` command for the advanced server instead, so the entry it writes always boots. To repair an
+existing install without re-running setup: `npx davinci-resolve-mcp sync`.
+
 ### Bradford Post Assistant — managed application (closed beta)
 
 The maintainers also build **Bradford Post Assistant**, a desktop application on top of this
@@ -225,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.203.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.203.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.205.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -105,6 +105,8 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 `install.py` 会把两个配置条目都打印出来。核心是纯 JS/MIT，无必需的原生模块；少数功能需要用户自装工具（`audio` 需要 ffmpeg，部分路径需要 `sharp`/`better-sqlite3`）——调用 `capabilities` 工具可查看实时状态和安装提示。
 
+和 Python 服务器不同，这个服务器有 Node 依赖。`npx davinci-resolve-mcp setup` 会先把依赖装进托管安装目录（在 `resolve-advanced/` 下执行 `npm install --omit=dev --omit=optional`），装好之后才注册这个可执行文件。如果安装跑不起来（离线，或者没有 npm），setup 会改为给 advanced 服务器写一条 `npx` 命令，这样写出去的配置条目总是能启动。要修复一个已有的安装而不重跑 setup：`npx davinci-resolve-mcp sync`。
+
 ### Bradford Post Assistant——托管应用（封闭测试中）
 
 维护者还在这个开源基础之上构建了 **Bradford Post Assistant**，一款桌面应用。MCP 服务器给了 agent 一双手，Post Assistant 则是围绕这双手的工作副驾——一个面向后期制作的本地 AI 助手，客户素材永不离开工作站：
@@ -150,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/bin/davinci-resolve-advanced-mcp.mjs

@@ -62,7 +62,55 @@ if (major < 20 || (major === 20 && minor < 9)) {
   process.exit(1);
 }
 
-const serverEntry = path.resolve(__dirname, '..', 'resolve-advanced', 'server', 'index.mjs');
+const advancedRoot = path.resolve(packageRoot, 'resolve-advanced');
+const serverEntry = path.join(advancedRoot, 'server', 'index.mjs');
+
+// Preflight, for the same reason as the Node floor above: a managed install
+// that never received resolve-advanced/ (or its deps) otherwise dies with a
+// bare ERR_MODULE_NOT_FOUND before the MCP handshake, and the client reports
+// only "subprocess closed stdout before responding" — a stack trace with no
+// fix in it. Issue #179. Say what is missing and how to repair it.
+function missingRuntimePieces() {
+  if (!fs.existsSync(serverEntry)) {
+    return { what: `the advanced server tree (${serverEntry} is missing)` };
+  }
+  let required = [];
+  try {
+    const manifest = JSON.parse(fs.readFileSync(path.join(advancedRoot, 'package.json'), 'utf8'));
+    required = Object.keys(manifest.dependencies || {});
+  } catch {
+    return { what: `resolve-advanced/package.json (cannot tell which deps are required)` };
+  }
+  const modulesDir = path.join(advancedRoot, 'node_modules');
+  const missing = required.filter(
+    (dep) => !fs.existsSync(path.join(modulesDir, ...dep.split('/'))),
+  );
+  // Deps may also be hoisted above the package (an npm/npx install puts them in
+  // a parent node_modules), so an empty local node_modules is not conclusive —
+  // only report deps the resolver genuinely cannot see.
+  const unresolvable = missing.filter((dep) => {
+    try {
+      import.meta.resolve(dep);
+      return false;
+    } catch {
+      return true;
+    }
+  });
+  return unresolvable.length ? { what: `dependencies: ${unresolvable.join(', ')}` } : null;
+}
+
+const gap = missingRuntimePieces();
+if (gap) {
+  process.stderr.write(
+    `[davinci-resolve-advanced-mcp] cannot start: ${gap.what}.\n` +
+    `This install is at ${packageRoot}.\n` +
+    `Fix: run \`npx davinci-resolve-mcp setup\` to repair the managed install ` +
+    `(it syncs resolve-advanced/ and installs its Node dependencies), or run the ` +
+    `server straight from the package with ` +
+    `\`npx -y --package davinci-resolve-mcp davinci-resolve-advanced-mcp\`.\n`,
+  );
+  process.exit(1);
+}
 
 const { startServer } = await import(pathToFileURL(serverEntry).href);
 await startServer();

package/bin/davinci-resolve-mcp.mjs

@@ -24,6 +24,11 @@ const PY_ABI_RISK_MINOR = 13;
 const SYNC_ITEMS = [
   "bin",
   "src",
+  // The Node 'advanced' bin resolves ../resolve-advanced/server/index.mjs
+  // relative to itself, and install.py registers that bin into every generated
+  // client config. Leaving the tree out of the sync shipped configs that
+  // pointed at a module the managed install could never contain (issue #179).
+  "resolve-advanced",
   "docs",
   "examples",
   "scripts",
@@ -52,6 +57,7 @@ Usage:
   davinci-resolve-mcp server [server.py options]
   davinci-resolve-mcp control-panel [control panel options]
   davinci-resolve-mcp batch <plan|run|status|list|resume|cancel> [options]
+  davinci-resolve-mcp sync [--no-deps]
   davinci-resolve-mcp --version
   davinci-resolve-mcp --help
 
@@ -61,6 +67,7 @@ Examples:
   npx davinci-resolve-mcp doctor
   npx davinci-resolve-mcp batch run /path/to/footage --depth standard
   npx davinci-resolve-mcp batch run /path/to/footage --json > progress.log
+  npx davinci-resolve-mcp sync            # refresh the managed install only
 
 Environment:
   DAVINCI_RESOLVE_MCP_INSTALL_ROOT   Override the managed install directory.
@@ -132,6 +139,28 @@ function validateManagedRoot(root) {
   }
 }
 
+// Top-level children of a synced item that the sync must NOT delete. The
+// advanced server's node_modules is installed *into* the managed root by
+// provisionAdvancedDeps and has no counterpart in the package, so a blanket
+// clear would throw it away on every subsequent command and force a reinstall.
+const SYNC_PRESERVE = {
+  "resolve-advanced": ["node_modules"],
+};
+
+function clearDestination(destination, preserve) {
+  if (!preserve.length || !fs.existsSync(destination)) {
+    fs.rmSync(destination, { recursive: true, force: true });
+    return;
+  }
+  const keep = new Set(preserve);
+  for (const entry of fs.readdirSync(destination)) {
+    if (keep.has(entry)) {
+      continue;
+    }
+    fs.rmSync(path.join(destination, entry), { recursive: true, force: true });
+  }
+}
+
 function copyItem(name, destinationRoot) {
   const source = path.join(PACKAGE_ROOT, name);
   if (!fs.existsSync(source)) {
@@ -139,7 +168,7 @@ function copyItem(name, destinationRoot) {
   }
 
   const destination = path.join(destinationRoot, name);
-  fs.rmSync(destination, { recursive: true, force: true });
+  clearDestination(destination, SYNC_PRESERVE[name] || []);
   fs.cpSync(source, destination, {
     recursive: true,
     errorOnExist: false,
@@ -154,6 +183,13 @@ function shouldSyncPath(sourcePath) {
   if (basename === "__pycache__" || basename === ".DS_Store") {
     return false;
   }
+  // A dev checkout carries resolve-advanced/node_modules with optional native
+  // deps (sharp, better-sqlite3) built for the developer's platform+ABI.
+  // Copying those into a managed install is slow and ships binaries that may
+  // not load there; provisionAdvancedDeps installs them fresh instead.
+  if (basename === "node_modules") {
+    return false;
+  }
   if (basename.endsWith(".pyc") || basename.endsWith(".pyo")) {
     return false;
   }
@@ -179,6 +215,124 @@ function syncManagedInstall(root) {
   return root;
 }
 
+// ─── Advanced (Node) server runtime ─────────────────────────────────────────
+//
+// The advanced bin imports ../resolve-advanced/server/index.mjs, which in turn
+// imports @modelcontextprotocol/sdk, zod, jszip, fzstd, zstd-codec and the
+// vendored codecs. Syncing the tree is only half the fix for issue #179: the
+// managed root has no node_modules, so the imports still fail. Node resolves
+// them from resolve-advanced/node_modules, which resolve-advanced/package.json
+// declares — so that manifest, not a list duplicated here, is the source of
+// truth for what has to be present.
+
+function advancedRoot(root) {
+  return path.join(root, "resolve-advanced");
+}
+
+function advancedServerEntry(root) {
+  return path.join(advancedRoot(root), "server", "index.mjs");
+}
+
+function advancedRequiredDeps(root) {
+  const manifest = path.join(advancedRoot(root), "package.json");
+  try {
+    const parsed = JSON.parse(fs.readFileSync(manifest, "utf8"));
+    return Object.keys(parsed.dependencies || {});
+  } catch {
+    return [];
+  }
+}
+
+/** Can the advanced server actually boot from this root? Names what is missing. */
+function advancedRuntimeStatus(root) {
+  const entry = advancedServerEntry(root);
+  const entryPresent = fs.existsSync(entry);
+  const modulesDir = path.join(advancedRoot(root), "node_modules");
+  const required = advancedRequiredDeps(root);
+  const missingDeps = required.filter(
+    (dep) => !fs.existsSync(path.join(modulesDir, ...dep.split("/")))
+  );
+  return {
+    entry,
+    entryPresent,
+    // No manifest to read means we cannot tell what is required; treat that as
+    // "not bootable" rather than quietly reporting a clean bill of health.
+    depsPresent: required.length > 0 && missingDeps.length === 0,
+    required,
+    missingDeps,
+    bootable: entryPresent && required.length > 0 && missingDeps.length === 0,
+  };
+}
+
+function npmCommand() {
+  return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+
+/**
+ * Install the advanced server's Node deps into the managed root.
+ *
+ * Optional deps (better-sqlite3, sharp, pg, js-yaml) stay omitted on purpose:
+ * they are native or heavy, the server already reports capability-specific
+ * setup gaps when they are absent, and a failed native build must not take the
+ * whole setup down with it.
+ *
+ * stdio is inherited on stderr only — this must never write to stdout, which
+ * on the server path is a JSON-RPC channel.
+ */
+function provisionAdvancedDeps(root, { force = false } = {}) {
+  const before = advancedRuntimeStatus(root);
+  if (!before.entryPresent) {
+    return { ...before, ran: false, reason: "advanced server tree is not present" };
+  }
+  if (before.depsPresent && !force) {
+    return { ...before, ran: false, reason: "already provisioned" };
+  }
+
+  const result = spawnSync(
+    npmCommand(),
+    ["install", "--omit=dev", "--omit=optional", "--no-audit", "--no-fund"],
+    { cwd: advancedRoot(root), stdio: ["ignore", "inherit", "inherit"], encoding: "utf8" }
+  );
+
+  const after = advancedRuntimeStatus(root);
+  return {
+    ...after,
+    ran: true,
+    ok: result.status === 0 && after.bootable,
+    status: result.status,
+    error: result.error ? result.error.message : null,
+  };
+}
+
+function reportAdvancedRuntime(root, { provision }) {
+  const outcome = provision
+    ? provisionAdvancedDeps(root)
+    : advancedRuntimeStatus(root);
+
+  if (outcome.bootable) {
+    console.log("Advanced server (Node): ready");
+    return outcome;
+  }
+  if (!outcome.entryPresent) {
+    console.log(
+      `Advanced server (Node): unavailable — ${outcome.entry} is missing. ` +
+      `The 'davinci-resolve-advanced' entry will be registered as an npx command instead.`
+    );
+    return outcome;
+  }
+  const missing = outcome.missingDeps.length
+    ? outcome.missingDeps.join(", ")
+    : "its dependency manifest";
+  console.log(
+    `Advanced server (Node): not bootable — missing ${missing}. ` +
+    (outcome.error ? `npm install failed: ${outcome.error}. ` : "") +
+    `Fix: run 'npm install --omit=dev --omit=optional' in ${advancedRoot(root)}, ` +
+    `or re-run 'npx davinci-resolve-mcp setup' with a network connection. ` +
+    `Until then the 'davinci-resolve-advanced' entry falls back to an npx command.`
+  );
+  return outcome;
+}
+
 function parseExecutable(value) {
   if (!value) {
     return null;
@@ -373,6 +527,9 @@ function commandSetup(args) {
 
   console.log(`DaVinci Resolve MCP managed install: ${root}`);
   console.log(`Python: ${python.executable} (${python.major}.${python.minor}.${python.micro})`);
+  // Before install.py, not after: it inspects this layout to decide whether the
+  // 'davinci-resolve-advanced' entry can point at the managed bin.
+  reportAdvancedRuntime(root, { provision: true });
   run(command, commandArgs, { cwd: root });
 }
 
@@ -394,6 +551,8 @@ function commandDoctor(args) {
 
   console.log(`DaVinci Resolve MCP managed install: ${root}`);
   console.log(`Python: ${python.executable} (${python.major}.${python.minor}.${python.micro})`);
+  // Diagnose only — doctor already forces --dry-run and must not install.
+  reportAdvancedRuntime(root, { provision: false });
   run(command, commandArgs, { cwd: root });
 }
 
@@ -422,6 +581,16 @@ function commandBatch(args) {
   run(command, commandArgs, { cwd: root });
 }
 
+function commandSync(args) {
+  const provision = !args.includes("--no-deps");
+  const root = syncManagedInstall(installRoot());
+  console.log(`DaVinci Resolve MCP managed install: ${root}`);
+  const outcome = reportAdvancedRuntime(root, { provision });
+  if (provision && !outcome.bootable) {
+    process.exit(1);
+  }
+}
+
 function main() {
   const argv = process.argv.slice(2);
   // No args → run the MCP stdio server. Anything printed to stdout would
@@ -457,6 +626,10 @@ function main() {
       commandBatch(args);
       return;
     }
+    if (command === "sync") {
+      commandSync(args);
+      return;
+    }
 
     console.error(`Unknown command: ${command}\n`);
     console.error(usage());

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/docs/install.md

@@ -127,6 +127,7 @@ npx davinci-resolve-mcp setup --clients all   # Configure all clients
 npx davinci-resolve-mcp doctor                # Dry-run environment/config check
 npx davinci-resolve-mcp server                # Launch the managed MCP server
 npx davinci-resolve-mcp control-panel         # Launch the local control panel
+npx davinci-resolve-mcp sync                  # Refresh the managed install only
 
 python install.py                              # Interactive mode
 python install.py --clients all                # Configure all clients

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.203.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
@@ -1180,8 +1180,17 @@ def build_advanced_entry(server_path, python_path=None):
     pyaaf2). We pin AAF_PROBE_PYTHON to the project venv's interpreter — the same
     venv install.py installs pyaaf2 into — so AAF preview works out of the box
     instead of depending on whatever `python3` happens to be on PATH.
+
+    The bin is only registered when this install can actually boot it. Pointing
+    a client config at a bin whose module tree is absent produced issue #179:
+    the process died with ERR_MODULE_NOT_FOUND before the MCP handshake and
+    every client reported the same uninformative "subprocess closed stdout
+    before responding". When the layout is incomplete we emit the npx form
+    instead, which resolves the module and its deps from the npm cache.
     """
     project_dir = Path(server_path).resolve().parents[1]  # .../src/server.py -> repo root
+    if not advanced_is_bootable(project_dir):
+        return build_advanced_npx_entry(python_path)
     advanced_bin = project_dir / "bin" / "davinci-resolve-advanced-mcp.mjs"
     entry = {"command": resolve_node_command(), "args": [str(advanced_bin)]}
     if python_path:
@@ -1189,6 +1198,66 @@ def build_advanced_entry(server_path, python_path=None):
     return entry
 
 
+def advanced_required_deps(project_dir):
+    """Runtime deps the advanced server needs, read from its own manifest.
+
+    resolve-advanced/package.json is the single source of truth — the same file
+    `npm install` in that directory acts on, and the same list the advanced bin
+    preflights against. Nothing here restates it.
+    """
+    manifest = Path(project_dir) / "resolve-advanced" / "package.json"
+    try:
+        with open(manifest, "r", encoding="utf-8") as fh:
+            return list(json.load(fh).get("dependencies", {}).keys())
+    except Exception:
+        return []
+
+
+def advanced_is_bootable(project_dir):
+    """True when resolve-advanced/ and its Node deps are both present here."""
+    project_dir = Path(project_dir)
+    if not (project_dir / "resolve-advanced" / "server" / "index.mjs").is_file():
+        return False
+    required = advanced_required_deps(project_dir)
+    if not required:
+        return False
+    # Deps live either in resolve-advanced/node_modules (what `npx
+    # davinci-resolve-mcp setup` provisions in a managed install) or hoisted to
+    # the package root (what a plain `npm install` of this package produces).
+    for dep in required:
+        local = project_dir / "resolve-advanced" / "node_modules" / dep
+        hoisted = project_dir / "node_modules" / dep
+        if not local.is_dir() and not hoisted.is_dir():
+            return False
+    return True
+
+
+def build_advanced_npx_entry(python_path=None):
+    """Fallback advanced entry that runs from the npm package, not this tree.
+
+    Slower to start (npx resolves the package first) but it always boots, which
+    a managed-install bin path does not guarantee.
+    """
+    entry = {
+        "command": "npx",
+        "args": ["-y", "--package", f"davinci-resolve-mcp@{package_version()}",
+                 "davinci-resolve-advanced-mcp"],
+    }
+    if python_path:
+        entry["env"] = {"AAF_PROBE_PYTHON": str(python_path)}
+    return entry
+
+
+def package_version(default="latest"):
+    """Version from package.json, for pinning the npx fallback."""
+    manifest = Path(__file__).resolve().parent / "package.json"
+    try:
+        with open(manifest, "r", encoding="utf-8") as fh:
+            return json.load(fh).get("version") or default
+    except Exception:
+        return default
+
+
 # Node floor for the advanced server (package.json engines). Below it the
 # pure-JS tools limp along while native-dep paths (better-sqlite3) die with a
 # cryptic NODE_MODULE_VERSION mismatch — measured live when a client config's