openmd-cli 0.1.0__py3-none-any.whl

openmd/routing/view.py

@@ -0,0 +1,40 @@
+"""Generate route views from the same declarations used by runtime selection."""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+from .loader import route_view
+
+
+def doctor_tools(*, probe_commands: bool = False):
+    from .providers import doctor_tools as build_report
+
+    return build_report(probe_commands=probe_commands)
+
+
+def render_routes_markdown(*, source: str | None = None, effective: bool = False) -> str:
+    view = route_view(source, effective=effective)
+    lines = ["# Openmd routes", "", f"Generated from bundled cards and routes, version `{view['version']}`.", "", "| Source | Capability | Ordered backends |", "|---|---|---|"]
+    for route in view["routes"]:
+        lines.append(f"| {route['source']} | {route['capability']} | {' → '.join(route['chain'])} |")
+    lines += ["", "Tools run only with the gates declared in their cards. Media steps require local ASR before producing text.", "", "Local overlay applied: " + str(view["overlay_applied"]).lower() + ".", ""]
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--source")
+    parser.add_argument("--format", choices=("json", "table", "markdown"), default="table")
+    parser.add_argument("--bundled", action="store_true", help="Use bundled routes only when generating repository documentation.")
+    args = parser.parse_args(argv)
+    if args.format == "json":
+        print(json.dumps(route_view(args.source, effective=not args.bundled), ensure_ascii=False, indent=2))
+    else:
+        print(render_routes_markdown(source=args.source, effective=not args.bundled), end="")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

openmd/runtime/__init__.py

@@ -0,0 +1 @@
+"""Local capability runtimes; the controller retains its own dependencies."""

openmd/runtime/_windows_job.py

@@ -0,0 +1,234 @@
+"""Windows Job ownership, including atomic assignment before child execution.
+
+Only imported on Windows. The small Popen creation hook uses STARTUPINFOEX's
+JOB_LIST (Windows 10+) so even controller death between CreateProcess and
+AssignProcessToJobObject cannot strand a suspended child. No global monkeypatch.
+"""
+
+from __future__ import annotations
+
+import ctypes as C
+from ctypes import wintypes as W
+import os
+import subprocess
+import sys
+import threading
+
+
+kernel = C.WinDLL("kernel32", use_last_error=True)
+SIZE = C.c_size_t
+
+
+class IO_COUNTERS(C.Structure):
+    _fields_ = [(name, C.c_ulonglong) for name in (
+        "ReadOperationCount", "WriteOperationCount", "OtherOperationCount",
+        "ReadTransferCount", "WriteTransferCount", "OtherTransferCount")]
+
+
+class BASIC_LIMITS(C.Structure):
+    _fields_ = [("PerProcessUserTimeLimit", C.c_longlong),
+                ("PerJobUserTimeLimit", C.c_longlong), ("LimitFlags", W.DWORD),
+                ("MinimumWorkingSetSize", SIZE), ("MaximumWorkingSetSize", SIZE),
+                ("ActiveProcessLimit", W.DWORD), ("Affinity", SIZE),
+                ("PriorityClass", W.DWORD), ("SchedulingClass", W.DWORD)]
+
+
+class EXTENDED_LIMITS(C.Structure):
+    _fields_ = [("BasicLimitInformation", BASIC_LIMITS), ("IoInfo", IO_COUNTERS),
+                ("ProcessMemoryLimit", SIZE), ("JobMemoryLimit", SIZE),
+                ("PeakProcessMemoryUsed", SIZE), ("PeakJobMemoryUsed", SIZE)]
+
+
+class BASIC_ACCOUNTING(C.Structure):
+    _fields_ = [(name, C.c_longlong) for name in ("TotalUserTime", "TotalKernelTime",
+                    "ThisPeriodTotalUserTime", "ThisPeriodTotalKernelTime")] + [
+                (name, W.DWORD) for name in ("TotalPageFaultCount", "TotalProcesses",
+                    "ActiveProcesses", "TotalTerminatedProcesses")]
+
+
+class STARTUPINFO(C.Structure):
+    _fields_ = [("cb", W.DWORD), ("lpReserved", W.LPWSTR),
+                ("lpDesktop", W.LPWSTR), ("lpTitle", W.LPWSTR),
+                *[(name, W.DWORD) for name in ("dwX", "dwY", "dwXSize", "dwYSize",
+                    "dwXCountChars", "dwYCountChars", "dwFillAttribute", "dwFlags")],
+                ("wShowWindow", W.WORD), ("cbReserved2", W.WORD),
+                ("lpReserved2", C.c_void_p), ("hStdInput", W.HANDLE),
+                ("hStdOutput", W.HANDLE), ("hStdError", W.HANDLE)]
+
+
+class STARTUPINFOEX(C.Structure):
+    _fields_ = [("StartupInfo", STARTUPINFO), ("lpAttributeList", C.c_void_p)]
+
+
+class PROCESS_INFORMATION(C.Structure):
+    _fields_ = [("hProcess", W.HANDLE), ("hThread", W.HANDLE),
+                ("dwProcessId", W.DWORD), ("dwThreadId", W.DWORD)]
+
+
+def _api(name, result, *args):
+    function = getattr(kernel, name)
+    function.restype, function.argtypes = result, args
+    return function
+
+
+CreateJobObject = _api("CreateJobObjectW", W.HANDLE, C.c_void_p, W.LPCWSTR)
+SetInformationJobObject = _api("SetInformationJobObject", W.BOOL, W.HANDLE, C.c_int, C.c_void_p, W.DWORD)
+AssignProcessToJobObject = _api("AssignProcessToJobObject", W.BOOL, W.HANDLE, W.HANDLE)
+TerminateJobObject = _api("TerminateJobObject", W.BOOL, W.HANDLE, W.UINT)
+QueryInformationJobObject = _api("QueryInformationJobObject", W.BOOL, W.HANDLE, C.c_int, C.c_void_p, W.DWORD, C.c_void_p)
+WaitForSingleObject = _api("WaitForSingleObject", W.DWORD, W.HANDLE, W.DWORD)
+CloseHandle = _api("CloseHandle", W.BOOL, W.HANDLE)
+ResumeThread = _api("ResumeThread", W.DWORD, W.HANDLE)
+TerminateProcess = _api("TerminateProcess", W.BOOL, W.HANDLE, W.UINT)
+InitializeProcThreadAttributeList = _api("InitializeProcThreadAttributeList", W.BOOL, C.c_void_p, W.DWORD, W.DWORD, C.POINTER(SIZE))
+UpdateProcThreadAttribute = _api("UpdateProcThreadAttribute", W.BOOL, C.c_void_p, W.DWORD, SIZE, C.c_void_p, SIZE, C.c_void_p, C.c_void_p)
+DeleteProcThreadAttributeList = _api("DeleteProcThreadAttributeList", None, C.c_void_p)
+CreateProcess = _api("CreateProcessW", W.BOOL, W.LPCWSTR, W.LPWSTR, C.c_void_p, C.c_void_p,
+                     W.BOOL, W.DWORD, C.c_void_p, W.LPCWSTR,
+                     C.POINTER(STARTUPINFOEX), C.POINTER(PROCESS_INFORMATION))
+OpenThread = _api("OpenThread", W.HANDLE, W.DWORD, W.BOOL, W.DWORD)
+CancelSynchronousIo = _api("CancelSynchronousIo", W.BOOL, W.HANDLE)
+
+
+def _checked(result):
+    if not result:
+        raise C.WinError(C.get_last_error())
+    return result
+
+
+class Job:
+    def __init__(self):
+        self.lock = threading.Lock()
+        self.handle = _checked(CreateJobObject(None, None))
+        try:
+            limits = EXTENDED_LIMITS()
+            limits.BasicLimitInformation.LimitFlags = 0x2000  # KILL_ON_JOB_CLOSE
+            _checked(SetInformationJobObject(self.handle, 9, C.byref(limits), C.sizeof(limits)))
+        except BaseException:
+            self.close()
+            raise
+
+    def close(self):
+        with self.lock:
+            if self.handle:
+                handle, self.handle = self.handle, None
+                try:
+                    # Terminate explicitly; closing also protects controller crashes.
+                    _checked(TerminateJobObject(handle, 1))
+                    # Termination is asynchronous. Waiting on the Job object
+                    # itself is the kernel synchronization point for the whole
+                    # tree; ActiveProcesses can reach zero before the process
+                    # handles and inherited file handles are fully released.
+                    WaitForSingleObject(handle, 2000)
+                finally:
+                    CloseHandle(handle)
+
+    def __del__(self):
+        if getattr(self, "handle", None):
+            CloseHandle(self.handle)
+
+
+def cancel_thread_io(thread):
+    if thread is not None and thread.is_alive() and thread.native_id:
+        handle = OpenThread(0x0001, False, thread.native_id)  # THREAD_TERMINATE
+        if handle:
+            try:
+                CancelSynchronousIo(handle)
+            finally:
+                CloseHandle(handle)
+
+
+class JobPopen(subprocess.Popen):
+    """Keep Popen's pipe/text/wait implementation; customize only OS creation.
+
+    Signature follows CPython's Windows Popen._execute_child; tested on 3.12.
+    Creation errors fail closed: never silently launch without Job ownership.
+    """
+
+    def _execute_child(self, args, executable, preexec_fn, close_fds, pass_fds,
+                       cwd, env, startupinfo, creationflags, shell,
+                       p2cread, p2cwrite, c2pread, c2pwrite, errread, errwrite,
+                       *unused, **unused_kwargs):
+        if pass_fds:
+            raise ValueError("pass_fds not supported on Windows")
+        if isinstance(args, (bytes, os.PathLike)):
+            if shell:
+                raise TypeError("bytes/path-like args is not allowed with shell")
+            args = subprocess.list2cmdline([args])
+        elif not isinstance(args, str):
+            args = subprocess.list2cmdline(args)
+        executable = os.fsdecode(executable) if executable is not None else None
+        startupinfo = startupinfo.copy() if startupinfo is not None else subprocess.STARTUPINFO()
+        if startupinfo.lpAttributeList and set(startupinfo.lpAttributeList) - {"handle_list"}:
+            raise ValueError("Unsupported Windows startup attribute")
+        native = STARTUPINFOEX()
+        native.StartupInfo.cb = C.sizeof(native)
+        native.StartupInfo.dwFlags = startupinfo.dwFlags
+        native.StartupInfo.wShowWindow = startupinfo.wShowWindow
+        handles = list((startupinfo.lpAttributeList or {}).get("handle_list", []))
+        if -1 not in (p2cread, c2pwrite, errwrite):
+            native.StartupInfo.dwFlags |= 0x100  # STARTF_USESTDHANDLES
+            native.StartupInfo.hStdInput = int(p2cread)
+            native.StartupInfo.hStdOutput = int(c2pwrite)
+            native.StartupInfo.hStdError = int(errwrite)
+            handles += [int(p2cread), int(c2pwrite), int(errwrite)]
+        handles = self._filter_handle_list(handles)
+        if shell:
+            native.StartupInfo.dwFlags |= 1
+            native.StartupInfo.wShowWindow = 0
+            executable = executable or os.environ.get("ComSpec") or os.path.join(os.environ.get("SystemRoot", ""), "System32", "cmd.exe")
+            if not os.path.isabs(executable):
+                raise FileNotFoundError("An absolute Windows shell path is required")
+            args = f'{executable} /c "{args}"'
+        cwd = os.fsdecode(cwd) if cwd is not None else None
+        environment = None
+        if env is not None:
+            entries = []
+            for key, value in sorted(env.items(), key=lambda pair: pair[0].upper()):
+                if "\0" in key or "\0" in value or "=" in key[1:] or not key:
+                    raise ValueError("illegal environment variable")
+                entries.append(f"{key}={value}")
+            environment = C.create_unicode_buffer("\0".join(entries) + "\0\0")
+        size = SIZE()
+        InitializeProcThreadAttributeList(None, 2 if handles else 1, 0, C.byref(size))
+        attributes = C.create_string_buffer(size.value)
+        _checked(InitializeProcThreadAttributeList(attributes, 2 if handles else 1, 0, C.byref(size)))
+        native.lpAttributeList = C.cast(attributes, C.c_void_p)
+        info = PROCESS_INFORMATION()
+        try:
+            # JOB_LIST assigns at CreateProcess itself, closing the crash window.
+            jobs = (W.HANDLE * 1)(self._openmd_owner.handle)
+            _checked(UpdateProcThreadAttribute(attributes, 0, 0x2000D, jobs, C.sizeof(jobs), None, None))
+            if handles:
+                inherited = (W.HANDLE * len(handles))(*handles)
+                _checked(UpdateProcThreadAttribute(attributes, 0, 0x20002, inherited, C.sizeof(inherited), None, None))
+            sys.audit("subprocess.Popen", executable, args, cwd, env)
+            _checked(CreateProcess(executable, C.create_unicode_buffer(args), None, None,
+                       bool(handles) or not close_fds,
+                       creationflags | 0x4 | 0x80000 | 0x400,  # SUSPENDED/EXTENDED/UNICODE
+                       environment, cwd, C.byref(native), C.byref(info)))
+            self._child_created = True
+            self._handle = subprocess.Handle(info.hProcess)
+            self.pid = info.dwProcessId
+            # Already in this Job atomically; explicit assignment validates it
+            # before any child code can run or spawn a grandchild.
+            _checked(AssignProcessToJobObject(self._openmd_owner.handle, info.hProcess))
+            if ResumeThread(info.hThread) == 0xFFFFFFFF:
+                raise C.WinError(C.get_last_error())
+        except BaseException:
+            if info.hProcess:
+                TerminateProcess(info.hProcess, 1)
+            raise
+        finally:
+            if info.hThread:
+                CloseHandle(info.hThread)
+            DeleteProcThreadAttributeList(attributes)
+            self._close_pipe_fds(p2cread, p2cwrite, c2pread, c2pwrite, errread, errwrite)
+
+    def __init__(self, *args, **kwargs):
+        self._openmd_owner = Job()
+        try:
+            super().__init__(*args, **kwargs)
+        except BaseException:
+            self._openmd_owner.close()
+            raise

openmd/runtime/asr.py

@@ -0,0 +1,217 @@
+"""ASR factory and bounded worker protocol used by every controller entrypoint."""
+
+from __future__ import annotations
+
+import json
+import hashlib
+import math
+import os
+import subprocess
+import tempfile
+from dataclasses import asdict, fields, replace
+from pathlib import Path
+from typing import Any
+
+from openmd.adapters.local_audio.asr import ASRBackend
+from openmd.core.models import COMPONENT_STATUS_VALUES, FAILURE_CLASS_VALUES, SOURCE_LEVEL_VALUES, STATUS_VALUES, ExtractionComponent, TranscriptResult
+from openmd.core.secrets import sanitize_error_summary
+from .interpreters import owned_popen, AsrRuntime, display_path, kill_process_tree, process_options, remove_tree_with_retry, select_asr_runtime, terminate_quietly, wait_interruptibly, worker_command, worker_environment
+
+from openmd.runtime.tempdirs import owned_mkdtemp
+from openmd.runtime.interpreters import run_interruptibly
+
+
+ASR_BACKENDS = ("asr.auto", "asr.faster_whisper", "asr.qwen3")
+
+
+def local_backend(name: str) -> ASRBackend:
+    if name == "asr.auto":
+        from openmd.adapters.local_audio.backends.auto import AutoASRBackend
+
+        return AutoASRBackend()
+    if name == "asr.faster_whisper":
+        from openmd.adapters.local_audio.backends.faster_whisper import FasterWhisperASRBackend
+
+        return FasterWhisperASRBackend()
+    if name == "asr.qwen3":
+        from openmd.adapters.local_audio.backends.qwen3_asr import Qwen3ASRBackend
+
+        return Qwen3ASRBackend()
+    raise ValueError(f"Unknown local ASR backend: {name}")
+
+
+def backend_execution_config(name: str) -> dict[str, Any]:
+    """Constructing fingerprints never starts a GPU probe or imports a model."""
+    from openmd.core.local_config import load_local_config
+    from .models import checkout_root
+
+    config = local_backend(name).execution_config()
+    local = load_local_config()
+    explicit = os.getenv("OPENMD_ASR_PYTHON") or local.get("asr_python")
+    root = checkout_root()
+    candidates = [Path(explicit).expanduser()] if explicit else [Path(os.sys.executable)]
+    if not explicit and root:
+        candidates.append(root / "out/asr-bench/venv" / ("Scripts/python.exe" if os.name == "nt" else "bin/python"))
+    identities = []
+    for candidate in candidates:
+        if not candidate.is_absolute():
+            candidate = (root or Path.cwd()) / candidate
+        try:
+            stamp = candidate.stat().st_mtime_ns
+        except OSError:
+            stamp = None
+        identities.append({"path": str(candidate.resolve()), "mtime_ns": stamp})
+    # Hash locations/settings for resume identity without publishing machine paths
+    # or starting a GPU probe during argument parsing.
+    settings = {key: value for key, value in os.environ.items() if key.startswith(("OPENMD_FASTER_WHISPER_", "OPENMD_ASR_AUTO_", "OPENMD_QWEN3_")) or key in {"OPENMD_MODEL_ROOTS", "OPENMD_ASR_CHINESE_SCRIPT", "CUDA_VISIBLE_DEVICES", "HF_HOME", "HF_HUB_CACHE", "MODELSCOPE_CACHE"}}
+    identity = {"interpreters": identities, "model_roots": local.get("model_roots", []), "settings": settings, "backend": config}
+    config_id = hashlib.sha256(json.dumps(identity, sort_keys=True, ensure_ascii=True).encode()).hexdigest()
+    return {**config, "runtime_policy": "local_worker_v2", "runtime_configured": bool(explicit), "runtime_source": "explicit" if explicit else "checkout" if root else "current_interpreter", "runtime_config_id": config_id}
+
+
+def get_asr_backend(name: str = "asr.auto") -> ASRBackend:
+    if name not in ASR_BACKENDS:
+        raise ValueError(f"Unknown local ASR backend: {name}")
+    # Resolve lazily: provider registration, health checks and execution fingerprints
+    # must not load torch or wait for a worker probe.
+    return WorkerASRBackend(name)
+
+
+def failed_result(name: str, code: str, error: object) -> TranscriptResult:
+    return TranscriptResult(text="", status="failed", source_level="partial_extraction", backend=name, error_code=code, error_summary=sanitize_error_summary(error), source_notes=["Local ASR did not produce usable text; no cloud service or model download was used."], metadata={"profile": "media", "asr_backend": name})
+
+
+def serialize_result(result: TranscriptResult) -> dict[str, Any]:
+    return {"schema": "openmd.asr-result/v1", "result": asdict(result)}
+
+
+def deserialize_result(payload: object) -> TranscriptResult:
+    if not isinstance(payload, dict) or payload.get("schema") != "openmd.asr-result/v1":
+        raise ValueError("invalid ASR worker schema")
+    result = payload.get("result")
+    if not isinstance(result, dict) or set(result) - {item.name for item in fields(TranscriptResult)}:
+        raise ValueError("invalid ASR result fields")
+    if not isinstance(result.get("text"), str) or result.get("status") not in STATUS_VALUES or result.get("source_level") not in SOURCE_LEVEL_VALUES or result.get("backend") not in ASR_BACKENDS:
+        raise ValueError("invalid ASR result status, source or backend")
+    for key in ("error_code", "error_summary", "title", "author", "published_at", "extraction_contract_version"):
+        if result.get(key) is not None and not isinstance(result[key], str):
+            raise ValueError(f"invalid ASR result {key}")
+    notes = result.get("source_notes", [])
+    metadata = result.get("metadata", {})
+    if not isinstance(notes, list) or not all(isinstance(note, str) for note in notes) or not isinstance(metadata, dict):
+        raise ValueError("invalid ASR notes or metadata")
+    components = result.get("components", [])
+    if not isinstance(components, list):
+        raise ValueError("invalid ASR components")
+    decoded: list[ExtractionComponent] = []
+    for component in components:
+        if not isinstance(component, dict) or set(component) - {item.name for item in fields(ExtractionComponent)}:
+            raise ValueError("invalid ASR component fields")
+        if component.get("status") not in COMPONENT_STATUS_VALUES or component.get("source_level") not in SOURCE_LEVEL_VALUES:
+            raise ValueError("invalid ASR component status")
+        if any(not isinstance(component.get(key), str) for key in ("id", "kind", "backend")):
+            raise ValueError("invalid ASR component identity")
+        if component.get("failure_class") is not None and component["failure_class"] not in FAILURE_CLASS_VALUES:
+            raise ValueError("invalid ASR component failure class")
+        for key in ("text_ref", "terminal_reason", "error_code"):
+            if component.get(key) is not None and not isinstance(component[key], str):
+                raise ValueError(f"invalid ASR component {key}")
+        warnings = component.get("warnings", [])
+        if not isinstance(warnings, list) or any(not isinstance(warning, str) for warning in warnings):
+            raise ValueError("invalid ASR component warnings")
+        decoded.append(ExtractionComponent(**component))
+    if result["status"] in {"verified", "partial"} and not result["text"].strip():
+        raise ValueError("successful ASR result has no text")
+    return TranscriptResult(**{**result, "source_notes": notes, "metadata": metadata, "components": decoded})
+
+
+def _timeout_for_audio(path: Path) -> float:
+    try:
+        done = run_interruptibly(["ffprobe", "-v", "error", "-show_entries", "format=duration", "-of", "default=noprint_wrappers=1:nokey=1", str(path)], stdin=subprocess.DEVNULL, capture_output=True, timeout=10, check=True)
+        duration = float(done.stdout.strip())
+        return max(600.0, min(duration * 2, 12 * 60 * 60)) if math.isfinite(duration) and duration >= 0 else 600.0
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return 600.0
+
+
+class WorkerASRBackend(ASRBackend):
+    def __init__(self, name: str, python: Path | None = None) -> None:
+        self.name = name
+        self.python = python
+
+    def execution_config(self) -> dict[str, Any]:
+        return backend_execution_config(self.name)
+
+    def is_available(self) -> bool:
+        return self._runtime().mode != "unavailable"
+
+    def _runtime(self) -> AsrRuntime:
+        if self.python is not None:
+            return AsrRuntime("worker", self.python, "Explicit worker instance")
+        return select_asr_runtime(backend=self.name)
+
+    def transcribe(self, path: Path) -> TranscriptResult:
+        from .gpu_quarantine import GPUQuarantined
+
+        try:
+            return self._transcribe(path)
+        except TimeoutError as exc:
+            return failed_result(self.name, "gpu_lock_timeout", exc)
+        except GPUQuarantined as exc:
+            return failed_result(self.name, exc.code, exc)
+
+    def _transcribe(self, path: Path) -> TranscriptResult:
+        path = path.expanduser().resolve()
+        if not path.is_file():
+            return failed_result(self.name, "asr_file_not_found", "Local audio file not found")
+        try:
+            runtime = self._runtime()
+        except (OSError, ValueError) as exc:
+            return failed_result(self.name, "asr_runtime_unavailable", exc)
+        if runtime.mode == "in_process":
+            from .gpu_lock import gpu_lock, release_torch_cache
+
+            with gpu_lock():
+                try:
+                    result = local_backend(self.name).transcribe(path)
+                finally:
+                    release_torch_cache()
+            return replace(result, source_notes=[*result.source_notes, runtime.reason], metadata={**result.metadata, "asr_runtime": {"mode": "in_process", "reason": runtime.reason}})
+        if runtime.mode == "unavailable" or runtime.python is None:
+            reports = runtime.probe.get("attempts", [runtime.probe])
+            missing = sorted({name for report in reports if isinstance(report, dict) for name, model in report.get("models", {}).items() if not model.get("available", False)})
+            if missing:
+                return failed_result(self.name, "asr_model_missing", runtime.reason + "; missing or incomplete local models: " + ", ".join(missing))
+            return failed_result(self.name, "asr_runtime_unavailable", runtime.reason)
+        workdir = owned_mkdtemp(prefix="openmd-asr-worker-")
+        try:
+            result_path = Path(workdir) / "result.json"
+            command = worker_command(runtime.python, "--backend", self.name, "--input", str(path), "--result", str(result_path))
+            try:
+                # Library chatter is bounded to a file and never becomes protocol data.
+                with (Path(workdir) / "worker.log").open("wb") as log:
+                    process = owned_popen(command, stdin=subprocess.DEVNULL, stdout=log, stderr=log, env=worker_environment(), cwd=workdir, **process_options())
+                    try:
+                        wait_interruptibly(process, _timeout_for_audio(path))
+                    except subprocess.TimeoutExpired:
+                        terminate_quietly(process)
+                        return failed_result(self.name, "asr_worker_timeout", "Local ASR worker exceeded its bounded time limit")
+                    except BaseException:
+                        # Ctrl+C must surface as cancellation, never as a worker failure.
+                        terminate_quietly(process)
+                        raise
+                if process.returncode:
+                    with (Path(workdir) / "worker.log").open("rb") as log:
+                        log.seek(max(0, log.seek(0, 2) - 2048))
+                        detail = log.read().decode("utf-8", errors="replace")
+                    return failed_result(self.name, "asr_worker_failed", detail or f"Worker exited with code {process.returncode}")
+                if not result_path.is_file() or result_path.stat().st_size > 64 * 1024 * 1024:
+                    raise ValueError("worker result missing or exceeds size limit")
+                result = deserialize_result(json.loads(result_path.read_text(encoding="utf-8")))
+                return replace(result, metadata={**result.metadata, "asr_runtime": {"mode": "worker", "python": display_path(runtime.python)}})
+            except (OSError, ValueError, TypeError, subprocess.SubprocessError) as exc:
+                return failed_result(self.name, "asr_worker_failed", exc)
+        finally:
+            # A killed worker's grandchild can briefly keep its cwd open on Windows; cleanup is
+            # retried and best-effort so it can never replace the original exception.
+            remove_tree_with_retry(Path(workdir))

openmd/runtime/asr_worker.py

@@ -0,0 +1,119 @@
+"""Offline ASR worker. Only a result file carries transcript protocol data."""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import importlib.metadata
+import importlib.util
+import json
+import os
+import platform
+import sys
+import time
+from dataclasses import replace
+from pathlib import Path
+
+
+def build_probe() -> dict:
+    from .interpreters import REQUIRED_MODULES, display_path
+    from .models import configured_models
+
+    modules = {name: importlib.util.find_spec(name) is not None for name in REQUIRED_MODULES}
+    versions = {}
+    for name, distribution in (("torch", "torch"), ("ctranslate2", "ctranslate2"), ("faster_whisper", "faster-whisper"), ("qwen_asr", "qwen-asr"), ("funasr", "funasr")):
+        try:
+            versions[name] = importlib.metadata.version(distribution)
+        except importlib.metadata.PackageNotFoundError:
+            versions[name] = None
+    report = {"schema": "openmd.asr-probe/v1", "python": display_path(Path(sys.executable)), "version": platform.python_version(), "modules": modules, "versions": versions, "torch_cuda_build": None, "torch_cuda_available": False, "ctranslate2_cuda_devices": 0, "gpu_name": None, "models": {key: model.as_dict() for key, model in configured_models().items()}, "ready": False}
+    errors = []
+    try:
+        if modules["torch"]:
+            import torch
+
+            report["torch_cuda_build"] = torch.version.cuda
+            report["torch_cuda_available"] = torch.cuda.is_available()
+            if report["torch_cuda_available"]:
+                report["gpu_name"] = torch.cuda.get_device_name(0)
+        if modules["faster_whisper"]:
+            from openmd.adapters.local_audio.backends.faster_whisper import _prepare_windows_dll_paths
+
+            _prepare_windows_dll_paths()
+        if modules["ctranslate2"]:
+            import ctranslate2
+
+            report["ctranslate2_cuda_devices"] = ctranslate2.get_cuda_device_count()
+    except Exception as exc:
+        from openmd.core.secrets import sanitize_error_summary
+
+        errors.append(sanitize_error_summary(exc))
+    report["ready"] = all(modules.values()) and report["torch_cuda_available"] and report["ctranslate2_cuda_devices"] > 0 and all(model["available"] for model in report["models"].values())
+    report["backend_readiness"] = {
+        "asr.faster_whisper": modules["faster_whisper"] and modules["ctranslate2"] and report["models"]["whisper-large-v3"]["available"],
+        "asr.qwen3": all(modules[key] for key in ("torch", "qwen_asr", "funasr", "soundfile")) and report["torch_cuda_available"] and all(report["models"][key]["available"] for key in ("qwen3-asr-1.7b", "fsmn-vad-zh")),
+        "asr.auto": report["ready"],
+    }
+    if os.getenv("OPENMD_ASR_AUTO_ZH_ENGINE") == "whisper":
+        report["backend_readiness"]["asr.auto"] = report["backend_readiness"]["asr.faster_whisper"] and report["models"]["whisper-large-v3-turbo"]["available"]
+    report["errors"] = errors
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--probe", action="store_true")
+    parser.add_argument("--backend", choices=("asr.auto", "asr.faster_whisper", "asr.qwen3"))
+    parser.add_argument("--input", type=Path)
+    parser.add_argument("--result", type=Path)
+    args = parser.parse_args(argv)
+    os.environ.update({"OPENMD_ASR_WORKER": "1", "HF_HUB_OFFLINE": "1", "TRANSFORMERS_OFFLINE": "1", "MODELSCOPE_OFFLINE": "1"})
+    if args.probe:
+        with contextlib.redirect_stdout(sys.stderr):
+            report = build_probe()
+        print(json.dumps(report, ensure_ascii=True, allow_nan=False))
+        return 0
+    if args.backend is None or args.input is None or args.result is None:
+        parser.error("--backend, --input and --result are required")
+    from .asr import serialize_result
+    from .gpu_quarantine import GPUQuarantined
+
+    # Share a structured failure with the controller; never initialize an ASR
+    # model when quarantine recovery fails inside the lease acquisition.
+    try:
+        return _transcribe_locked(args)
+    except GPUQuarantined as exc:
+        from .asr import failed_result
+
+        args.result.write_text(json.dumps(serialize_result(failed_result(args.backend, exc.code, exc))), encoding="utf-8")
+        return 0
+
+
+def _transcribe_locked(args) -> int:
+    from .asr import local_backend, serialize_result
+    from .gpu_lock import gpu_lock, release_torch_cache
+
+    # The inference process owns the lease. If its controller crashes, an orphan
+    # worker keeps the lease until its inference exits, so a new OCR cannot race it.
+    with gpu_lock():
+        started = time.perf_counter()
+        try:
+            with contextlib.redirect_stdout(sys.stderr):
+                result = local_backend(args.backend).transcribe(args.input)
+            torch = sys.modules.get("torch")
+            execution = {"python_version": platform.python_version(), "torch_cuda_build": None, "torch_cuda_available": False,
+                         "elapsed_seconds": round(time.perf_counter() - started, 3)}
+            if torch is not None:
+                execution.update({"torch_cuda_build": torch.version.cuda, "torch_cuda_available": torch.cuda.is_available()})
+                if execution["torch_cuda_available"]:
+                    execution.update({"gpu_name": torch.cuda.get_device_name(0), "torch_peak_allocated_bytes": torch.cuda.max_memory_allocated(),
+                                      "torch_peak_reserved_bytes": torch.cuda.max_memory_reserved()})
+        finally:
+            release_torch_cache()
+    result = replace(result, metadata={**result.metadata, "asr_execution": execution})
+    args.result.write_text(json.dumps(serialize_result(result), ensure_ascii=False, allow_nan=False), encoding="utf-8")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())