davinci-resolve-mcp 2.59.0 → 2.61.0

package/CHANGELOG.md

@@ -2,6 +2,140 @@
 
 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.61.0
+
+Perception strata — a timecoded track model over every analyzed clip, plus the
+query layer that turns it into editorial answers. Ten new `media_analysis`
+actions, all local compute (ffmpeg + numpy; the face tier detects opencv +
+mediapipe and degrades honestly when absent). Everything measures, compares,
+flags, or aims — nothing decides; the cut is the editor's.
+
+### Added
+
+- **Schema v13: perception strata** — two generic track shapes instead of a
+  table per sensor: `events` (point/span occurrences: pause, breath,
+  hesitation, blink, beat, downbeat, …) and `curves` (float32 time series:
+  pitch, vocal_energy, speech_rate, motion_energy, face curves), plus two
+  promotions out of the report blob: `transcript_words` (per-word timestamps
+  as queryable rows) and `story_beats` (units of meaning over the transcript).
+  Machine re-runs replace their own rows; `source='human'` rows are append-only
+  and always win.
+- **Local analyzers (`strata_run`)** — prosody (pitch/energy/speech-rate curves
+  + pause/breath/hesitation events), beat grid (beat/downbeat + tempo), motion
+  energy (per-frame luma difference), and face strata (blink/gaze/expression
+  via opencv + mediapipe when installed). `strata_status` reports the per-clip
+  track inventory and what this machine can run; `backfill_words` promotes
+  word timestamps already sitting in stored report blobs — no re-analysis.
+- **`take_diff(clip_a, clip_b, text?)`** — align two deliveries of the same
+  line on transcript words and diff pace, pauses, pitch, and energy. Deltas
+  only; it never picks a winner.
+- **`cut_candidates(clip_id, time_seconds)`** — the joint solver: scores every
+  frame around an intended cut on the cut-point grammar (cut on the blink,
+  don't cut mid-word, don't bisect a breath, pauses are doors, land on the
+  beat, cut inside movement) with human-readable reasons per candidate and
+  honest reporting of missing tracks.
+- **`strata_query`** — the strata as one queryable surface: windowed
+  cross-track bundles per clip, or project-wide word find with a joined
+  ±context bundle per hit. **`timeline_strata`** projects clip strata through
+  a versioned timeline's recorded placements.
+- **Story beats (host-LLM pass)** — `plan_story_beats` assembles a timecoded
+  digest + JSON schema (the server never calls an LLM), the host chat produces
+  the beats, `commit_story_beats` validates and persists them append-only;
+  `list_story_beats` reads them back.
+- **Schema v14: timeline timebase snapshot** — `timeline_versions` now records
+  the timeline's fps and start frame at archive time, so `timeline_strata`
+  returns timeline-relative frames/seconds instead of assuming 24fps against
+  absolute (start-timecode-inclusive) snapshot frames.
+
+### Fixed
+
+Pre-release review (multi-agent, 8 finder angles + adversarial verification)
+caught and fixed before anything shipped:
+
+- **Re-ingest cascade wipe** — the ingest `INSERT OR REPLACE` on the clips row
+  cascade-deleted every clip-child table under `PRAGMA foreign_keys=ON`. The
+  legacy children are rebuilt during ingest, so this was invisible until the
+  strata tables (which ingest does NOT rebuild — human annotations included)
+  landed on the same cascade. The clips row is now a true upsert and is never
+  deleted.
+- **Words-less re-analysis wiped word rows** — `ingest_transcript_words`
+  deleted before validating; a re-analysis without transcription (or a mixed
+  report whose words lived only at the top level) silently destroyed
+  previously backfilled rows. Now parses first, preserves existing rows when
+  the incoming report has no words, and falls back per-segment to the
+  top-level words list.
+- **Machine story-beat commits could replace human rows** — the content-hash
+  `beat_uuid` let `INSERT OR REPLACE` overwrite a human beat sharing the same
+  span+label and erased supersede history on identical recommits. Beat rows
+  now get random UUIDs and plain INSERTs; duplicate spans within one commit
+  are skipped and reported.
+- **Dispatch hardening** — stringified numbers from LLM clients no longer
+  crash `strata_query` (TypeError in curve slicing) or silently redirect
+  `timeline_strata` to the latest version; `cut_candidates` rejects
+  non-positive fps instead of ZeroDivisionError; word matches escape SQL LIKE
+  metacharacters; clip bundles fetch every recorded track (gesture_boundary,
+  loudness, custom human tracks) instead of a hardcoded subset; analyzer
+  ffmpeg calls go through the stdio-safe `proc.safe_run`; a broken
+  mediapipe/protobuf install degrades to "face unavailable" instead of
+  crashing `strata_status`.
+
+### Validation
+
+- Full offline suite: 1,418 tests green (17 new regression tests covering the
+  fixes above). Static checks, drift guards, npm pack, and API-parity audit
+  all pass. No live Resolve behavior changed beyond two defensive getter reads
+  (`GetSetting("timelineFrameRate")`, `GetStartFrame()`) at archive time, both
+  try/except-guarded and unit-tested against mock timelines.
+
+## What's New in v2.60.0
+
+A community bug-fix bundle — three external contributions plus the three issues
+they filed, integrated with the contributors credited as co-authors.
+
+### Fixed
+
+- **Frame accuracy (`edit_engine`)** — `MediaPool.AppendToTimeline` clipInfo
+  `endFrame` is an *exclusive* bound (duration = `endFrame - startFrame`), but
+  three plan builders wrote an inclusive end (`round(t*fps) - 1`) and
+  `execute_selects` advanced its record cursor by `end - start + 1`. Result:
+  `plan_tighten` kept ranges were one frame short per segment (~4.3s across 130
+  segments), `plan_selects`/`plan_swap` source ranges were one frame short, and
+  `execute_selects` left a 1-frame gap between selects. Now half-open everywhere.
+  (#82, thanks @chenyuxiaojin)
+- **Timeline rename no longer archives (`destructive_hook`)** — `timeline.set_name`
+  was version-on-mutate, so renames spawned redundant `_archived` timelines
+  (and renaming an archive archived the archive). A rename is content-preserving,
+  so it's out of the destructive registry. (#83, thanks @chenyuxiaojin)
+- **Windows startup (`server`)** — initialize the Resolve scripting env
+  (PYTHONHOME, PATH, `os.add_dll_directory`) before importing the fusionscript
+  bridge, avoiding a native access violation that crashed network transports
+  before bind. No-op off Windows. (#78, thanks @POLEPALLIANVESH)
+- Fixed a stale offline test that patched a refactored-away seam
+  (`project_manager` delete routing), restoring a fully green baseline.
+
+### Added
+
+- **`execute_tighten(..., include_details?)`** — the readback `structural_diff`
+  is compact by default (counts + a small head/tail sample) instead of embedding
+  every before/after item id (226 KB for a 130-segment tighten). The full
+  per-item diff is persisted in the plan record (`get_plan` →
+  `execution_summary.structural_diff`) and returned inline with
+  `include_details=true`. (#84, thanks @chenyuxiaojin)
+- **`plan_tighten` skip dedup** — identical `(item, reason)` skip rows collapse
+  into one entry with a `count` (an unanalyzed layer no longer repeats the same
+  row once per segment). (#81, thanks @chenyuxiaojin)
+
+### Documentation
+
+- Recorded the `AppendToTimeline` `endFrame` exclusive-bound semantics in the
+  `api_truth` ledger (internal quirk entry). (#80, thanks @chenyuxiaojin)
+
+### Validation
+
+- Full offline suite green (1343 tests). Static/drift guards pass.
+- Live Resolve validation of the #82 frame-accuracy fix (selects butt-join +
+  tighten frame-exact keep ranges) on a disposable project.
+
 ## What's New in v2.59.0
 
 First-class conform ingest for **AAF** and **DRP**, an offline **Premiere `.prproj`** reader with

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.59.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.61.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-34%20(341%20full)-blue.svg)](#server-modes)
@@ -12,7 +12,7 @@
 
 A Model Context Protocol (MCP) server that lets AI assistants control DaVinci Resolve Studio through the official Scripting API. It provides full API coverage plus guarded workflow helpers for editing, media pool organization, render setup, review markers, grading, Fusion, Fairlight, project lifecycle tasks, extension authoring, and source-safe media analysis.
 
-[![Local control panel](docs/images/control-panel/01-overview.png)](docs/guides/control-panel.md)
+[![Local control panel](https://raw.githubusercontent.com/samuelgursky/davinci-resolve-mcp/main/docs/images/control-panel/01-overview.png)](docs/guides/control-panel.md)
 
 A local browser control panel ships with the server for inspecting Resolve state, running source-safe analysis, drilling into analyzed clips and shots, and editing analysis output inline. See the [Control Panel Guide](docs/guides/control-panel.md) for the full tour.
 

package/docs/SKILL.md

@@ -551,8 +551,10 @@ Key actions: `capabilities`, `install_guidance`, `resolve_output_root`, `plan`,
 `list_corrections`, `deepen`, `commit_shot_vision`, `vision_pending_sweep`,
 `build_embeddings`, `find_similar`, `detect_entities`, `commit_entities`,
 `list_entities`, `prepare_bin_briefing`, `commit_bin_summary`,
-`detect_shot_relationships`, `commit_shot_relationships`, and
-`list_shot_relationships`.
+`detect_shot_relationships`, `commit_shot_relationships`,
+`list_shot_relationships`, `strata_status`, `backfill_words`, `strata_run`,
+`take_diff`, `cut_candidates`, `strata_query`, `timeline_strata`,
+`plan_story_beats`, `commit_story_beats`, and `list_story_beats`.
 
 **Cross-clip entities + bin briefing v2 (v2.44.0+).** Recurring
 people/places/props across a project's media, found cheaply and confirmed
@@ -596,6 +598,40 @@ no editorial suggestions): `same_setup_as` / `alt_take_of` (symmetric) and
   confirmed `alt_take_of` alternates over raw cosine (the rationale states
   which basis ranked each alternate).
 
+**Perception strata (v2.61.0+, schema v13/v14).** A timecoded track model over
+each analyzed clip — events (pause/breath/hesitation/blink/beat/downbeat/…),
+sampled curves (pitch/vocal_energy/speech_rate/motion_energy/face curves),
+per-word transcript rows, and story beats. Local compute only (ffmpeg + numpy;
+face tier needs opencv + mediapipe); machine re-runs replace their own rows,
+human rows are append-only and always win. These measure and rank — they never
+decide; the editor picks.
+- `strata_status(clip_id?)` — project or per-clip track inventory plus what
+  this machine can run (`analyzer_capabilities`).
+- `strata_run(clip_id, analyzers?)` — run prosody / beat_grid / motion_energy
+  / face on one clip (default: whatever is available locally).
+- `backfill_words()` — promote word timestamps already inside stored report
+  blobs into queryable `transcript_words` rows; idempotent, no re-analysis.
+- `take_diff(clip_a, clip_b, text?)` — align two takes on transcript words
+  and diff their delivery (pace, pauses, pitch, energy). Deltas only, no
+  winner.
+- `cut_candidates(clip_id, time_seconds, window_seconds?, fps?, limit?)` —
+  rank cut frames around an intended joint with human-readable reasons
+  (blink / word-gap / pause / breath / beat / motion); missing tracks are
+  reported, never treated as "no signal".
+- `strata_query(clip_id?, start_seconds?, end_seconds?, match_word?, …)` —
+  one queryable surface: a windowed cross-track bundle for a clip, or a
+  project-wide word find with a joined ±context bundle per hit.
+- `timeline_strata(timeline_name, timeline_version?, …)` — project clip
+  strata through a versioned timeline's recorded placements. Snapshot frames
+  are absolute record frames (start-timecode-inclusive); snapshots from
+  schema v14+ carry the timeline's fps/start frame so placements also get
+  timeline-relative frames and seconds.
+- `plan_story_beats(clip_id)` / `commit_story_beats(clip_id, beats)` /
+  `list_story_beats(clip_id)` — host-LLM pass over the transcript digest
+  (the server never calls an LLM): beats are units of meaning with types
+  (topic/claim/revelation/emotional/anecdote/question/callback), links, and
+  supersede semantics.
+
 **Embeddings + similarity (v2.43.0+).** Local-compute semantic search; no
 vendor tokens, so nothing here touches the caps ledger. Backends are
 detected, never installed (capabilities lists them with install guidance):
@@ -794,8 +830,10 @@ clip-count readback plus `brain_edits` rationale rows.
   media-id fallback), and `readback` carries per-track-type
   `track_counts` plus an `audio_accounting` block so swap symmetry is
   verifiable. `execute_tighten` readback gains `structural_diff` (source
-  vs variant, via the same engine as `diff_timelines`); `execute_selects`
-  readback gains a `usage_summary`.
+  vs variant, via the same engine as `diff_timelines`) — compact by
+  default (counts + a small sample; full per-item diff persisted in the
+  plan record via `get_plan`, or inline with `include_details=true`);
+  `execute_selects` readback gains a `usage_summary`.
 - `list_plans(limit?)` / `get_plan(plan_id)`.
 
 The engine needs the analysis substrate: analyzed clips in the DB (run

package/docs/install.md

@@ -64,6 +64,14 @@ The installer can automatically configure any of these clients:
 
 You can configure multiple clients at once, or use `--clients manual` to get copy-paste config snippets.
 
+For [Autohand Code](https://github.com/autohandai/code-cli/), register the managed launcher after setup:
+
+```bash
+autohand mcp add davinci-resolve npx davinci-resolve-mcp server
+```
+
+Autohand adds npx's `-y` flag automatically. Add `--scope project` after `mcp add` to keep the registration in the current workspace.
+
 ### Installer Options
 
 ```bash

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.0
 
-**Totals:** 18 missing capabilities, 11 bugs / unreliable behaviors.
+**Totals:** 19 missing capabilities, 11 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -134,6 +134,14 @@ equivalent, blocking full automation.
 - **Workaround / current handling:** Position clips with AppendToTimeline clipInfo recordFrame, or perform insert/overwrite/replace edits in the Resolve UI.
 - **Tags:** missing-method, timeline, edit
 
+### Render in Place / bake a timeline clip to new media
+
+- **Object:** `Timeline / TimelineItem / MediaPool`
+- **Behavior:** There is no scripting method for the Edit-page clip context-menu action 'Render in Place', which bakes a clip (including its Fusion composition and effects) into a NEW rendered media file and drops that file back on the timeline at the same position, replacing the source clip. No Render*/Bake*/Freeze* method exists on Timeline, TimelineItem or MediaPool in the Resolve scripting API reference (BMD docs) or a dir() audit. NOTE the frequently-confused-but-distinct sibling: the render *cache* (a temporary, non-destructive cache of a clip's Color/Fusion output that reduces playback load WITHOUT creating a new media file) IS scriptable — TimelineItem.SetColorOutputCache / SetFusionOutputCache ('Render Cache Color/Fusion Output' menu actions) and Graph.SetNodeCacheMode. Render in Place is the permanent, media-producing bake; the render cache is the transient one.
+- **Workaround / current handling:** If the goal is only to reduce playback/render load, use the render cache — exposed as timeline_item get_color_cache/set_color_cache/get_fusion_cache/set_fusion_cache and the Color-page graph node cache_mode (no new media, fully reversible). If you genuinely need a baked media file, render the clip's in/out range from the Deliver page (proj.AddRenderJob with MarkIn/MarkOut) and relink/append the result yourself, or run Render in Place from the Resolve UI. There is no one-call API equivalent. See issue #86.
+- **Reference:** [issue #86](https://github.com/samuelgursky/davinci-resolve-mcp/issues/86)
+- **Tags:** missing-method, timeline, render, cache, render-in-place, bake
+
 ### Smart Bins / Power Bins creation
 
 - **Object:** `MediaPool`

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.59.0"
+VERSION = "2.61.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.59.0",
+  "version": "2.61.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.59.0"
+VERSION = "2.61.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 341-tool granular server instead
 """
 
-VERSION = "2.59.0"
+VERSION = "2.61.0"
 
 import base64
 import os
@@ -745,6 +745,32 @@ resolve = None
 dvr_script = None
 _resolve_lock = threading.RLock()
 
+# On Windows the fusionscript native bridge DLL must be locatable before the
+# Python import machinery attempts to load it.  Setting PYTHONHOME, prepending
+# the Resolve install directory to PATH, and registering it with
+# os.add_dll_directory() ensures the dynamic loader can find fusionscript.dll
+# and its dependencies even when the server is launched from a virtual-env or
+# a working directory that is not the Resolve install directory.  These steps
+# MUST happen before `import DaVinciResolveScript` or the import triggers a
+# native access-violation on Windows (crash before port bind in network mode).
+if sys.platform.startswith("win") and RESOLVE_LIB_PATH:
+    _resolve_install_dir = os.path.dirname(RESOLVE_LIB_PATH)
+    if os.path.isdir(_resolve_install_dir):
+        # Ensure Python's own runtime DLLs are discoverable by the bridge.
+        if not os.environ.get("PYTHONHOME"):
+            os.environ["PYTHONHOME"] = sys.base_prefix
+        # Prepend Resolve's install dir to PATH so the loader finds
+        # fusionscript.dll and sibling DLLs even without a system-wide install.
+        _cur_path = os.environ.get("PATH", "")
+        if _resolve_install_dir.lower() not in _cur_path.lower():
+            os.environ["PATH"] = _resolve_install_dir + os.pathsep + _cur_path
+        # os.add_dll_directory is available on Python 3.8+ (Windows only).
+        if hasattr(os, "add_dll_directory"):
+            try:
+                os.add_dll_directory(_resolve_install_dir)
+            except OSError:
+                pass
+
 try:
     import DaVinciResolveScript as dvr_script
     logger.info("DaVinciResolveScript module loaded")
@@ -16654,6 +16680,40 @@ def media_pool_item_markers(action: str, params: Optional[Dict[str, Any]] = None
 # TOOL 15: media_analysis
 # ═══════════════════════════════════════════════════════════════════════════════
 
+_STRATA_CLIP_REF_KEYS = (
+    "clip_id", "clipId", "clip_uuid", "clipUuid",
+    "clip_dir", "clipDir", "file_path", "filePath",
+)
+
+
+def _strata_clip_ref(p: Dict[str, Any]) -> Any:
+    """The clip ref from any accepted alias — one place, so aliases can't drift
+    between action handlers."""
+    for key in _STRATA_CLIP_REF_KEYS:
+        value = p.get(key)
+        if value:
+            return value
+    return None
+
+
+def _opt_number(value: Any) -> Optional[float]:
+    """Coerce int/float/numeric-string to float; anything else → None.
+
+    LLM clients routinely stringify numbers; params must not crash (or be
+    silently dropped) because "12.5" arrived instead of 12.5.
+    """
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, str):
+        try:
+            return float(value.strip())
+        except ValueError:
+            return None
+    return None
+
+
 @mcp.tool()
 async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, ctx: Optional[Context] = None) -> Dict[str, Any]:
     """Project-scoped media analysis and guarded metadata publishing.
@@ -16719,6 +16779,16 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
       cancel_batch_job(job_id) -> stop future slices
       resume_batch_job(job_id) -> requeue a canceled or interrupted job
       cleanup_artifacts(frames_only=true) -> remove generated frame artifacts only
+      strata_status(clip_id?) -> perception-strata inventory (events/curves/words/story beats) for the project or one clip
+      backfill_words(analysis_root?) -> promote word timestamps from stored report blobs into transcript_words rows
+      strata_run(clip_id, analyzers?) -> run local strata analyzers (prosody | beat_grid | motion_energy | face) on one clip; default = whatever this machine can run
+      take_diff(clip_a, clip_b, text?) -> align two takes on transcript words and diff their delivery (pace, pauses, pitch, energy) — measures only, never picks
+      cut_candidates(clip_id, time_seconds, window_seconds?, fps?, limit?) -> rank cut frames around an intended joint with reasons (blink/pause/word-gap/breath/beat/motion) — aims, never decides
+      strata_query(clip_id?, start_seconds?, end_seconds?, match_word?, context_seconds?, include_curve_values?, limit?) -> cross-track window bundle for a clip, or project-wide word find with joined context per hit
+      timeline_strata(timeline_name, timeline_version?, record_start_frame?, record_end_frame?, fps?) -> project clip strata through a timeline's recorded placements (whole-clip bundles; frames are absolute record frames incl. start-timecode offset; fps defaults to the snapshot's stored value; source-offset mapping needs the live item)
+      plan_story_beats(clip_id) -> timecoded transcript digest + prosody evidence + JSON schema for the host model to segment into story beats (no LLM call server-side)
+      commit_story_beats(clip_id, beats, source_model?) -> validate + persist host-produced story beats; machine commits supersede machine rows only, human rows always win
+      list_story_beats(clip_id) -> current (non-superseded) story beats for a clip
 
     Analysis outputs stay under a davinci-resolve-mcp-analysis project root
     and are validated so they are never written beside source media. Executed
@@ -17017,6 +17087,17 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         "detect_shot_relationships",
         "commit_shot_relationships",
         "list_shot_relationships",
+        # Perception strata (schema v13) — timecoded track model.
+        "strata_status",
+        "backfill_words",
+        "strata_run",
+        "take_diff",
+        "cut_candidates",
+        "strata_query",
+        "timeline_strata",
+        "plan_story_beats",
+        "commit_story_beats",
+        "list_story_beats",
     }:
         root = resolve_media_analysis_output_root(
             project_name=project_name,
@@ -17076,6 +17157,119 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         if action == "db_ingest":
             from src.utils import analysis_store
             return analysis_store.ingest_project(project_root)
+        # Perception strata (schema v13).
+        if action == "strata_status":
+            from src.utils import strata, strata_analyzers
+            clip_ref = _strata_clip_ref(p)
+            status = strata.strata_status(project_root, clip_ref)
+            if status.get("success") and clip_ref is None:
+                status["analyzer_capabilities"] = strata_analyzers.capabilities()
+            return status
+        if action == "backfill_words":
+            from src.utils import strata
+            return strata.backfill_transcript_words(project_root)
+        if action == "strata_run":
+            from src.utils import strata_analyzers
+            clip_ref = _strata_clip_ref(p)
+            if not clip_ref:
+                return _err("strata_run requires clip_id (or clip_uuid / clip_dir / file_path)")
+            analyzers = p.get("analyzers") or p.get("analyzer")
+            if isinstance(analyzers, str):
+                analyzers = [analyzers]
+            return strata_analyzers.run_analyzers(project_root, clip_ref, analyzers)
+        if action == "take_diff":
+            from src.utils import strata_queries
+            clip_a = p.get("clip_a") or p.get("clipA") or p.get("take_a") or p.get("takeA")
+            clip_b = p.get("clip_b") or p.get("clipB") or p.get("take_b") or p.get("takeB")
+            if not clip_a or not clip_b:
+                return _err("take_diff requires clip_a and clip_b")
+            return strata_queries.take_diff(project_root, clip_a, clip_b, text=p.get("text") or p.get("line"))
+        if action == "cut_candidates":
+            from src.utils import strata_queries
+            clip_ref = _strata_clip_ref(p)
+            t = _opt_number(p.get("time_seconds", p.get("timeSeconds")))
+            if not clip_ref or t is None:
+                return _err("cut_candidates requires clip_id and a numeric time_seconds")
+            fps_raw = p.get("fps")
+            fps = _opt_number(fps_raw)
+            if fps_raw is not None and fps is None:
+                return _err(f"fps must be a number, got {fps_raw!r}")
+            return strata_queries.cut_candidates(
+                project_root,
+                clip_ref,
+                t,
+                window_seconds=_opt_number(p.get("window_seconds", p.get("windowSeconds"))) or 0.35,
+                fps=fps,
+                limit=int(_opt_number(p.get("limit")) or 7),
+            )
+        if action == "strata_query":
+            from src.utils import strata_queries
+            start_raw = p.get("start_seconds", p.get("startSeconds"))
+            end_raw = p.get("end_seconds", p.get("endSeconds"))
+            start = _opt_number(start_raw)
+            end = _opt_number(end_raw)
+            if (start_raw is not None and start is None) or (end_raw is not None and end is None):
+                return _err("start_seconds/end_seconds must be numbers")
+            return strata_queries.strata_query(
+                project_root,
+                clip_ref=_strata_clip_ref(p),
+                start_seconds=start,
+                end_seconds=end,
+                match_word=p.get("match_word") or p.get("matchWord") or p.get("word"),
+                context_seconds=_opt_number(p.get("context_seconds", p.get("contextSeconds"))) or 2.0,
+                include_curve_values=bool(p.get("include_curve_values", p.get("includeCurveValues", False))),
+                limit=int(_opt_number(p.get("limit")) or 20),
+            )
+        if action == "timeline_strata":
+            from src.utils import strata_queries
+            timeline_name = p.get("timeline_name") or p.get("timelineName") or p.get("timeline")
+            if not timeline_name:
+                return _err("timeline_strata requires timeline_name")
+            version_raw = p.get("timeline_version", p.get("timelineVersion"))
+            version = _opt_number(version_raw)
+            if version_raw is not None and version is None:
+                return _err(f"timeline_version must be an integer, got {version_raw!r}")
+            fps_raw = p.get("fps")
+            fps = _opt_number(fps_raw)
+            if fps_raw is not None and fps is None:
+                return _err(f"fps must be a number, got {fps_raw!r}")
+            start_frame = _opt_number(p.get("record_start_frame", p.get("recordStartFrame")))
+            end_frame = _opt_number(p.get("record_end_frame", p.get("recordEndFrame")))
+            return strata_queries.timeline_strata(
+                project_root,
+                str(timeline_name),
+                timeline_version=int(version) if version is not None else None,
+                record_start_frame=int(start_frame) if start_frame is not None else None,
+                record_end_frame=int(end_frame) if end_frame is not None else None,
+                fps=fps,
+                include_curve_values=bool(p.get("include_curve_values", p.get("includeCurveValues", False))),
+            )
+        if action == "plan_story_beats":
+            from src.utils import strata_story
+            clip_ref = _strata_clip_ref(p)
+            if not clip_ref:
+                return _err("plan_story_beats requires clip_id")
+            return strata_story.plan_story_beats(project_root, clip_ref)
+        if action == "commit_story_beats":
+            from src.utils import strata_story
+            clip_ref = _strata_clip_ref(p)
+            if not clip_ref:
+                return _err("commit_story_beats requires clip_id")
+            beats = p.get("beats")
+            if beats is None:
+                return _err("commit_story_beats requires beats")
+            return strata_story.commit_story_beats(
+                project_root,
+                clip_ref,
+                beats,
+                source_model=p.get("source_model") or p.get("sourceModel"),
+            )
+        if action == "list_story_beats":
+            from src.utils import strata_story
+            clip_ref = _strata_clip_ref(p)
+            if not clip_ref:
+                return _err("list_story_beats requires clip_id")
+            return strata_story.list_story_beats(project_root, clip_ref)
         # Phase B — deep shot-level vision tier.
         if action == "deepen":
             from src.utils import deep_vision
@@ -17634,6 +17828,16 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         "detect_shot_relationships",
         "commit_shot_relationships",
         "list_shot_relationships",
+        "strata_status",
+        "backfill_words",
+        "strata_run",
+        "take_diff",
+        "cut_candidates",
+        "strata_query",
+        "timeline_strata",
+        "plan_story_beats",
+        "commit_story_beats",
+        "list_story_beats",
         "get_caps",
         "set_caps_preset",
         "get_usage",
@@ -17880,6 +18084,47 @@ def _edit_engine_capture(tl) -> Dict[str, Any]:
     return out
 
 
+def _compact_structural_diff(diff: Any, *, sample_n: int = 3) -> Any:
+    """Trim a compare_usage_snapshots result for the default execute response.
+
+    The full added/removed/moved/trimmed rows (one per timeline item, each with
+    media_pool_item_id + track + in/out frames) dominate large tighten
+    responses — 226 KB for a 130-segment tighten (issue #84). The counts already
+    live in `summary`; keep those plus a small head/tail sample per change kind.
+    The full diff is persisted in the executed plan record (edit_engine
+    get_plan(plan_id) → plan.execution_summary.structural_diff) and returned
+    inline when the caller passes include_details=true.
+    """
+    if not isinstance(diff, dict):
+        return diff
+    # An error stand-in (diff failed) or an already-compact payload: pass through.
+    if "summary" not in diff:
+        return diff
+    sample: Dict[str, Any] = {}
+    omitted = 0
+    for kind in ("added", "removed", "moved", "trimmed"):
+        rows = diff.get(kind)
+        if not isinstance(rows, list) or not rows:
+            continue
+        if len(rows) <= sample_n:
+            sample[kind] = list(rows)
+            continue
+        # Head sample + final row so the caller sees both ends of the change set.
+        sample[kind] = list(rows[: sample_n - 1]) + [rows[-1]]
+        omitted += len(rows) - sample_n
+    return {
+        "summary": diff.get("summary"),
+        "sample": sample,
+        "truncated": True,
+        "omitted_rows": omitted,
+        "detail_hint": (
+            "Full per-item diff persisted in the plan record — retrieve via "
+            "edit_engine get_plan(plan_id) → plan.execution_summary.structural_diff, "
+            "or re-run with include_details=true to inline it."
+        ),
+    }
+
+
 def _edit_engine_track_counts(tl) -> Dict[str, int]:
     """Per-track-type item counts — the swap symmetry signal in readback."""
     counts: Dict[str, int] = {}
@@ -18001,9 +18246,12 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
       evidence for the current (or named) timeline. Kept ranges mirror onto the
       items' linked audio tracks by default so the variant is audible; pass
       include_audio=false for a video-only (silent) assembly.
-    - execute_tighten(plan_id, confirm_token?) — assembles a tightened VARIANT
-      timeline from the plan's keep ranges (video + mirrored audio), never
-      mutating the original. Readback includes an audio_accounting block.
+    - execute_tighten(plan_id, confirm_token?, include_details?) — assembles a
+      tightened VARIANT timeline from the plan's keep ranges (video + mirrored
+      audio), never mutating the original. Readback includes an audio_accounting
+      block and a compact structural_diff (counts + a small sample); the full
+      per-item diff is persisted in the plan record (get_plan → execution_summary)
+      and returned inline only when include_details=true.
     - plan_swap(track_index?, timeline_start_frame | item_name, kind?, limit?)
       — alternates for one timeline item via the similarity index.
     - execute_swap(plan_id, alternate_index, confirm_token?) — replaces the
@@ -18161,7 +18409,10 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                 build_errors.append({"index": i, "error": row_err.get("error")})
                 continue
             built.append(row)
-            record_cursor += int(append_ci.get("end_frame", 0)) - int(append_ci.get("start_frame", 0)) + 1
+            # AppendToTimeline endFrame is exclusive: the item occupies
+            # (end - start) frames. Advancing by +1 more leaves a 1-frame gap
+            # (black flash) between consecutive selects. See api_truth endFrame entry.
+            record_cursor += int(append_ci.get("end_frame", 0)) - int(append_ci.get("start_frame", 0))
         appended = mp.AppendToTimeline(built) if built else None
         readback = _edit_engine_capture(tl)
         # A diff against a source timeline is meaningless for a fresh assembly;
@@ -18291,12 +18542,20 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
             )
         except Exception:
             pass
+        # The full per-item structural diff is persisted in the plan record so it
+        # stays retrievable (edit_engine get_plan) without bloating every
+        # response — see issue #84. The MCP response carries a compact form by
+        # default and the full diff only when include_details=true.
+        include_details = _media_analysis_bool(
+            p.get("include_details", p.get("includeDetails")), False
+        )
         _edit_engine_mod.mark_plan_executed(project_root, plan["plan_id"], {
             "variant_timeline": variant.get("name") or variant_name,
             "keep_ranges": len(keep_ranges),
             "lifts": len(lifts),
             "before": before,
             "after": after,
+            "structural_diff": structural_diff,
         })
         return {
             "success": True,
@@ -18316,7 +18575,10 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                     if before.get("duration_seconds") is not None and after.get("duration_seconds") is not None
                     else None
                 ),
-                "structural_diff": structural_diff,
+                "structural_diff": (
+                    structural_diff if include_details
+                    else _compact_structural_diff(structural_diff)
+                ),
                 "audio_accounting": {
                     "planned_audio_ranges": audio_keep_ranges,
                     "planned_video_ranges": video_keep_ranges,