davinci-resolve-mcp 2.41.0 → 2.42.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 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.42.0
+
+Deep shot-level vision tier — Phase B of the analysis + edit-engine program.
+Opt-in, estimate-first per-shot field filling for the Visual / Content /
+Production / Editorial / Cuttability groups the shot pages already render.
+
+- **Added** `src/utils/deep_vision.py` and three `media_analysis` actions:
+  `deepen` (estimate → confirm_token → deferred host-vision payload per
+  clip/shot), `commit_shot_vision` (writes `vision_deep_v1` provenance rows,
+  updates the canonical blob, re-exports analysis.json in lockstep), and
+  `vision_pending_sweep` (lists clips stuck in `pending_host_analysis`;
+  `reoffer=true` returns the stored payload, `expire=true` stamps them).
+- **Added** deep depth to the analyze flow: `depth="deep"` extends the
+  deferred payload with the per-shot schema and requires `confirm_deep=true`
+  after a token-cost estimate. Caps pre-call refusal applies on both paths.
+- **Added** panel affordances: `Deepen analysis` (clip view) and `Deepen this
+  shot` (shot view) copy ready-made chat prompts, per the chat-first UX.
+  Shots with no sampled frames on disk get 1–2 frames re-extracted via
+  ffmpeg, downscaled per caps (source media stays read-only).
+- **Fixed** a provenance bug in the analysis store: a source re-deriving an
+  unchanged value no longer re-attributes the row (a deep pass would
+  otherwise claim every untouched field as `vision_deep_v1`).
+- **Validation**: full offline suite (1081 tests; 15 new), and a real
+  end-to-end deep pass on the 2026-05-17 sample clip — estimate → confirm →
+  frames read by the host chat → commit → rows/blob/export parity → fields
+  visible in the panel shot view. Control-panel guide screenshots
+  regenerated from the live panel.
+
 ## What's New in v2.41.0
 
 DB-canonical clip analysis (C1) — Phase A of the analysis + edit-engine

package/README.md

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

package/docs/SKILL.md

@@ -494,8 +494,29 @@ Key actions: `capabilities`, `install_guidance`, `resolve_output_root`, `plan`,
 `cancel_batch_job`, `resume_batch_job`, `review_timeline_markers`,
 `cleanup_artifacts`, `db_status`, `db_ingest`, `get_panel_state`,
 `set_panel_state`, `session_start_context`, `update_clip_field`,
-`update_shot_field`, `get_field_history`, `revert_field`, and
-`list_corrections`.
+`update_shot_field`, `get_field_history`, `revert_field`,
+`list_corrections`, `deepen`, `commit_shot_vision`, and
+`vision_pending_sweep`.
+
+**Deep shot-level vision tier (v2.42.0+).** Opt-in, estimate-first. Two
+entry points share one per-shot schema (Visual / Content / Production /
+Editorial / Cuttability / description / confidence):
+- `depth="deep"` on any analyze action extends the deferred host-vision
+  payload with `deep_shot_schema`; each `shot_descriptions` entry must carry
+  the field groups. The first deep run returns `confirmation_required` with
+  a token-cost estimate — re-call with `confirm_deep=true`. Caps still apply.
+- `deepen(clip_id|clip_dir, shot_index?|shot_indices?)` runs the pass
+  post-hoc on an already-analyzed clip. First call returns the estimate +
+  `confirm_token`; re-call with the token to get the deferred payload, read
+  its `frame_paths`, and commit via
+  `commit_shot_vision(clip_id, shots=[{shot_index, ...groups...}],
+  vision_token)`. Deep fields land as `vision_deep_v1` provenance rows;
+  human corrections always survive. Shots with no sampled frames on disk get
+  1–2 frames re-extracted via ffmpeg (read-only on source media).
+`vision_pending_sweep(expire?, max_age_days?, reoffer?)` lists clips stuck
+in `pending_host_analysis`; `reoffer=true` returns each clip's stored
+deferred payload to finish the run, `expire=true` stamps them
+`expired_host_analysis` so pendings never linger silently.
 
 **DB-canonical analysis store (v2.41.0+).** The per-project SQLite DB
 (`_soul/timeline_brain.sqlite`, schema v9+) is the source of truth for clip

package/docs/guides/control-panel.md

@@ -86,7 +86,10 @@ transcripts once the search index is built.
 
 The clip view shows the full summary, tags, star rating, editorial notes, and
 a contact sheet of every detected shot. From here you can open the clip in
-Resolve, jump to the transcript, or click into any shot.
+Resolve, jump to the transcript, or click into any shot. `Deepen analysis`
+copies a ready-made chat prompt that asks your MCP session to run the opt-in
+deep shot pass (cost estimate first, then per-shot Visual / Content /
+Editorial / Cuttability fields).
 
 ### Transcript
 
@@ -107,7 +110,9 @@ start", "After cut", "Flash frame", "Motion peak"). Subjective fields are
 editable inline; edits are kept with the clip's analysis and merged on top of
 future re-analysis so human notes survive fresh vision runs. `Open in Resolve`
 jumps straight to the clip in the source viewer with the shot's mark in/out
-set.
+set. The field groups (Visual, Content, Production, Editorial, Cuttability)
+are filled by the opt-in deep vision pass — `Deepen this shot` copies a chat
+prompt that runs it for just this shot, estimate first.
 
 ### Media → History
 

package/install.py

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

package/src/analysis_dashboard.py

@@ -8390,7 +8390,7 @@ HTML = r"""<!doctype html>
         <span class="meta">${formatDuration(card.duration_seconds)} · ${shots.length} shots</span>
         ${cls.primary_use ? `<span class="review-chip">${escapeHtml(cls.primary_use)}</span>` : ''}
         ${cls.select_potential ? `<span class="review-chip ${selectChipClass(cls.select_potential)}">${escapeHtml(cls.select_potential)}</span>` : ''}
-        <div class="actions"><button class="secondary" id="reviewClipTranscriptBtn">Transcript</button><button class="secondary" id="reviewClipOpenInResolveBtn">Open in Resolve</button></div>
+        <div class="actions"><button class="secondary" id="reviewClipTranscriptBtn">Transcript</button><button class="secondary" id="reviewClipOpenInResolveBtn">Open in Resolve</button><button class="secondary" data-copy-chat-prompt="${escapeHtml(`Deepen the analysis of clip “${card.clip_name || state.review.currentClipId}”: call media_analysis(action="deepen", params={"clip_id": "${card.clip_id || state.review.currentClipId}"}), show me the cost estimate, and after I confirm, read the frames and commit the per-shot fields via commit_shot_vision.`)}">Deepen analysis</button></div>
       `;
       $('reviewClipSummary').textContent = data.clip_summary || data.clip_summary_oneliner || '';
       $('reviewClipTags').innerHTML = tags.map(t => `<span class="review-chip">${escapeHtml(t)}</span>`).join('');
@@ -9440,6 +9440,7 @@ HTML = r"""<!doctype html>
         <span class="meta">${escapeHtml(shot.description || '')}</span>
         <div class="actions">
           <button class="secondary" id="reviewShotOpenInResolveBtn">Open in Resolve</button>
+          <button class="secondary" data-copy-chat-prompt="${escapeHtml(`Deepen shot ${shotIndex} of clip “${(state.review.currentClipData && state.review.currentClipData.card && state.review.currentClipData.card.clip_name) || clipId}”: call media_analysis(action="deepen", params={"clip_id": "${clipId}", "shot_index": ${shotIndex}}), show me the cost estimate, and after I confirm, read the frames and commit the per-shot fields via commit_shot_vision.`)}">Deepen this shot</button>
           <button id="reviewShotEditToggleBtn" ${editing ? '' : 'class="secondary"'}>${editToggleLabel}</button>
         </div>
       `;

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.41.0"
+VERSION = "2.42.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.41.0"
+VERSION = "2.42.0"
 
 import base64
 import os
@@ -15020,6 +15020,10 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         # C1 — DB-canonical analysis store.
         "db_status",
         "db_ingest",
+        # Phase B — deep shot-level vision tier.
+        "deepen",
+        "commit_shot_vision",
+        "vision_pending_sweep",
     }:
         root = resolve_media_analysis_output_root(
             project_name=project_name,
@@ -15079,6 +15083,42 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         if action == "db_ingest":
             from src.utils import analysis_store
             return analysis_store.ingest_project(project_root)
+        # Phase B — deep shot-level vision tier.
+        if action == "deepen":
+            from src.utils import deep_vision
+            clip_ref = p.get("clip_id") or p.get("clipId") or p.get("clip_dir") or p.get("clipDir") or p.get("file_path") or p.get("filePath")
+            if not clip_ref:
+                return _err("deepen requires clip_id, clip_dir, or file_path")
+            raw_indices = p.get("shot_indices") or p.get("shotIndices")
+            if raw_indices is None and p.get("shot_index") is not None:
+                raw_indices = [p.get("shot_index")]
+            return deep_vision.deepen_clip(
+                project_root,
+                clip_ref=clip_ref,
+                shot_indices=[int(i) for i in raw_indices] if raw_indices else None,
+                confirm_token=p.get("confirm_token") or p.get("confirmToken"),
+                job_id=p.get("job_id") or p.get("jobId"),
+            )
+        if action == "commit_shot_vision":
+            from src.utils import deep_vision
+            clip_ref = p.get("clip_id") or p.get("clipId") or p.get("clip_dir") or p.get("clipDir") or p.get("file_path") or p.get("filePath")
+            if not clip_ref:
+                return _err("commit_shot_vision requires clip_id, clip_dir, or file_path")
+            return deep_vision.commit_shot_vision(
+                project_root,
+                shots=p.get("shots"),
+                vision_token=p.get("vision_token") or p.get("visionToken"),
+                clip_ref=clip_ref,
+                author=p.get("author") or "host_chat",
+            )
+        if action == "vision_pending_sweep":
+            from src.utils import deep_vision
+            return deep_vision.vision_pending_sweep(
+                project_root,
+                expire=_media_analysis_bool(p.get("expire"), False),
+                max_age_days=p.get("max_age_days") or p.get("maxAgeDays"),
+                reoffer=_media_analysis_bool(p.get("reoffer"), False),
+            )
         if action in {"build_index", "rebuild_index"}:
             return build_analysis_index(project_root, index_path=p.get("index_path") or p.get("indexPath"))
         if action == "index_status":
@@ -15490,6 +15530,9 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         "list_corrections",
         "db_status",
         "db_ingest",
+        "deepen",
+        "commit_shot_vision",
+        "vision_pending_sweep",
         "get_caps",
         "set_caps_preset",
         "get_usage",

package/src/utils/analysis_store.py

@@ -253,7 +253,10 @@ def _write_subjective(
         value_json = _dumps(value)
         existing = current.get(field_path)
         if existing is not None:
-            if str(existing["value_json"]) == value_json and str(existing["source"]) == source:
+            # Identical value → keep the existing row and its provenance. A
+            # different source re-deriving the same value must not re-attribute
+            # it (a deep pass would otherwise claim every unchanged field).
+            if str(existing["value_json"]) == value_json:
                 continue
             if (
                 str(existing["source"]) == HUMAN_SOURCE

package/src/utils/deep_vision.py

@@ -0,0 +1,643 @@
+"""Deep shot-level vision tier (Phase B of the analysis program).
+
+Fills the per-shot Visual / Content / Production / Editorial / Cuttability
+field groups (v2 shot schema spec §3.2–3.8) via the same deferred-payload
+host-vision pattern as standard analysis: the server prepares frames + a
+schema, the host chat reads the frames and commits JSON back.
+
+Two entry points share the schema:
+
+- ``depth="deep"`` on analyze extends the single-pass payload (handled in
+  media_analysis.build_host_chat_paths_payload via deep_shot_schema()).
+- ``deepen`` is the post-hoc per-clip/per-shot pass for already-analyzed
+  clips. It is estimate-first: the first call returns the frame/token cost
+  and a confirm_token; the second call (with the token) returns the deferred
+  payload. Both paths pass the caps pre-call refusal — confirmation never
+  bypasses budgets.
+
+Deep results commit via ``commit_shot_vision``: subjective rows are written
+with source ``vision_deep_v1`` (human rows still win), the canonical report
+blob is updated, and analysis.json re-exports in lockstep.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from typing import Any, Dict, List, Optional, Tuple
+
+from src.utils import analysis_store, timeline_brain_db
+
+DEEP_SHOT_SCHEMA_REFERENCE = "davinci_resolve_mcp.shot_deep_analysis.v1"
+DEEP_SOURCE = "vision_deep_v1"
+
+# Threshold above which a shot gets one extra extracted frame for the deep pass.
+LONG_SHOT_SECONDS = 15.0
+
+# Per-shot field groups (v2-shot-schema-spec §3.2–3.8). Values are the schema
+# template shown to the host chat; enums are listed inline.
+DEEP_SHOT_FIELD_GROUPS: Dict[str, Any] = {
+    "visual": {
+        "shot_size": "wide|medium_wide|medium|medium_close|close|extreme_close|insert|establishing|other",
+        "framing": "single|two_shot|group|crowd|empty|insert|establishing|abstract",
+        "camera_height": "eye_level|high_angle|low_angle|birds_eye|dutch|unknown",
+        "camera_motion": "locked|pan|tilt|dolly|handheld|crane|drone|zoom|composite|other",
+        "motion_direction": "left|right|up|down|in|out|clockwise|counter_clockwise|none",
+        "depth_of_field": "deep|shallow|rack_focus|unknown",
+        "lens_character": "wide|normal|tele|fisheye|unknown",
+        "lighting": "natural|high_key|low_key|practical|backlit|silhouette|mixed|unknown",
+        "color_mood": "warm|cool|neutral|desaturated|saturated|monochrome|unnatural|unknown",
+        "composition_notes": "<short free text>",
+    },
+    "content": {
+        "primary_subject": {
+            "type": "person|object|landscape|interior|vehicle|animal|text_graphic|abstract",
+            "description": "<one phrase>",
+            "performance": "null unless type==person: {eye_line: to_camera|off_left|off_right|down|up|closed|unknown, energy: low|medium|high, emotional_register: <short free text>}",
+        },
+        "secondary_subjects": ["<[{type, description}]>"],
+        "action": "<one sentence — what is happening>",
+        "location": "<one sentence — where this is>",
+        "visible_text": ["<readable on-screen text>"],
+        "objects_of_note": ["<notable props/elements>"],
+        "audio_character": "silence|sync_dialogue|vo_dialogue|music|ambient|sfx|mixed|unknown",
+    },
+    "production": {
+        "composite_shot": "<bool — split-screen / PiP / multi-angle composite>",
+        "composite_panels": "null unless composite_shot: [{region, primary_subject, action}]",
+        "vfx_present": "none|minor|major|unknown",
+    },
+    "editorial": {
+        "editorial_role": "establishing|coverage|reaction|insert|transition|b_roll|montage_element|titles_or_graphics|bumper|other",
+        "select_potential": "low|medium|high",
+        "best_moment": "null if the shot is a sustained flat beat, else {time_seconds, why}",
+        "best_moment_present": "<bool>",
+        "pacing": "still|moderate|kinetic|variable",
+        "stillness_type": "held_tension|quiet|contemplative|transitional|dead_air|unknown — null unless pacing is still/variable",
+        "pacing_note": "<free text or null — only when pacing is still/variable>",
+    },
+    "cuttability": {
+        "cut_in": {"quality": "poor|ok|clean", "notes": "<short>"},
+        "cut_out": {"quality": "poor|ok|clean", "notes": "<short>"},
+        "match_action_in": "<bool — could receive a match cut>",
+        "match_action_out": "<bool — could send a match cut>",
+        "cut_compatibility_hints": "<free text>",
+    },
+    "description": "<1-3 sentences, editorially useful, colleague-style note>",
+    "confidence": {
+        "visual": "low|medium|high",
+        "content": "low|medium|high",
+        "audio": "low|medium|high",
+        "editorial": "low|medium|high",
+        "cuttability": "low|medium|high",
+    },
+}
+
+DEEP_SHOT_PROMPT = (
+    "Deep per-shot editorial analysis. For EACH shot listed in shot_table, look "
+    "only at the frames whose indices appear in that shot's frame_indices and "
+    "fill every field group in deep_shot_schema (visual, content, production, "
+    "editorial, cuttability, description, confidence). Use the enum values "
+    "verbatim; use 'unknown' or null when the frames do not support a claim — "
+    "hedge identity/intent/value when frame evidence is thin. Return strict "
+    "JSON only: {\"shots\": [{\"shot_index\": <int>, ...field groups...}]}."
+)
+
+
+def _ma():
+    from src.utils import media_analysis
+
+    return media_analysis
+
+
+def deep_shot_schema() -> Dict[str, Any]:
+    """The per-shot deep field groups (shared by deep-depth analyze + deepen)."""
+    return json.loads(json.dumps(DEEP_SHOT_FIELD_GROUPS))
+
+
+def _now() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def _clip_context(project_root: str, clip_ref: Any) -> Tuple[Optional[Dict[str, Any]], Optional[str]]:
+    """Resolve a clip to (context, error). Auto-ingests the JSON report when
+    the DB has no rows yet (pre-v9 analysis roots)."""
+    ma = _ma()
+    conn = timeline_brain_db.connect(project_root)
+    clip_uuid = analysis_store.resolve_clip_uuid(conn, clip_ref)
+    if not clip_uuid:
+        # Pre-v9 report? Find the analysis.json by walking clips/ and ingest it.
+        clips_root = os.path.join(project_root, "clips")
+        candidate = str(clip_ref or "")
+        if os.path.isdir(clips_root):
+            for entry in sorted(os.listdir(clips_root)):
+                report_path = os.path.join(clips_root, entry, "analysis.json")
+                if not os.path.isfile(report_path):
+                    continue
+                try:
+                    with open(report_path, "r", encoding="utf-8") as handle:
+                        report = json.load(handle)
+                except (OSError, json.JSONDecodeError):
+                    continue
+                clip_block = report.get("clip") or {}
+                if candidate not in (
+                    entry,
+                    str(clip_block.get("clip_id") or ""),
+                    str(clip_block.get("media_id") or ""),
+                    ma.normalize_path(clip_block.get("file_path") or ""),
+                ):
+                    continue
+                ingest = analysis_store.ingest_report(
+                    project_root, report, clip_dir=os.path.join(clips_root, entry)
+                )
+                if ingest.get("success"):
+                    clip_uuid = ingest["clip_uuid"]
+                break
+    if not clip_uuid:
+        return None, f"No analyzed clip found for {clip_ref!r} (run db_ingest if this is an older analysis root)"
+    clip_row = conn.execute("SELECT * FROM clips WHERE clip_uuid = ?", (clip_uuid,)).fetchone()
+    shots = conn.execute(
+        "SELECT * FROM shots WHERE clip_uuid = ? ORDER BY shot_index", (clip_uuid,)
+    ).fetchall()
+    frames = conn.execute(
+        "SELECT * FROM frames WHERE clip_uuid = ? ORDER BY frame_index", (clip_uuid,)
+    ).fetchall()
+    if not shots:
+        return None, "Clip has no detected shots — deep shot analysis needs a standard analysis with cut detection first"
+    return {
+        "clip_uuid": clip_uuid,
+        "clip": dict(clip_row) if clip_row else {},
+        "shots": [dict(s) for s in shots],
+        "frames": [dict(f) for f in frames],
+    }, None
+
+
+def _select_shots(shots: List[Dict[str, Any]], shot_indices: Optional[List[int]]) -> Tuple[List[Dict[str, Any]], List[int]]:
+    if not shot_indices:
+        return shots, []
+    wanted = {int(i) for i in shot_indices}
+    selected = [s for s in shots if int(s["shot_index"]) in wanted]
+    missing = sorted(wanted - {int(s["shot_index"]) for s in selected})
+    return selected, missing
+
+
+def _frames_for_shot(shot: Dict[str, Any], frames: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    rows = [f for f in frames if f.get("shot_uuid") == shot["shot_uuid"]]
+    if rows:
+        return rows
+    start, end = shot.get("time_seconds_start"), shot.get("time_seconds_end")
+    if start is None or end is None:
+        return []
+    return [
+        f for f in frames
+        if f.get("time_seconds") is not None and start <= float(f["time_seconds"]) < end
+    ]
+
+
+def _extract_frame(source: str, time_seconds: float, out_path: str) -> Optional[str]:
+    """Extract one frame with ffmpeg (read-only on source). None on failure."""
+    ma = _ma()
+    os.makedirs(os.path.dirname(out_path), exist_ok=True)
+    code, _out, _err = ma._run_command([
+        "ffmpeg", "-y", "-ss", f"{max(0.0, time_seconds):.3f}", "-i", source,
+        "-frames:v", "1", "-q:v", "3", out_path,
+    ])
+    if code != 0 or not os.path.isfile(out_path):
+        return None
+    try:
+        from src.utils import analysis_caps
+
+        caps = ma._resolve_active_caps()
+        analysis_caps.downscale_frame_if_needed(out_path, caps.max_frame_dim_pixels)
+    except Exception:
+        pass
+    return out_path
+
+
+def _confirm_token_for(clip_uuid: str, shot_uuids: List[str]) -> str:
+    return _ma().short_hash(f"deepen:{clip_uuid}:{','.join(sorted(shot_uuids))}", 16)
+
+
+def _vision_token_for(clip_uuid: str, shot_uuids: List[str]) -> str:
+    return _ma().short_hash(f"deep_vision:{clip_uuid}:{','.join(sorted(shot_uuids))}", 16)
+
+
+def deepen_clip(
+    project_root: str,
+    *,
+    clip_ref: Any,
+    shot_indices: Optional[List[int]] = None,
+    confirm_token: Optional[str] = None,
+    job_id: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Estimate-first deep pass over a clip (or selected shots).
+
+    First call (no confirm_token) returns the cost estimate + confirm_token.
+    Second call with the token returns the deferred host-vision payload.
+    """
+    ma = _ma()
+    context, err = _clip_context(project_root, clip_ref)
+    if err:
+        return {"success": False, "error": err}
+    clip_uuid = context["clip_uuid"]
+    clip = context["clip"]
+    shots, missing = _select_shots(context["shots"], shot_indices)
+    if missing:
+        return {"success": False, "error": f"shot_index not found: {missing}", "available": [s['shot_index'] for s in context['shots']]}
+    if not shots:
+        return {"success": False, "error": "No shots selected"}
+
+    shot_uuids = [s["shot_uuid"] for s in shots]
+    expected_confirm = _confirm_token_for(clip_uuid, shot_uuids)
+
+    # Frame plan: existing on-disk frames per shot; shots with none get
+    # extraction placeholders; long shots get one extra mid-late frame.
+    source = clip.get("file_path")
+    frame_plan: List[Dict[str, Any]] = []
+    total_frames = 0
+    for shot in shots:
+        rows = _frames_for_shot(shot, context["frames"])
+        on_disk = [r for r in rows if r.get("frame_path") and os.path.isfile(str(r["frame_path"]))]
+        start = float(shot.get("time_seconds_start") or 0.0)
+        end = float(shot.get("time_seconds_end") or start)
+        duration = max(0.0, end - start)
+        to_extract: List[float] = []
+        if not on_disk:
+            to_extract.append(start + duration / 2.0)
+        if duration > LONG_SHOT_SECONDS:
+            to_extract.append(start + duration * 2.0 / 3.0)
+        count = len(on_disk) + len(to_extract)
+        total_frames += count
+        frame_plan.append({
+            "shot_index": shot["shot_index"],
+            "shot_uuid": shot["shot_uuid"],
+            "existing_frames": len(on_disk),
+            "frames_to_extract": len(to_extract),
+            "extract_times": to_extract,
+            "rows": on_disk,
+        })
+
+    estimated_tokens = total_frames * ma.AVG_VISION_TOKENS_PER_FRAME
+    refusal = ma._check_caps_pre_call(
+        project_root=project_root,
+        estimated_vision_tokens=estimated_tokens,
+        clip_id=clip.get("resolve_clip_id") or clip_uuid,
+        job_id=job_id,
+    )
+    if refusal is not None:
+        return refusal
+
+    estimate = {
+        "clip_uuid": clip_uuid,
+        "clip_name": clip.get("clip_name"),
+        "shot_count": len(shots),
+        "frame_count": total_frames,
+        "estimated_vision_tokens": estimated_tokens,
+        "tokens_per_frame_assumption": ma.AVG_VISION_TOKENS_PER_FRAME,
+    }
+
+    if confirm_token != expected_confirm:
+        return {
+            "success": True,
+            "status": "confirmation_required",
+            "estimate": estimate,
+            "confirm_token": expected_confirm,
+            "note": (
+                "Deep shot analysis is opt-in and costs vision tokens. Re-call "
+                "media_analysis(action='deepen') with this confirm_token to "
+                "proceed. Confirmation does not bypass caps."
+            ),
+        }
+
+    # Confirmed: materialize missing frames, then build the deferred payload.
+    clip_dir_name = clip.get("clip_dir")
+    clip_dir = os.path.join(project_root, "clips", clip_dir_name) if clip_dir_name else None
+    shot_table: List[Dict[str, Any]] = []
+    frame_metadata: List[Dict[str, Any]] = []
+    frame_paths: List[str] = []
+    synthetic_index = 100000  # extraction-only frames get indices above sampled ones
+    for plan in frame_plan:
+        indices: List[int] = []
+        for row in plan["rows"]:
+            path = ma.normalize_path(str(row["frame_path"]))
+            if path not in frame_paths:
+                frame_paths.append(path)
+                frame_metadata.append({
+                    "frame_index": int(row["frame_index"]),
+                    "frame_path": path,
+                    "time_seconds": row.get("time_seconds"),
+                    "selection_reason": row.get("selection_reason"),
+                    "shot_index": plan["shot_index"],
+                })
+            indices.append(int(row["frame_index"]))
+        for t in plan["extract_times"]:
+            if not source or not os.path.isfile(source):
+                continue
+            if not clip_dir:
+                continue
+            out_path = os.path.join(clip_dir, "frames", f"deep_shot{int(plan['shot_index']):03d}_{int(t * 1000):08d}.jpg")
+            extracted = out_path if os.path.isfile(out_path) else _extract_frame(source, t, out_path)
+            if not extracted:
+                continue
+            synthetic_index += 1
+            path = ma.normalize_path(extracted)
+            frame_paths.append(path)
+            frame_metadata.append({
+                "frame_index": synthetic_index,
+                "frame_path": path,
+                "time_seconds": t,
+                "selection_reason": "deep_pass_extraction",
+                "shot_index": plan["shot_index"],
+            })
+            indices.append(synthetic_index)
+        shot = next(s for s in shots if s["shot_index"] == plan["shot_index"])
+        shot_table.append({
+            "shot_index": int(shot["shot_index"]),
+            "shot_uuid": shot["shot_uuid"],
+            "time_seconds_start": shot.get("time_seconds_start"),
+            "time_seconds_end": shot.get("time_seconds_end"),
+            "current_description": shot.get("description"),
+            "frame_indices": indices,
+        })
+
+    vision_token = _vision_token_for(clip_uuid, shot_uuids)
+    commit_params: Dict[str, Any] = {
+        "vision_token": vision_token,
+        "shots": "<host chat: [{shot_index, ...deep_shot_schema groups...}]>",
+        "analysis_root": project_root,
+    }
+    if clip.get("resolve_clip_id"):
+        commit_params["clip_id"] = clip["resolve_clip_id"]
+    elif clip_dir_name:
+        commit_params["clip_dir"] = clip_dir_name
+
+    return {
+        "success": True,
+        "status": "pending_host_analysis",
+        "provider": "host_chat_paths",
+        "mode": "deep_shots",
+        "vision_token": vision_token,
+        "estimate": estimate,
+        "clip": {
+            "clip_uuid": clip_uuid,
+            "clip_id": clip.get("resolve_clip_id"),
+            "clip_name": clip.get("clip_name"),
+            "file_path": source,
+        },
+        "frame_count": len(frame_paths),
+        "frame_paths": frame_paths,
+        "frame_metadata": frame_metadata,
+        "shot_table": shot_table,
+        "deep_shot_schema": deep_shot_schema(),
+        "schema_reference": DEEP_SHOT_SCHEMA_REFERENCE,
+        "prompt": DEEP_SHOT_PROMPT,
+        "commit_action": {
+            "tool": "media_analysis",
+            "action": "commit_shot_vision",
+            "params": commit_params,
+        },
+        "instructions": (
+            "Read every file under frame_paths as a local image. For each entry in "
+            "shot_table, produce one object in `shots` with its shot_index and the "
+            "deep_shot_schema field groups, grounded ONLY in the frames listed in "
+            "that shot's frame_indices. Then call the tool in commit_action with "
+            "`shots` set to that array. Skipping the commit leaves the deep pass "
+            "incomplete — surface that rather than silently stopping."
+        ),
+    }
+
+
+_DEEP_GROUP_KEYS = ("visual", "content", "production", "editorial", "cuttability")
+
+
+def commit_shot_vision(
+    project_root: str,
+    *,
+    shots: Any,
+    vision_token: Optional[str] = None,
+    clip_ref: Any = None,
+    author: str = "host_chat",
+) -> Dict[str, Any]:
+    """Commit a deep per-shot payload: subjective rows (source vision_deep_v1),
+    canonical blob update, and lockstep analysis.json re-export."""
+    if isinstance(shots, str):
+        try:
+            shots = json.loads(shots)
+        except json.JSONDecodeError as exc:
+            return {"success": False, "error": f"shots was a string but not valid JSON: {exc}"}
+    if isinstance(shots, dict) and isinstance(shots.get("shots"), list):
+        shots = shots["shots"]
+    if not isinstance(shots, list) or not shots:
+        return {"success": False, "error": "commit_shot_vision requires `shots`: a non-empty array of per-shot objects"}
+
+    context, err = _clip_context(project_root, clip_ref)
+    if err:
+        return {"success": False, "error": err}
+    clip_uuid = context["clip_uuid"]
+    db_shots = {int(s["shot_index"]): s for s in context["shots"]}
+    by_uuid = {s["shot_uuid"]: s for s in context["shots"]}
+
+    # Token check: recompute over the shots being committed.
+    target_uuids = []
+    normalized_entries: List[Tuple[Dict[str, Any], Dict[str, Any]]] = []  # (db_shot, payload_entry)
+    for entry in shots:
+        if not isinstance(entry, dict):
+            continue
+        db_shot = None
+        if entry.get("shot_uuid") and entry["shot_uuid"] in by_uuid:
+            db_shot = by_uuid[entry["shot_uuid"]]
+        else:
+            try:
+                db_shot = db_shots.get(int(entry.get("shot_index")))
+            except (TypeError, ValueError):
+                db_shot = None
+        if db_shot is None:
+            return {"success": False, "error": f"shot not found for entry: {entry.get('shot_uuid') or entry.get('shot_index')!r}"}
+        target_uuids.append(db_shot["shot_uuid"])
+        normalized_entries.append((db_shot, entry))
+    if not normalized_entries:
+        return {"success": False, "error": "No valid shot entries in payload"}
+    expected = _vision_token_for(clip_uuid, target_uuids)
+    if vision_token and str(vision_token) != expected:
+        return {
+            "success": False,
+            "error": "vision_token mismatch; the clip was re-analyzed or the shot selection changed since the deepen payload was issued.",
+            "expected_vision_token": expected,
+            "received_vision_token": vision_token,
+        }
+
+    ma = _ma()
+    conn = timeline_brain_db.connect(project_root)
+    report_row = conn.execute(
+        "SELECT report_json FROM analysis_reports WHERE clip_uuid = ?", (clip_uuid,)
+    ).fetchone()
+    if not report_row:
+        return {"success": False, "error": "No canonical report for clip — run db_ingest first"}
+    report = json.loads(report_row["report_json"])
+    visual = report.get("visual") if isinstance(report.get("visual"), dict) else {}
+    shot_entries = visual.get("shot_descriptions") if isinstance(visual.get("shot_descriptions"), list) else []
+    entries_by_index: Dict[int, Dict[str, Any]] = {}
+    for se in shot_entries:
+        if isinstance(se, dict) and se.get("shot_index") is not None:
+            try:
+                entries_by_index[int(se["shot_index"])] = se
+            except (TypeError, ValueError):
+                continue
+
+    updated = 0
+    for db_shot, entry in normalized_entries:
+        target = entries_by_index.get(int(db_shot["shot_index"]))
+        if target is None:
+            target = {
+                "shot_index": int(db_shot["shot_index"]),
+                "time_seconds_start": db_shot.get("time_seconds_start"),
+                "time_seconds_end": db_shot.get("time_seconds_end"),
+                "description": db_shot.get("description") or "",
+                "qc_flags": [],
+            }
+            shot_entries.append(target)
+            entries_by_index[int(db_shot["shot_index"])] = target
+        for group in _DEEP_GROUP_KEYS:
+            if isinstance(entry.get(group), dict):
+                target[group] = entry[group]
+        if isinstance(entry.get("confidence"), dict):
+            target["confidence"] = entry["confidence"]
+        description = entry.get("description")
+        if isinstance(description, str) and description.strip():
+            target["description"] = description.strip()
+        updated += 1
+
+    visual["shot_descriptions"] = shot_entries
+    report["visual"] = visual
+    report["deep_shots_committed_at"] = _now()
+
+    # Rows first (canonical), deep source label; human rows preserved inside.
+    ingest = analysis_store.ingest_report(
+        project_root,
+        report,
+        clip_dir=os.path.join(project_root, "clips", context["clip"].get("clip_dir") or ""),
+        author=author,
+        source=DEEP_SOURCE,
+    )
+    if not ingest.get("success"):
+        return {"success": False, "error": f"DB ingest failed: {ingest.get('error')}"}
+
+    # Lockstep JSON export.
+    export_path = None
+    clip_dir_name = context["clip"].get("clip_dir")
+    if clip_dir_name:
+        candidate = os.path.join(project_root, "clips", clip_dir_name, "analysis.json")
+        if os.path.isfile(candidate):
+            export_path = analysis_store.export_report_file(project_root, clip_uuid, candidate)
+
+    # Caps usage: frames that fed this pass (frames table rows for the target
+    # shots), falling back to one frame per shot when none are recorded.
+    placeholders = ",".join("?" for _ in target_uuids)
+    frames_seen = int(conn.execute(
+        f"SELECT COUNT(*) FROM frames WHERE clip_uuid = ? AND shot_uuid IN ({placeholders})",
+        (clip_uuid, *target_uuids),
+    ).fetchone()[0]) or len(normalized_entries)
+    ma._record_caps_usage(
+        project_root=project_root,
+        clip_id=context["clip"].get("resolve_clip_id") or clip_uuid,
+        vision_tokens=frames_seen * ma.AVG_VISION_TOKENS_PER_FRAME,
+        frames_uploaded=frames_seen,
+    )
+
+    return {
+        "success": True,
+        "clip_uuid": clip_uuid,
+        "shots_updated": updated,
+        "subjective_fields_written": ingest.get("subjective_fields_written"),
+        "subjective_fields_preserved_human": ingest.get("subjective_fields_preserved_human"),
+        "source": DEEP_SOURCE,
+        "analysis_json": export_path,
+    }
+
+
+def vision_pending_sweep(
+    project_root: str,
+    *,
+    expire: bool = False,
+    max_age_days: Optional[float] = None,
+    reoffer: bool = False,
+) -> Dict[str, Any]:
+    """List clips stuck in pending_host_analysis; optionally expire or re-offer.
+
+    Re-offer returns each clip's stored deferred payload (report["visual"])
+    after verifying its frame files still exist. Expire stamps the report
+    ``expired_host_analysis`` so pendings never linger silently.
+    """
+    ma = _ma()
+    root = ma.normalize_path(project_root)
+    clips_root = os.path.join(root, "clips")
+    now = time.time()
+    pending: List[Dict[str, Any]] = []
+    expired: List[str] = []
+    reoffers: List[Dict[str, Any]] = []
+    if os.path.isdir(clips_root):
+        for entry in sorted(os.listdir(clips_root)):
+            clip_dir = os.path.join(clips_root, entry)
+            report_path = os.path.join(clip_dir, "analysis.json")
+            if not os.path.isfile(report_path):
+                continue
+            report = analysis_store.load_db_report(root, clip_dir=entry)
+            if report is None:
+                try:
+                    with open(report_path, "r", encoding="utf-8") as handle:
+                        report = json.load(handle)
+                except (OSError, json.JSONDecodeError):
+                    continue
+            if report.get("vision_status") != "pending_host_analysis":
+                continue
+            analyzed_at = report.get("analyzed_at")
+            age_days = None
+            ts = ma._timestamp_from_analyzed_at(analyzed_at)
+            if ts:
+                age_days = round((now - ts) / 86400.0, 2)
+            visual = report.get("visual") if isinstance(report.get("visual"), dict) else {}
+            frame_paths = visual.get("frame_paths") if isinstance(visual.get("frame_paths"), list) else []
+            frames_present = sum(1 for p in frame_paths if p and os.path.isfile(str(p)))
+            row = {
+                "clip_dir": entry,
+                "clip_name": (report.get("clip") or {}).get("clip_name"),
+                "clip_id": (report.get("clip") or {}).get("clip_id"),
+                "analyzed_at": analyzed_at,
+                "age_days": age_days,
+                "vision_token": report.get("vision_token") or visual.get("vision_token"),
+                "frame_count": len(frame_paths),
+                "frames_still_on_disk": frames_present,
+                "reofferable": frames_present > 0,
+            }
+            pending.append(row)
+            over_age = max_age_days is not None and (age_days or 0) >= float(max_age_days)
+            if expire and (max_age_days is None or over_age):
+                report["vision_status"] = "expired_host_analysis"
+                report["vision_expired_at"] = _now()
+                ingest = analysis_store.ingest_report(root, report, clip_dir=clip_dir)
+                if ingest.get("success"):
+                    analysis_store.export_report_file(root, ingest["clip_uuid"], report_path)
+                else:
+                    ma._write_json(report_path, report)
+                expired.append(entry)
+                row["expired"] = True
+            elif reoffer and frames_present:
+                reoffers.append({
+                    "clip_dir": entry,
+                    "payload": visual,
+                })
+    result: Dict[str, Any] = {
+        "success": True,
+        "project_root": root,
+        "pending_count": len(pending),
+        "pending": pending,
+        "expired": expired,
+    }
+    if reoffer:
+        result["reoffers"] = reoffers
+        result["note"] = (
+            "Each reoffer.payload is the original deferred host-vision payload; "
+            "read its frame_paths and call its commit_action to finish the run."
+        )
+    return result

package/src/utils/media_analysis.py

@@ -4265,7 +4265,7 @@ def build_host_chat_paths_payload(
     if refusal is not None:
         return refusal
 
-    return {
+    payload: Dict[str, Any] = {
         "success": True,
         "status": "pending_host_analysis",
         "provider": HOST_CHAT_PATHS_PROVIDER,
@@ -4327,6 +4327,21 @@ def build_host_chat_paths_payload(
             "the clip's analysis directory; commit_vision finishes the run."
         ),
     }
+    # Phase B — deep depth: each shot_descriptions entry must additionally
+    # carry the per-shot field groups. The extra keys flow through
+    # commit_vision → canonical blob → subjective_fields rows unchanged.
+    if str(options.get("depth") or "").lower() == "deep":
+        from src.utils import deep_vision as _deep_vision
+
+        payload["deep_shot_schema"] = _deep_vision.deep_shot_schema()
+        payload["deep_schema_reference"] = _deep_vision.DEEP_SHOT_SCHEMA_REFERENCE
+        payload["instructions"] += (
+            " DEEP PASS: in addition to `description`, every shot_descriptions "
+            "entry MUST include the field groups in `deep_shot_schema` (visual, "
+            "content, production, editorial, cuttability, confidence), using the "
+            "enum values verbatim and 'unknown'/null when frame evidence is thin."
+        )
+    return payload
 
 
 def _vision_analysis(record: Dict[str, Any], motion: Dict[str, Any], options: Dict[str, Any], artifacts: Dict[str, Any], capabilities: Dict[str, Any]) -> Dict[str, Any]:
@@ -5096,6 +5111,9 @@ async def execute_plan_async(
         # Same for project_root — caps recording needs it to address the per-
         # project usage DB; falling back to the plan's output_root is fine.
         "project_root": params.get("project_root") or output_root,
+        # Phase B — depth threads into the vision payload builder so deep runs
+        # carry the per-shot field-group schema.
+        "depth": plan.get("depth", DEFAULT_DEPTH),
     }
     keep_frame_artifacts_for_vision = vision_uses_chat_context(options, caps)
     depth = plan.get("depth", DEFAULT_DEPTH)
@@ -5114,6 +5132,37 @@ async def execute_plan_async(
     }
     _write_json(os.path.join(output_root, "capabilities.json"), caps)
 
+    # Phase B — deep depth is opt-in with an explicit cost estimate first.
+    # The per-shot field-group pass multiplies vision spend, so the first call
+    # returns the estimate; re-call with confirm_deep=true to run. Caps still
+    # apply downstream — confirmation does not bypass budgets.
+    if (
+        depth == "deep"
+        and vision_uses_chat_context(options, caps)
+        and not _coerce_bool(params.get("confirm_deep") or params.get("confirmDeep"), default=False)
+    ):
+        executing = [
+            clip for clip in plan.get("clips", [])
+            if not (clip.get("skip_execution") and (clip.get("existing_report") or {}).get("path"))
+        ]
+        estimated_frames = sum(int(c.get("analysis_keyframe_budget") or 0) for c in executing)
+        return {
+            "success": True,
+            "status": "confirmation_required",
+            "reason": "deep_depth_cost_estimate",
+            "estimate": {
+                "clip_count": len(executing),
+                "estimated_frames": estimated_frames,
+                "estimated_vision_tokens": estimated_frames * AVG_VISION_TOKENS_PER_FRAME,
+                "tokens_per_frame_assumption": AVG_VISION_TOKENS_PER_FRAME,
+            },
+            "note": (
+                "Deep analysis fills per-shot Visual/Content/Editorial field groups "
+                "and costs vision tokens accordingly. Re-call the same analyze action "
+                "with confirm_deep=true to proceed, or drop depth to 'standard'."
+            ),
+        }
+
     for clip_plan in plan.get("clips", []):
         record = clip_plan["record"]
         artifacts = clip_plan["artifacts"]