davinci-resolve-mcp 2.69.3 → 2.70.1

package/scripts/install_resolve_bridge.py

@@ -3,9 +3,9 @@
     python scripts/install_resolve_bridge.py --probe-only    # settle the host model first
     python scripts/install_resolve_bridge.py                 # probe + bridge launcher
 
-Deploys to every applicable macOS/Linux location, including the sandboxed App
-Store container used by the free edition — which is why the free edition can be
-installed alongside a direct-download Studio without either disturbing the other.
+Deploys to every applicable macOS/Windows/Linux location, including the sandboxed
+App Store container used by the free edition — which is why the free edition can
+be installed alongside a direct-download Studio without either disturbing the other.
 
 Nothing is started here. Resolve must be restarted after installing so it
 re-scans the Scripts folders, and the script is then run from
@@ -76,6 +76,56 @@ _SANDBOX_FALLBACK_SUFFIX = "Library/Application Support/Fusion/Scripts/Utility"
 #: Containers that are not Resolve (RAW Player, Speed Test, the IO XPC helper).
 _NON_RESOLVE_CONTAINERS = ("BlackmagicRaw", "IOXPC")
 
+#: Windows Scripts/Utility trees, per Blackmagic's own README
+#: (docs/reference/resolve_scripting_api.txt, "Specific user"/"All users").
+#: Two traps, both live in those two lines:
+#:
+#: 1. The per-user tree carries a `Support` segment that the all-users tree does
+#:    NOT. They are not one layout under two roots, and deriving one from the
+#:    other lands in a folder Resolve never scans.
+#: 2. The README writes the per-user root as `%APPDATA%\Roaming\...`, which is
+#:    wrong — `%APPDATA%` already IS `...\AppData\Roaming`, so following it
+#:    literally yields `AppData\Roaming\Roaming\...`. The paths below drop the
+#:    doubled segment; both were confirmed present and writable on the Windows 11
+#:    machine in issue #106.
+_WINDOWS_USER_SCRIPTS_SUFFIX = (
+    "Blackmagic Design/DaVinci Resolve/Support/Fusion/Scripts/Utility"
+)
+_WINDOWS_ALL_USERS_SCRIPTS_SUFFIX = "Blackmagic Design/DaVinci Resolve/Fusion/Scripts/Utility"
+
+
+#: The product folder both Windows trees hang off. Its existence is the "Resolve
+#: is installed" signal — see `_windows_script_candidates`.
+_WINDOWS_PRODUCT_ROOT = "Blackmagic Design/DaVinci Resolve"
+
+
+def _windows_script_candidates() -> list[Path]:
+    """Scripts/Utility trees Resolve scans on Windows (issue #106).
+
+    Gated on the *product* folder, not the Scripts/Utility tree, for the same
+    reason the sandbox branch is: Resolve does not create its `Fusion/Scripts`
+    tree until a script is installed, so requiring the target to pre-exist skips
+    a fresh free-edition install — the one build the bridge exists for. The
+    product folder is created on first launch, so it answers "is Resolve
+    installed" without demanding a folder only we will ever create.
+
+    Per-user first: it is the one a non-elevated account can actually write,
+    while `%PROGRAMDATA%` typically needs an elevated prompt. Ordering it first
+    means the target that will succeed is also the one reported first.
+    """
+    candidates: list[Path] = []
+    for env_var, suffix in (
+        ("APPDATA", _WINDOWS_USER_SCRIPTS_SUFFIX),
+        ("PROGRAMDATA", _WINDOWS_ALL_USERS_SCRIPTS_SUFFIX),
+    ):
+        root = os.environ.get(env_var)
+        if not root:
+            continue
+        target = Path(root) / suffix
+        if target.is_dir() or (Path(root) / _WINDOWS_PRODUCT_ROOT).is_dir():
+            candidates.append(target)
+    return candidates
+
 
 def _is_resolve_container(path: Path) -> bool:
     if not path.name.startswith(_SANDBOX_MARKER):
@@ -91,28 +141,40 @@ def script_targets() -> list[Path]:
     coexist with a direct-download Studio install. Each container contributes
     TWO targets (see the module comment on issue #104): the documented tree
     first, then the Fusion standalone tree that Lite also scans.
+
+    Windows has no sandbox and no `~/Library`, so it gets its own candidate list
+    (issue #106) — without one this returned empty on every Windows machine and
+    the installer exited with "Is Resolve installed?" on a working install.
+    Those candidates arrive pre-vetted, like the sandboxed ones: they are gated
+    on Resolve's product folder rather than on the Scripts tree, which Resolve
+    does not create until a script is installed.
     """
     home = Path.home()
-    candidates = [
-        home / _SCRIPTS_SUFFIX,
-        Path("/") / _SCRIPTS_SUFFIX,
-        home / ".local/share/DaVinciResolve/Fusion/Scripts/Utility",
-    ]
-    containers = home / "Library/Containers"
-    sandboxed: list[Path] = []
-    if containers.is_dir():
-        for entry in sorted(containers.iterdir()):
-            if _is_resolve_container(entry) and (entry / "Data").is_dir():
-                sandboxed.append(entry / "Data" / _SCRIPTS_SUFFIX)
-                sandboxed.append(entry / "Data" / _SANDBOX_FALLBACK_SUFFIX)
+    # Pre-vetted targets, whose tree gets created rather than being required.
+    vetted: list[Path] = []
+    candidates: list[Path] = []
+    if sys.platform == "win32":
+        vetted.extend(_windows_script_candidates())
+    else:
+        candidates = [
+            home / _SCRIPTS_SUFFIX,
+            Path("/") / _SCRIPTS_SUFFIX,
+            home / ".local/share/DaVinciResolve/Fusion/Scripts/Utility",
+        ]
+        containers = home / "Library/Containers"
+        if containers.is_dir():
+            for entry in sorted(containers.iterdir()):
+                if _is_resolve_container(entry) and (entry / "Data").is_dir():
+                    # The container's existence is the signal; the tree gets created.
+                    vetted.append(entry / "Data" / _SCRIPTS_SUFFIX)
+                    vetted.append(entry / "Data" / _SANDBOX_FALLBACK_SUFFIX)
 
     usable: list[Path] = []
     for path in candidates:
         # Non-sandboxed: the install created the tree, so require it.
         if path.is_dir() or (path.parent.is_dir() and os.access(path.parent, os.W_OK)):
             usable.append(path)
-    # Sandboxed: the container's existence is the signal; the tree gets created.
-    usable.extend(sandboxed)
+    usable.extend(vetted)
     return list(dict.fromkeys(usable))
 
 
@@ -197,7 +259,23 @@ def framework_pythons() -> list[str]:
 
 
 def python_preflight() -> dict:
-    """Will Resolve list the Python probe we are about to install?"""
+    """Will Resolve list the Python probe we are about to install?
+
+    The framework-Python trap is **macOS-only**: `/Library/Frameworks/...` does
+    not exist on Windows or Linux, where Resolve finds Python by other means (the
+    registry, or the system interpreter). Running the macOS check there always
+    found nothing and emitted the macOS remediation — telling the Windows 11 user
+    in issue #106, who had a working python.org 3.12, to go install the Python
+    they already had. Report "no known reason it will not list" off macOS rather
+    than a false alarm; the Lua canary still ships either way, so a genuine
+    enumeration problem remains diagnosable.
+    """
+    if sys.platform != "darwin":
+        return {
+            "framework_pythons": [],
+            "resolve_will_list_python_scripts": True,
+            "advice": None,
+        }
     frameworks = framework_pythons()
     return {
         "framework_pythons": frameworks,
@@ -256,48 +334,41 @@ def install(*, probe_only: bool, port: int, rotate: bool) -> dict:
             "No writable DaVinci Resolve Scripts/Utility folder found. Is Resolve installed?"
         )
     installed: list[str] = []
+    # A target can be real, scanned by Resolve, and still unwritable — the
+    # Windows all-users tree under %PROGRAMDATA% needs elevation, and Windows
+    # `os.access(W_OK)` reports the read-only flag rather than the ACL, so the
+    # filter above cannot screen it out. One un-writable target must not abort an
+    # install that already succeeded into the per-user tree, so failures are
+    # collected and only a clean sweep is fatal.
+    skipped: list[tuple[str, str]] = []
     for target in targets:
-        target.mkdir(mode=0o700, parents=True, exist_ok=True)
-        for probe in ("resolve_bridge_probe.py", "resolve_capability_probe.py"):
-            shutil.copy2(REPO / "scripts" / probe, target / probe)
-            installed.append(str(target / probe))
-        # Lua always enumerates; Python only with a framework install. The canary
-        # makes "Python not detected" distinguishable from "wrong folder".
-        canary = target / "resolve_bridge_canary.lua"
-        canary.write_text(_LUA_CANARY, encoding="utf-8")
-        installed.append(str(canary))
-        if not probe_only:
-            runtime = target.parents[1] / ".davinci_mcp_runtime"
-            runtime.mkdir(mode=0o700, parents=True, exist_ok=True)
-            for module in ("resolve_bridge.py", "resolve_bridge_ops.py"):
-                shutil.copy2(REPO / "src/utils" / module, runtime / module)
-                installed.append(str(runtime / module))
-            # A sandboxed (App Store) build cannot read ~/.config at all — inside
-            # the container `~` IS the container, so an absolute real-home path is
-            # unreachable by construction (measured: "Operation not permitted").
-            # The runtime dir is already inside the container, so the config goes
-            # beside the modules. Same token, so the out-of-sandbox client still
-            # authenticates against ~/.config.
-            runtime_config = runtime / "bridge.json"
-            shutil.copy2(CONFIG_PATH, runtime_config)
-            os.chmod(runtime_config, 0o600)
-            installed.append(str(runtime_config))
-            # The launcher IS the menu entry. Without it the modules sit in the
-            # runtime dir with nothing able to start them.
-            launcher_source = (REPO / "scripts/resolve_bridge_launcher.py").read_text(encoding="utf-8")
-            launcher = launcher_source.replace(
-                "@@RUNTIME_ROOT_B64@@",
-                base64.urlsafe_b64encode(str(runtime).encode("utf-8")).decode("ascii"),
-            ).replace(
-                "@@CONFIG_PATH_B64@@",
-                base64.urlsafe_b64encode(str(CONFIG_PATH).encode("utf-8")).decode("ascii"),
-            )
-            launcher_path = target / "resolve_bridge.py"
-            launcher_path.write_text(launcher, encoding="utf-8")
-            installed.append(str(launcher_path))
+        try:
+            target.mkdir(mode=0o700, parents=True, exist_ok=True)
+            _install_to(target, probe_only=probe_only, installed=installed)
+        except OSError as exc:
+            skipped.append((str(target), str(exc)))
+    if not installed:
+        raise SystemExit(
+            "Found DaVinci Resolve Scripts/Utility folders but could not write to "
+            "any of them:\n"
+            + "\n".join(f"  {path}: {reason}" for path, reason in skipped)
+            + "\nRe-run from an account that can write these folders (on Windows, "
+            "the %PROGRAMDATA% tree needs an elevated prompt; the per-user "
+            "%APPDATA% tree does not)."
+        )
     result = {"installed": installed, "probe_only": probe_only, "python": python_preflight()}
     stale = stale_container_warning(targets)
     result["warnings"] = [stale] if stale else []
+    if skipped:
+        result["warnings"].append(
+            "Skipped "
+            + str(len(skipped))
+            + " unwritable Scripts/Utility folder(s): "
+            + "; ".join(f"{path} ({reason})" for path, reason in skipped)
+            + ". This is harmless as long as the bridge appears under "
+            "Workspace > Scripts."
+        )
+    result["skipped"] = [path for path, _ in skipped]
     if not probe_only:
         loaded = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
         result["config"] = {"path": str(CONFIG_PATH),
@@ -305,6 +376,53 @@ def install(*, probe_only: bool, port: int, rotate: bool) -> dict:
     return result
 
 
+def _install_to(target: Path, *, probe_only: bool, installed: list[str]) -> None:
+    """Place the probes, canary and (unless probe-only) the bridge into `target`.
+
+    Raises OSError if the target turns out to be unwritable; `install()` treats
+    that as a skip rather than a failure so one un-writable tree cannot abort an
+    install that succeeded elsewhere.
+    """
+    for probe in ("resolve_bridge_probe.py", "resolve_capability_probe.py"):
+        shutil.copy2(REPO / "scripts" / probe, target / probe)
+        installed.append(str(target / probe))
+    # Lua always enumerates; Python only with a framework install. The canary
+    # makes "Python not detected" distinguishable from "wrong folder".
+    canary = target / "resolve_bridge_canary.lua"
+    canary.write_text(_LUA_CANARY, encoding="utf-8")
+    installed.append(str(canary))
+    if probe_only:
+        return
+    runtime = target.parents[1] / ".davinci_mcp_runtime"
+    runtime.mkdir(mode=0o700, parents=True, exist_ok=True)
+    for module in ("resolve_bridge.py", "resolve_bridge_ops.py"):
+        shutil.copy2(REPO / "src/utils" / module, runtime / module)
+        installed.append(str(runtime / module))
+    # A sandboxed (App Store) build cannot read ~/.config at all — inside
+    # the container `~` IS the container, so an absolute real-home path is
+    # unreachable by construction (measured: "Operation not permitted").
+    # The runtime dir is already inside the container, so the config goes
+    # beside the modules. Same token, so the out-of-sandbox client still
+    # authenticates against ~/.config.
+    runtime_config = runtime / "bridge.json"
+    shutil.copy2(CONFIG_PATH, runtime_config)
+    os.chmod(runtime_config, 0o600)
+    installed.append(str(runtime_config))
+    # The launcher IS the menu entry. Without it the modules sit in the
+    # runtime dir with nothing able to start them.
+    launcher_source = (REPO / "scripts/resolve_bridge_launcher.py").read_text(encoding="utf-8")
+    launcher = launcher_source.replace(
+        "@@RUNTIME_ROOT_B64@@",
+        base64.urlsafe_b64encode(str(runtime).encode("utf-8")).decode("ascii"),
+    ).replace(
+        "@@CONFIG_PATH_B64@@",
+        base64.urlsafe_b64encode(str(CONFIG_PATH).encode("utf-8")).decode("ascii"),
+    )
+    launcher_path = target / "resolve_bridge.py"
+    launcher_path.write_text(launcher, encoding="utf-8")
+    installed.append(str(launcher_path))
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--probe-only", action="store_true",

package/scripts/mode_matrix.py

@@ -0,0 +1,345 @@
+#!/usr/bin/env python3
+"""Exhaustively difference GUI against headless Resolve, surviving hangs.
+
+    python scripts/mode_matrix.py run --mode gui      --out runs/gui.jsonl
+    python scripts/mode_matrix.py run --mode headless --out runs/headless.jsonl
+    python scripts/mode_matrix.py compare runs/gui.jsonl runs/headless.jsonl \
+        --out docs/reference/headless-capability-matrix.md
+
+## The architecture, and why it is not one script
+
+`ProjectManager.SaveProject()` on the never-saved `Untitled Project` never
+returns headless. Any harness that calls it in-process stops there, and its
+report is whatever it wrote before it died. The first differential could not have
+found that bug, and did not.
+
+So this splits in two:
+
+  - a **worker** that runs probes in order and streams each result to JSONL,
+    flushed per line;
+  - a **supervisor** that runs the worker with a deadline. If the worker exits
+    early or overruns, the supervisor reads the JSONL, sees which probe has no
+    result, records it as `hang`, restarts Resolve, waits for it to be healthy,
+    and relaunches the worker to resume *after* the offender.
+
+The consequence worth stating: a hang costs one probe and one Resolve restart,
+not the run. That is what makes "exhaustive" possible at all.
+
+## Health, not liveness
+
+Between batches the supervisor requires `GetCurrentDatabase()` to be non-None.
+Resolve can accept scripting connections, answer product/version/page queries,
+and still have no database attached — in that state every project call returns
+False forever. A liveness check passes straight through it; only the database
+reading catches it.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from src.utils import mode_matrix as mm  # noqa: E402
+from src.utils import resolve_runtime as rr  # noqa: E402
+from src.utils.probe_catalogue import CATALOGUE, fingerprint  # noqa: E402
+
+WORKER = Path(__file__).resolve().parent / "mode_matrix_worker.py"
+
+
+def scripting_env() -> Dict[str, str]:
+    env = dict(os.environ)
+    api = env.get(
+        "RESOLVE_SCRIPT_API",
+        "/Library/Application Support/Blackmagic Design/DaVinci Resolve/Developer/Scripting",
+    )
+    env["RESOLVE_SCRIPT_API"] = api
+    env.setdefault(
+        "RESOLVE_SCRIPT_LIB",
+        "/Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/Libraries/Fusion/fusionscript.so",
+    )
+    modules = str(Path(api) / "Modules")
+    env["PYTHONPATH"] = f"{modules}:{env['PYTHONPATH']}" if env.get("PYTHONPATH") else modules
+    env.pop("DAVINCI_RESOLVE_BRIDGE", None)
+    return env
+
+
+# ── Resolve supervision ──────────────────────────────────────────────────────
+
+
+def health(timeout: float = 420.0) -> Optional[Dict[str, Any]]:
+    """Wait for a Resolve whose ProjectManager has a database attached."""
+    code = (
+        "import DaVinciResolveScript as d, json, time, sys\n"
+        "for _ in range(int(sys.argv[1])):\n"
+        "    r = d.scriptapp('Resolve')\n"
+        "    if r is not None:\n"
+        "        try:\n"
+        "            pm = r.GetProjectManager()\n"
+        "            db = pm.GetCurrentDatabase() if pm else None\n"
+        "            if db:\n"
+        "                print(json.dumps(db)); sys.exit(0)\n"
+        "        except Exception: pass\n"
+        "    time.sleep(1)\n"
+        "sys.exit(3)\n"
+    )
+    try:
+        out = subprocess.run([sys.executable, "-c", code, str(int(timeout))],
+                             env=scripting_env(), capture_output=True, text=True,
+                             timeout=timeout + 60)
+    except subprocess.TimeoutExpired:
+        print("  health: timed out waiting for a database", file=sys.stderr)
+        return None
+    if out.returncode != 0:
+        # Say WHY. "no healthy Resolve" with no reason sent this investigation
+        # looking at Resolve twice when the probe subprocess had simply failed to
+        # start — an unhelpful error of exactly the kind this study keeps finding
+        # in the API it is measuring.
+        detail = (out.stderr or out.stdout or "").strip().splitlines()
+        print(f"  health: probe exited {out.returncode}"
+              + (f": {detail[-1][:200]}" if detail else " with no output"), file=sys.stderr)
+        return None
+    try:
+        return json.loads(out.stdout.strip().splitlines()[-1])
+    except Exception:
+        print(f"  health: unparseable output {out.stdout.strip()[:200]!r}", file=sys.stderr)
+        return None
+
+
+def stop_resolve(force_after: float = 30.0) -> str:
+    """Quit, escalating to a kill. Returns how it went."""
+    code = (
+        "import DaVinciResolveScript as d, signal\n"
+        "signal.signal(signal.SIGALRM, lambda *a: (_ for _ in ()).throw(SystemExit(7)))\n"
+        "signal.alarm(20)\n"
+        "r = d.scriptapp('Resolve')\n"
+        "r and r.Quit()\n"
+    )
+    subprocess.run([sys.executable, "-c", code], env=scripting_env(),
+                   capture_output=True, text=True, timeout=60, check=False)
+    deadline = time.monotonic() + force_after
+    while time.monotonic() < deadline:
+        if not (rr.resolve_processes() or []):
+            return "clean"
+        time.sleep(1)
+    subprocess.run(["pkill", "-9", "-f", "MacOS/Resolve"], check=False)
+    time.sleep(8)
+    return "forced"
+
+
+def start_resolve(headless: bool) -> bool:
+    command = rr.launch_command(headless=headless)
+    if command is None:
+        return False
+    subprocess.Popen(command, stdin=subprocess.DEVNULL,
+                     stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    return True
+
+
+def restart(headless: bool) -> Optional[Dict[str, Any]]:
+    how = stop_resolve()
+    print(f"    resolve stopped ({how}); restarting {'headless' if headless else 'gui'}", flush=True)
+    if not start_resolve(headless):
+        return None
+    # Generous: a boot after an unclean shutdown was measured at 2m05s to a
+    # usable script server, against under 3s clean. Giving up early here would
+    # abort the run for a Resolve that was merely slow.
+    return health(420.0)
+
+
+# ── the run ──────────────────────────────────────────────────────────────────
+
+
+def completed_probes(path: Path) -> Dict[str, Dict[str, Any]]:
+    results: Dict[str, Dict[str, Any]] = {}
+    if not path.exists():
+        return results
+    for line in path.read_text(errors="replace").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            record = json.loads(line)
+        except json.JSONDecodeError:
+            continue  # a torn final line from a killed worker
+        # `_start` breadcrumbs are phase markers, not results; `last_phase`
+        # reads them. Keyed apart so a marker can never be mistaken for an
+        # outcome.
+        if "probe" in record:
+            results[record["probe"]] = record
+    return results
+
+
+def last_phase(path: Path) -> Optional[Dict[str, Any]]:
+    """The most recent phase breadcrumb, naming what was in flight."""
+    if not path.exists():
+        return None
+    marker = None
+    for line in path.read_text(errors="replace").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            record = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if "_start" in record:
+            marker = record
+    return marker
+
+
+def append(path: Path, record: Dict[str, Any]) -> None:
+    with path.open("a") as handle:
+        handle.write(json.dumps(record, default=str) + "\n")
+
+
+def run(mode: str, out: Path, only: Optional[List[str]], batch_timeout: float) -> int:
+    headless = mode == "headless"
+    observed = rr.runtime_mode()
+    if observed["running"] and bool(observed["headless"]) != headless:
+        print(f"REFUSE: a Resolve is running in the other mode: {observed['command_lines']}",
+              file=sys.stderr)
+        return 1
+    if not observed["running"]:
+        start_resolve(headless)
+    db = health()
+    if db is None:
+        print("REFUSE: no healthy Resolve (no database attached).", file=sys.stderr)
+        return 2
+
+    # Blocking probes are opt-in by name. One of them stops the whole
+    # application in both modes, costing a force-kill and a slow restart, so a
+    # sweep that included them by default could never run to completion
+    # unattended — which is the entire point of a sweep.
+    if only:
+        planned = [p.name for p in CATALOGUE if p.name in only]
+    else:
+        planned = [p.name for p in CATALOGUE if not p.blocking]
+    skipped_blocking = [p.name for p in CATALOGUE if p.blocking and p.name not in planned]
+    out.parent.mkdir(parents=True, exist_ok=True)
+    print(f"mode={mode} db={json.dumps(db)} probes={len(planned)} out={out}", flush=True)
+    if skipped_blocking:
+        # Never silently: an excluded probe that vanishes from the report reads
+        # as one that passed.
+        print(f"  excluded (blocking, run explicitly with --only): {', '.join(skipped_blocking)}",
+              flush=True)
+
+    hangs = 0
+    while True:
+        done = completed_probes(out)
+        remaining = [n for n in planned if n not in done]
+        if not remaining:
+            break
+        print(f"  worker: {len(remaining)} probe(s) remaining, starting at {remaining[0]}", flush=True)
+        proc = subprocess.Popen(
+            [sys.executable, "-u", str(WORKER), "--out", str(out), "--probes", *remaining],
+            env=scripting_env(), stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True,
+        )
+        try:
+            proc.communicate(timeout=batch_timeout)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.communicate()
+
+        after = completed_probes(out)
+        newly = [n for n in remaining if n in after]
+        still = [n for n in remaining if n not in after]
+        if not still:
+            break
+        # The first unrecorded probe is the one that was in flight when the
+        # worker stopped. Nothing else can have taken it down: results are
+        # flushed per line, in order.
+        culprit = still[0]
+        probe = next(p for p in CATALOGUE if p.name == culprit)
+        marker = last_phase(out) or {}
+        phase = marker.get("phase") if marker.get("_start") == culprit else "unknown"
+        hangs += 1
+        print(f"  !! {culprit} did not return in phase={phase} "
+              f"(worker completed {len(newly)} probe(s) first)", flush=True)
+        append(out, {
+            "probe": culprit, "category": probe.category, "outcome": "hang",
+            "value": None, "seconds": None, "mode": mode, "phase": phase,
+            "catalogue": fingerprint(),
+            # A hang during `state` setup is NOT evidence about the probe's own
+            # call; it is evidence about reaching the state. Recorded as such so
+            # the comparison does not report a bug in the wrong place.
+            "detail": ("hung while setting up its state, not in the probe call itself"
+                       if phase == "state" else
+                       "worker died or overran with this probe's call in flight"),
+        })
+        if restart(headless) is None:
+            print("REFUSE: Resolve did not come back healthy after a hang.", file=sys.stderr)
+            return 3
+
+    results = completed_probes(out)
+    counts: Dict[str, int] = {}
+    for record in results.values():
+        counts[record.get("outcome", "?")] = counts.get(record.get("outcome", "?"), 0) + 1
+    print(json.dumps({"mode": mode, "probes": len(results), "outcomes": counts,
+                      "hangs_recovered": hangs}, indent=2))
+    return 0
+
+
+def compare(gui_paths: List[Path], headless_paths: List[Path], out: Optional[Path]) -> int:
+    gui_stores, headless_stores = [], []
+    for label, paths, sink in (("gui", gui_paths, gui_stores),
+                               ("headless", headless_paths, headless_stores)):
+        for path in paths:
+            store = completed_probes(path)
+            modes = {r.get("mode") for r in store.values()}
+            # A mislabeled file inverts every verdict silently; the recorded mode
+            # is the check, not the filename.
+            if modes and modes != {label}:
+                print(f"REFUSE: {path} was labelled {label} but contains {modes}", file=sys.stderr)
+                return 1
+            stamps = {r.get("catalogue") for r in store.values() if r.get("catalogue")}
+            if stamps and stamps != {fingerprint()}:
+                print(f"REFUSE: {path} was recorded with catalogue {stamps}, "
+                      f"current is {fingerprint()}. Re-run it; comparing across "
+                      f"catalogue versions reports harness changes as findings.",
+                      file=sys.stderr)
+                return 1
+            sink.append(store)
+    matrix = mm.build_repeated_matrix(gui_stores, headless_stores)
+    matrix["generated_at"] = datetime.now(timezone.utc).isoformat(timespec="seconds")
+    text = mm.render_markdown(matrix)
+    if out:
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(text, encoding="utf-8")
+        out.with_suffix(".json").write_text(json.dumps(matrix, indent=2, default=str), encoding="utf-8")
+    print(text)
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__,
+                                     formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest="command", required=True)
+    r = sub.add_parser("run")
+    r.add_argument("--mode", choices=("gui", "headless"), required=True)
+    r.add_argument("--out", type=Path, required=True)
+    r.add_argument("--only", nargs="*")
+    r.add_argument("--batch-timeout", type=float, default=900.0)
+    c = sub.add_parser("compare")
+    # Lists, not single files: one run per mode reports flakes as findings, which
+    # was measured happening. Repeats are how a difference is distinguished from
+    # noise.
+    c.add_argument("--gui", type=Path, nargs="+", required=True)
+    c.add_argument("--headless", type=Path, nargs="+", required=True)
+    c.add_argument("--out", type=Path)
+    args = parser.parse_args()
+    if args.command == "run":
+        return run(args.mode, args.out, args.only, args.batch_timeout)
+    return compare(args.gui, args.headless, args.out)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())