davinci-resolve-mcp 2.103.2 → 2.103.3

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.103.3
+
+**A batch transcription fix that would have failed every clip.** Issue #160 by
+@techsolvehq-source was real and precisely reported: a Whisper transcription that
+hit the 90s wall-clock cap already returned `success: False`, but
+`execute_plan_async` then hard-set `clip_result["success"] = True`, so the batch
+job counted the clip as succeeded, closed as `completed`, and left `last_error`
+unset. PR #161 by @Steve0x2a fixed that by giving transcription the failure
+annotation vision already had.
+
+The gate it landed with keyed on `success` alone, and that is where it went wrong.
+Transcription is enabled by default, and `allow_model_download` is off by default,
+so `_transcribe` returns `success: False, status: "skipped"` on a stock install —
+no Whisper backend, or one the user has not opted into model downloads for. Every
+clip of every batch would have been marked failed and no batch job could have
+reached `completed`. Vision can treat every non-success as a failure because
+vision defaults to *disabled*; transcription cannot.
+
+So the failure class is now drawn by status rather than by `success`: skipped,
+disabled, and not_implemented mean the backend never ran, while timeouts, caps
+refusals, and backend errors are real failures. The original timeout bug stays
+fixed.
+
+**Antigravity's config path, settled without picking a winner.** Issue #159 by
+@KMiNT21 reports `~/.gemini/config/mcp_config.json`; commit 85afe82 wrote
+`~/.gemini/antigravity/mcp_config.json`. Neither is verifiable from macOS, and
+swapping one unverifiable path for another is a coin flip that breaks it for
+whichever contributor was right — this repo has already been bitten by a
+documented-but-decoy config path (Claude Desktop MSIX, issue #93). The installer
+now probes: `~/.gemini/config/` first, because the installer has never written
+there, so that file existing is evidence something else created it. It looks for
+the file rather than the directory, since `~/.gemini/antigravity/` holds runtime
+state on every install.
+
+### Fixed
+
+- A transcription backend that is unavailable, disabled, or not implemented no
+  longer marks a batch clip failed. `transcription_attempt_failed` in
+  `src/utils/media_analysis.py` screens the "never ran" statuses out of the
+  failure class; timeouts, caps refusals, and backend errors stay in it.
+- Whisper wall-clock timeouts are reported as failed batch clips instead of
+  silently succeeding (#160, PR #161 by @Steve0x2a).
+- `install.py` resolves Antigravity's MCP config path from what is on disk
+  instead of a hard-coded guess (#159).
+- `scripts/gen_api_limitations.py --help` prints usage instead of silently
+  overwriting the generated report (PR #163 by @diesdaas).
+
+### Changed
+
+- The read/write symmetry audit resolves `_unknown(action, ...)` groups through
+  the AST rather than a regex, so action lists expressed as named, starred,
+  annotated, or concatenated module constants are now scanned. This surfaced a
+  genuine readback gap (`set_clip_marks`) the regex was missing, and known
+  readback aliases such as `get_cache_enabled` and `mcp_update_status` no longer
+  register as false gaps (PR #162 by @diesdaas).
+- `scripts/audit_readwrite_symmetry.py` writes `docs/reference/readwrite-symmetry.md`
+  by default and gains `--check` and `--stdout`, matching the
+  `gen_api_limitations.py` convention. The report is pinned to `src/server.py` by
+  a drift guard, so it needed a regeneration path: the check now runs in the
+  release checklist, and both the script and the failing test name the command
+  that clears it.
+
 ## What's New in v2.103.2
 
 **A Windows setup that failed with nothing to read.** Reported in issue #158 by

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.103.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.103.3-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-36%20(353%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.103.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.103.3-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-36%20(353%20full)-blue.svg)](#服务器模式)
@@ -12,7 +12,7 @@
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> 本翻译对应 v2.103.2 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.103.3 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/docs/install.md

@@ -86,7 +86,7 @@ The installer can automatically configure any of these clients:
 
 | Client | Config Written To |
 |--------|-------------------|
-| Antigravity (Google) | `~/.gemini/antigravity/mcp_config.json` (all platforms) |
+| Antigravity (Google) | `~/.gemini/config/mcp_config.json`, or `~/.gemini/antigravity/mcp_config.json` if that file already exists (all platforms) |
 | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS); `%APPDATA%\Claude\claude_desktop_config.json` (Windows, see MSIX note below) |
 | Claude Code | `.mcp.json` (project root) |
 | Cursor | `~/.cursor/mcp.json` |

package/docs/process/release-process.md

@@ -73,6 +73,7 @@ venv/bin/python tests/test_import.py
 npm install --package-lock-only --no-audit --no-fund   # re-stage package-lock.json if it moved
 venv/bin/python scripts/audit_api_parity.py
 venv/bin/python scripts/gen_api_limitations.py --check
+venv/bin/python scripts/audit_readwrite_symmetry.py --check
 node scripts/agent-rules/generate.mjs --check
 venv/bin/python -m unittest tests.test_static_undefined_names tests.test_duplicate_definitions tests.test_action_list_drift tests.test_panel_docs_drift tests.test_doc_tool_counts tests.test_agent_rules_drift
 node bin/davinci-resolve-mcp.mjs --help

package/docs/reference/readwrite-symmetry.md

@@ -2,24 +2,21 @@
 
 # Read/Write Symmetry Audit
 
-- write-style actions scanned: **106**
-- with a matching read: **57**
-- `set_` actions with no `get_`/`list_` (real readback gaps): **11**
+- write-style action occurrences scanned: **116**
+- write-style action occurrences with a matching read: **67**
+- distinct high-signal `set_` actions without a direct/known readback: **8**
 
-## High-signal gaps — `set_` with no read counterpart
+## High-signal gaps — `set_` with no direct/known readback
 
-- `set_cache`
 - `set_cdl`
+- `set_clip_marks`
 - `set_clips_linked`
 - `set_high_priority`
 - `set_keyframe_interpolation`
-- `set_mcp_update_policy`
 - `set_name`
 - `set_node_enabled`
 - `set_title_text`
-- `set_track_enable`
-- `set_track_lock`
 
-## Low-signal (create/add/insert/import — usually expected): 37
+## Low-signal (create/add/insert/apply/import — usually expected): 40 distinct names
 
-`add_clip_mattes`, `add_comp`, `add_subfolder`, `add_sync_event_markers`, `add_timeline_mattes`, `add_track`, `add_version`, `apply_arri_cdl_lut`, `apply_fairlight_preset`, `apply_grade_from_drx`, `apply_look_to_items`, `apply_spec`, `create_compound_clip`, `create_fusion_clip`, `create_magic_mask`, `create_stereo_clip`, `create_subtitles`, `create_timeline`, `create_timeline_from_clips`, `create_variant_from_ranges`, `import_burnin`, `import_comp`, `import_folder`, `import_into_timeline`, `import_media`, `import_preset`, `import_project`, `import_render`, `import_timeline`, `import_to_pool`, `insert_audio`, `insert_fusion_composition`, `insert_fusion_generator`, `insert_fusion_title`, `insert_generator`, `insert_ofx_generator`, `insert_title`
+`add_clip_mattes`, `add_comp`, `add_fusion_mask`, `add_subfolder`, `add_sync_event_markers`, `add_timeline_mattes`, `add_track`, `add_version`, `apply_arri_cdl_lut`, `apply_cuts`, `apply_fairlight_preset`, `apply_grade_from_drx`, `apply_look_to_items`, `apply_spec`, `create_compound_clip`, `create_fusion_clip`, `create_magic_mask`, `create_stereo_clip`, `create_subtitles`, `create_timeline`, `create_timeline_from_clips`, `create_variant_from_ranges`, `import_comp`, `import_folder`, `import_from_drp`, `import_into_timeline`, `import_media`, `import_preset`, `import_project`, `import_render`, `import_timeline`, `import_timeline_checked`, `import_to_pool`, `insert_audio`, `insert_fusion_composition`, `insert_fusion_generator`, `insert_fusion_title`, `insert_generator`, `insert_ofx_generator`, `insert_title`

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.103.2"
+VERSION = "2.103.3"
 # 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
@@ -393,6 +393,33 @@ def vscode_global_storage():
         return xdg_config() / "Code" / "User" / "globalStorage"
 
 
+def antigravity_config():
+    """Antigravity's MCP config path, resolved by what is on disk (issue #159).
+
+    Two contributors report two different locations and neither is verifiable
+    from here: 85afe82 added ~/.gemini/antigravity/mcp_config.json, and #159
+    reports ~/.gemini/config/mcp_config.json, with ~/.gemini/antigravity/ being
+    runtime state (logs, crash reports, brain state). Swapping one unverifiable
+    path for the other is a coin flip that breaks it for whoever was right, and
+    this repo has already been bitten by a documented-but-decoy config path
+    (Claude Desktop MSIX, issue #93).
+
+    So probe instead of choosing. ~/.gemini/config/ is checked first because
+    the installer has never written there — if that file exists, something else
+    created it, which is real evidence. ~/.gemini/antigravity/mcp_config.json
+    may exist merely because an earlier run of this installer put it there.
+    With neither present, fall back to ~/.gemini/config/ as #159 documents.
+    """
+    candidates = (
+        home() / ".gemini" / "config" / "mcp_config.json",
+        home() / ".gemini" / "antigravity" / "mcp_config.json",
+    )
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+    return candidates[0]
+
+
 # Each client entry:
 #   id, name, config_path_fn, config_key, merge_strategy, notes
 # config_path_fn returns the path; config_key is the JSON key wrapping the server entry
@@ -402,7 +429,7 @@ MCP_CLIENTS = [
     {
         "id": "antigravity",
         "name": "Antigravity",
-        "get_path": lambda: home() / ".gemini" / "antigravity" / "mcp_config.json",
+        "get_path": antigravity_config,
         "config_key": "mcpServers",
         "notes": "Google's agentic AI coding assistant (VS Code fork)",
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.103.2",
+  "version": "2.103.3",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/scripts/audit_readwrite_symmetry.py

@@ -7,15 +7,22 @@ asymmetries. The goal is to find write-without-read gaps before users have to
 the repeatable feature-discovery method behind R5.
 
 Reads the `_unknown(action, [...])` lists in src/server.py, which enumerate every
-action a tool accepts. Prints a markdown report.
+action a tool accepts. Writes docs/reference/readwrite-symmetry.md.
+
+`--check` verifies the committed report matches the current server surface; it is
+what tests/test_readwrite_audit.py and the release checklist gate on. `--stdout`
+prints the report instead of writing it.
 """
+import argparse
 import ast
 import os
-import re
 import sys
 
 ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 SERVER = os.path.join(ROOT, "src", "server.py")
+DOC_PATH = os.path.join(ROOT, "docs", "reference", "readwrite-symmetry.md")
+DOC_REL = os.path.relpath(DOC_PATH, ROOT)
+REGEN_COMMAND = "venv/bin/python scripts/audit_readwrite_symmetry.py"
 
 READ_PREFIXES = ("get_", "list_", "probe_", "is_", "has_", "find_")
 # `set_` is the high-signal class: a set with no get is a genuine readback gap.
@@ -24,20 +31,94 @@ READ_PREFIXES = ("get_", "list_", "probe_", "is_", "has_", "find_")
 HIGH_SIGNAL = ("set_",)
 LOW_SIGNAL = ("add_", "create_", "insert_", "apply_", "import_")
 
+STEM_READ_ALIASES = {
+    # Resolve's public names often use enable/lock verbs on writes but enabled/
+    # locked nouns on reads; keep the audit focused on real missing readbacks.
+    "cache": ("cache_enabled",),
+    "caps_preset": ("caps",),
+    "track_enable": ("track_enabled",),
+    "track_lock": ("track_locked",),
+}
+
+DIRECT_READ_ALIASES = {
+    # mcp_update_status returns the persisted prompt policy and effective
+    # decision, so set_mcp_update_policy has a direct readback without a get_
+    # name.
+    "mcp_update_policy": ("mcp_update_status",),
+}
+
+
+def _module_constants(tree: ast.Module):
+    """Collect module-level named assignments without evaluating the module."""
+    constants = {}
+    for node in tree.body:
+        if isinstance(node, ast.Assign):
+            targets = node.targets
+        elif isinstance(node, ast.AnnAssign):
+            targets = (node.target,)
+        else:
+            continue
+        for target in targets:
+            if isinstance(target, ast.Name):
+                constants[target.id] = node.value
+    return constants
+
+
+def _resolve_actions(expr, constants, seen=None):
+    """Resolve supported action-list expressions or return None."""
+    seen = set() if seen is None else seen
+    if isinstance(expr, ast.Constant) and isinstance(expr.value, str):
+        return [expr.value]
+    if isinstance(expr, ast.Name):
+        if expr.id in seen or expr.id not in constants:
+            return None
+        return _resolve_actions(expr=constants[expr.id], constants=constants,
+                                 seen=seen | {expr.id})
+    if isinstance(expr, (ast.List, ast.Tuple)):
+        actions = []
+        for element in expr.elts:
+            if isinstance(element, ast.Starred):
+                element = element.value
+            resolved = _resolve_actions(element, constants, seen)
+            if resolved is None:
+                return None
+            actions.extend(resolved)
+        return actions
+    if isinstance(expr, ast.BinOp) and isinstance(expr.op, ast.Add):
+        left = _resolve_actions(expr.left, constants, seen)
+        right = _resolve_actions(expr.right, constants, seen)
+        if left is None or right is None:
+            return None
+        return left + right
+    return None
+
 
 def _action_lists(src: str):
-    """Yield lists of action-name string literals from each _unknown(action, [...])."""
-    for m in re.finditer(r"_unknown\(action,\s*\[(.*?)\]\)", src, re.DOTALL):
-        names = re.findall(r'"([a-z][a-z0-9_]*)"', m.group(1))
-        if names:
-            yield names
+    """Yield action lists passed to ``_unknown(action, ...)`` calls."""
+    tree = ast.parse(src)
+    constants = _module_constants(tree)
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        if not (isinstance(node.func, ast.Name)
+                and node.func.id == "_unknown"
+                and len(node.args) >= 2
+                and isinstance(node.args[0], ast.Name)
+                and node.args[0].id == "action"):
+            continue
+        actions = _resolve_actions(node.args[1], constants)
+        if actions is not None:
+            yield actions
 
 
 def _has_read(stem: str, aset: set) -> bool:
     # Match get_<stem>, list_<stem>, and plural get_<stem>s (e.g. add_keyframe -> get_keyframes).
-    candidates = {rp + stem for rp in READ_PREFIXES}
-    candidates |= {rp + stem + "s" for rp in READ_PREFIXES}
-    candidates |= {rp + stem.rstrip("s") for rp in READ_PREFIXES}
+    stems = {stem, *STEM_READ_ALIASES.get(stem, ())}
+    candidates = set(DIRECT_READ_ALIASES.get(stem, ()))
+    for candidate_stem in stems:
+        candidates |= {rp + candidate_stem for rp in READ_PREFIXES}
+        candidates |= {rp + candidate_stem + "s" for rp in READ_PREFIXES}
+        candidates |= {rp + candidate_stem.rstrip("s") for rp in READ_PREFIXES}
     return bool(candidates & aset)
 
 
@@ -60,19 +141,76 @@ def audit(src: str):
     return total, covered, sorted(high), sorted(low)
 
 
-def main():
-    src = open(SERVER, encoding="utf-8").read()
+def render_report(src: str) -> str:
     total, covered, high, low = audit(src)
-    print("# Read/Write Symmetry Audit\n")
-    print(f"- write-style actions scanned: **{total}**")
-    print(f"- with a matching read: **{covered}**")
-    print(f"- `set_` actions with no `get_`/`list_` (real readback gaps): **{len(high)}**\n")
+    lines = [
+        "<!-- Generated by scripts/audit_readwrite_symmetry.py — do not edit by hand. -->",
+        "",
+        "# Read/Write Symmetry Audit",
+        "",
+        f"- write-style action occurrences scanned: **{total}**",
+        f"- write-style action occurrences with a matching read: **{covered}**",
+        f"- distinct high-signal `set_` actions without a direct/known readback: **{len(high)}**",
+        "",
+    ]
     if high:
-        print("## High-signal gaps — `set_` with no read counterpart\n")
+        lines += [
+            "## High-signal gaps — `set_` with no direct/known readback",
+            "",
+        ]
         for a in high:
-            print(f"- `{a}`")
-    print(f"\n## Low-signal (create/add/insert/import — usually expected): {len(low)}\n")
-    print(", ".join(f"`{a}`" for a in low))
+            lines.append(f"- `{a}`")
+    lines += [
+        "",
+        f"## Low-signal (create/add/insert/apply/import — usually expected): "
+        f"{len(low)} distinct names",
+        "",
+        ", ".join(f"`{a}`" for a in low),
+    ]
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _parse_args(argv):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="fail if the committed report is out of date",
+    )
+    parser.add_argument(
+        "--stdout",
+        action="store_true",
+        help="print the report instead of writing it",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv=None):
+    if argv is None:
+        argv = sys.argv[1:]
+    args = _parse_args(argv)
+    with open(SERVER, encoding="utf-8") as fh:
+        src = fh.read()
+    content = render_report(src)
+    if args.stdout:
+        print(content, end="")
+        return 0
+    if args.check:
+        current = ""
+        if os.path.exists(DOC_PATH):
+            with open(DOC_PATH, encoding="utf-8") as fh:
+                current = fh.read()
+        if current != content:
+            print(
+                f"STALE: {DOC_REL} is out of date.\nRun: {REGEN_COMMAND}",
+                file=sys.stderr,
+            )
+            return 1
+        print(f"OK: {DOC_REL} is up to date.")
+        return 0
+    with open(DOC_PATH, "w", encoding="utf-8") as fh:
+        fh.write(content)
+    print(f"Wrote {DOC_REL}")
     return 0
 
 

package/scripts/gen_api_limitations.py

@@ -17,6 +17,7 @@ Run with ``--check`` to fail (exit 1) when the committed doc is stale.
 """
 from __future__ import annotations
 
+import argparse
 import sys
 from pathlib import Path
 
@@ -122,9 +123,22 @@ def render() -> str:
     return "\n".join(out).rstrip() + "\n"
 
 
+def _parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="fail if the committed report is out of date",
+    )
+    return parser.parse_args(argv)
+
+
 def main(argv: list[str]) -> int:
+    if argv is None:
+        raise TypeError("argv must not be None")
+    args = _parse_args(argv)
     content = render()
-    if "--check" in argv:
+    if args.check:
         current = DOC_PATH.read_text() if DOC_PATH.exists() else ""
         if current != content:
             print(

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.103.2"
+VERSION = "2.103.3"
 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 353-tool granular server instead
 """
 
-VERSION = "2.103.2"
+VERSION = "2.103.3"
 
 import base64
 import os

package/src/utils/media_analysis.py

@@ -200,6 +200,62 @@ def _annotate_clip_vision_failure(clip_result: Dict[str, Any], vision: Any) -> N
         })
 
 
+# Transcription statuses that mean "never attempted", as opposed to "attempted
+# and did not produce a transcript". Transcription is on by default
+# (DEFAULT_TRANSCRIPTION_ENABLED) and allow_model_download is off by default, so
+# a machine with no Whisper backend — or one that has simply not opted into model
+# downloads — reports "skipped" on every clip. Those are configuration states,
+# not clip failures, and counting them as failures fails every clip of every
+# batch on a default install.
+TRANSCRIPTION_UNATTEMPTED_STATUSES = frozenset({"skipped", "disabled", "not_implemented"})
+
+
+def transcription_attempt_failed(transcript: Any, *, enabled: bool) -> bool:
+    """True when requested transcription ran and still produced no transcript.
+
+    The vision counterpart is visual_analysis_completed, but vision defaults to
+    disabled, so it can treat every non-success as a failure. Transcription
+    defaults to enabled, so it has to separate "the backend refused to start" —
+    which is the normal state of an install without Whisper — from a real
+    failure such as a wall-clock timeout, a caps refusal, or a backend error.
+    """
+    if not enabled or not isinstance(transcript, dict):
+        return False
+    if transcript.get("success"):
+        return False
+    status = str(transcript.get("status") or "").strip().lower()
+    return status not in TRANSCRIPTION_UNATTEMPTED_STATUSES
+
+
+def _annotate_clip_transcript_failure(clip_result: Dict[str, Any], transcript: Any) -> None:
+    """Mark a clip failed when requested transcription did not complete.
+
+    execute_plan_async writes the analysis JSON and then hard-sets success True.
+    Vision already overwrites that via _annotate_clip_vision_failure; a
+    transcription timeout had no equivalent, so batch jobs counted an empty
+    transcript as succeeded. Callers gate on transcription_attempt_failed, which
+    keeps the "backend never ran" statuses out of the failure class.
+    """
+    status = ""
+    reason = ""
+    if isinstance(transcript, dict):
+        status = str(transcript.get("status") or "").strip()
+        reason = str(transcript.get("reason") or transcript.get("error") or "").strip()
+    if status == "wall_clock_timeout":
+        message = "Transcription timed out before a transcript was produced."
+        if reason:
+            message = f"{message} {reason}"
+    elif reason:
+        message = f"Transcription was requested but did not complete: {reason}"
+    else:
+        message = "Transcription was requested but did not complete."
+    clip_result.update({
+        "success": False,
+        "error": message,
+        "transcription": transcript,
+    })
+
+
 def _annotate_partial_success(manifest: Dict[str, Any]) -> None:
     """D3 — Mark batch manifests with explicit completed/failed clip-id lists.
 
@@ -5697,6 +5753,13 @@ async def execute_plan_async(
             and not vision_pending
             and not visual_analysis_completed(vision)
         )
+        transcript_failed = transcription_attempt_failed(
+            transcript,
+            enabled=_coerce_bool(
+                (options.get("transcription") or {}).get("enabled"),
+                default=DEFAULT_TRANSCRIPTION_ENABLED,
+            ),
+        )
         frame_count = int(clip_plan.get("analysis_keyframe_budget") or 0)
         marker_plan = _build_clip_marker_plan(
             record,
@@ -5757,6 +5820,8 @@ async def execute_plan_async(
             manifest["vision_pending"] = True
         elif vision_failed:
             _annotate_clip_vision_failure(clip_result, vision)
+        if transcript_failed:
+            _annotate_clip_transcript_failure(clip_result, transcript)
         manifest["clips"].append(clip_result)
 
     manifest["completed_at"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())

package/src/utils/media_analysis_jobs.py

@@ -745,6 +745,8 @@ def run_batch_job_slice(
                     _event(conn, job_id, "info", f"Clip {row['position'] + 1} {status}", {"clip": clip_result.get("record")})
                 else:
                     error = clip_result.get("error") or manifest.get("error") or "Clip analysis failed"
+                    if not isinstance(error, str):
+                        error = str(error)
                     conn.execute(
                         """
                         UPDATE job_clips
@@ -753,6 +755,10 @@ def run_batch_job_slice(
                         """,
                         (error, completed_at, completed_at, row["id"]),
                     )
+                    conn.execute(
+                        "UPDATE jobs SET last_error = ?, updated_at = ? WHERE job_id = ?",
+                        (error, completed_at, job_id),
+                    )
                     processed.append({"position": row["position"], "status": "failed", "error": error})
                     _event(conn, job_id, "error", f"Clip {row['position'] + 1} failed", {"error": error})
             except Exception as exc:  # pragma: no cover - defensive for arbitrary media/tool failures
@@ -766,6 +772,10 @@ def run_batch_job_slice(
                     (str(exc), completed_at, completed_at, row["id"]),
                 )
                 processed.append({"position": row["position"], "status": "failed", "error": str(exc)})
+                conn.execute(
+                    "UPDATE jobs SET last_error = ?, updated_at = ? WHERE job_id = ?",
+                    (str(exc), completed_at, job_id),
+                )
                 _event(conn, job_id, "error", f"Clip {row['position'] + 1} raised an exception", {"error": str(exc)})
             _sync_job_counts(conn, job_id)
             conn.commit()