davinci-resolve-mcp 2.46.1 → 2.48.0

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 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.48.0
+
+Edit-engine hardening: trustworthy execute readback ahead of the first
+real-cut pilot. Live-validated end-to-end on a disposable synthetic-media
+project (24/24 checks).
+
+- **Added** `timeline_versioning(action="diff_timelines", params={from_timeline,
+  to_timeline})`: structural diff (added/removed/moved/trimmed + summary)
+  between two LIVE timelines by name — read-only, no archived snapshots
+  needed. Built for edit-engine variants, which are new-name timelines with
+  no shared version chain. The item walk and the snapshot comparison were
+  factored out of the version-snapshot path
+  (`capture_timeline_clip_usage` / `compare_usage_snapshots`) and reused.
+- **Fixed** `execute_swap` audio accounting: the lift was video-only while
+  the replacement appended linked video+audio, so item counts drifted on
+  every swap. The lift is now scoped to the target's video track plus its
+  linked audio tracks (`GetLinkedItems`, with a media-id track-scan fallback;
+  items with no linked audio and audio-only timelines are handled
+  gracefully), and readback reports per-track-type `track_counts`
+  before/after plus an `audio_accounting` block.
+- **Added** `execute_tighten` readback now includes `structural_diff`
+  (source vs variant); `execute_selects` readback includes a
+  `usage_summary` (per-track-type item counts — a diff against a source
+  timeline is meaningless for a fresh assembly).
+- **Changed** the live edit-engine validation harness asserts the tighten
+  structural diff, `diff_timelines` agreement, and swap track-count
+  symmetry (24 checks, up from 20).
+
+## What's New in v2.47.0
+
+Edit-engine plan browser in the control panel (Media → Edit Plans) — the
+panel UX pass for the v2.45.0 edit engine. Chat-first: the panel surfaces
+plans and evidence; execution stays in chat behind the confirm-token gate.
+
+- **Added** a plan browser at `#analysis/review/plans`: every saved
+  `edit_engine` plan with kind, summary, save time, and an `executed` chip;
+  fingerprint-corrupt plans surface as warning rows instead of being hidden.
+- **Added** plan detail views per kind: selects decisions render with shot
+  thumbnails, rank, duration, rationale, and a deep link to the shot page;
+  tighten plans list each dead-air lift with its transcript-gap evidence and
+  skipped items; swap plans show the current item plus numbered alternates
+  with similarity scores. Executed plans show their execution readback.
+- **Added** a copyable per-kind execute chat prompt on each plan (the panel
+  never executes; swaps include an `alternate_index` placeholder).
+- **Added** `/api/edit_plans` + `/api/edit_plans/<plan_id>` panel endpoints
+  (DB/file only — no Resolve round-trips; decisions are enriched server-side
+  with `resolve_clip_id` and a `thumb_frame_index` for the existing frames
+  route).
+- **Changed** `edit_engine.list_plans` gained `include_corrupt` (default off;
+  the MCP action shape is unchanged).
+
 ## What's New in v2.46.1
 
 Test and hygiene hardening; no public tool surface changes.

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.46.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.48.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)

package/docs/SKILL.md

@@ -699,13 +699,25 @@ clip-count readback plus `brain_edits` rationale rows.
   filtered to shots long enough to fill the slot exactly.
   `execute_swap(plan_id, alternate_index)` replaces the item in place
   (lift + positioned append at the same record frame) on the
-  version-archived timeline.
+  version-archived timeline. v2.48.0+: the lift is scoped to the target's
+  video track plus its linked audio tracks (GetLinkedItems with a
+  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`.
 - `list_plans(limit?)` / `get_plan(plan_id)`.
 
 The engine needs the analysis substrate: analyzed clips in the DB (run
 `db_ingest` on older roots), transcripts for tighten, and visual embeddings
 (`build_embeddings(kinds=['visual'])`) for swap.
 
+Plans are reviewable in the control panel (Media → Edit Plans, v2.47.0+):
+decisions/lifts/alternates with thumbnails and rationale, deep links to shot
+pages, and a copyable per-kind execute prompt. The panel never executes —
+when the user says they reviewed a plan there, execution still comes back
+through chat with the confirm-token gate.
+
 **`timeline_versioning`** — Version-on-mutate, archive, rollback, brain-edit history (C6).
 
 Every destructive timeline op (compound, captions, ripple delete, gap close,
@@ -734,6 +746,11 @@ Key actions:
   lists clips kept in place but re-trimmed (carries `out_frame_before`); `summary`
   has per-bucket counts plus `before_clip_count`/`after_clip_count`. Clips are
   keyed by media_pool_item_id and timeline position.
+- `diff_timelines(from_timeline, to_timeline)` (v2.48.0+) — the same
+  structural diff between two LIVE timelines by NAME, read-only, no archived
+  snapshots needed. Built for edit-engine variants (tighten/selects produce
+  new-name timelines with no shared version chain). For unrelated timelines
+  everything reports as added/removed.
 - `get_history(timeline_name?, analysis_run_id?, limit?)` — brain-edit rows
   with `edit_type`, `target_metric`, `before_value`, `after_value`, `delta`,
   `rationale`, and `initiator`. Filter by timeline or run; defaults to 50.

package/docs/guides/control-panel.md

@@ -26,10 +26,10 @@ pidfile and `resolve_control(action="close_control_panel")` stops it.
 
 ## Navigation and deep links
 
-Top-level sections: **Overview**, **Media** (Inventory / Review / History),
-**AI Console**, **Setup** (Resolve / MCP / Storage / Tools / Media Pool
-History), **Docs**, and **Preferences** (Analysis / Caps + Safety / Metadata
-and Markers / Paths and Workflow / MCP Updates). The project selector on the
+Top-level sections: **Overview**, **Media** (Inventory / Review / History /
+Edit Plans), **AI Console**, **Setup** (Resolve / MCP / Storage / Tools /
+Media Pool History), **Docs**, and **Preferences** (Analysis / Caps + Safety /
+Metadata and Markers / Paths and Workflow / MCP Updates). The project selector on the
 right scopes the panel to an analysis context; **View All Projects** opens a
 read-only browser over the Resolve project database with confirm-gated
 loading.
@@ -42,6 +42,7 @@ into chat:
 #analysis/media                            #analysis/review
 #analysis/review/history                   #analysis/review/clip/<clip_id>
 #analysis/review/clip/<clip_id>/shot/<n>   #analysis/review/clip/<clip_id>/transcript
+#analysis/review/plans                     #analysis/review/plans/<plan_id>
 #diagnostics/mcp                           #preferences/caps
 ```
 
@@ -131,6 +132,26 @@ timeline before risky work, and select any timeline to inspect its version
 chain and the edits between versions. Every destructive timeline edit made
 through the MCP archives a version here automatically.
 
+### Media → Edit Plans
+
+![Edit plan browser](../images/control-panel/11-edit-plans.png)
+
+Dry-run plans saved by the edit engine (`edit_engine` actions
+`plan_selects` / `plan_tighten` / `plan_swap`). The list shows each plan's
+kind, summary, save time, and an `executed` chip once it has run; plans that
+fail their fingerprint check appear as a warning row instead of being hidden.
+Opening a plan shows its full evidence: selects decisions render with shot
+thumbnails, rank, duration, and rationale (with a deep link to each shot
+page); tighten plans list every dead-air lift with its transcript-gap
+evidence; swap plans show the current item and each numbered alternate with
+its similarity score.
+
+The panel never executes a plan. Each detail view carries a copyable chat
+prompt (per kind, with the `alternate_index` placeholder for swaps) — paste
+it into your MCP chat session, which holds the confirm-token gate and the
+versioned execution path. Executed plans keep their execution readback
+inline.
+
 ### AI Console
 
 ![AI Console with governance](../images/control-panel/09-ai-console.png)

package/install.py

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

package/scripts/regen_panel_screenshots.py

@@ -57,6 +57,7 @@ def main() -> int:
         ("#preferences/analysis", "08-preferences-analysis.png", 3000),
         ("#aiconsole", "09-ai-console.png", 3000),
         ("#analysis/review/history", "10-history.png", 3500),
+        ("#analysis/review/plans", "11-edit-plans.png", 3500),
     ]
     with sync_playwright() as pw:
         browser = pw.chromium.launch()

package/src/analysis_dashboard.py

@@ -2379,6 +2379,84 @@ HTML = r"""<!doctype html>
     }
     .history-rollback-btn:hover { background: var(--accent-warning); color: var(--bg-base); }
 
+    /* ─── Edit-engine plan browser ──────────────────────────────────── */
+    .plans-toolbar {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: var(--space-3);
+      margin-bottom: var(--space-3);
+    }
+    .plans-toolbar .section-meta { margin-left: var(--space-2); }
+    .plans-list { display: grid; gap: var(--space-2); }
+    .plan-row {
+      display: flex;
+      align-items: center;
+      gap: var(--space-3);
+      padding: var(--space-2) var(--space-3);
+      border: 1px solid var(--border-default);
+      border-radius: var(--radius-md);
+      background: var(--lab-panel-elevated, var(--bg-base));
+      cursor: pointer;
+    }
+    .plan-row:hover { background: var(--bg-muted); }
+    .plan-row.is-corrupt {
+      cursor: default;
+      border-color: var(--accent-warning);
+      background: var(--accent-warning-muted);
+    }
+    .plan-row .summary { flex: 1; min-width: 0; }
+    .plan-row .saved-at { color: var(--text-muted); font-size: var(--text-xs); white-space: nowrap; }
+    .plan-chip {
+      display: inline-block;
+      padding: 1px var(--space-2);
+      border-radius: var(--radius-sm);
+      font-size: var(--text-xs);
+      font-weight: 600;
+      text-transform: uppercase;
+      letter-spacing: 0.04em;
+      border: 1px solid var(--border-default);
+      color: var(--text-secondary);
+      white-space: nowrap;
+    }
+    .plan-chip.kind-selects { color: var(--accent-success); border-color: var(--accent-success); }
+    .plan-chip.kind-tighten { color: var(--accent-warning); border-color: var(--accent-warning); }
+    .plan-chip.kind-swap { color: var(--accent-info, var(--text-secondary)); border-color: currentColor; }
+    .plan-chip.executed { color: var(--text-muted); text-transform: none; letter-spacing: 0; }
+    .plan-chip.corrupt { color: var(--accent-warning); border-color: var(--accent-warning); }
+    .plan-detail-header {
+      display: flex;
+      align-items: center;
+      flex-wrap: wrap;
+      gap: var(--space-2);
+      margin-bottom: var(--space-3);
+    }
+    .plan-detail-header .timeline-name { font-weight: 600; font-size: var(--text-md); }
+    .plan-detail-body { display: grid; gap: var(--space-3); }
+    .plan-section {
+      padding: var(--space-3);
+      border: 1px solid var(--border-default);
+      border-radius: var(--radius-md);
+      background: var(--lab-panel-elevated, var(--bg-base));
+    }
+    .plan-section > strong { display: block; margin-bottom: var(--space-2); }
+    .plan-decision-card {
+      display: flex;
+      gap: var(--space-3);
+      padding: var(--space-2) 0;
+      border-bottom: 1px solid var(--border-default);
+    }
+    .plan-decision-card:last-child { border-bottom: none; }
+    .plan-decision-card .review-thumb { width: 120px; height: 68px; object-fit: cover; border-radius: var(--radius-sm); flex: none; }
+    .plan-decision-card .review-thumb.placeholder {
+      display: flex; align-items: center; justify-content: center;
+      background: var(--bg-muted); color: var(--text-muted); font-size: var(--text-xs);
+    }
+    .plan-decision-card .body { flex: 1; min-width: 0; display: grid; gap: 2px; align-content: start; }
+    .plan-decision-card .title-row { display: flex; align-items: center; gap: var(--space-2); flex-wrap: wrap; }
+    .plan-decision-card .rationale { color: var(--text-secondary); font-size: var(--text-xs); }
+    .plan-decision-card .meta { color: var(--text-muted); font-size: var(--text-xs); }
+
     /* ─── Analysis caps preferences widget ──────────────────────────── */
     .caps-section {
       margin-top: var(--space-4);
@@ -3847,6 +3925,7 @@ HTML = r"""<!doctype html>
           <button class="nav-dropdown-item" data-panel-target="analysis" data-subpage-target="media" role="menuitem"><span class="nav-dropdown-icon" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="5" width="18" height="14" rx="2"></rect><path d="m7 15 3-3 2 2 4-5 1 2"></path></svg></span>Inventory</button>
           <button class="nav-dropdown-item" data-panel-target="analysis" data-subpage-target="review" role="menuitem"><span class="nav-dropdown-icon" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="3" width="18" height="14" rx="2"></rect><circle cx="9" cy="10" r="2"></circle><path d="m21 17-5-5-9 9"></path></svg></span>Review</button>
           <button class="nav-dropdown-item" id="navHistoryItem" data-panel-target="analysis" data-subpage-target="review" data-review-view="history" role="menuitem"><span class="nav-dropdown-icon" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8"></path><path d="M3 3v5h5"></path><path d="M12 7v5l4 2"></path></svg></span>History</button>
+          <button class="nav-dropdown-item" id="navPlansItem" data-panel-target="analysis" data-subpage-target="review" data-review-view="plans" role="menuitem"><span class="nav-dropdown-icon" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="8" y="2" width="8" height="4" rx="1"></rect><path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2"></path><path d="M9 12h6"></path><path d="M9 16h6"></path></svg></span>Edit Plans</button>
         </div>
       </div>
       <button class="control-tab" data-panel-target="aiconsole">AI Console</button>
@@ -4192,6 +4271,20 @@ HTML = r"""<!doctype html>
           </section>
         </div>
       </div>
+      <div id="reviewPlansView" style="display:none">
+        <div class="plans-toolbar">
+          <div>
+            <strong>Edit plans</strong>
+            <span class="section-meta">Dry-run plans saved by the edit engine — review here, execute from chat.</span>
+          </div>
+          <button id="plansRefreshBtn" class="secondary" type="button">Refresh</button>
+        </div>
+        <div id="plansListBody" class="plans-list"><div class="empty">Loading…</div></div>
+      </div>
+      <div id="reviewPlanView" style="display:none">
+        <div id="planDetailHeader" class="plan-detail-header"></div>
+        <div id="planDetailBody" class="plan-detail-body"></div>
+      </div>
     </section>
   </main>
 
@@ -5160,6 +5253,10 @@ HTML = r"""<!doctype html>
       if (r.view === 'combined' && Array.isArray(r.combinedClipIds) && r.combinedClipIds.length) {
         return `/combined/${r.combinedClipIds.map(encodeURIComponent).join(',')}`;
       }
+      if (r.view === 'plan' && state.plans?.currentPlanId) {
+        return `/plans/${encodeURIComponent(state.plans.currentPlanId)}`;
+      }
+      if (r.view === 'plans') return '/plans';
       return '';
     }
 
@@ -5191,6 +5288,15 @@ HTML = r"""<!doctype html>
         reviewSetView('history');
         refreshHistoryTimelines().catch(alertError);
       }
+      // Deep links: #analysis/review/plans[/<plan_id>]
+      if (panelName === 'analysis' && subpage === 'review' && route[2] === 'plans') {
+        if (route[3]) {
+          openEditPlan(decodeURIComponent(route[3]), { pushHash: false }).catch(alertError);
+        } else {
+          reviewSetView('plans', { pushHash: false });
+          refreshEditPlans().catch(alertError);
+        }
+      }
       // Deep links: #analysis/review/combined/<id1,id2,...>
       if (panelName === 'analysis' && subpage === 'review' && route[2] === 'combined' && route[3]) {
         const ids = decodeURIComponent(route[3]).split(',').filter(Boolean);
@@ -7210,6 +7316,229 @@ HTML = r"""<!doctype html>
       await refreshHistoryTimelines();
     }
 
+    // ─── Edit-engine plan browser (chat-first: the panel surfaces plans
+    //     and evidence; execution happens via copyable chat prompts only) ─
+    state.plans = state.plans || { list: null, currentPlanId: null, payload: null };
+
+    const PLAN_KIND_LABELS = { selects: 'Selects', tighten: 'Tighten', swap: 'Swap' };
+
+    function planExecutePrompt(plan) {
+      const id = plan.plan_id;
+      if (plan.kind === 'selects') {
+        return `Execute edit plan ${id}: call edit_engine(action="execute_selects", params={"plan_id": "${id}"}). It creates a NEW selects timeline; nothing existing is touched. Show me the readback when done.`;
+      }
+      if (plan.kind === 'tighten') {
+        return `Execute edit plan ${id}: call edit_engine(action="execute_tighten", params={"plan_id": "${id}"}). It assembles a tightened VARIANT timeline from the keep ranges; the original timeline is never mutated. Show me the readback when done.`;
+      }
+      if (plan.kind === 'swap') {
+        return `Execute edit plan ${id} with alternate <N>: call edit_engine(action="execute_swap", params={"plan_id": "${id}", "alternate_index": <N>}) — replace <N> with the number of the alternate I picked below (0-based). The timeline is version-archived before the swap. Show me the readback when done.`;
+      }
+      return `Load edit plan ${id} with edit_engine(action="get_plan", params={"plan_id": "${id}"}) and walk me through it.`;
+    }
+
+    function planThumb(row, altText) {
+      const clipId = row.resolve_clip_id;
+      const frameIndex = row.thumb_frame_index;
+      if (clipId && frameIndex != null) {
+        return `<img class="review-thumb" loading="lazy" src="/api/clips/${encodeURIComponent(clipId)}/frames/${frameIndex}" alt="${escapeHtml(altText)}" onerror="this.replaceWith(Object.assign(document.createElement('div'),{className:'review-thumb placeholder',textContent:'no frame'}))">`;
+      }
+      return '<div class="review-thumb placeholder">no frame</div>';
+    }
+
+    async function refreshEditPlans() {
+      const body = $('plansListBody');
+      if (body) body.innerHTML = '<div class="empty">Loading…</div>';
+      const data = await api('/api/edit_plans').catch(err => ({ success: false, error: String(err) }));
+      if (!data || !data.success) {
+        if (body) body.innerHTML = `<div class="empty">Error: ${escapeHtml(data?.error || 'unknown')}</div>`;
+        return;
+      }
+      state.plans.list = data.plans || [];
+      renderPlansList();
+    }
+
+    function renderPlansList() {
+      const body = $('plansListBody');
+      if (!body) return;
+      const plans = state.plans.list || [];
+      if (!plans.length) {
+        body.innerHTML = '<div class="empty">No edit plans yet. Ask your chat session to plan one, e.g. “Plan a selects reel from this bin” (edit_engine action="plan_selects").</div>';
+        return;
+      }
+      body.innerHTML = plans.map(p => {
+        if (p.corrupt) {
+          return `<div class="plan-row is-corrupt">
+            <span class="plan-chip corrupt">corrupt</span>
+            <span class="summary">Plan ${escapeHtml(p.plan_id || '?')} failed its fingerprint check — it was edited on disk or truncated. It cannot be executed; re-plan to replace it.</span>
+          </div>`;
+        }
+        const executed = p.executed_at
+          ? `<span class="plan-chip executed" title="${escapeHtml(p.executed_at)}">executed</span>` : '';
+        return `<div class="plan-row" data-plan-id="${escapeHtml(p.plan_id)}" tabindex="0" role="button" aria-label="Open plan ${escapeHtml(p.plan_id)}">
+          <span class="plan-chip kind-${escapeHtml(p.kind || '')}">${escapeHtml(PLAN_KIND_LABELS[p.kind] || p.kind || '?')}</span>
+          <span class="summary" title="${escapeHtml(p.summary || '')}">${escapeHtml(p.summary || p.plan_id)}</span>
+          ${executed}
+          <span class="saved-at">${escapeHtml(formatVersionDate(p.saved_at))}</span>
+        </div>`;
+      }).join('');
+      body.querySelectorAll('.plan-row[data-plan-id]').forEach(row => {
+        const open = () => openEditPlan(row.dataset.planId).catch(alertError);
+        row.addEventListener('click', open);
+        row.addEventListener('keydown', e => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); open(); } });
+      });
+    }
+
+    async function openEditPlan(planId, opts = {}) {
+      state.plans.currentPlanId = planId;
+      reviewSetView('plan', opts);
+      const body = $('planDetailBody');
+      const header = $('planDetailHeader');
+      if (body) body.innerHTML = '<div class="empty">Loading…</div>';
+      if (header) header.innerHTML = '';
+      const data = await api(`/api/edit_plans/${encodeURIComponent(planId)}`)
+        .catch(err => ({ success: false, error: String(err) }));
+      if (!data || !data.success) {
+        if (body) body.innerHTML = `<div class="empty">Error: ${escapeHtml(data?.error || 'unknown')}</div>`;
+        return;
+      }
+      state.plans.payload = data;
+      renderPlanDetail(data);
+    }
+
+    function renderPlanDetail(data) {
+      const header = $('planDetailHeader');
+      const body = $('planDetailBody');
+      if (!header || !body) return;
+      if (data.corrupt) {
+        header.innerHTML = `<span class="plan-chip corrupt">corrupt</span><span class="timeline-name">Plan ${escapeHtml(data.plan_id || '?')}</span>`;
+        body.innerHTML = '<div class="empty">This plan failed its fingerprint check — it was edited on disk or truncated. It cannot be executed; re-plan to replace it.</div>';
+        return;
+      }
+      const plan = data.plan || {};
+      const executed = plan.executed_at
+        ? `<span class="plan-chip executed" title="${escapeHtml(plan.executed_at)}">executed ${escapeHtml(formatVersionDate(plan.executed_at))}</span>` : '';
+      header.innerHTML = `
+        <span class="plan-chip kind-${escapeHtml(plan.kind || '')}">${escapeHtml(PLAN_KIND_LABELS[plan.kind] || plan.kind || '?')}</span>
+        <span class="timeline-name">${escapeHtml(plan.timeline_name || plan.plan_id || '')}</span>
+        ${executed}
+        <span class="saved-at" style="color:var(--text-muted);font-size:var(--text-xs)">saved ${escapeHtml(formatVersionDate(plan.saved_at))} · plan ${escapeHtml(plan.plan_id || '')}</span>`;
+
+      const sections = [];
+      if (plan.summary) {
+        sections.push(`<div class="plan-section"><strong>Summary</strong><div>${escapeHtml(plan.summary)}</div></div>`);
+      }
+      // Chat-first execute affordance: the panel NEVER executes. Executed
+      // plans keep the card (re-execution of selects is harmless and swap
+      // may target another alternate) — the chip above signals state.
+      sections.push(`<div class="plan-section"><strong>Execute (from chat)</strong>${chatPromptCard(
+        plan.kind === 'swap'
+          ? 'Pick an alternate below, then paste this in your chat session (fill in <N>):'
+          : 'Paste this in your chat session to execute the plan:',
+        planExecutePrompt(plan))}</div>`);
+      if (plan.execution_summary) {
+        sections.push(`<div class="plan-section"><strong>Execution readback</strong><pre style="margin:0;white-space:pre-wrap;font-size:var(--text-xs)">${escapeHtml(JSON.stringify(plan.execution_summary, null, 2))}</pre></div>`);
+      }
+      if (plan.settings) {
+        const settings = Object.entries(plan.settings)
+          .map(([k, v]) => `${escapeHtml(k)}=${escapeHtml(v == null ? '—' : String(v))}`).join(' · ');
+        sections.push(`<div class="plan-section"><strong>Settings</strong><div style="font-size:var(--text-xs);color:var(--text-secondary)">${settings}</div></div>`);
+      }
+      if (plan.kind === 'selects') {
+        sections.push(renderSelectsDecisions(plan));
+      } else if (plan.kind === 'tighten') {
+        sections.push(renderTightenLifts(plan));
+      } else if (plan.kind === 'swap') {
+        sections.push(renderSwapAlternates(plan));
+      }
+      body.innerHTML = sections.join('');
+      body.querySelectorAll('[data-open-shot-clip]').forEach(btn => {
+        btn.addEventListener('click', () => {
+          const clipId = btn.dataset.openShotClip;
+          const shotIndex = Number(btn.dataset.openShotIndex);
+          openClipDetail(clipId)
+            .then(() => Number.isFinite(shotIndex) ? openShotDetail(shotIndex) : null)
+            .catch(alertError);
+        });
+      });
+    }
+
+    function renderSelectsDecisions(plan) {
+      const decisions = plan.decisions || [];
+      const rankLabel = { 3: 'high', 2: 'medium', 1: 'low' };
+      const cards = decisions.map((d, i) => {
+        const range = Array.isArray(d.source_frame_range) ? `frames ${d.source_frame_range[0]}–${d.source_frame_range[1]}` : '';
+        const shotLink = d.resolve_clip_id != null && d.shot_index != null
+          ? `<button class="secondary" style="font-size:var(--text-xs);padding:1px 8px" data-open-shot-clip="${escapeHtml(d.resolve_clip_id)}" data-open-shot-index="${d.shot_index}">Open shot page</button>` : '';
+        return `<div class="plan-decision-card">
+          ${planThumb(d, `decision ${i + 1}`)}
+          <div class="body">
+            <div class="title-row">
+              <strong>${i + 1}. ${escapeHtml(d.clip_name || d.clip_uuid || '?')} · shot ${d.shot_index ?? '?'}</strong>
+              <span class="plan-chip">${escapeHtml(rankLabel[d.rank] || `rank ${d.rank}`)}</span>
+              <span class="meta">${(d.duration_seconds ?? '?')}s${range ? ` · ${range}` : ''}</span>
+              ${shotLink}
+            </div>
+            ${d.description ? `<div class="meta">${escapeHtml(d.description)}</div>` : ''}
+            <div class="rationale">${escapeHtml(d.rationale || '')}</div>
+          </div>
+        </div>`;
+      });
+      return `<div class="plan-section"><strong>Decisions (${decisions.length} shots, ~${plan.estimated_duration_seconds ?? '?'}s)</strong>${cards.join('') || '<div class="empty">No decisions.</div>'}</div>`;
+    }
+
+    function renderTightenLifts(plan) {
+      const lifts = plan.lifts || [];
+      const rows = lifts.map(l => {
+        const gap = l.evidence?.source_gap_seconds;
+        return `<tr>
+          <td class="edit-type">${escapeHtml(l.kind || 'lift')}</td>
+          <td>${escapeHtml(l.item_name || '—')}</td>
+          <td>${l.timeline_start_frame}–${l.timeline_end_frame}</td>
+          <td>${l.duration_seconds ?? '—'}s</td>
+          <td>${escapeHtml(l.rationale || '')}${gap ? ` <span style="color:var(--text-muted)">(gap ${gap[0]}–${gap[1]}s)</span>` : ''}</td>
+        </tr>`;
+      }).join('');
+      const skipped = (plan.skipped || []).map(s =>
+        `<div class="plan-decision-card"><div class="body"><div class="meta">skipped ${escapeHtml(s.item || '?')}: ${escapeHtml(s.reason || '')}</div></div></div>`).join('');
+      return `<div class="plan-section">
+        <strong>Lifts (${lifts.length} · ${plan.keep_ranges ? plan.keep_ranges.length : 0} keep ranges)</strong>
+        <table class="history-edits-table">
+          <thead><tr><th>Kind</th><th>Item</th><th>Timeline frames</th><th>Removes</th><th>Rationale</th></tr></thead>
+          <tbody>${rows || '<tr><td colspan="5">No lifts.</td></tr>'}</tbody>
+        </table>
+        ${skipped}
+      </div>`;
+    }
+
+    function renderSwapAlternates(plan) {
+      const alternates = plan.alternates || [];
+      const item = plan.item || {};
+      const current = `<div class="plan-decision-card"><div class="body">
+        <div class="title-row"><strong>Current: ${escapeHtml(item.item_name || 'item')}</strong>
+        <span class="meta">slot ${item.timeline_start_frame}–${item.timeline_end_frame} · track ${item.track_index ?? 1}</span></div>
+        ${item.current_description ? `<div class="meta">${escapeHtml(item.current_description)}</div>` : ''}
+      </div></div>`;
+      const cards = alternates.map((a, i) => {
+        const range = Array.isArray(a.source_frame_range) ? `frames ${a.source_frame_range[0]}–${a.source_frame_range[1]}` : '';
+        const shotLink = a.resolve_clip_id != null && a.shot_index != null
+          ? `<button class="secondary" style="font-size:var(--text-xs);padding:1px 8px" data-open-shot-clip="${escapeHtml(a.resolve_clip_id)}" data-open-shot-index="${a.shot_index}">Open shot page</button>` : '';
+        return `<div class="plan-decision-card">
+          ${planThumb(a, `alternate ${i}`)}
+          <div class="body">
+            <div class="title-row">
+              <strong>alternate_index ${i} · ${escapeHtml(a.clip_name || '?')} · shot ${a.shot_index ?? '?'}</strong>
+              <span class="plan-chip">score ${a.score ?? '?'}</span>
+              <span class="meta">${range}</span>
+              ${shotLink}
+            </div>
+            ${a.description ? `<div class="meta">${escapeHtml(a.description)}</div>` : ''}
+            <div class="rationale">${escapeHtml(a.rationale || '')}</div>
+          </div>
+        </div>`;
+      });
+      return `<div class="plan-section"><strong>Alternates (${alternates.length})</strong>${current}${cards.join('') || '<div class="empty">No alternates.</div>'}</div>`;
+    }
+
     // ─── Run scoping controls ──────────────────────────────────────────
     state.runScope = state.runScope || { current: null, recent: [] };
 
@@ -8088,6 +8417,10 @@ HTML = r"""<!doctype html>
       if (combinedEl) combinedEl.style.display = view === 'combined' ? '' : 'none';
       const historyEl = $('reviewHistoryView');
       if (historyEl) historyEl.style.display = view === 'history' ? '' : 'none';
+      const plansEl = $('reviewPlansView');
+      if (plansEl) plansEl.style.display = view === 'plans' ? '' : 'none';
+      const planEl = $('reviewPlanView');
+      if (planEl) planEl.style.display = view === 'plan' ? '' : 'none';
       const back = $('reviewBackBtn');
       if (back) back.style.display = view === 'bin' ? 'none' : '';
       const meta = $('reviewMeta');
@@ -8098,6 +8431,8 @@ HTML = r"""<!doctype html>
         else if (view === 'transcript') meta.textContent = `Transcript · ${state.review.currentClipData?.card?.clip_name || 'clip'}`;
         else if (view === 'combined') meta.textContent = `Combined review · ${state.review.combinedData?.clip_count || '?'} clips`;
         else if (view === 'history') meta.textContent = 'Timeline history · archived versions and brain edits per timeline';
+        else if (view === 'plans') meta.textContent = 'Edit plans · dry-run plans saved by the edit engine';
+        else if (view === 'plan') meta.textContent = `Plan ${state.plans?.currentPlanId || ''} · review here, execute from chat`;
       }
       if (opts.writePanelState !== false) {
         writePanelStateAsync({
@@ -10470,6 +10805,12 @@ HTML = r"""<!doctype html>
           if (window.location.hash !== '#analysis/review/history') {
             window.history.replaceState(null, '', '#analysis/review/history');
           }
+        } else if (control.dataset.reviewView === 'plans') {
+          reviewSetView('plans');
+          refreshEditPlans().catch(alertError);
+          if (window.location.hash !== '#analysis/review/plans') {
+            window.history.replaceState(null, '', '#analysis/review/plans');
+          }
         }
       });
     });
@@ -10588,6 +10929,10 @@ HTML = r"""<!doctype html>
     if (historyRefreshEl) {
       historyRefreshEl.onclick = () => refreshHistoryTimelines().catch(alertError);
     }
+    const plansRefreshEl = $('plansRefreshBtn');
+    if (plansRefreshEl) {
+      plansRefreshEl.onclick = () => refreshEditPlans().catch(alertError);
+    }
     const historyArchiveBtnEl = $('historyArchiveCurrentBtn');
     if (historyArchiveBtnEl) {
       historyArchiveBtnEl.onclick = () => {
@@ -10707,6 +11052,13 @@ HTML = r"""<!doctype html>
         reviewSetView('bin');
       } else if (state.review.view === 'history') {
         reviewSetView('bin');
+      } else if (state.review.view === 'plan') {
+        state.plans.currentPlanId = null;
+        state.plans.payload = null;
+        reviewSetView('plans');
+        refreshEditPlans().catch(alertError);
+      } else if (state.review.view === 'plans') {
+        reviewSetView('bin');
       }
     };
     $('reviewBinGrid').addEventListener('click', event => {
@@ -13361,6 +13713,71 @@ def get_timeline_history_payload(
     }
 
 
+def list_edit_plans_payload(project_root: str) -> Dict[str, Any]:
+    """Edit-engine plan list for the panel browser (DB/file only, no Resolve).
+
+    Fingerprint-corrupt plans surface as {"plan_id", "corrupt": True} warning
+    rows rather than being silently hidden.
+    """
+    try:
+        from src.utils import edit_engine as _edit_engine
+        return _edit_engine.list_plans(project_root, limit=50, include_corrupt=True)
+    except Exception as exc:  # noqa: BLE001 — panel reads fail soft
+        return {"success": False, "error": f"{type(exc).__name__}: {exc}", "plans": []}
+
+
+def get_edit_plan_payload(project_root: str, plan_id: str) -> Dict[str, Any]:
+    """Full plan detail for the panel, enriched for rendering: selects
+    decisions and swap alternates gain a `thumb_frame_index` (the shot's first
+    sampled frame, for the existing /api/clips/<id>/frames/<idx> route) and a
+    `resolve_clip_id` fallback mapped from clip_uuid. Enrichment is best-effort
+    — the plan still renders without thumbnails when the DB is unavailable.
+    """
+    try:
+        from src.utils import edit_engine as _edit_engine
+        plan = _edit_engine.load_plan(project_root, plan_id)
+    except Exception as exc:  # noqa: BLE001
+        return {"success": False, "error": f"{type(exc).__name__}: {exc}"}
+    if plan is None:
+        return {"success": False, "error": f"Plan {plan_id} not found"}
+    if plan.get("_corrupt"):
+        return {"success": True, "plan_id": plan_id, "corrupt": True}
+    plan = json.loads(json.dumps(plan, default=str))  # detach a plain copy
+    try:
+        conn = _timeline_brain_db.connect(project_root)
+        clip_id_cache: Dict[str, Any] = {}
+
+        def _enrich(row: Dict[str, Any]) -> None:
+            clip_uuid = str(row.get("clip_uuid") or "")
+            if not row.get("resolve_clip_id") and clip_uuid:
+                if clip_uuid not in clip_id_cache:
+                    hit = conn.execute(
+                        "SELECT resolve_clip_id FROM clips WHERE clip_uuid = ?",
+                        (clip_uuid,),
+                    ).fetchone()
+                    clip_id_cache[clip_uuid] = hit["resolve_clip_id"] if hit else None
+                if clip_id_cache[clip_uuid]:
+                    row["resolve_clip_id"] = clip_id_cache[clip_uuid]
+            shot_uuid = row.get("shot_uuid")
+            if shot_uuid and row.get("thumb_frame_index") is None:
+                hit = conn.execute(
+                    "SELECT MIN(frame_index) AS frame_index FROM frames WHERE shot_uuid = ?",
+                    (str(shot_uuid),),
+                ).fetchone()
+                if hit and hit["frame_index"] is not None:
+                    row["thumb_frame_index"] = int(hit["frame_index"])
+
+        for decision in plan.get("decisions") or []:
+            if isinstance(decision, dict):
+                _enrich(decision)
+        for alternate in plan.get("alternates") or []:
+            if isinstance(alternate, dict):
+                _enrich(alternate)
+    except Exception:  # noqa: BLE001 — thumbnails are progressive enhancement
+        pass
+    return {"success": True, "corrupt": False, "plan": plan}
+
+
 def proxy_timeline_versioning_action(body: Dict[str, Any]) -> Dict[str, Any]:
     """Bridge dashboard → MCP server timeline_versioning tool.
 
@@ -14473,6 +14890,21 @@ class Handler(BaseHTTPRequestHandler):
                 return
             self._json(get_timeline_history_payload(self.state.project_root, timeline_name))
             return
+        # ─── Edit-engine plan browser (DB/file only — no Resolve) ───────
+        if path == "/api/edit_plans":
+            self._json(list_edit_plans_payload(self.state.project_root))
+            return
+        if path.startswith("/api/edit_plans/"):
+            plan_id = unquote(path[len("/api/edit_plans/"):])
+            if not plan_id:
+                self._json({"success": False, "error": "plan_id required"}, HTTPStatus.BAD_REQUEST)
+                return
+            payload = get_edit_plan_payload(self.state.project_root, plan_id)
+            if not payload.get("success") and "not found" in str(payload.get("error", "")):
+                self._json(payload, HTTPStatus.NOT_FOUND)
+                return
+            self._json(payload)
+            return
         if path == "/api/brain_edits/registry":
             self._json({"success": True, **_brain_edits.read_brain_edits_registry(self.state.project_root)})
             return

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.46.1"
+VERSION = "2.48.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.46.1"
+VERSION = "2.48.0"
 
 import base64
 import os
@@ -16386,6 +16386,10 @@ def timeline_versioning(action: str, params: Optional[Dict[str, Any]] = None) ->
       list_versions(timeline_name) -> [{version, archived_timeline_name, created_at, ...}]
         Version chain for `timeline_name`, oldest first. Includes any retention-
         collapsed versions (drt_export_path populated).
+      diff_timelines(from_timeline, to_timeline) -> {added, removed, moved, trimmed, summary}
+        Structural diff between two LIVE timelines by name (read-only; no
+        archived versions needed). Built for edit-engine variants — tighten/
+        selects produce new-name timelines with no shared version chain.
       get_history(timeline_name?, analysis_run_id?, limit?) -> [{edit_type, target_metric, before_value, after_value, delta, ...}]
         Brain-edit history. Filter by timeline_name or analysis_run_id; defaults
         to the most recent 50 across the project.
@@ -16453,6 +16457,14 @@ def timeline_versioning(action: str, params: Optional[Dict[str, Any]] = None) ->
                 to_version=int(p["to_version"]),
             ),
         }
+    if action == "diff_timelines":
+        if not p.get("from_timeline") or not p.get("to_timeline"):
+            return _err("from_timeline and to_timeline required")
+        return _timeline_versioning.diff_timelines(
+            project=project_h,
+            from_timeline=str(p["from_timeline"]),
+            to_timeline=str(p["to_timeline"]),
+        )
     if action == "get_history":
         rows = _brain_edits.get_brain_edit_history(
             project_root=project_root,
@@ -16562,6 +16574,105 @@ def _edit_engine_capture(tl) -> Dict[str, Any]:
     return out
 
 
+def _edit_engine_track_counts(tl) -> Dict[str, int]:
+    """Per-track-type item counts — the swap symmetry signal in readback."""
+    counts: Dict[str, int] = {}
+    for tt in ("video", "audio"):
+        total = 0
+        try:
+            n = int(tl.GetTrackCount(tt) or 0)
+        except Exception:
+            n = 0
+        for ti in range(1, n + 1):
+            try:
+                total += len(tl.GetItemListInTrack(tt, ti) or [])
+            except Exception:
+                continue
+        counts[tt] = total
+    return counts
+
+
+def _edit_engine_find_slot_item(tl, track_index: int, slot_start: int, slot_end: int):
+    """The video item occupying exactly [slot_start, slot_end] on a track."""
+    try:
+        for cand in (tl.GetItemListInTrack("video", int(track_index)) or []):
+            if _frame_int(cand.GetStart()) == slot_start and _frame_int(cand.GetEnd()) == slot_end:
+                return cand
+    except Exception:
+        pass
+    return None
+
+
+def _edit_engine_linked_audio_tracks(
+    tl, target_item, slot_start: int, slot_end: int,
+) -> Tuple[List[int], str]:
+    """Audio track indices carrying the target item's linked audio.
+
+    Prefers GetLinkedItems; falls back to matching slot-overlapping audio
+    items that share the target's media-pool source. ([], note) when there is
+    no linked audio (audio-only handling stays untouched) or no target item.
+    """
+    if target_item is None:
+        return [], "target video item not found on its track; audio left untouched"
+    linked_ids: set = set()
+    get_linked = getattr(target_item, "GetLinkedItems", None)
+    if callable(get_linked):
+        try:
+            for linked_item in (get_linked() or []):
+                uid = getattr(linked_item, "GetUniqueId", None)
+                if callable(uid):
+                    linked_ids.add(str(uid()))
+        except Exception:
+            linked_ids = set()
+    target_media_id = None
+    try:
+        mpi = target_item.GetMediaPoolItem()
+        if mpi is not None:
+            target_media_id = str(mpi.GetUniqueId())
+    except Exception:
+        target_media_id = None
+    if not linked_ids and not target_media_id:
+        return [], "GetLinkedItems unavailable and no media id to match; audio left untouched"
+
+    indices: List[int] = []
+    try:
+        audio_tracks = int(tl.GetTrackCount("audio") or 0)
+    except Exception:
+        audio_tracks = 0
+    for ti in range(1, audio_tracks + 1):
+        try:
+            items = tl.GetItemListInTrack("audio", ti) or []
+        except Exception:
+            continue
+        for cand in items:
+            try:
+                c_start = _frame_int(cand.GetStart())
+                c_end = _frame_int(cand.GetEnd())
+            except Exception:
+                continue
+            if c_start is None or c_end is None or c_start >= slot_end or c_end <= slot_start:
+                continue
+            is_linked = False
+            if linked_ids:
+                uid = getattr(cand, "GetUniqueId", None)
+                if callable(uid):
+                    try:
+                        is_linked = str(uid()) in linked_ids
+                    except Exception:
+                        is_linked = False
+            if not is_linked and target_media_id:
+                try:
+                    c_mpi = cand.GetMediaPoolItem()
+                    is_linked = c_mpi is not None and str(c_mpi.GetUniqueId()) == target_media_id
+                except Exception:
+                    is_linked = False
+            if is_linked and ti not in indices:
+                indices.append(ti)
+    if not indices:
+        return [], "no linked audio found for the target item"
+    return indices, ""
+
+
 @mcp.tool()
 @_destructive_op("edit_engine")
 def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
@@ -16743,6 +16854,16 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
             record_cursor += int(append_ci.get("end_frame", 0)) - int(append_ci.get("start_frame", 0)) + 1
         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;
+        # a usage-snapshot summary is the structural readback that fits.
+        try:
+            usage = _timeline_versioning.capture_timeline_clip_usage(tl)
+            by_type: Dict[str, int] = {}
+            for usage_row in usage:
+                by_type[usage_row["track_type"]] = by_type.get(usage_row["track_type"], 0) + 1
+            readback["usage_summary"] = {"items": len(usage), "by_track_type": by_type}
+        except Exception:
+            pass
         run_id = _analysis_runs.current_run_id()
         try:
             _brain_edits.log_brain_edit(
@@ -16820,6 +16941,17 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
             return {"success": False, "error": f"variant assembly failed: {variant.get('error')}", "variant": variant}
         new_tl, _new_index = _find_timeline_by_name(proj, variant.get("name") or variant_name)
         after = _edit_engine_capture(new_tl) if new_tl else {}
+        # Cross-name structural diff (source vs variant): trustworthy readback
+        # without archived version rows — variants are new-name timelines.
+        structural_diff = None
+        if new_tl is not None:
+            try:
+                structural_diff = _timeline_versioning.compare_usage_snapshots(
+                    _timeline_versioning.capture_timeline_clip_usage(source_tl),
+                    _timeline_versioning.capture_timeline_clip_usage(new_tl),
+                )
+            except Exception as diff_exc:
+                structural_diff = {"error": f"{type(diff_exc).__name__}: {diff_exc}"}
         run_id = _analysis_runs.current_run_id()
         try:
             _brain_edits.log_brain_edit(
@@ -16865,6 +16997,7 @@ 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,
             },
             "plan_id": plan.get("plan_id"),
         }
@@ -16916,14 +17049,44 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
         except Exception:
             pass
         before = _edit_engine_capture(tl)
+        before["track_counts"] = _edit_engine_track_counts(tl)
+        slot_start = int(item_block.get("timeline_start_frame"))
+        slot_end = int(item_block.get("timeline_end_frame"))
+        target_track = int(item_block.get("track_index") or 1)
+        # Capture the target's linked audio BEFORE the lift so the audio lift
+        # is scoped to exactly those tracks (the replacement appends linked
+        # video+audio, so both sides of the swap stay symmetric).
+        target_item = _edit_engine_find_slot_item(tl, target_track, slot_start, slot_end)
+        linked_audio_indices, audio_note = _edit_engine_linked_audio_tracks(
+            tl, target_item, slot_start, slot_end,
+        )
         lift = _timeline_lift_range_impl(tl, {
-            "start_frame": item_block.get("timeline_start_frame"),
-            "end_frame": item_block.get("timeline_end_frame"),
+            "start_frame": slot_start,
+            "end_frame": slot_end,
+            "track_types": ["video"],
+            "track_indices": [target_track],
             "allow_partial_item_delete": True,
             "ripple": False,
         })
         if not lift.get("success"):
             return {"success": False, "error": f"lift failed: {lift.get('error')}", "lift": lift}
+        audio_lift = None
+        if linked_audio_indices:
+            audio_lift = _timeline_lift_range_impl(tl, {
+                "start_frame": slot_start,
+                "end_frame": slot_end,
+                "track_types": ["audio"],
+                "track_indices": linked_audio_indices,
+                "allow_partial_item_delete": True,
+                "ripple": False,
+            })
+            if not audio_lift.get("success"):
+                return {
+                    "success": False,
+                    "error": f"linked-audio lift failed: {audio_lift.get('error')}",
+                    "lift": lift,
+                    "audio_lift": audio_lift,
+                }
         mp = proj.GetMediaPool()
         root_folder = mp.GetRootFolder()
         timeline_start = _timeline_start_frame(tl)
@@ -16940,8 +17103,11 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
         row, row_err = _build_append_clip_info_dict(root_folder, ci, 0, timeline_start)
         if row_err:
             return {"success": False, "error": f"swap append failed: {row_err.get('error')}", "lifted": lift}
+        # No mediaType on the clip info: the replacement appends video+audio
+        # linked, mirroring the video + linked-audio lift above.
         appended = mp.AppendToTimeline([row])
         after = _edit_engine_capture(tl)
+        after["track_counts"] = _edit_engine_track_counts(tl)
         run_id = _analysis_runs.current_run_id()
         try:
             _brain_edits.log_brain_edit(
@@ -16972,6 +17138,13 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
             "before": before,
             "after": after,
         })
+        readback: Dict[str, Any] = {"before": before, "after": after}
+        readback["audio_accounting"] = {
+            "linked_audio_tracks_lifted": linked_audio_indices,
+            "audio_items_lifted": (audio_lift or {}).get("deleted", 0),
+            "video_items_lifted": lift.get("deleted", 0),
+            **({"note": audio_note} if audio_note else {}),
+        }
         return {
             "success": bool(appended),
             "timeline_name": tl.GetName(),
@@ -16981,7 +17154,7 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                 "shot_index": alternate.get("shot_index"),
                 "score": alternate.get("score"),
             },
-            "readback": {"before": before, "after": after},
+            "readback": readback,
             "plan_id": plan.get("plan_id"),
         }
 

package/src/utils/edit_engine.py

@@ -81,7 +81,13 @@ def load_plan(project_root: str, plan_id: str) -> Optional[Dict[str, Any]]:
     return plan
 
 
-def list_plans(project_root: str, *, limit: int = 20) -> Dict[str, Any]:
+def list_plans(project_root: str, *, limit: int = 20, include_corrupt: bool = False) -> Dict[str, Any]:
+    """List saved plans, newest first.
+
+    `include_corrupt=True` (panel browser) surfaces fingerprint-mismatched
+    plans as ``{"plan_id", "corrupt": True}`` warning rows instead of hiding
+    them; the default keeps the MCP-action shape unchanged.
+    """
     directory = _plan_dir(project_root)
     rows: List[Dict[str, Any]] = []
     if os.path.isdir(directory):
@@ -90,6 +96,8 @@ def list_plans(project_root: str, *, limit: int = 20) -> Dict[str, Any]:
                 continue
             plan = load_plan(project_root, name[:-5])
             if not plan or plan.get("_corrupt"):
+                if include_corrupt:
+                    rows.append({"plan_id": name[:-5], "corrupt": True})
                 continue
             rows.append({
                 "plan_id": plan.get("plan_id"),

package/src/utils/timeline_versioning.py

@@ -261,22 +261,11 @@ def _resolve_media_pool_item_id(item: Any) -> Optional[str]:
         return None
 
 
-def _snapshot_timeline_clip_usage(
-    *,
-    project_root: str,
-    timeline: Any,
-    timeline_name: str,
-    timeline_version: int,
-    analysis_run_id: Optional[str],
-) -> int:
-    """Walk every track/item on the timeline and INSERT a row per clip.
-
-    Returns the number of rows written. Safe to call repeatedly for the same
-    (timeline, version) — version is part of the row, not unique, so diffs
-    between two versions are a SQL JOIN on media_pool_item_id.
-    """
-    observed_at = _now_iso()
-    rows: List[Tuple[str, str, int, str, int, int, int, Optional[str], str]] = []
+def capture_timeline_clip_usage(timeline: Any) -> List[Dict[str, Any]]:
+    """Walk every track/item on a LIVE timeline into structural-usage rows
+    (no DB writes). Shared by the version snapshot writer and the cross-name
+    live diff."""
+    rows: List[Dict[str, Any]] = []
     for tt in ("video", "audio", "subtitle"):
         try:
             count = timeline.GetTrackCount(tt)
@@ -298,10 +287,39 @@ def _snapshot_timeline_clip_usage(
                     out_frame = int(item.GetEnd())
                 except Exception:
                     continue
-                rows.append((
-                    mpi_id, timeline_name, timeline_version,
-                    tt, ti, in_frame, out_frame, analysis_run_id, observed_at,
-                ))
+                rows.append({
+                    "media_pool_item_id": mpi_id,
+                    "track_type": tt,
+                    "track_index": ti,
+                    "in_frame": in_frame,
+                    "out_frame": out_frame,
+                })
+    return rows
+
+
+def _snapshot_timeline_clip_usage(
+    *,
+    project_root: str,
+    timeline: Any,
+    timeline_name: str,
+    timeline_version: int,
+    analysis_run_id: Optional[str],
+) -> int:
+    """Walk every track/item on the timeline and INSERT a row per clip.
+
+    Returns the number of rows written. Safe to call repeatedly for the same
+    (timeline, version) — version is part of the row, not unique, so diffs
+    between two versions are a SQL JOIN on media_pool_item_id.
+    """
+    observed_at = _now_iso()
+    rows: List[Tuple[str, str, int, str, int, int, int, Optional[str], str]] = [
+        (
+            usage["media_pool_item_id"], timeline_name, timeline_version,
+            usage["track_type"], usage["track_index"],
+            usage["in_frame"], usage["out_frame"], analysis_run_id, observed_at,
+        )
+        for usage in capture_timeline_clip_usage(timeline)
+    ]
 
     if not rows:
         return 0
@@ -348,9 +366,22 @@ def diff_versions(
 
     before = _snapshot(from_version)
     after = _snapshot(to_version)
-    # Position key: (media id, track type, track index, in_frame). Same key in
-    # both versions = same placement; a differing out_frame on that same key is
-    # a *trim*. A differing track/in_frame for the same media id is a *move*.
+    return {
+        "from_version": from_version,
+        "to_version": to_version,
+        **compare_usage_snapshots(before, after),
+    }
+
+
+def compare_usage_snapshots(
+    before: List[Dict[str, Any]], after: List[Dict[str, Any]],
+) -> Dict[str, Any]:
+    """added/removed/moved/trimmed between two structural-usage snapshots.
+
+    Position key: (media id, track type, track index, in_frame). Same key in
+    both snapshots = same placement; a differing out_frame on that same key is
+    a *trim*. A differing track/in_frame for the same media id is a *move*.
+    """
     def _key(row: Dict[str, Any]) -> Tuple[str, str, int, int]:
         return (row["media_pool_item_id"], row["track_type"], row["track_index"], row["in_frame"])
 
@@ -382,8 +413,6 @@ def diff_versions(
             moved.append(r)
 
     return {
-        "from_version": from_version,
-        "to_version": to_version,
         "added": added,
         "removed": removed,
         "moved": moved,
@@ -399,6 +428,36 @@ def diff_versions(
     }
 
 
+def diff_timelines(
+    *,
+    project: Any,
+    from_timeline: str,
+    to_timeline: str,
+) -> Dict[str, Any]:
+    """Structural diff between two LIVE timelines by name (read-only).
+
+    Unlike diff_versions this needs no archived snapshots and works across
+    timeline NAMES — built for edit-engine variants (tighten/selects produce
+    new-name timelines that have no shared version chain with their source).
+    For moved/trimmed to mean anything the timelines should share source
+    clips; for unrelated timelines everything reports as added/removed.
+    """
+    from_tl = _find_timeline_by_name(project, from_timeline)
+    if from_tl is None:
+        return {"success": False, "error": f"Timeline '{from_timeline}' not found"}
+    to_tl = _find_timeline_by_name(project, to_timeline)
+    if to_tl is None:
+        return {"success": False, "error": f"Timeline '{to_timeline}' not found"}
+    before = capture_timeline_clip_usage(from_tl)
+    after = capture_timeline_clip_usage(to_tl)
+    return {
+        "success": True,
+        "from_timeline": from_timeline,
+        "to_timeline": to_timeline,
+        **compare_usage_snapshots(before, after),
+    }
+
+
 def ensure_versioned_before_mutation(
     *,
     resolve: Any,