davinci-resolve-mcp 2.31.0 → 2.32.1

package/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 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.1
+
+Fixes `fusion_comp(action="add_keyframe")` so it actually **animates** the input.
+
+Previously the handler did `inp[time] = value` on the input directly. On an input
+with no animation spline, that only assigns a **static** value (last write wins) —
+no keyframe is created. Symptoms: `get_keyframes` returned `[]`, `get_input` at
+different times returned the same value, and the clip never animated.
+
+The handler now attaches a `BezierSpline` modifier the first time an input is
+animated, then sets the keyframe. A new optional `modifier` param lets callers
+pass e.g. `"Path"` for Point inputs such as `Center`. Behavior is unchanged for
+inputs that are already animated or otherwise connected.
+
+- **Fixed** `add_keyframe` now creates real, editable keyframes (live-validated on
+  DaVinci Resolve Studio 21.0.0).
+- **Added** optional `modifier` param to `add_keyframe`.
+- Thanks to @sandypoli-boop for the diagnosis and fix ([#56](https://github.com/samuelgursky/davinci-resolve-mcp/pull/56)).
+
+## 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

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.31.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.32.1-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.31.0"
+VERSION = "2.32.1"
 # 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.31.0",
+  "version": "2.32.1",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/analysis_dashboard.py

@@ -4178,6 +4178,13 @@ HTML = r"""<!doctype html>
         <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>
@@ -7377,10 +7384,14 @@ HTML = r"""<!doctype html>
         // 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: 'Creates new media',
+            kicker: gov.exceeded ? 'Over governance limit' : 'Creates new media',
             title: AI_OP_LABELS[op] || op,
-            body: preview.warning || 'This operation creates new media. Proceed?',
+            body: (preview.warning || 'This operation creates new media. Proceed?') + govWarn,
             detail: JSON.stringify(preview, null, 2),
             confirmLabel: 'Run it',
             tone: 'danger',
@@ -7392,20 +7403,101 @@ HTML = r"""<!doctype html>
           }).catch(err => ({ success: false, error: String(err && err.message || err) }));
         }
         aiShowResult(op, res, !(res && res.success));
-        // Refresh the ledger widget so creators' file/byte totals update.
+        // 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(); return; }
+      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 ──────────────────────────
@@ -14048,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
@@ -14317,6 +14419,18 @@ class Handler(BaseHTTPRequestHandler):
             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.31.0"
+VERSION = "2.32.1"
 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.31.0"
+VERSION = "2.32.1"
 
 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
@@ -18597,7 +18663,17 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
             inp = tool[p["input_name"]]
             if not inp:
                 return _err(f"Input '{p['input_name']}' not found on tool '{p['tool_name']}'")
-            inp[p["time"]] = p["value"]
+            # Attach a BezierSpline modifier the first time this input is animated.
+            # Without a spline, `inp[time] = value` only sets a STATIC value (the last
+            # write wins) and never creates a keyframe. See the Fusion Scripting Guide.
+            # Optional `modifier` lets callers pass e.g. "Path" for Point inputs.
+            try:
+                _already_animated = inp.GetConnectedOutput() is not None
+            except Exception:
+                _already_animated = False
+            if not _already_animated:
+                tool.AddModifier(p["input_name"], p.get("modifier", "BezierSpline"))
+            tool[p["input_name"]][p["time"]] = p["value"]
             return _ok()
         finally:
             comp.Unlock()

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(),
+    }