davinci-resolve-mcp 2.79.2 → 2.80.0

package/CHANGELOG.md

@@ -2,6 +2,66 @@
 
 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.80.0
+
+Three community PRs from @staahlarkitektur, all found on Windows, all real. Each is merged with
+its diagnosis intact and a fix on top for what the patch didn't reach.
+
+### Added
+
+- **`background=true` now actually runs the analysis.** `background`/`async_job` were accepted on
+  `analyze_clip` / `analyze_bin` / `analyze_file` / `analyze_project` / `analyze_sequence` and
+  silently ignored — the call ran the whole analysis inline and returned no `job_id`, which from
+  the caller's side is indistinguishable from a hang (#119). The two async opt-ins are now
+  distinct and both do what their names say:
+  - `prefer_handle=true` — creates the durable batch job and hands it back **queued**. Nothing
+    runs until you call `run_batch_job_slice`. Unchanged contract.
+  - `background=true` / `async_job=true` — creates the job **and drives it to completion
+    off-thread**, matching what `background` means on every other tool in this server. Poll
+    `batch_job_status` until `completed` / `completed_with_errors` / `canceled`.
+
+  Aliasing the two, as the PR proposed, would have replaced one silence with a quieter one: a job
+  that nothing ever advanced, polled forever. The runner deliberately does **not** hold the
+  Resolve busy gate — analysis drives ffmpeg, whisper and vision over file paths and touches the
+  scripting bridge nowhere, so holding it for an hour of transcription would lock the editor out
+  for nothing. A process-wide slice lock bounds the real cost instead: queued analyses interleave
+  a clip at a time rather than starting N ffmpeg passes at once.
+
+### Fixed
+
+- **A timeout could take 82 seconds to report a 5-second limit.** `subprocess.run(timeout=...)`
+  kills only the direct child. On Windows a bare-name PATH lookup can resolve to a shim
+  (Chocolatey, npm, a pip console script) that runs the real work as a grandchild, so the kill hit
+  the wrapper while the real `ffmpeg` kept running — and the follow-up read blocked on the pipe
+  handles it had inherited. Measured on a Chocolatey-managed machine: `ffmpeg` on PATH was a 392KB
+  shim, and a 5s timeout against an ~82s pass returned after the full 82s with "timed out after
+  5s" attached to complete, correct output (#120). `_run_command` now spawns via `Popen` in its own
+  session/process group and kills the whole tree. Beyond the PR: the kill helper no longer raises
+  (`killpg` returns EPERM, `taskkill` can be missing from PATH — either escaped and broke the
+  return contract mid-failure), the read after the kill is bounded and says so when it gives up
+  rather than hanging on a survivor, and a cancellation mid-run kills the tree instead of orphaning
+  it. Fixes every `_run_command` caller at once — the whisper CLI and every ffmpeg pass in
+  `_readthrough_analysis`, `silence_ripple`, and `deep_vision`.
+- **The whisper CLI inherited a `PYTHONHOME` that killed it.** `PYTHONHOME`/`PYTHONPATH` point this
+  server at Resolve's bundled Python so `DaVinciResolveScript` imports. Inherited by a child that
+  is itself a *different* Python, they corrupt its stdlib resolution — and whisper's CLI is exactly
+  that. Measured: whisper on 3.14 inheriting a 3.10 `PYTHONHOME` dies on `AssertionError: SRE
+  module mismatch` (#118). The whisper subprocess now gets a scrubbed environment. This is the
+  **shipped Windows configuration**, not a local quirk: `install.py` writes `PYTHONHOME` into
+  generated client configs (issue #26) and `server.py` sets it on Windows whenever it isn't
+  already set, so every Windows install hands a foreign `PYTHONHOME` to every child it spawns.
+
+### Corrected in the merged PRs
+
+- The documented async return shape was wrong — `{job_id, status}` was advertised, the real
+  envelope is `{success, job, plan}` with the id at `job.job_id`. Now documented as it is, plus
+  `running` and a `note` naming the next call so the queued and running routes can't be confused.
+- The async divert ran *after* `dry_run` was resolved from the `dry_run_first_default` preference,
+  so a user with that preference on still got `background=true` swallowed in silence. An explicit
+  `dry_run` still wins; an inherited one no longer does.
+- A code comment attributed the whisper failure to a silent stall with an ffmpeg child at 0% CPU —
+  a diagnosis the PR's own description retracted, and one that belongs to the shim problem above.
+
 ## What's New in v2.79.2
 
 A published contract was **wrong**. This release corrects it. If you read the retime entry in

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.79.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.80.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(341%20full)-blue.svg)](#server-modes)

package/install.py

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

package/src/granular/common.py

@@ -85,7 +85,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.79.2"
+VERSION = "2.80.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.79.2"
+VERSION = "2.80.0"
 
 import base64
 import os
@@ -104,9 +104,11 @@ from src.utils.media_analysis_jobs import (
     batch_job_status as media_analysis_batch_job_status,
     cancel_batch_job as cancel_media_analysis_batch_job,
     create_batch_job as create_media_analysis_batch_job,
+    join_batch_job_runner as join_media_analysis_batch_job_runner,
     list_batch_jobs as list_media_analysis_batch_jobs,
     resume_batch_job as resume_media_analysis_batch_job,
     run_batch_job_slice as run_media_analysis_batch_job_slice,
+    start_batch_job_runner as start_media_analysis_batch_job_runner,
 )
 from src.utils.platform import get_resolve_paths, get_resolve_plugin_paths
 from src.utils.resolve_connection import connect_resolve
@@ -8241,6 +8243,49 @@ def _media_analysis_bool(value: Any, default: bool = False) -> bool:
     return bool(value)
 
 
+MEDIA_ANALYSIS_ASYNC_QUEUED = "queued"
+MEDIA_ANALYSIS_ASYNC_RUNNING = "running"
+
+
+def _media_analysis_async_mode(p: Dict[str, Any], *, dry_run_explicit: bool = True) -> Optional[str]:
+    """How an analyze_* call wants its work handled. None means synchronously.
+
+    Two opt-ins, deliberately not synonyms:
+
+      prefer_handle        -> "queued".  Create the durable batch job and hand
+                              it back. Nothing runs until the caller drives
+                              run_batch_job_slice. This is the pre-existing
+                              contract and is unchanged.
+      background/async_job -> "running". Create the job AND drive it off-thread,
+                              so the work is under way when the call returns.
+
+    The split exists because `background` already means something specific
+    everywhere else in this server — _run_maybe_background starts the work and
+    the caller polls until it finishes on its own. Before, these two params were
+    accepted here and silently ignored: the analyze_* actions collapsed to
+    action="plan" and ran to completion inline, so a caller got no job_id and no
+    signal, indistinguishable from a hang. Aliasing them onto prefer_handle
+    would have replaced that with a job that never progressed — a quieter
+    failure than the one being fixed. So `background` keeps its meaning and gets
+    the runner it always implied.
+
+    `dry_run` still wins, but only when the caller asked for it. Pass
+    dry_run_explicit=False when p["dry_run"] came from the dry_run_first_default
+    preference rather than the call: a preference should not silently swallow an
+    explicit async request and hand back a plan the caller never asked for,
+    which is the same silence this whole change is closing.
+    """
+    if dry_run_explicit and _media_analysis_bool(p.get("dry_run"), False):
+        return None
+    if _media_analysis_bool(p.get("background"), False) or _media_analysis_bool(
+        p.get("async_job"), False
+    ):
+        return MEDIA_ANALYSIS_ASYNC_RUNNING
+    if _media_analysis_bool(p.get("prefer_handle"), False):
+        return MEDIA_ANALYSIS_ASYNC_QUEUED
+    return None
+
+
 def _media_analysis_target_dict(raw_target: Any, p: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     p = p or {}
     if raw_target is None:
@@ -17928,12 +17973,22 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
       set_ai_governance(preset?, mode?, overrides?) -> {success, tier, mode, overrides} — set the tier, the mode (advisory|enforce), and/or overrides (deblur_runs, speech_runs, render_bytes, render_wall_clock_ms; int or "unlimited"). In enforce mode a blocked run returns GOVERNANCE_BLOCKED; pass override_governance=true on the op to consciously exceed the tier once.
       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}
-      analyze_clip(clip_id|selected, dry_run?, session_only?, persist?) -> {clips, manifest}
-      analyze_bin(path|bin_path, recursive?, dry_run?, session_only?, persist?) -> {clips, manifest}
-      analyze_project(recursive?, dry_run?, session_only?, persist?) -> {clips, manifest}
-      analyze_sequence(timeline_index?, track_types?, dry_run?, session_only?, persist?) -> {clips, manifest}
+      analyze_file(path|file_path, dry_run?, session_only?, persist?, prefer_handle?|background?|async_job?) -> {clips, manifest} | {success, job, plan, running, note} when async
+      analyze_clip(clip_id|selected, dry_run?, session_only?, persist?, prefer_handle?|background?|async_job?) -> {clips, manifest} | {success, job, plan, running, note} when async
+      analyze_bin(path|bin_path, recursive?, dry_run?, session_only?, persist?, prefer_handle?|background?|async_job?) -> {clips, manifest} | {success, job, plan, running, note} when async
+      analyze_project(recursive?, dry_run?, session_only?, persist?, prefer_handle?|background?|async_job?) -> {clips, manifest} | {success, job, plan, running, note} when async
+      analyze_sequence(timeline_index?, track_types?, dry_run?, session_only?, persist?, prefer_handle?|background?|async_job?) -> {clips, manifest} | {success, job, plan, running, note} when async
       analyze_timeline(...) -> alias for analyze_sequence on the current timeline
+      -- async opt-ins on the analyze_* actions above. Both reroute to start_batch_job and return its
+         {success, job, plan} envelope — the id is job.job_id, NOT a top-level job_id — plus `running`
+         and a `note` naming the next call. They differ in what happens next:
+           prefer_handle=true        job is created and left queued; nothing runs until you call
+                                     run_batch_job_slice yourself. Unchanged contract.
+           background|async_job=true job is created AND driven to completion off-thread, matching what
+                                     `background` means on every other tool here. Poll batch_job_status
+                                     until status is completed / completed_with_errors / canceled.
+         An explicit dry_run=true still returns the synchronous plan and starts nothing. A dry_run that
+         came from the dry_run_first_default preference does not override an explicit async request.
       detect_sync_events(paths?|target?, event_types?, windows?) -> {files, alignment}
       add_sync_event_markers(target?|paths?|detections?, confirm?) -> {added, skipped}
       publish_clip_metadata(target?, fields?, slate_detection?, timed_markers?|write_markers?, dry_run?, confirm?) -> {results}
@@ -18787,21 +18842,56 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
             if warnings:
                 target_err["warnings"] = warnings
             return target_err
+        capabilities = detect_media_analysis_capabilities()
         created = create_media_analysis_batch_job(
             project_name=project_name,
             project_id=project_id,
             records=records or [],
             target=normalized_target,
             params=p,
-            capabilities=detect_media_analysis_capabilities(),
+            capabilities=capabilities,
             name=p.get("name") or p.get("job_name") or p.get("jobName"),
         )
         if warnings:
             created.setdefault("warnings", warnings)
+        # A created job sits at "queued" and nothing advances it on its own.
+        # That is the right default for start_batch_job and prefer_handle, whose
+        # contract is "here is a handle, drive it". It is the wrong one for
+        # background/async_job, which promise the work is under way — so those
+        # get a runner. Reached either by the analyze_* divert (which sets
+        # _async_mode) or by calling start_batch_job with background=true.
+        job_id = str((created.get("job") or {}).get("job_id") or "")
+        project_root = str((created.get("plan") or {}).get("output_root") or "")
+        wants_runner = p.get("_async_mode") == MEDIA_ANALYSIS_ASYNC_RUNNING or (
+            _media_analysis_bool(p.get("background"), False)
+            or _media_analysis_bool(p.get("async_job"), False)
+        )
+        if wants_runner and job_id and project_root:
+            started = start_media_analysis_batch_job_runner(
+                project_root, job_id, capabilities=capabilities
+            )
+            created["running"] = bool(started.get("started"))
+            created["note"] = (
+                f"Analysis is running off-thread. Poll with "
+                f"media_analysis(action='batch_job_status', params={{'job_id': '{job_id}'}})."
+            )
+            if not started.get("started"):
+                created["note"] = (
+                    f"Job created but not started ({started.get('reason')}). Drive it with "
+                    f"media_analysis(action='run_batch_job_slice', params={{'job_id': '{job_id}'}})."
+                )
+        else:
+            created["running"] = False
+            created["note"] = (
+                f"Job is queued, not running. Drive it with "
+                f"media_analysis(action='run_batch_job_slice', params={{'job_id': '{job_id}'}}), "
+                f"or pass background=true to have the server run it."
+            )
         return created
 
     if action in {"analyze_file", "analyze_clip", "analyze_bin", "analyze_project", "analyze_timeline", "analyze_sequence"}:
         dry_run_default = bool(_media_analysis_effective_preferences().get("dry_run_first_default"))
+        dry_run_explicit = _has_any_param(p, "dry_run", "dryRun")
         p["dry_run"] = _media_analysis_bool(p.get("dry_run"), dry_run_default)
         target = _media_analysis_target_dict(p.get("target"), p)
         if target.get("_invalid_target"):
@@ -18821,15 +18911,17 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
                 "track_types": p.get("track_types") or p.get("trackTypes") or target.get("track_types") or target.get("trackTypes"),
             })
         p["target"] = target
-        # E3 — `prefer_handle` opt-in. When true AND this isn't a dry-run,
-        # divert to the durable batch-job machinery so the call returns a
-        # job_id immediately instead of blocking on vision/transcription.
-        # Default false: existing blocking semantics are preserved.
+        # E3 — async opt-ins. `prefer_handle` hands back a queued job for the
+        # caller to drive; `background`/`async_job` additionally start driving
+        # it. Either way the call returns at once instead of blocking on
+        # vision/transcription. Default: unchanged blocking semantics.
         # The start_batch_job handler lives ABOVE this block in the dispatch
         # chain, so we can't just rewrite `action` and fall through — we
         # re-enter the tool with the rewritten action via await so the
         # handler chain restarts from the top.
-        if _media_analysis_bool(p.get("prefer_handle"), False) and not p.get("dry_run"):
+        async_mode = _media_analysis_async_mode(p, dry_run_explicit=dry_run_explicit)
+        if async_mode:
+            p["_async_mode"] = async_mode
             return await media_analysis("start_batch_job", p, ctx)
         action = "plan"
 

package/src/utils/media_analysis.py

@@ -17,6 +17,7 @@ import os
 import platform as _platform
 import re
 import shutil
+import signal
 import sqlite3
 import subprocess
 import sys
@@ -2376,23 +2377,105 @@ def build_plan(
     }
 
 
-def _run_command(args: List[str], timeout: int = COMMAND_TIMEOUT_SECONDS) -> Tuple[int, str, str]:
+def _kill_process_tree(pid: int) -> None:
+    """Best-effort: terminate pid and its descendants, not just the direct child.
+
+    Popen.kill() reaches only the immediate child. On Windows a bare-name PATH
+    lookup can resolve to a wrapper — a Chocolatey/npm shim, a pip console
+    script — that runs the real work as a grandchild, which a single-PID kill
+    leaves untouched. Measured: `ffmpeg` on PATH was a 392KB shim, and a 5s
+    timeout against an ~82s real ffmpeg pass had no effect at all, because the
+    surviving grandchild still held the stdout/stderr handles it had inherited
+    and the follow-up read blocked until it finished on its own.
+
+    Failure here is never fatal. The caller is already on its error path and
+    owes its own caller a (code, stdout, stderr) tuple, so this must not raise:
+    `taskkill` can be absent from PATH and `killpg` can return EPERM, which is
+    why the whole branch catches OSError rather than only ProcessLookupError.
+    """
     try:
-        proc = subprocess.run(
+        if os.name == "nt":
+            subprocess.run(
+                ["taskkill", "/F", "/T", "/PID", str(pid)],
+                capture_output=True,
+                check=False,
+            )
+        else:
+            os.killpg(pid, signal.SIGKILL)
+    except OSError:
+        pass
+
+
+# How long to wait for the pipes to drain after a tree kill. The kill is
+# best-effort, so this read has to be bounded: anything that escaped it still
+# holds the inherited pipe handles, and an unbounded read there would hang for
+# exactly the reason the kill exists.
+_POST_KILL_DRAIN_SECONDS = 5
+
+
+def _run_command(
+    args: List[str],
+    timeout: int = COMMAND_TIMEOUT_SECONDS,
+    env: Optional[Dict[str, str]] = None,
+) -> Tuple[int, str, str]:
+    """Run args to completion and return (returncode, stdout, stderr).
+
+    Spawned via Popen rather than subprocess.run so a timeout can kill the whole
+    process tree instead of one PID — see _kill_process_tree.
+
+    `env=None` inherits this process's environment, matching what subprocess.run
+    did. Pass an explicit mapping for a child that must not inherit it: on
+    Windows this server sets PYTHONHOME so the fusionscript bridge can find
+    Resolve's Python, and a child that is itself a *different* Python (the
+    whisper CLI) dies loading a foreign stdlib against its own C extensions.
+
+    Returns 124 on timeout, 127 when the binary cannot be spawned.
+    """
+    popen_kwargs: Dict[str, Any] = {}
+    if os.name == "nt":
+        # Isolates the child from console signals sent to the server. Note this
+        # is not what makes the tree kill work — taskkill /T walks parent-child
+        # links, not process groups. start_new_session is load-bearing on POSIX,
+        # where killpg needs the child to lead a group of its own.
+        popen_kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+    else:
+        popen_kwargs["start_new_session"] = True
+    try:
+        proc = subprocess.Popen(
             args,
-            capture_output=True,
-            timeout=timeout,
-            check=False,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            env=env,
+            **popen_kwargs,
         )
-    except subprocess.TimeoutExpired as exc:
-        stdout = exc.stdout.decode("utf-8", errors="replace") if exc.stdout else ""
-        stderr_tail = exc.stderr.decode("utf-8", errors="replace") if exc.stderr else ""
-        return 124, stdout, f"Command timed out after {timeout}s. {stderr_tail}".strip()
     except OSError as exc:
         return 127, "", str(exc)
-    stdout = proc.stdout.decode("utf-8", errors="replace") if proc.stdout else ""
-    stderr = proc.stderr.decode("utf-8", errors="replace") if proc.stderr else ""
-    return proc.returncode, stdout, stderr
+    try:
+        stdout, stderr = proc.communicate(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        _kill_process_tree(proc.pid)
+        abandoned = False
+        try:
+            stdout, stderr = proc.communicate(timeout=_POST_KILL_DRAIN_SECONDS)
+        except subprocess.TimeoutExpired:
+            # A descendant outlived the tree kill and still holds the pipes.
+            # Give up the output rather than block — a stalled caller is a
+            # worse outcome than a timeout report with no stderr tail.
+            stdout, stderr = b"", b""
+            abandoned = True
+        stdout_s = stdout.decode("utf-8", errors="replace") if stdout else ""
+        stderr_s = stderr.decode("utf-8", errors="replace") if stderr else ""
+        detail = " Output abandoned: a descendant survived the kill." if abandoned else ""
+        return 124, stdout_s, f"Command timed out after {timeout}s.{detail} {stderr_s}".strip()
+    except BaseException:
+        # subprocess.run kills the child on any exception on the way out;
+        # Popen does not. Under the server's threaded dispatch a cancellation
+        # or KeyboardInterrupt here would otherwise leave an orphaned tree.
+        _kill_process_tree(proc.pid)
+        raise
+    stdout_s = stdout.decode("utf-8", errors="replace") if stdout else ""
+    stderr_s = stderr.decode("utf-8", errors="replace") if stderr else ""
+    return proc.returncode, stdout_s, stderr_s
 
 
 def _write_json(path: str, payload: Dict[str, Any]) -> None:
@@ -4023,7 +4106,28 @@ def _transcribe_with_whisper_cli(path: str, artifacts: Dict[str, Any], transcrip
     ]
     if transcription.get("language"):
         cmd.extend(["--language", str(transcription["language"])])
-    code, _, stderr = _run_command(cmd, timeout=int(transcription.get("timeout", 1800)))
+    # PYTHONHOME/PYTHONPATH point this server at Resolve's bundled Python so
+    # DaVinciResolveScript imports. Inherited by a child that is itself a
+    # *different* Python, they corrupt its stdlib resolution — and the whisper
+    # CLI is exactly that: a Python program, frequently on another interpreter
+    # entirely. Measured: whisper under Python 3.14 inheriting a 3.10
+    # PYTHONHOME loads 3.10's stdlib against its own compiled extensions and
+    # dies on `AssertionError: SRE module mismatch`. That crash is fast, not a
+    # hang; it only reads as one when something else delays the response.
+    #
+    # This is the shipped Windows configuration, not a local quirk: install.py
+    # writes PYTHONHOME into generated client configs (see docs/install.md,
+    # issue #26), and server.py sets it on Windows whenever it isn't already
+    # set. So every Windows install hands a foreign PYTHONHOME to every child
+    # it spawns, and any Python-based tool added here needs the same scrub.
+    #
+    # PYTHONIOENCODING=utf-8 is unrelated: it avoids a UnicodeEncodeError in
+    # whisper's own argparse help text on a non-UTF-8 console.
+    whisper_env = dict(os.environ)
+    whisper_env.pop("PYTHONHOME", None)
+    whisper_env.pop("PYTHONPATH", None)
+    whisper_env["PYTHONIOENCODING"] = "utf-8"
+    code, _, stderr = _run_command(cmd, timeout=int(transcription.get("timeout", 1800)), env=whisper_env)
     if code != 0:
         return {"success": False, "backend": "whisper_cli", "error": stderr.strip() or "whisper CLI failed"}
     json_files = sorted(Path(work_dir).glob("*.json"), key=lambda p: p.stat().st_mtime, reverse=True)

package/src/utils/media_analysis_jobs.py

@@ -13,6 +13,7 @@ import hashlib
 import json
 import os
 import sqlite3
+import threading
 import time
 from pathlib import Path
 from typing import Any, Dict, Iterable, List, Optional, Tuple
@@ -795,6 +796,135 @@ def run_batch_job_slice(
     }
 
 
+# A job reaching one of these is finished; the runner stops rather than
+# spinning on a queue that will never drain.
+TERMINAL_JOB_STATUSES = {"completed", "completed_with_errors", "canceled"}
+
+# Runner threads in flight, keyed by (project_root, job_id). Starting a second
+# runner for a job already being driven is a no-op, not a second pump — two
+# pumps on one job would race for the same pending rows.
+_ACTIVE_RUNNERS: Dict[Tuple[str, str], threading.Thread] = {}
+_RUNNERS_LOCK = threading.Lock()
+
+# Exactly one slice executes at a time across the whole process. Slices are
+# bounded (max_clips defaults to 1), so several jobs interleave a clip at a
+# time instead of one starving the others — and a laptop never ends up running
+# N ffmpeg/whisper passes at once because someone queued N analyses.
+_SLICE_LOCK = threading.Lock()
+
+
+def _job_status_value(root: str, job_id: str) -> Optional[str]:
+    """Current status string for a job, or None if it no longer exists.
+
+    Deliberately not batch_job_status: that assembles every clip row and event
+    for the caller, and the runner only needs the one column between slices.
+    """
+    conn = _connect_jobs(root)
+    try:
+        row = conn.execute("SELECT status FROM jobs WHERE job_id = ?", (job_id,)).fetchone()
+        return str(row["status"]) if row else None
+    finally:
+        conn.close()
+
+
+def _drive_batch_job(root: str, job_id: str, capabilities: Optional[Dict[str, Any]], max_clips: int) -> None:
+    """Run slices back to back until the job finishes, is canceled, or stalls."""
+    try:
+        while True:
+            status = _job_status_value(root, job_id)
+            if status is None or status in TERMINAL_JOB_STATUSES:
+                return
+            with _SLICE_LOCK:
+                result = run_batch_job_slice(
+                    root, job_id, max_clips=max_clips, capabilities=capabilities
+                )
+            if not result.get("success"):
+                return
+            # No pending rows left to claim. Either the job just finished (the
+            # status check above catches that next pass) or it is wedged; in
+            # both cases another identical slice would be a spin.
+            if not int(result.get("processed_count") or 0):
+                return
+            if str((result.get("job") or {}).get("status") or "") in TERMINAL_JOB_STATUSES:
+                return
+    except Exception as exc:  # pragma: no cover - defensive; per-clip errors are handled in the slice
+        conn = _connect_jobs(root)
+        try:
+            _event(conn, job_id, "error", "Batch job runner stopped", {"error": f"{type(exc).__name__}: {exc}"})
+            conn.commit()
+        except Exception:
+            pass
+        finally:
+            conn.close()
+    finally:
+        with _RUNNERS_LOCK:
+            _ACTIVE_RUNNERS.pop((root, job_id), None)
+
+
+def start_batch_job_runner(
+    project_root: str,
+    job_id: str,
+    *,
+    capabilities: Optional[Dict[str, Any]] = None,
+    max_clips: int = 1,
+) -> Dict[str, Any]:
+    """Drive a queued batch job to completion on a daemon thread.
+
+    This is what makes `background=true` mean the same thing on the analyze_*
+    actions as it does everywhere else in the server: the work is running when
+    the call returns, and the caller polls until it stops. Without it,
+    start_batch_job only ever left a row at status "queued" that nothing
+    advanced, so a caller that trusted the name waited forever.
+
+    Deliberately NOT routed through background_jobs.start_job, which wraps its
+    worker in resolve_busy.long_resolve_op. That gate exists to serialize calls
+    against Resolve's single-threaded scripting bridge, and analysis touches it
+    nowhere — media_analysis and this module drive ffmpeg, whisper and vision
+    over file paths only. Holding the gate for an hour of transcription would
+    lock the editor out of Resolve for the duration, for no benefit.
+
+    Returns {"started": bool, "reason": str} — `started` is False when a runner
+    is already driving this job or the job is already finished, neither of
+    which is an error.
+    """
+    root = normalize_path(project_root)
+    key = (root, job_id)
+    status = _job_status_value(root, job_id)
+    if status is None:
+        return {"started": False, "reason": "job_not_found"}
+    if status in TERMINAL_JOB_STATUSES:
+        return {"started": False, "reason": f"job_already_{status}"}
+    with _RUNNERS_LOCK:
+        existing = _ACTIVE_RUNNERS.get(key)
+        if existing is not None and existing.is_alive():
+            return {"started": False, "reason": "already_running"}
+        thread = threading.Thread(
+            target=_drive_batch_job,
+            args=(root, job_id, capabilities, max(1, int(max_clips or 1))),
+            name=f"media-analysis-job-{job_id}",
+            daemon=True,
+        )
+        _ACTIVE_RUNNERS[key] = thread
+    thread.start()
+    return {"started": True, "reason": "running"}
+
+
+def join_batch_job_runner(project_root: str, job_id: str, timeout: Optional[float] = None) -> bool:
+    """Block until this job's runner exits. True if it is gone, False on timeout.
+
+    A daemon thread dies with the process, so a server restart leaves a job
+    stuck at "running" with nothing driving it — resume_batch_job is the way
+    back from that. This exists so tests (and any caller that genuinely needs
+    to wait) don't have to poll the database.
+    """
+    with _RUNNERS_LOCK:
+        thread = _ACTIVE_RUNNERS.get((normalize_path(project_root), job_id))
+    if thread is None:
+        return True
+    thread.join(timeout)
+    return not thread.is_alive()
+
+
 def project_root_for_dashboard(project_name: Any, project_id: Any = None, analysis_root: Any = None, source_paths: Optional[Iterable[Any]] = None) -> Dict[str, Any]:
     return resolve_output_root(
         project_name=project_name,