davinci-resolve-mcp 2.30.0 → 2.32.0

package/CHANGELOG.md

@@ -2,6 +2,68 @@
 
 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.32.0
+
+Adds **governance tiers** for the media-creating Resolve 21 AI ops (Phase 3, the
+final phase of the AI-ops build: ledger → console → governance).
+
+The two ops that render new files — `remove_motion_blur` and `generate_speech` —
+now have **soft, per-session limits** chosen by a named tier:
+
+| dimension | off | lenient | standard | strict |
+|---|---|---|---|---|
+| deblur runs | ∞ | 50 | 15 | 5 |
+| speech runs | ∞ | 50 | 15 | 5 |
+| media created | ∞ | 50 GB | 10 GB | 2 GB |
+| render time | ∞ | 1 h | 20 min | 5 min |
+
+Governance is **advisory** — it never hard-blocks (the ops are already
+confirm-token gated). When you're near or over the active tier, the confirmation
+dialog surfaces a warning before you proceed; the limits are computed from the
+v2.30.0 AI-ops ledger for the current session.
+
+- **New module** `src/utils/resolve_ai_governance.py` — tiers + `check()` (status
+  for the next run) + `status()` (session usage vs tier). Default tier: `standard`.
+- **New MCP actions** `media_analysis(action="get_ai_governance")` and
+  `media_analysis(action="set_ai_governance", preset, overrides?)`. Override keys:
+  `deblur_runs`, `speech_runs`, `render_bytes`, `render_wall_clock_ms` (int or `"unlimited"`).
+- **Confirm preview** for the two creators now carries a `governance` block
+  (current usage, projected, warnings, exceeded/near flags).
+- **Control panel** — the AI Console gains a **Governance** section: a tier picker
+  (off/lenient/standard/strict, with each tier's thresholds) plus live
+  consumption gauges, and the confirm dialog shows the warning inline.
+
+This completes the staged AI-ops build. Validated live against Resolve Studio
+21.0.0.47 (tier switching, persistence, gauges, confirm-dialog warnings).
+
+## What's New in v2.31.0
+
+Adds the **AI Console** to the control panel — an interactive surface for the
+Resolve 21 local AI operations (Phase 2 of the staged AI-ops build: ledger →
+console → governance).
+
+A new **AI Console** tab runs the 21.0 ops against the current Media Pool folder
+or a specific clip:
+
+- **Capability matrix** — shows which AI methods this Resolve build exposes (green
+  = available, grey = absent on older builds) and which Extra each gated method
+  needs to actually run.
+- **Analysis** — Classify audio / Clear classification, IntelliSearch (with
+  identify-faces and Better-mode toggles), Analyze for slate (16-color marker
+  picker), Transcribe (with speaker-detection toggle), Clear transcription.
+- **Motion deblur** and **Speech generator** — full options forms; because both
+  create new media files they route through a confirmation modal (the same
+  confirm-token gate the MCP tools use) before running.
+- **Session** — Disable background tasks for the current Resolve session.
+- A live result readout, and the *Resolve 21 AI ops* ledger refreshes after each
+  run so file/byte totals stay current.
+
+Backend: a loopback-only `POST /api/resolve_ai/run` endpoint dispatches each op
+to the consolidated `folder` / `media_pool_item` / `project_settings` /
+`resolve_control` tools, relaying the confirm-token two-step. No new MCP tools or
+Resolve API surface — the console reuses the existing v2.29.0 actions. Validated
+live end-to-end against Resolve Studio 21.0.0.47.
+
 ## What's New in v2.30.0
 
 Adds the **Resolve 21 AI-ops ledger** — usage/time/file accounting for the

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.30.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.32.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-32%20(341%20full)-blue.svg)](#server-modes)

package/docs/SKILL.md

@@ -677,6 +677,14 @@ spend the Claude analysis token budget — they are tracked separately in the
 `remove_motion_blur` / `generate_speech`). The control panel shows the same as a
 read-only "Resolve 21 AI ops" card.
 
+The two media-creating ops also have **soft governance tiers**
+(`off`|`lenient`|`standard`|`strict`, default `standard`) capping per-session
+deblur/speech runs, bytes, and render time. It is advisory — the confirm dialog
+warns when near/over the tier but never blocks (the ops are confirm-gated).
+Inspect/set with `media_analysis(action="get_ai_governance")` and
+`media_analysis(action="set_ai_governance", preset=…, overrides={...})`; the AI
+Console's Governance section offers a tier picker + consumption gauges.
+
 The caps layer:
 - Slices `frame_paths` to `frames_per_clip` before the host LLM sees them.
 - Downscales each sampled frame in place to `max_frame_dim_pixels` (Pillow;

package/install.py

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

package/src/analysis_dashboard.py

@@ -2378,6 +2378,51 @@ HTML = r"""<!doctype html>
       font-size: var(--text-xs);
       color: var(--text-muted);
     }
+    .ai-op-row {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      gap: var(--space-3);
+      grid-column: 1 / -1;
+      margin: var(--space-1) 0;
+    }
+    .ai-op-btn {
+      padding: 6px 14px;
+      border-radius: var(--radius-sm, 6px);
+      border: 1px solid var(--border, rgba(255,255,255,0.18));
+      background: var(--accent, #3b82f6);
+      color: #fff;
+      font-size: var(--text-sm, 13px);
+      cursor: pointer;
+    }
+    .ai-op-btn:hover { filter: brightness(1.08); }
+    .ai-op-btn:disabled { opacity: 0.4; cursor: not-allowed; filter: none; }
+    .ai-op-btn.ghost { background: transparent; color: var(--text, inherit); }
+    .ai-op-btn.danger { background: #b4452f; }
+    .ai-caps-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
+      gap: var(--space-2);
+      margin-top: var(--space-2);
+    }
+    .ai-caps-item {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      font-size: var(--text-xs);
+    }
+    .ai-caps-dot { width: 9px; height: 9px; border-radius: 50%; flex: 0 0 auto; }
+    .ai-caps-dot.on { background: #34a853; }
+    .ai-caps-dot.off { background: rgba(255,255,255,0.25); }
+    .ai-caps-extra { opacity: 0.6; }
+    .ai-console-result {
+      white-space: pre-wrap;
+      font-family: var(--mono, ui-monospace, monospace);
+      max-height: 240px;
+      overflow: auto;
+    }
+    .ai-console-result.ok { color: var(--text, inherit); }
+    .ai-console-result.err { color: #e06c5a; }
     .caps-section-subtitle {
       font-size: var(--text-xs);
       color: var(--text-muted);
@@ -3777,6 +3822,7 @@ HTML = r"""<!doctype html>
           <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>
         </div>
       </div>
+      <button class="control-tab" data-panel-target="aiconsole">AI Console</button>
       <div class="control-nav-item">
         <button class="control-tab has-menu" data-panel-target="diagnostics">Setup <span class="tab-chevron" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><path d="m6 9 6 6 6-6"></path></svg></span></button>
         <div class="nav-dropdown" role="menu" aria-label="Diagnostic pages">
@@ -4119,6 +4165,101 @@ HTML = r"""<!doctype html>
     </section>
   </main>
 
+  <main id="panel-aiconsole" class="panel control-grid">
+    <section class="span-12">
+      <div class="section-top">
+        <div>
+          <h2>Resolve 21 AI Console</h2>
+          <p class="section-sub">Run Resolve's local AI operations on the current Media Pool folder or a specific clip. These run on Resolve's GPU/AI engine — the analysis and slate ops are safe and reversible; <strong>motion-deblur</strong> and <strong>speech generation</strong> create new media files and ask for confirmation first. Source media is never modified. Every run is recorded in the <em>Resolve 21 AI ops</em> ledger (Preferences → Caps + Safety).</p>
+        </div>
+      </div>
+
+      <div id="aiConsoleCaps" class="caps-section" style="margin-top:12px;">
+        <div class="caps-section-hint">Checking which AI methods this Resolve build exposes…</div>
+      </div>
+
+      <div class="caps-section" style="margin-top:12px;">
+        <div class="caps-section-head"><div class="caps-section-title">Governance</div>
+          <div class="caps-section-hint">Soft per-session limits for the two media-creating ops (deblur, speech). Advisory only — you'll be warned in the confirm dialog, but never blocked (the ops are confirm-gated). Pick the tier that matches the job.</div></div>
+        <div id="aiGovTiers" class="caps-preset-cards" role="radiogroup" aria-label="AI governance tier"></div>
+        <div id="aiGovUsage" class="caps-usage-gauges" style="margin-top:10px;"></div>
+      </div>
+
+      <div class="caps-section" style="margin-top:12px;">
+        <div class="caps-section-head"><div class="caps-section-title">Target</div>
+          <div class="caps-section-hint">Folder ops run on the current Media Pool folder in Resolve. Choose <em>Specific clip</em> and paste a clip id (from <code>media_pool.get_clips</code>) to target one clip.</div></div>
+        <div class="settings-grid">
+          <label class="checkbox-row"><input type="radio" name="aiTarget" value="folder" checked><span>Current folder</span></label>
+          <label class="checkbox-row"><input type="radio" name="aiTarget" value="clip"><span>Specific clip</span></label>
+          <label>Clip id <input id="aiClipId" type="text" placeholder="(clip UniqueId)"></label>
+        </div>
+      </div>
+
+      <div class="caps-section" style="margin-top:12px;">
+        <div class="caps-section-head"><div class="caps-section-title">Analysis</div>
+          <div class="caps-section-hint">Safe, reversible. IntelliSearch and Slate require their AI Extras (Extras Download Manager).</div></div>
+        <div class="settings-grid">
+          <div class="ai-op-row"><button class="ai-op-btn" data-ai-op="perform_audio_classification">Classify audio</button>
+            <button class="ai-op-btn ghost" data-ai-op="clear_audio_classification">Clear classification</button></div>
+          <div class="ai-op-row">
+            <button class="ai-op-btn" data-ai-op="analyze_for_intellisearch">IntelliSearch</button>
+            <label class="checkbox-row"><input id="aiIdentifyFaces" type="checkbox"><span>Identify faces</span></label>
+            <label class="checkbox-row"><input id="aiBetterMode" type="checkbox"><span>Better mode</span></label>
+          </div>
+          <div class="ai-op-row">
+            <button class="ai-op-btn" data-ai-op="analyze_for_slate">Analyze for slate</button>
+            <label>Marker <select id="aiSlateColor"></select></label>
+          </div>
+          <div class="ai-op-row">
+            <button class="ai-op-btn" data-ai-op="transcribe_audio">Transcribe</button>
+            <label class="checkbox-row"><input id="aiSpeakerDetection" type="checkbox"><span>Speaker detection</span></label>
+            <button class="ai-op-btn ghost" data-ai-op="clear_transcription">Clear transcription</button>
+          </div>
+        </div>
+      </div>
+
+      <div class="caps-section" style="margin-top:12px;">
+        <div class="caps-section-head"><div class="caps-section-title">Motion deblur</div>
+          <div class="caps-section-hint">Renders new deblurred media. Creates files; asks for confirmation. Leave fields blank for Resolve defaults.</div></div>
+        <div class="settings-grid">
+          <label>Format <input id="aiDeblurFormat" type="text" placeholder="mov"></label>
+          <label>Codec <input id="aiDeblurCodec" type="text" placeholder="ProRes422"></label>
+          <label class="checkbox-row"><input id="aiDeblurExtreme" type="checkbox"><span>Extreme mode</span></label>
+          <label class="checkbox-row"><input id="aiDeblurMarkInOut" type="checkbox"><span>Use mark in/out</span></label>
+          <label class="checkbox-row"><input id="aiDeblurSourceRes" type="checkbox"><span>Render at source res</span></label>
+          <div class="ai-op-row"><button class="ai-op-btn danger" data-ai-op="remove_motion_blur">Remove motion blur</button></div>
+        </div>
+      </div>
+
+      <div class="caps-section" style="margin-top:12px;">
+        <div class="caps-section-head"><div class="caps-section-title">Speech generator</div>
+          <div class="caps-section-hint">AI text-to-speech. Requires the AI Speech Generator Extra. Creates a new audio item; asks for confirmation.</div></div>
+        <div class="settings-grid">
+          <label style="grid-column:1/-1;">Text <textarea id="aiSpeechText" rows="2" placeholder="Text to synthesize"></textarea></label>
+          <label>Voice model <input id="aiSpeechVoice" type="text" placeholder="Female 1"></label>
+          <label>Speed <input id="aiSpeechSpeed" type="number" placeholder="(default)"></label>
+          <label>Pitch <input id="aiSpeechPitch" type="number" placeholder="(default)"></label>
+          <label>Variation <input id="aiSpeechVariation" type="number" placeholder="(default)"></label>
+          <label class="checkbox-row"><input id="aiSpeechAddTimeline" type="checkbox"><span>Add to timeline</span></label>
+          <label>Timecode <input id="aiSpeechTimecode" type="text" placeholder="01:00:00:00"></label>
+          <label>Audio track <input id="aiSpeechTrack" type="number" placeholder="(default)"></label>
+          <div class="ai-op-row"><button class="ai-op-btn danger" data-ai-op="generate_speech">Generate speech</button></div>
+        </div>
+      </div>
+
+      <div class="caps-section" style="margin-top:12px;">
+        <div class="caps-section-head"><div class="caps-section-title">Session</div>
+          <div class="caps-section-hint">Quiet Resolve's background tasks for this session before heavy work. Resets on restart.</div></div>
+        <div class="ai-op-row"><button class="ai-op-btn ghost" data-ai-op="disable_background_tasks">Disable background tasks</button></div>
+      </div>
+
+      <div class="caps-section" style="margin-top:12px;">
+        <div class="caps-section-head"><div class="caps-section-title">Result</div></div>
+        <div id="aiConsoleResult" class="ai-console-result caps-section-hint">No op run yet.</div>
+      </div>
+    </section>
+  </main>
+
   <main id="panel-diagnostics" class="panel control-grid">
     <section class="span-12 subpage active" data-subpage-scope="diagnostics" data-subpage="resolve">
       <h2>Resolve</h2>
@@ -4712,6 +4853,7 @@ HTML = r"""<!doctype html>
     const PANEL_LABELS = {
       overview: 'Overview',
       analysis: 'Analysis',
+      aiconsole: 'AI Console',
       diagnostics: 'Setup',
       projects: 'Projects',
       docs: 'Docs',
@@ -4720,6 +4862,7 @@ HTML = r"""<!doctype html>
     const PANEL_ICONS = {
       overview: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="3" width="7" height="7"></rect><rect x="14" y="3" width="7" height="7"></rect><rect x="14" y="14" width="7" height="7"></rect><rect x="3" y="14" width="7" height="7"></rect></svg>',
       analysis: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 3v18h18"></path><path d="m19 9-5 5-4-4-3 3"></path></svg>',
+      aiconsole: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 8V4H8"></path><rect x="4" y="12" width="16" height="8" rx="2"></rect><path d="M2 14h2"></path><path d="M20 14h2"></path><path d="M15 13v2"></path><path d="M9 13v2"></path></svg>',
       diagnostics: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l2.1-2.1a6 6 0 0 1-7.6 7.6l-4 4a2.1 2.1 0 0 1-3-3l4-4a6 6 0 0 1 7.6-7.6z"></path></svg>',
       projects: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 7h5l2 3h11v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"></path><path d="M7 7V5a2 2 0 0 1 2-2h3l2 2h3a2 2 0 0 1 2 2v3"></path></svg>',
       docs: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 19.5A2.5 2.5 0 0 1 6.5 17H20"></path><path d="M4 4.5A2.5 2.5 0 0 1 6.5 2H20v20H6.5A2.5 2.5 0 0 1 4 19.5z"></path></svg>',
@@ -4882,6 +5025,9 @@ HTML = r"""<!doctype html>
         syncPreferencesPanel();
         refreshSetupDefaults().catch(alertError);
       }
+      if (next === 'aiconsole') {
+        initAiConsole();
+      }
       if (next === 'docs' && subpage) {
         loadDoc(subpage, { updateHash: false }).catch(alertError);
       }
@@ -7111,6 +7257,249 @@ HTML = r"""<!doctype html>
       tableEl.style.display = '';
     }
 
+    // ─── Resolve 21 AI Console ──────────────────────────────────────
+    const AI_MARKER_COLORS = ['Blue','Cyan','Green','Yellow','Red','Pink','Purple',
+      'Fuchsia','Rose','Lavender','Sky','Mint','Lemon','Sand','Cocoa','Cream'];
+    const AI_OP_LABELS = {
+      perform_audio_classification: 'Classify audio',
+      clear_audio_classification: 'Clear classification',
+      analyze_for_intellisearch: 'IntelliSearch',
+      analyze_for_slate: 'Analyze for slate',
+      transcribe_audio: 'Transcribe',
+      clear_transcription: 'Clear transcription',
+      remove_motion_blur: 'Remove motion blur',
+      generate_speech: 'Generate speech',
+      disable_background_tasks: 'Disable background tasks',
+    };
+    // Which features gate which buttons (key in resolve.ai_features.features).
+    const AI_OP_FEATURE = {
+      perform_audio_classification: 'perform_audio_classification',
+      clear_audio_classification: 'clear_audio_classification',
+      analyze_for_intellisearch: 'analyze_for_intellisearch',
+      analyze_for_slate: 'analyze_for_slate',
+      remove_motion_blur: 'remove_motion_blur',
+      generate_speech: 'generate_speech',
+      disable_background_tasks: 'disable_background_tasks',
+    };
+    let _aiConsoleInit = false;
+
+    function renderAiConsole() {
+      const feats = (state.boot?.resolve?.ai_features) || {};
+      const features = feats.features || {};
+      const requiresExtra = feats.requires_extra || {};
+      const capsEl = $('aiConsoleCaps');
+      if (capsEl) {
+        if (state.boot?.resolve?.available !== true) {
+          capsEl.innerHTML = '<div class="caps-section-hint">Resolve is not connected. Open a project in DaVinci Resolve, then reload.</div>';
+        } else {
+          const items = Object.keys(AI_OP_LABELS)
+            .filter(op => op in AI_OP_FEATURE)
+            .map(op => {
+              const key = AI_OP_FEATURE[op];
+              const on = !!features[key];
+              const extra = requiresExtra[key];
+              return `<div class="ai-caps-item"><span class="ai-caps-dot ${on ? 'on' : 'off'}"></span>`
+                + `<span>${escapeHtml(AI_OP_LABELS[op])}</span>`
+                + (extra ? `<span class="ai-caps-extra">· needs ${escapeHtml(extra)}</span>` : '')
+                + `</div>`;
+            }).join('');
+          capsEl.innerHTML = `<div class="caps-section-head"><div class="caps-section-title">Available on this Resolve build</div>`
+            + `<div class="caps-section-hint">A grey dot means the method is absent (older Resolve). "needs …" means the method is present but requires that Extra to actually run — install via Extras Download Manager.</div></div>`
+            + `<div class="ai-caps-grid">${items}</div>`;
+        }
+      }
+      // Slate color dropdown (once).
+      const sel = $('aiSlateColor');
+      if (sel && !sel.options.length) {
+        sel.innerHTML = AI_MARKER_COLORS.map(c => `<option value="${c}">${c}</option>`).join('');
+      }
+    }
+
+    function aiTarget() {
+      const checked = document.querySelector('input[name="aiTarget"]:checked');
+      return checked ? checked.value : 'folder';
+    }
+
+    function aiBuildParams(op) {
+      const params = {};
+      if (op === 'analyze_for_intellisearch') {
+        params.identify_faces = !!$('aiIdentifyFaces')?.checked;
+        params.is_better_mode = !!$('aiBetterMode')?.checked;
+      } else if (op === 'analyze_for_slate') {
+        params.marker_color = $('aiSlateColor')?.value || 'Blue';
+      } else if (op === 'transcribe_audio') {
+        if ($('aiSpeakerDetection')?.checked) params.use_speaker_detection = true;
+      } else if (op === 'remove_motion_blur') {
+        const d = {};
+        const fmt = ($('aiDeblurFormat')?.value || '').trim(); if (fmt) d.Format = fmt;
+        const codec = ($('aiDeblurCodec')?.value || '').trim(); if (codec) d.Codec = codec;
+        if ($('aiDeblurExtreme')?.checked) d.UseExtremeMode = true;
+        if ($('aiDeblurMarkInOut')?.checked) d.UseMarkInMarkOut = true;
+        if ($('aiDeblurSourceRes')?.checked) d.RenderAtSourceRes = true;
+        params.deblur_option = d;
+      } else if (op === 'generate_speech') {
+        const text = ($('aiSpeechText')?.value || '').trim();
+        const settings = { TextInput: text };
+        const voice = ($('aiSpeechVoice')?.value || '').trim(); if (voice) settings.VoiceModel = voice;
+        const num = (id) => { const v = ($(id)?.value || '').trim(); return v === '' ? null : Number(v); };
+        const speed = num('aiSpeechSpeed'); if (speed != null) settings.Speed = speed;
+        const pitch = num('aiSpeechPitch'); if (pitch != null) settings.Pitch = pitch;
+        const variation = num('aiSpeechVariation'); if (variation != null) settings.Variation = variation;
+        if ($('aiSpeechAddTimeline')?.checked) {
+          settings.AddToTimeline = true;
+          const track = num('aiSpeechTrack'); if (track != null) settings.AudioTrack = track;
+        }
+        params.speech_generation_settings = settings;
+        const tc = ($('aiSpeechTimecode')?.value || '').trim(); if (tc) params.timecode = tc;
+      }
+      return params;
+    }
+
+    function aiShowResult(op, payload, isErr) {
+      const el = $('aiConsoleResult');
+      if (!el) return;
+      el.classList.toggle('err', !!isErr);
+      el.classList.toggle('ok', !isErr);
+      const head = `${AI_OP_LABELS[op] || op} — ${new Date().toLocaleTimeString()}\n`;
+      el.textContent = head + JSON.stringify(payload, null, 2);
+    }
+
+    async function runAiOp(op) {
+      const target = (op === 'generate_speech' || op === 'disable_background_tasks') ? 'folder' : aiTarget();
+      const params = aiBuildParams(op);
+      if (target === 'clip') {
+        const clipId = ($('aiClipId')?.value || '').trim();
+        if (!clipId) { aiShowResult(op, { error: 'Enter a clip id, or switch target to Current folder.' }, true); return; }
+        params.clip_id = clipId;
+      }
+      if (op === 'generate_speech' && !params.speech_generation_settings?.TextInput) {
+        aiShowResult(op, { error: 'Enter text to synthesize.' }, true); return;
+      }
+      const buttons = document.querySelectorAll('.ai-op-btn');
+      buttons.forEach(b => { b.disabled = true; });
+      try {
+        let res = await api('/api/resolve_ai/run', {
+          method: 'POST', body: JSON.stringify({ op, target, params }),
+        }).catch(err => ({ success: false, error: String(err && err.message || err) }));
+        // Confirm-token two-step for the media-creating ops.
+        if (res && res.status === 'confirmation_required') {
+          const preview = res.preview || {};
+          const gov = preview.governance || {};
+          const govWarn = (gov.applies && (gov.warnings || []).length)
+            ? '\n\nGovernance (' + (gov.tier || '') + '):\n• ' + gov.warnings.join('\n• ')
+            : '';
+          const proceed = await brandedConfirm({
+            kicker: gov.exceeded ? 'Over governance limit' : 'Creates new media',
+            title: AI_OP_LABELS[op] || op,
+            body: (preview.warning || 'This operation creates new media. Proceed?') + govWarn,
+            detail: JSON.stringify(preview, null, 2),
+            confirmLabel: 'Run it',
+            tone: 'danger',
+          });
+          if (!proceed) { aiShowResult(op, { cancelled: true }, false); return; }
+          const params2 = { ...params, confirm_token: res.confirm_token };
+          res = await api('/api/resolve_ai/run', {
+            method: 'POST', body: JSON.stringify({ op, target, params: params2 }),
+          }).catch(err => ({ success: false, error: String(err && err.message || err) }));
+        }
+        aiShowResult(op, res, !(res && res.success));
+        // Refresh the ledger + governance widgets so totals stay current.
+        refreshResolveAiOps().catch(() => {});
+        refreshGovernance().catch(() => {});
+      } finally {
+        buttons.forEach(b => { b.disabled = false; });
+      }
+    }
+
+    // ─── Governance tier selector + consumption ─────────────────────
+    const AI_GOV_TIER_ORDER = ['off', 'lenient', 'standard', 'strict'];
+    const AI_GOV_TIER_TAGS = {
+      off: 'No limits',
+      lenient: 'Big jobs',
+      standard: 'Sensible default',
+      strict: 'Tight leash',
+    };
+    state.aiGov = state.aiGov || { tier: 'standard', thresholds: {}, usage: {} };
+
+    function aiGovFmt(dim, v) {
+      if (v == null) return '∞';
+      if (dim === 'render_bytes') return fmtBytes(v);
+      if (dim === 'render_wall_clock_ms') return fmtMs(v);
+      return String(v);
+    }
+    function renderGovTiers() {
+      const el = $('aiGovTiers');
+      if (!el) return;
+      const tiers = state.aiGov.tiersAvailable || {};
+      const active = state.aiGov.tier || 'standard';
+      el.innerHTML = AI_GOV_TIER_ORDER.filter(k => tiers[k]).map(key => {
+        const t = tiers[key];
+        const stats = [['deblur_runs','Deblur runs'],['speech_runs','Speech runs'],
+          ['render_bytes','Media'],['render_wall_clock_ms','Render time']].map(([d,label]) =>
+          `<span class="stat-label">${escapeHtml(label)}</span><span class="stat-value">${escapeHtml(aiGovFmt(d, t[d]))}</span>`).join('');
+        return `<button type="button" class="caps-preset-card${key === active ? ' is-active' : ''}" data-gov-tier="${escapeHtml(key)}" role="radio" aria-checked="${key === active}">
+          <div class="caps-preset-card-head"><span class="caps-preset-card-name">${escapeHtml(key)}</span>${key === active ? '<span class="caps-preset-card-badge">Active</span>' : ''}</div>
+          <div class="caps-preset-card-tag">${escapeHtml(AI_GOV_TIER_TAGS[key] || '')}</div>
+          <div class="caps-preset-card-stats">${stats}</div>
+        </button>`;
+      }).join('');
+    }
+    function renderGovUsage() {
+      const el = $('aiGovUsage');
+      if (!el) return;
+      const usage = state.aiGov.usage || {};
+      const th = state.aiGov.thresholds || {};
+      const dims = [['deblur_runs','Deblur runs'],['speech_runs','Speech runs'],
+        ['render_bytes','Media created'],['render_wall_clock_ms','Render time']];
+      el.innerHTML = dims.map(([d,label]) => {
+        const used = usage[d] || 0;
+        const cap = th[d];
+        const pct = (cap == null || cap === 0) ? 0 : Math.min(100, Math.round((used / cap) * 100));
+        const tone = pct >= 100 ? '#e06c5a' : (pct >= 80 ? '#e0a83a' : '#34a853');
+        return `<div class="caps-gauge">
+          <div class="caps-gauge-top"><span class="caps-gauge-label">${escapeHtml(label)}</span>
+            <span class="caps-gauge-numbers">${escapeHtml(aiGovFmt(d, used))}${cap == null ? '' : ' / ' + escapeHtml(aiGovFmt(d, cap))}</span></div>
+          <div class="caps-gauge-bar"><span class="caps-gauge-fill" style="width:${pct}%; background:${tone};"></span></div>
+        </div>`;
+      }).join('');
+    }
+    async function refreshGovernance() {
+      const data = await api('/api/resolve_ai/governance').catch(() => ({ success: false }));
+      if (!data || !data.success) return;
+      state.aiGov.tier = data.tier;
+      state.aiGov.thresholds = data.thresholds || {};
+      state.aiGov.usage = data.usage || {};
+      state.aiGov.tiersAvailable = data.tiers_available || {};
+      renderGovTiers();
+      renderGovUsage();
+    }
+    async function setGovernanceTier(tier) {
+      state.aiGov.tier = tier;
+      renderGovTiers();
+      const res = await api('/api/resolve_ai/governance', {
+        method: 'POST', body: JSON.stringify({ preset: tier }),
+      }).catch(err => ({ success: false, error: String(err) }));
+      if (!res || !res.success) console.warn('governance save failed:', res && res.error);
+      await refreshGovernance();
+    }
+
+    function initAiConsole() {
+      if (_aiConsoleInit) { renderAiConsole(); refreshGovernance().catch(() => {}); return; }
+      _aiConsoleInit = true;
+      renderAiConsole();
+      document.querySelectorAll('#panel-aiconsole .ai-op-btn').forEach(btn => {
+        btn.addEventListener('click', () => runAiOp(btn.dataset.aiOp));
+      });
+      const govEl = $('aiGovTiers');
+      if (govEl) {
+        govEl.addEventListener('click', (ev) => {
+          const card = ev.target.closest('[data-gov-tier]');
+          if (card && card.dataset.govTier) setGovernanceTier(card.dataset.govTier);
+        });
+      }
+      refreshGovernance().catch(() => {});
+    }
+
     // ─── Caps inspector + refusals + reset ──────────────────────────
     async function inspectCapsFromUI() {
       const clipId = ($('capsInspectClipId')?.value || '').trim();
@@ -10783,6 +11172,58 @@ def _resolve_identity() -> Dict[str, Any]:
     }
 
 
+# ── Resolve 21 AI Console: op dispatch ──────────────────────────────────────
+# Folder/clip-level ops are routed to the consolidated `folder` /
+# `media_pool_item` tools; project/resolve-level ops to their tools. The
+# consolidated tools own the confirm-token gate for the two media-creators, so
+# this dispatcher just relays params (incl. confirm_token) and the result.
+
+_AI_CONSOLE_FOLDER_OPS = frozenset({
+    "perform_audio_classification", "clear_audio_classification",
+    "analyze_for_intellisearch", "analyze_for_slate", "remove_motion_blur",
+    "transcribe_audio", "clear_transcription",
+})
+
+
+def _run_resolve_ai_op(body: Dict[str, Any]) -> Dict[str, Any]:
+    """Dispatch one AI Console op to the right consolidated server tool.
+
+    body = {op, target?, params?}. target is 'folder' (current Media Pool
+    folder, default) or 'clip' (params.clip_id required). Returns the tool's
+    response verbatim — including a {status:'confirmation_required', confirm_token,
+    preview} shape for the gated media-creating ops.
+    """
+    op = (body.get("op") or "").strip()
+    target = (body.get("target") or "folder").strip()
+    params = dict(body.get("params") or {})
+    if not op:
+        return {"success": False, "error": "op is required"}
+    try:
+        from src.server import (
+            folder as _folder_tool,
+            media_pool_item as _mpi_tool,
+            project_settings as _ps_tool,
+            resolve_control as _rc_tool,
+        )
+    except Exception as exc:  # pragma: no cover - import guard
+        return {"success": False, "error": f"server tools unavailable: {exc}"}
+
+    if op == "disable_background_tasks":
+        return _rc_tool("disable_background_tasks_for_current_session", {})
+    if op == "generate_speech":
+        return _ps_tool("generate_speech", params)
+    if op not in _AI_CONSOLE_FOLDER_OPS:
+        return {"success": False, "error": f"unknown op {op!r}"}
+    if target == "clip":
+        clip_id = params.get("clip_id") or body.get("clip_id")
+        if not clip_id:
+            return {"success": False, "error": "clip target requires a clip_id"}
+        params["clip_id"] = clip_id
+        return _mpi_tool(op, params)
+    # default: operate on the current Media Pool folder
+    return _folder_tool(op, params)
+
+
 def _clip_props(clip: Any) -> Dict[str, Any]:
     props, _ = _safe_call(clip, "GetClipProperty", "")
     return props if isinstance(props, dict) else {}
@@ -13699,6 +14140,16 @@ class Handler(BaseHTTPRequestHandler):
             except Exception as exc:
                 self._json({"success": False, "error": f"{type(exc).__name__}: {exc}"})
             return
+        if path == "/api/resolve_ai/governance":
+            # Effective governance tier + this project's render usage. Proxies
+            # into the media_analysis get_ai_governance action.
+            try:
+                from src.server import media_analysis as _ma_tool
+                import asyncio
+                self._json(asyncio.run(_ma_tool("get_ai_governance", params={})))
+            except Exception as exc:
+                self._json({"success": False, "error": f"{type(exc).__name__}: {exc}"})
+            return
         if path.startswith("/api/timeline_thumbnail/"):
             rel = unquote(path[len("/api/timeline_thumbnail/"):])
             # Path is <slug>/<vNN.png>; constrain it to live under _soul/timeline_versions
@@ -13953,6 +14404,33 @@ class Handler(BaseHTTPRequestHandler):
             except Exception as exc:
                 self._json({"success": False, "error": f"{type(exc).__name__}: {exc}"})
             return
+        if path == "/api/resolve_ai/run":
+            # Run a Resolve 21 AI op from the panel. Loopback-only because it
+            # mutates Resolve (and the media-creators write new files). The
+            # confirm-token two-step is handled by the consolidated tool; the
+            # 'confirmation_required' shape is relayed to the panel as 200.
+            if not _request_is_loopback(self):
+                self._json({"success": False, "error": "Loopback only."}, HTTPStatus.FORBIDDEN)
+                return
+            try:
+                result = _run_resolve_ai_op(body)
+                ok = bool(result.get("success")) or result.get("status") == "confirmation_required"
+                self._json(result, 200 if ok else 400)
+            except Exception as exc:
+                self._json({"success": False, "error": f"{type(exc).__name__}: {exc}"})
+            return
+        if path == "/api/resolve_ai/governance":
+            if not _request_is_loopback(self):
+                self._json({"success": False, "error": "Loopback only."}, HTTPStatus.FORBIDDEN)
+                return
+            try:
+                from src.server import media_analysis as _ma_tool
+                import asyncio
+                result = asyncio.run(_ma_tool("set_ai_governance", params=body))
+                self._json(result, 200 if result.get("success") else 400)
+            except Exception as exc:
+                self._json({"success": False, "error": f"{type(exc).__name__}: {exc}"})
+            return
         if path == "/api/caps/reset_day":
             if not _request_is_loopback(self):
                 self._json({"success": False, "error": "Loopback only."}, HTTPStatus.FORBIDDEN)

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.30.0"
+VERSION = "2.32.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.30.0"
+VERSION = "2.32.0"
 
 import base64
 import os
@@ -675,6 +675,37 @@ def _ai_ledger_timed(op: str, *, clip_id: Optional[str] = None):
     )
 
 
+# ─── Resolve 21 AI-ops governance (soft tiers over the ledger) ────────────────
+
+from src.utils import resolve_ai_governance as _resolve_ai_governance
+
+
+def _ai_governance_preset() -> Optional[str]:
+    try:
+        return _read_media_analysis_preferences().get("resolve_ai_governance_preset")
+    except Exception:
+        return None
+
+
+def _ai_governance_overrides() -> Optional[Dict[str, Any]]:
+    try:
+        raw = _read_media_analysis_preferences().get("resolve_ai_governance_overrides") or {}
+        return raw if isinstance(raw, dict) else None
+    except Exception:
+        return None
+
+
+def _ai_governance_check(op: str) -> Dict[str, Any]:
+    """Advisory governance status for the next run of `op` (best-effort)."""
+    try:
+        return _resolve_ai_governance.check(
+            project_root=_ai_ledger_root(), session_id=_AI_LEDGER_SESSION_ID, op=op,
+            preset=_ai_governance_preset(), overrides=_ai_governance_overrides(),
+        )
+    except Exception:
+        return {"applies": False}
+
+
 def _destructive_preference_provider(key: str) -> Any:
     """Reader for C6 preferences out of the existing media-analysis prefs file."""
     try:
@@ -6459,6 +6490,11 @@ _MEDIA_ANALYSIS_DEFAULT_PREFS = {
     # vision_tokens_per_job, vision_tokens_per_day, wall_clock_seconds_per_call,
     # max_frame_dim_pixels). Pass an integer or "unlimited" to lift that cap.
     "analysis_caps_overrides": {},
+    # Soft governance tier for the media-creating Resolve 21 AI ops (deblur /
+    # speech): off | lenient | standard | strict. Advisory only — surfaced in the
+    # confirm preview + panel; never hard-blocks (the ops are confirm-gated).
+    "resolve_ai_governance_preset": "standard",
+    "resolve_ai_governance_overrides": {},
 }
 
 
@@ -12458,6 +12494,7 @@ def project_settings(action: str, params: Optional[Dict[str, Any]] = None) -> Di
                     "voice_model": settings.get("VoiceModel"),
                     "add_to_timeline": bool(settings.get("AddToTimeline")),
                     "timecode": timecode,
+                    "governance": _ai_governance_check("generate_speech"),
                 },
             )
         blocked = _consume_confirm_token(action="project_settings.generate_speech", params=p)
@@ -13504,6 +13541,7 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
                     "warning": "Renders NEW deblurred media files for clips in the folder; source media is not modified.",
                     "folder": f.GetName(),
                     "deblur_option": deblur,
+                    "governance": _ai_governance_check("remove_motion_blur"),
                 },
             )
         blocked = _consume_confirm_token(action="folder.remove_motion_blur", params=p)
@@ -13814,6 +13852,7 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
                     "warning": "Renders a NEW deblurred media file; the source clip is not modified.",
                     "clip": clip.GetName(),
                     "deblur_option": deblur,
+                    "governance": _ai_governance_check("remove_motion_blur"),
                 },
             )
         blocked = _consume_confirm_token(action="media_pool_item.remove_motion_blur", params=p)
@@ -13979,6 +14018,8 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
       set_caps_preset(preset, overrides?) -> {success, preset, overrides} — preset is minimal | standard | generous | unlimited. Overrides is a dict of {field: int|"unlimited"} that wins over the preset.
       get_usage(scope?, scope_key?, clip_id?, job_id?) -> {scope, usage} — raw usage rollup for one scope (clip | job | day).
       get_resolve_ai_usage(session_only?, op?, limit?) -> {summary, recent} — ledger of Resolve 21 local AI ops (audio classification, IntelliSearch, slate, motion-deblur, speech). Tracks invocations, wall-clock, and files/bytes created by the two media-creating ops. Separate from get_caps/get_usage (those meter Claude-side tokens; these ops don't spend them).
+      get_ai_governance() -> {tier, thresholds, usage, tiers_available} — soft governance tier (off|lenient|standard|strict) for the media-creating AI ops vs this session's render usage. Advisory; surfaced in the confirm preview + panel, never blocks.
+      set_ai_governance(preset, overrides?) -> {success, tier, overrides} — set the governance tier. Overrides keys: deblur_runs, speech_runs, render_bytes, render_wall_clock_ms (int or "unlimited").
       resolve_output_root(analysis_root?, source_paths?) -> {project_root}
       plan(target, depth?, analysis_root?, transcription?, vision?, dry_run?) -> {clips, artifacts}
       analyze_file(path|file_path, dry_run?, session_only?, persist?) -> {clips, manifest}
@@ -14152,6 +14193,31 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
             }
         except Exception as exc:
             return _err(f"{type(exc).__name__}: {exc}")
+    if action == "get_ai_governance":
+        # Soft-tier governance for the media-creating AI ops (deblur / speech).
+        # Advisory only — reports this session's render usage vs the active tier.
+        try:
+            project_root = _ai_ledger_root()
+            st = _resolve_ai_governance.status(
+                project_root=project_root, session_id=_AI_LEDGER_SESSION_ID,
+                preset=_ai_governance_preset(), overrides=_ai_governance_overrides(),
+            )
+            return {"success": True, "session_id": _AI_LEDGER_SESSION_ID, **st}
+        except Exception as exc:
+            return _err(f"{type(exc).__name__}: {exc}")
+    if action == "set_ai_governance":
+        preset = (p.get("preset") or "").strip().lower()
+        if preset not in _resolve_ai_governance.VALID_TIERS:
+            return _err(f"unknown tier '{preset}'. Valid: {sorted(_resolve_ai_governance.VALID_TIERS)}")
+        prefs = _read_media_analysis_preferences()
+        prefs["resolve_ai_governance_preset"] = preset
+        if isinstance(p.get("overrides"), dict):
+            prefs["resolve_ai_governance_overrides"] = p["overrides"]
+        path = _media_analysis_preferences_path()
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w", encoding="utf-8") as fh:
+            json.dump(prefs, fh, indent=2)
+        return {"success": True, "tier": preset, "overrides": prefs.get("resolve_ai_governance_overrides") or {}}
     if action == "set_caps_preset":
         preset = (p.get("preset") or "").strip().lower()
         from src.utils import analysis_caps as _ac

package/src/utils/resolve_ai_governance.py

@@ -0,0 +1,214 @@
+"""Soft governance tiers for the Resolve 21 media-creating AI ops.
+
+The two media-creating ops (`remove_motion_blur`, `generate_speech`) render new
+files on Resolve's GPU/AI engine. They are already confirm-token gated, so
+governance here is intentionally **advisory**: it reads the AI-ops ledger for the
+current session and reports how the *next* run sits against a named tier's soft
+thresholds. The result is surfaced in the confirm preview and the control panel —
+it never hard-blocks (the analysis-caps layer meters Claude tokens; this is a
+different, local concern).
+
+Tiers (per session):
+
+| dimension                 | off  | lenient | standard | strict |
+|---------------------------|-----:|--------:|---------:|-------:|
+| deblur_runs               | None | 50      | 15       | 5      |
+| speech_runs               | None | 50      | 15       | 5      |
+| render_bytes (new media)  | None | 50 GB   | 10 GB    | 2 GB   |
+| render_wall_clock_ms       | None | 1 h     | 20 min   | 5 min  |
+
+`standard` is the default. Only the render ops are governed; analysis ops
+(classify / IntelliSearch / slate / transcribe) are always within-tier.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from src.utils import resolve_ai_ledger
+
+logger = logging.getLogger("resolve-mcp.resolve-ai-governance")
+
+TIER_OFF = "off"
+TIER_LENIENT = "lenient"
+TIER_STANDARD = "standard"
+TIER_STRICT = "strict"
+DEFAULT_TIER = TIER_STANDARD
+
+_GB = 1024 ** 3
+
+# dimension -> value (None = uncapped)
+TIERS: Dict[str, Dict[str, Optional[int]]] = {
+    TIER_OFF: {
+        "deblur_runs": None, "speech_runs": None,
+        "render_bytes": None, "render_wall_clock_ms": None,
+    },
+    TIER_LENIENT: {
+        "deblur_runs": 50, "speech_runs": 50,
+        "render_bytes": 50 * _GB, "render_wall_clock_ms": 60 * 60 * 1000,
+    },
+    TIER_STANDARD: {
+        "deblur_runs": 15, "speech_runs": 15,
+        "render_bytes": 10 * _GB, "render_wall_clock_ms": 20 * 60 * 1000,
+    },
+    TIER_STRICT: {
+        "deblur_runs": 5, "speech_runs": 5,
+        "render_bytes": 2 * _GB, "render_wall_clock_ms": 5 * 60 * 1000,
+    },
+}
+
+VALID_TIERS = frozenset(TIERS)
+
+_OVERRIDE_KEYS = frozenset({"deblur_runs", "speech_runs", "render_bytes", "render_wall_clock_ms"})
+
+# Which ledger op feeds which run-count dimension.
+_OP_RUN_DIM = {
+    "remove_motion_blur": "deblur_runs",
+    "generate_speech": "speech_runs",
+}
+
+GOVERNED_OPS = frozenset(_OP_RUN_DIM)
+
+
+def list_tiers() -> Dict[str, Dict[str, Optional[int]]]:
+    return {name: dict(vals) for name, vals in TIERS.items()}
+
+
+def resolve_tier(preset: Optional[str] = None, overrides: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """Return the effective thresholds dict for `preset` with `overrides` applied.
+
+    An override value of None / "unlimited" means uncapped on that dimension.
+    """
+    name = (preset or DEFAULT_TIER).strip().lower()
+    if name not in TIERS:
+        name = DEFAULT_TIER
+    effective = dict(TIERS[name])
+    if isinstance(overrides, dict):
+        for key, val in overrides.items():
+            if key not in _OVERRIDE_KEYS:
+                continue
+            if val is None or (isinstance(val, str) and val.strip().lower() == "unlimited"):
+                effective[key] = None
+            else:
+                try:
+                    effective[key] = int(val)
+                except (TypeError, ValueError):
+                    continue
+    return {"preset": name, "thresholds": effective}
+
+
+def _render_usage(project_root: str, session_id: Optional[str]) -> Dict[str, int]:
+    """Aggregate this session's render-op usage from the ledger."""
+    summary = resolve_ai_ledger.get_summary(project_root=project_root, session_id=session_id)
+    by_op = summary.get("by_op", {})
+    deblur = by_op.get("remove_motion_blur", {})
+    speech = by_op.get("generate_speech", {})
+    render_bytes = (deblur.get("bytes_created", 0) or 0) + (speech.get("bytes_created", 0) or 0)
+    render_ms = (deblur.get("wall_clock_ms", 0) or 0) + (speech.get("wall_clock_ms", 0) or 0)
+    return {
+        "deblur_runs": deblur.get("runs", 0) or 0,
+        "speech_runs": speech.get("runs", 0) or 0,
+        "render_bytes": render_bytes,
+        "render_wall_clock_ms": render_ms,
+    }
+
+
+def check(
+    *,
+    project_root: Optional[str],
+    session_id: Optional[str],
+    op: str,
+    preset: Optional[str] = None,
+    overrides: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """Advisory governance status for the NEXT run of `op`.
+
+    Returns {applies, exceeded, near, tier, thresholds, usage, projected, warnings}.
+    `applies` is False for non-render ops (no governance) or missing project_root.
+    `exceeded` is True if the projected run-count is over the tier's run cap, or a
+    cumulative dimension (bytes/time) is already over. `near` is True at >=80%.
+    Never blocks — purely informational.
+    """
+    resolved = resolve_tier(preset, overrides)
+    base = {
+        "applies": False,
+        "exceeded": False,
+        "near": False,
+        "tier": resolved["preset"],
+        "thresholds": resolved["thresholds"],
+        "usage": {},
+        "projected": {},
+        "warnings": [],
+    }
+    if op not in GOVERNED_OPS or not project_root:
+        return base
+    thresholds = resolved["thresholds"]
+    usage = _render_usage(project_root, session_id)
+    run_dim = _OP_RUN_DIM[op]
+    projected = dict(usage)
+    projected[run_dim] = usage[run_dim] + 1  # this run adds one
+
+    warnings: List[str] = []
+    exceeded = False
+    near = False
+
+    def _assess(dim: str, value: int, label: str, fmt) -> None:
+        nonlocal exceeded, near
+        cap = thresholds.get(dim)
+        if cap is None:
+            return
+        if value > cap:
+            exceeded = True
+            warnings.append(f"{label}: {fmt(value)} exceeds the {resolved['preset']} limit of {fmt(cap)}.")
+        elif value >= cap * 0.8:
+            near = True
+            warnings.append(f"{label}: {fmt(value)} is approaching the {resolved['preset']} limit of {fmt(cap)}.")
+
+    def _fmt_bytes(n: int) -> str:
+        if not n:
+            return "0 B"
+        units = ["B", "KB", "MB", "GB", "TB"]
+        v = float(n)
+        i = 0
+        while v >= 1024 and i < len(units) - 1:
+            v /= 1024
+            i += 1
+        return f"{v:.1f} {units[i]}"
+
+    def _fmt_min(ms: int) -> str:
+        return f"{ms / 60000:.1f} min"
+
+    _assess(run_dim, projected[run_dim], "Runs this session", str)
+    _assess("render_bytes", usage["render_bytes"], "Media created this session", _fmt_bytes)
+    _assess("render_wall_clock_ms", usage["render_wall_clock_ms"], "Render time this session", _fmt_min)
+
+    base.update({
+        "applies": True,
+        "exceeded": exceeded,
+        "near": near,
+        "usage": usage,
+        "projected": projected,
+        "warnings": warnings,
+    })
+    return base
+
+
+def status(
+    *,
+    project_root: Optional[str],
+    session_id: Optional[str],
+    preset: Optional[str] = None,
+    overrides: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """Current session render usage vs the effective tier (for the panel/MCP)."""
+    resolved = resolve_tier(preset, overrides)
+    usage = _render_usage(project_root, session_id) if project_root else {
+        "deblur_runs": 0, "speech_runs": 0, "render_bytes": 0, "render_wall_clock_ms": 0,
+    }
+    return {
+        "tier": resolved["preset"],
+        "thresholds": resolved["thresholds"],
+        "usage": usage,
+        "tiers_available": list_tiers(),
+    }