davinci-resolve-mcp 2.205.2 → 2.207.0

package/CHANGELOG.md

@@ -2,6 +2,109 @@
 
 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.207.0 — execution audit report exports
+
+Contributed in PR #185.
+
+### Added
+
+- **Execution traces can now be exported as reviewable audit reports.**
+  `resolve_control(action="export_execution_report")` writes the latest trace,
+  or a named `execution_id`, as Markdown or JSON. The report carries the
+  request, status, start/end timestamps, duration, tool summary, semantic
+  deltas, verification rollup, warnings, notes, and optional per-step table.
+- **Reports default beside the trace log.** When no path is passed, reports are
+  written under `logs/execution-reports/<execution_id>.md` or `.json`.
+  `RESOLVE_MCP_TRACE_REPORT_DIR` can move that default destination without
+  changing where append-only trace events are logged.
+- **Exports are observer-safe.** Creating a report is exempt from execution-step
+  recording, just like querying traces, so inspecting or exporting a trace
+  cannot mutate the trace being reviewed.
+- **Existing files are protected by default.** A caller must pass
+  `overwrite=true` to replace a report at the chosen path.
+
+### Notes
+
+- The export is built from the existing trace summary fields, not raw tool
+  arguments or raw tool results. It is meant for review and audit, not a replay
+  script.
+- Added focused unit and server integration coverage for Markdown export, JSON
+  export, step omission, invalid formats, overwrite protection, observer
+  isolation, and `resolve_control` dispatch.
+
+### Fixed on the way in
+
+- **An unverified run no longer reports itself as passed.** The verification
+  rollup collapsed "nothing reported any evidence" into `passed: True`, and the
+  report printed it verbatim — so a workflow where nothing was checked produced
+  an audit document reading `Status: unverified` on one line and `Passed: yes`
+  on the next. Those sit inches apart and only one of them gets scanned. The
+  rollup now carries `None` for the unknown case and the Passed row renders
+  "not established — no checks recorded"; a real pass still says yes and a real
+  failure still says no. This is the same distinction v2.206.0 documented for
+  `verification.status`, and the export is exactly where it stops being a
+  nuance and starts being a claim on paper.
+- **The Simplified Chinese README was carrying a false version line.** Its
+  badge and "本翻译对应 vX.Y.Z 版 README" line were bumped to 2.207.0 without the
+  section itself, which is the specific failure the release process calls out —
+  a lagging translation whose version line asserts otherwise. Translated.
+- `path` is documented as honoured-as-given, creating directories to reach the
+  destination: deliberate, since a conform's paperwork belongs beside the
+  conform rather than in `logs/`, but worth stating next to a source-media
+  safety policy. The `execution_id` route is sanitised to a bare filename and
+  cannot escape the report directory — verified.
+
+## What's New in v2.206.0 — agent execution traces
+
+Adapted from the design contributed in PR #183.
+
+### Added
+
+- **Execution traces answer "why did the editor do this?"** v2.205.0's
+  `_operation` envelope describes one call; a real editorial pass is a loop of
+  them. When an agent removes 17 pauses, seventeen individual returns each show
+  one deletion. A trace correlates them into a single execution carrying the
+  request that started it, the tools invoked and how often, cumulative
+  `duration_ms`, the summed semantic deltas (`items_deleted: 17`), and a
+  verification rollup that keeps a contradiction distinct.
+- **Six actions on `resolve_control`** — `begin_execution`, `end_execution`,
+  `get_execution_trace`, `get_execution`, `list_recent_executions`,
+  `clear_executions` — with the compound tool count unchanged at 36. Any call
+  passing an explicit `execution_id` is correlated automatically; queries are
+  exempt from step recording, so observing a trace cannot alter it.
+- **`duration_ms` on the `_operation` envelope**, measured with
+  `time.perf_counter()` around the call.
+
+### Notes on the adaptation
+
+- **The trace log is anchored to the repo, not the working directory.** It was
+  derived from `os.getcwd()` and returned None when `./logs` did not exist —
+  and the generated client configs set no `cwd`, so on a standard install
+  persistence silently did nothing, with no signal either way. It now sits
+  beside `server.log`, the way `media-analysis-preferences.json` and
+  `server-preferences.json` already do, and the directory is created on first
+  write rather than being a precondition.
+- **`list_recent_executions` reports where the log is and whether it is
+  writable.** The append is best-effort and must never fail a real edit, which
+  means a broken destination is otherwise invisible — "the file is empty" and
+  "nothing is being written" looked identical from the caller's side.
+- **The log rotates at 8 MB, keeping one generation.** The in-memory ring was
+  capped at 100 executions; the file had no bound at all, at one append per
+  tool call, on machines that run for months.
+- **The persistence is described accurately.** It is a synchronous buffered
+  append on the calling thread — measured at ~0.07ms per call, immaterial
+  beside any Resolve round-trip, but "non-blocking" was the wrong word for it.
+  It runs outside the lock, so a slow filesystem cannot serialize concurrent
+  tool calls.
+- **What is recorded is now documented**: tool, action, timing, status,
+  semantic deltas, verification — no parameters, no file paths, no clip or
+  project names. The one free-text field is the `request` passed to
+  `begin_execution`, which on client work deserves the care of a commit
+  message.
+- Verified through the real stdio JSON-RPC tool layer: 36 tools register, a
+  begin/call/end cycle produces one correlated trace, and the reported
+  persistence path is the one actually written.
+
 ## What's New in v2.205.2 — #184: background analysis actually starts
 
 ### Fixed

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.205.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.207.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)
@@ -266,6 +266,35 @@ 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`.
 
+### Agent execution traces ("Why did the editor do this?")
+
+Multi-step AI operations correlate across tool calls into unified execution
+traces. Each trace aggregates tool durations (`duration_ms`), call counts, cumulative
+semantic deltas (`items_deleted`, `items_added`), and readback verifications.
+Agents and editors can inspect workflows via `resolve_control`:
+`get_execution_trace(execution_id?)`, `list_recent_executions()`, or open a
+scoped execution with `begin_execution(request="...")` / `end_execution()`.
+`export_execution_report(execution_id?, format="markdown"|"json")` writes a
+reviewable audit artifact with the same summary, defaulting to
+`logs/execution-reports/<execution_id>.md`. `path` writes it anywhere you want
+it instead — alongside a conform in a dated TransferFiles folder, say — and
+creates the directories to get there, so check the path before you send it.
+An existing file is never replaced without `overwrite: true`.
+
+A report for a run where nothing was verified says **"not established — no
+checks recorded"**, not "passed". Absence of evidence is a question still open,
+and an audit document is the last place to let a reader read it as an all-clear.
+
+Traces live in a 100-entry in-memory ring and are appended to
+`logs/execution-traces.jsonl` beside `server.log` — `RESOLVE_MCP_TRACE_FILE`
+moves it. `list_recent_executions` reports that path and whether it is
+writable, so "the log is empty" and "nothing is being written" are
+distinguishable without reading the source. What is recorded is tool name,
+action, timing, status, semantic deltas and verification — no parameters and no
+file paths. The one free-text field is the `request` you pass to
+`begin_execution`, so treat it the way you would a commit message on a client
+project.
+
 ## 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.205.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.207.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.205.2 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.207.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -166,6 +166,18 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 信封是带命名空间的，而不是平铺到顶层，因为 `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`。
 
+### Agent 执行轨迹（"编辑器为什么这么做？"）
+
+多步 AI 操作会跨工具调用关联成统一的执行轨迹，聚合各工具耗时（`duration_ms`）、调用次数、累计语义增量（`items_deleted`、`items_added`）以及回读校验结果。通过 `resolve_control` 查看：`get_execution_trace(execution_id?)`、`list_recent_executions()`，或用 `begin_execution(request="...")` / `end_execution()` 圈定一段执行。
+
+轨迹保存在一个容量 100 条的内存环形缓冲里，并追加写入 `logs/execution-traces.jsonl`（就在 `server.log` 旁边，可用 `RESOLVE_MCP_TRACE_FILE` 改位置），文件到 8 MB 会轮转并保留一份上一代。`list_recent_executions` 会返回该路径以及是否可写，这样"日志是空的"和"根本没在写"就能区分开。记录的内容是工具名、动作、耗时、状态、语义增量和校验结果——不记录参数，也不记录文件路径。唯一的自由文本是你传给 `begin_execution` 的 `request`，在客户项目上请把它当成提交信息来写。
+
+### 导出执行审计报告
+
+`export_execution_report(execution_id?, format="markdown"|"json")` 会把一条轨迹写成可供审阅的审计文件，默认落在 `logs/execution-reports/<execution_id>.md`。传 `path` 可以写到任何你想要的位置——比如跟着某次套底放进当天的 TransferFiles 文件夹——并且会自动创建沿途的目录，所以发出去之前请先确认路径。已存在的文件不会被覆盖，除非显式传 `overwrite: true`。
+
+如果这次运行根本没有做过校验，报告里写的是**"not established — no checks recorded"（未确立——没有记录任何检查）**，而不是"通过"。没有证据是一个仍然悬而未决的问题；审计文件恰恰是最不该让读者把它读成"一切正常"的地方。
+
 ## 可选增强
 
 核心安装刻意保持精简：Python、ffmpeg 和 Resolve 脚本 API。有些功能需要更多依赖，且**每一项都会诚实拒绝并给出自己的安装命令，而不是退化成瞎猜**——编造的节拍或虚构的电平会产出自信但错误的结果，比没有这个功能更糟。

package/docs/SKILL.md

@@ -219,6 +219,99 @@ nested under `result`; `legacy` adds nothing.
 
 ---
 
+## Agent Observability: Execution Traces ("Why did the editor do this?")
+
+Multi-step AI operations (such as detecting pauses, deleting multiple timeline
+items, and verifying the result) correlate across calls into unified execution
+traces. Each trace captures the user request or prompt, tool execution timing,
+cumulative semantic deltas, and verification outcomes.
+
+Example trace shape returned by `resolve_control(action="get_execution_trace")`:
+
+```json
+{
+  "execution_id": "exec_8f91c7a210bc",
+  "request": "Remove all pauses longer than 800ms",
+  "status": "success",
+  "started_at": "2026-09-04T07:30:00Z",
+  "ended_at": "2026-09-04T07:30:02Z",
+  "duration_ms": 2845,
+  "tools": [
+    {
+      "tool": "media_analysis.analyze_timeline",
+      "count": 1,
+      "duration_ms": 821
+    },
+    {
+      "tool": "timeline.delete_item",
+      "count": 17,
+      "duration_ms": 1420
+    }
+  ],
+  "changes": {
+    "items_deleted": 17
+  },
+  "verification": {
+    "status": "passed",
+    "passed": true,
+    "checks": [{"check": "readback_verification", "passed": true}]
+  },
+  "warnings": []
+}
+```
+
+### Trace Actions on `resolve_control`
+
+- **`begin_execution(request?, execution_id?, initiator?)`**: Opens a scoped
+  multi-step execution. Subsequent tool calls in the session automatically thread
+  under this `execution_id` until ended.
+- **`end_execution(execution_id?, verification?, status?, notes?)`**: Closes the
+  active execution, finalizes timestamps and aggregated metrics.
+- **`get_execution_trace(execution_id?)`** / **`get_execution(execution_id)`**:
+  Fetches the trace for a specific ID, or the most recent execution if omitted.
+- **`list_recent_executions(limit?)`**: Returns the recent execution traces
+  (newest first, default limit 20).
+- **`export_execution_report(execution_id?, format?, path?, overwrite?, include_steps?)`**:
+  Writes a Markdown or JSON audit report for a trace. The default destination is
+  `logs/execution-reports/<execution_id>.md`; pass `format: "json"` for
+  structured output, `include_steps: false` for a shorter summary, or
+  `overwrite: true` to replace an existing report.
+- **`clear_executions(dry_run?)`**: Clears the in-memory execution trace buffer.
+
+Explicit correlation is also supported per-call: pass `params={"execution_id": ...}`
+or `params={"trace_id": ...}` in any tool call to associate it with a specific trace.
+
+Two things to know when a trace is not where you expect it. The buffer holds the
+**100 most recent** executions and is in memory only — a server restart empties
+it, and the on-disk `logs/execution-traces.jsonl` is the durable record.
+`list_recent_executions` returns a `persistence` block naming that file and
+whether it is writable; check it before concluding that nothing was traced,
+since the append is best-effort and will never fail a real edit to report a
+logging problem.
+
+Recorded per step: tool, action, `duration_ms`, status, semantic deltas and
+verification. **Not** recorded: parameters, file paths, clip or project names.
+The only free text is the `request` string passed to `begin_execution`.
+
+The file rotates at 8 MB, keeping one previous generation as
+`execution-traces.jsonl.1`. Both are gitignored along with the rest of `logs/`.
+Audit reports are separate point-in-time exports; `RESOLVE_MCP_TRACE_REPORT_DIR`
+moves their default directory without moving the append-only trace log.
+
+`path` is honoured as given — the report can be written anywhere, and the
+directories are created to reach it. That is deliberate (a conform's paperwork
+belongs beside the conform, not in `logs/`), so treat it the way you would any
+other export destination and do not invent a path near source media. The
+`execution_id` route cannot escape the report directory: it is sanitised to a
+filename.
+
+A report whose run recorded no verification checks renders **"not established
+— no checks recorded"** in the Passed row, never "yes" — the same rule as
+`verification.status: "unverified"` in the envelope. Do not report such a run
+to the user as verified.
+
+---
+
 ## 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.205.2"
+VERSION = "2.207.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.205.2",
+  "version": "2.207.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.205.2"
+VERSION = "2.207.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.205.2"
+VERSION = "2.207.0"
 
 import base64
 import os
@@ -66,6 +66,16 @@ from src.utils.operation_result import (
     get_envelope_mode as _get_envelope_mode,
     set_envelope_mode as _set_envelope_mode,
 )
+from src.utils import execution_trace as _execution_trace
+from src.utils.execution_trace import (
+    get_execution_trace,
+    get_execution,
+    list_recent_executions,
+    begin_execution,
+    end_execution,
+    clear_executions,
+    export_execution_report,
+)
 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,
@@ -1487,6 +1497,51 @@ def _guarded_params(args, kwargs) -> Optional[Dict[str, Any]]:
     return None
 
 
+_TRACE_OBSERVER_ACTIONS = {
+    "get_execution_trace", "get_execution", "list_recent_executions",
+    "clear_executions", "begin_execution", "end_execution",
+    "export_execution_report",
+}
+
+
+def _record_execution_step(
+    tool_name: str,
+    action: str,
+    params: Optional[Dict[str, Any]],
+    raw_result: Any,
+    enveloped: Any,
+    duration_ms: int,
+) -> None:
+    if tool_name == "resolve_control" and action in _TRACE_OBSERVER_ACTIONS:
+        return
+    try:
+        env = None
+        if isinstance(enveloped, dict):
+            env = enveloped.get(_operation_result.ENVELOPE_KEY)
+            if not env and "execution_id" in enveloped:
+                env = enveloped
+        exec_id = env.get("execution_id") if isinstance(env, dict) else None
+        status = env.get("status") if isinstance(env, dict) else None
+        verification = env.get("verification") if isinstance(env, dict) else None
+        changes = env.get("changes") if isinstance(env, dict) else None
+        warnings = env.get("warnings") if isinstance(env, dict) else None
+
+        _execution_trace.record_step(
+            tool=tool_name,
+            action=action,
+            params=params if isinstance(params, dict) else None,
+            raw_result=raw_result,
+            duration_ms=duration_ms,
+            execution_id=exec_id,
+            status=status,
+            verification=verification,
+            changes=changes,
+            warnings=warnings,
+        )
+    except Exception as exc:  # pragma: no cover
+        logger.debug("Failed to record execution step: %s", exc)
+
+
 def _guard_missing_params(fn):
     """Tool decorator: report a missing parameter instead of leaking a KeyError.
 
@@ -1517,22 +1572,32 @@ def _guard_missing_params(fn):
         @functools.wraps(fn)
         async def wrapper(*args, **kwargs):
             action = _guarded_action_name(args, kwargs)
+            params = _guarded_params(args, kwargs)
+            t0 = time.perf_counter()
             try:
                 result = await fn(*args, **kwargs)
             except _MissingParam as exc:
                 result = _missing_param_error(exc, action)
-            return _build_operation_envelope(
-                tool_name, action, _guarded_params(args, kwargs), result)
+            duration_ms = max(0, int((time.perf_counter() - t0) * 1000))
+            enveloped = _build_operation_envelope(
+                tool_name, action, params, result, duration_ms=duration_ms)
+            _record_execution_step(tool_name, action, params, result, enveloped, duration_ms)
+            return enveloped
     else:
         @functools.wraps(fn)
         def wrapper(*args, **kwargs):
             action = _guarded_action_name(args, kwargs)
+            params = _guarded_params(args, kwargs)
+            t0 = time.perf_counter()
             try:
                 result = fn(*args, **kwargs)
             except _MissingParam as exc:
                 result = _missing_param_error(exc, action)
-            return _build_operation_envelope(
-                tool_name, action, _guarded_params(args, kwargs), result)
+            duration_ms = max(0, int((time.perf_counter() - t0) * 1000))
+            enveloped = _build_operation_envelope(
+                tool_name, action, params, result, duration_ms=duration_ms)
+            _record_execution_step(tool_name, action, params, result, enveloped, duration_ms)
+            return enveloped
 
     wrapper.__wrapped_by_missing_param_guard__ = True
     return wrapper
@@ -16047,6 +16112,20 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         — Captures the current Resolve UI state so it can be restored after a preview.
       restore_state(state_token) -> {success, restored: {...}}
         — Returns Resolve to a previously-saved state.
+      get_execution_trace(execution_id?) -> {success, trace}
+        — Correlated agent execution trace by execution_id, or most recent if omitted (no connection needed).
+      get_execution(execution_id) -> {success, trace}
+        — Alias for get_execution_trace.
+      list_recent_executions(limit?) -> {success, executions, count}
+        — List recent execution traces with aggregated tool calls, durations, and verifications (no connection needed).
+      begin_execution(request?, execution_id?, initiator?) -> {success, execution_id, started_at, request}
+        — Open a multi-step execution trace so subsequent tool calls thread under this execution ID.
+      end_execution(execution_id?, verification?, status?, notes?) -> {success, trace}
+        — Conclude an execution trace and compute final rollups.
+      export_execution_report(execution_id?, format?, path?, overwrite?, include_steps?) -> {success, path, bytes}
+        — Write a Markdown or JSON audit report for an execution trace (no connection needed).
+      clear_executions(dry_run?) -> {success, cleared}
+        — Clear the in-memory execution trace buffer.
     """
     p = _params(params)
 
@@ -16134,6 +16213,80 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     if action == "list_jobs":
         return {"jobs": background_jobs.list_jobs()}
 
+    if action in {"get_execution_trace", "get_execution"}:
+        exec_id = p.get("execution_id") or p.get("id")
+        trace = _execution_trace.get_execution_trace(exec_id)
+        if not trace:
+            return _err(f"No execution trace found for id: {exec_id or 'latest'}", code="NOT_FOUND", category="state")
+        return {"success": True, "trace": trace}
+    if action == "list_recent_executions":
+        limit = _safe_int(p.get("limit"), 20, minimum=1, maximum=100)
+        executions = _execution_trace.list_recent_executions(limit=limit)
+        # Say where the on-disk log is and whether it is actually writable.
+        # The traces themselves live in a 100-entry in-memory ring, so "the
+        # list is short" and "the log is not being written" are different
+        # facts, and a caller should not have to guess which one they have.
+        return {
+            "success": True,
+            "executions": executions,
+            "count": len(executions),
+            "buffer_capacity": _execution_trace.MAX_RECENT_EXECUTIONS,
+            "persistence": _execution_trace.persistence_status(),
+        }
+    if action == "begin_execution":
+        req = p.get("request") or p.get("prompt") or p.get("reason")
+        exec_id = p.get("execution_id") or p.get("id")
+        res = _execution_trace.begin_execution(
+            request=req,
+            execution_id=exec_id,
+            initiator=p.get("initiator") or "agent",
+        )
+        return res
+    if action == "end_execution":
+        exec_id = p.get("execution_id") or p.get("id")
+        trace = _execution_trace.end_execution(
+            execution_id=exec_id,
+            verification=p.get("verification"),
+            status=p.get("status"),
+            notes=p.get("notes"),
+        )
+        if not trace:
+            return _err("No active or matching execution to end", code="NOT_FOUND", category="state")
+        return {"success": True, "trace": trace}
+    if action == "export_execution_report":
+        exec_id = p.get("execution_id") or p.get("id")
+        report_format = p.get("format") or p.get("report_format") or "markdown"
+        include_steps = _setup_bool(p.get("include_steps", p.get("includeSteps")), True)
+        overwrite = _setup_bool(p.get("overwrite"), False)
+        try:
+            res = _execution_trace.export_execution_report(
+                execution_id=exec_id,
+                report_format=report_format,
+                output_path=p.get("path") or p.get("output_path") or p.get("outputPath"),
+                overwrite=overwrite,
+                include_steps=include_steps,
+            )
+        except FileExistsError as exc:
+            return _err(str(exc), code="REPORT_EXISTS", category="invalid_input")
+        except ValueError as exc:
+            return _err(str(exc), code="INVALID_REPORT_FORMAT", category="invalid_input")
+        except OSError as exc:
+            return _err(
+                "Could not write execution report",
+                code="REPORT_WRITE_FAILED",
+                category="io",
+                reason=str(exc),
+            )
+        if not res:
+            return _err(f"No execution trace found for id: {exec_id or 'latest'}", code="NOT_FOUND", category="state")
+        return res
+    if action == "clear_executions":
+        dry_run = _setup_bool(p.get("dry_run", p.get("dryRun")), False)
+        if dry_run:
+            return {"success": True, "dry_run": True, "count": len(_execution_trace.list_recent_executions(100))}
+        res = _execution_trace.clear_executions()
+        return res
+
     # Control-panel actions don't require Resolve to be running.
     if action == "open_control_panel":
         return _open_control_panel(p)
@@ -16348,7 +16501,7 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         if err:
             return _err(err)
         return {"success": bool(r.ExportUserPreferencesPreset(clean["name"], clean["path"]))}
-    return _unknown(action, ["launch","runtime_mode","get_version","api_truth","check_version_support","verification_stats","job_status","list_jobs","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","list_user_preferences_presets","save_user_preferences_preset","load_user_preferences_preset","delete_user_preferences_preset","import_user_preferences_preset","export_user_preferences_preset","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
+    return _unknown(action, ["launch","runtime_mode","get_version","api_truth","check_version_support","verification_stats","job_status","list_jobs","get_execution_trace","get_execution","list_recent_executions","begin_execution","end_execution","export_execution_report","clear_executions","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","list_user_preferences_presets","save_user_preferences_preset","load_user_preferences_preset","delete_user_preferences_preset","import_user_preferences_preset","export_user_preferences_preset","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
 
 
 # ─── V2 C4: Per-field corrections with provenance + changelog ────────────────