openmd-cli 0.1.0__py3-none-any.whl

openmd/runtime/managed_tools.py

@@ -0,0 +1,204 @@
+"""Tools Openmd installs and runs for the user, so one `pip install openmd-cli` is enough.
+
+opencli (Apache-2.0, npm `@jackwener/opencli`) powers the browser-session
+routes (Bilibili subtitles, Weixin, X, Douyin ...). Node.js comes from the
+`nodejs-wheel-binaries` dependency; opencli itself is installed once, on first
+need, into ``<data>/tools/opencli`` at a pinned version.
+
+A user's own `opencli` on PATH always wins and is never modified.
+Set ``OPENMD_AUTO_INSTALL_TOOLS=0`` to disable the automatic install, and
+``OPENMD_NPM_REGISTRY`` to use a registry mirror.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import shutil
+import stat
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Callable
+
+from openmd.core.preferences import data_directory
+from openmd.runtime.interpreters import run_interruptibly
+
+OPENCLI_PACKAGE = "@jackwener/opencli"
+OPENCLI_VERSION = "2.0.3"
+OPENCLI_BRIDGE_STORE_URL = "https://chromewebstore.google.com/detail/opencli/ildkmabpimmkaediidaifkhjpohdnifk"
+_host_package_warning_shown = False
+
+
+def node_dir() -> Path | None:
+    """Directory holding the bundled `node` executable, if the wheel is installed."""
+    spec = importlib.util.find_spec("nodejs_wheel")
+    if spec is None or not spec.origin:
+        return None
+    root = Path(spec.origin).parent
+    folder = root if os.name == "nt" else root / "bin"
+    return folder if (folder / ("node.exe" if os.name == "nt" else "node")).is_file() else None
+
+
+def _npm_cli(node: Path) -> Path | None:
+    root = node if os.name == "nt" else node.parent
+    candidate = root / "lib" / "node_modules" / "npm" / "bin" / "npm-cli.js"
+    return candidate if candidate.is_file() else None
+
+
+def managed_root() -> Path:
+    return data_directory() / "tools" / "opencli"
+
+
+def managed_bin() -> Path:
+    return managed_root() / "node_modules" / ".bin"
+
+
+def managed_package_root() -> Path:
+    """Package root used by plugins when the managed host is active."""
+    return managed_root() / "node_modules" / "@jackwener" / "opencli"
+
+
+def _managed_ready() -> bool:
+    return (managed_bin() / ("opencli.cmd" if os.name == "nt" else "opencli")).is_file()
+
+
+def _prepend_path(*folders: Path) -> None:
+    current = os.environ.get("PATH", "").split(os.pathsep)
+    additions = [str(f) for f in folders if str(f) not in current]
+    if additions:
+        os.environ["PATH"] = os.pathsep.join([*additions, *current])
+
+
+def _is_junction(path: Path) -> bool:
+    # Path.is_symlink() does not identify junctions on Python 3.10/3.11.
+    try:
+        return getattr(path.lstat(), "st_reparse_tag", None) == getattr(stat, "IO_REPARSE_TAG_MOUNT_POINT", 0xA0000003)
+    except FileNotFoundError:
+        return False
+
+
+def _create_junction(source: Path, target: Path) -> None:
+    if os.name != "nt":
+        raise OSError("Directory junctions require Windows")
+    import _winapi
+
+    _winapi.CreateJunction(str(source.resolve()), str(target))
+
+
+def _prepare_bundled_node_host_package() -> None:
+    """Expose the managed host at the bundled Node resolution root.
+
+    Some user plugins were compiled by older OpenCLI versions that resolve
+    ``@jackwener/opencli`` relative to ``process.execPath``.  The managed
+    install keeps Node and npm under one private runtime directory, so provide
+    the same package shape there without touching ``~/.opencli`` or a user's
+    plugin directory.
+    """
+    global _host_package_warning_shown
+    node = node_dir()
+    source = managed_package_root()
+    if node is None or not source.is_dir():
+        return
+    target = node / "node_modules" / "@jackwener" / "opencli"
+    try:
+        junction = _is_junction(target)
+        if junction or target.is_symlink():
+            try:
+                if target.resolve() == source.resolve():
+                    return
+            except OSError:
+                pass
+            # rmdir removes only the junction, never the linked package tree.
+            if junction:
+                target.rmdir()
+            else:
+                target.unlink(missing_ok=True)
+        elif target.exists():
+            # Never replace a real package supplied by the Node runtime.
+            return
+        target.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            target.symlink_to(source, target_is_directory=True)
+        except OSError:
+            _create_junction(source, target)
+    except OSError:
+        if not _host_package_warning_shown:
+            print("Openmd: browser plugin compatibility link could not be prepared; check runtime directory permissions and retry.", file=sys.stderr)
+            _host_package_warning_shown = True
+
+
+def activate() -> str:
+    """Make a usable opencli visible to this process and its children.
+
+    Returns "user" (own install on PATH), "managed" (Openmd's copy) or "missing".
+    Browser reads default to a background (minimized) window.
+    """
+    show = os.environ.get("OPENMD_SHOW_BROWSER", "").strip().lower() in {"1", "true", "yes", "on"}
+    os.environ.setdefault("OPENCLI_WINDOW", "foreground" if show else "background")
+    if _managed_ready():
+        if shutil.which("opencli") and Path(shutil.which("opencli")).parent != managed_bin():
+            return "user"
+        node = node_dir()
+        _prepend_path(*([node] if node else []), managed_bin())
+        _prepare_bundled_node_host_package()
+        return "managed"
+    return "user" if shutil.which("opencli") else "missing"
+
+
+def auto_install_enabled() -> bool:
+    return os.environ.get("OPENMD_AUTO_INSTALL_TOOLS", "1").strip().lower() not in {"0", "false", "no", "off"}
+
+
+def ensure_opencli(say: Callable[[str], None] | None = None) -> str:
+    """Install the pinned opencli once if no opencli is available.
+
+    Returns the activate() state after the attempt; never raises for a failed
+    install (the route then reports opencli as missing with a hint).
+    """
+    state = activate()
+    if state != "missing" or not auto_install_enabled():
+        return state
+    node = node_dir()
+    npm = _npm_cli(node) if node else None
+    if node is None or npm is None:
+        return "missing"
+    say = say or (lambda message: print(message, file=sys.stderr))
+    say("首次使用这类链接，正在准备浏览器读取组件（约 20MB，只需一次）…")
+    root = managed_root()
+    root.parent.mkdir(parents=True, exist_ok=True)
+    staging = Path(tempfile.mkdtemp(prefix="opencli-", dir=root.parent))
+    command = [str(node / ("node.exe" if os.name == "nt" else "node")), str(npm), "install", "--prefix", str(staging),
+               f"{OPENCLI_PACKAGE}@{OPENCLI_VERSION}", "--no-audit", "--no-fund", "--loglevel=error", "--save-exact"]
+    registry = os.environ.get("OPENMD_NPM_REGISTRY")
+    if registry:
+        command += ["--registry", registry]
+    env = {**os.environ, "PATH": os.pathsep.join([str(node), os.environ.get("PATH", "")])}
+    try:
+        completed = run_interruptibly(command, env=env, capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=900, check=False)
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        shutil.rmtree(staging, ignore_errors=True)
+        say(f"浏览器读取组件准备失败：{type(exc).__name__}；检查网络，或设置 OPENMD_NPM_REGISTRY 使用 npm 镜像后重试。")
+        return "missing"
+    if completed.returncode != 0:
+        shutil.rmtree(staging, ignore_errors=True)
+        tail = (completed.stderr or completed.stdout or "").strip().splitlines()[-1:] or [""]
+        say(f"浏览器读取组件准备失败（{tail[0][:120]}）；检查网络，或设置 OPENMD_NPM_REGISTRY 使用 npm 镜像后重试。")
+        return "missing"
+    shutil.rmtree(root, ignore_errors=True)
+    staging.rename(root)
+    say("浏览器读取组件已就绪。")
+    return activate()
+
+
+def status() -> dict[str, object]:
+    """Doctor view: where opencli comes from, without probing the network."""
+    state = activate()
+    return {
+        "opencli": state,
+        "opencli_version_pinned": OPENCLI_VERSION,
+        "managed_path": str(managed_root()),
+        "bundled_node": node_dir() is not None,
+        "auto_install": auto_install_enabled(),
+    }

openmd/runtime/models.py

@@ -0,0 +1,202 @@
+"""Resolve ASR models from existing local files without calling a model hub."""
+
+from __future__ import annotations
+
+import json
+import os
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterator
+
+
+@dataclass(frozen=True)
+class ModelSpec:
+    logical_id: str
+    repo: str
+    family: str
+    required: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class ResolvedModel:
+    logical_id: str
+    path: Path | None
+    origin: str
+    missing: tuple[str, ...] = ()
+    searched: tuple[str, ...] = ()
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "logical_id": self.logical_id,
+            "available": self.path is not None,
+            "origin": self.origin,
+            "missing": list(self.missing),
+            "searched": list(self.searched),
+        }
+
+
+MODEL_SPECS = (
+    ModelSpec("whisper-large-v3", "Systran/faster-whisper-large-v3", "whisper", ("model.bin", "config.json", "tokenizer.json")),
+    ModelSpec("whisper-large-v3-turbo", "mobiuslabsgmbh/faster-whisper-large-v3-turbo", "whisper", ("model.bin", "config.json", "tokenizer.json")),
+    ModelSpec("qwen3-asr-1.7b", "Qwen/Qwen3-ASR-1.7B", "qwen3", ("config.json", "tokenizer_config.json", "preprocessor_config.json")),
+    ModelSpec("fsmn-vad-zh", "iic/speech_fsmn_vad_zh-cn-16k-common-pytorch", "vad", ("model.pt", "config.yaml", "am.mvn")),
+)
+_SPECS = {spec.logical_id: spec for spec in MODEL_SPECS}
+_ALIASES = {spec.repo: spec.logical_id for spec in MODEL_SPECS}
+_ALIASES.update({"large-v3": "whisper-large-v3", "large": "whisper-large-v3", "large-v3-turbo": "whisper-large-v3-turbo", "turbo": "whisper-large-v3-turbo"})
+
+
+class ModelNotFoundError(FileNotFoundError):
+    def __init__(self, resolution: ResolvedModel) -> None:
+        self.resolution = resolution
+        super().__init__(
+            f"Local ASR model {resolution.logical_id!r} is missing or incomplete "
+            f"({', '.join(resolution.missing)}). Searched: {', '.join(resolution.searched) or 'explicit path'}. "
+            "Set OPENMD_MODEL_ROOTS or the model's OPENMD_*_MODEL variable to an installed local directory; no download was attempted."
+        )
+
+
+def checkout_root() -> Path | None:
+    root = Path(__file__).resolve().parents[3]
+    return root if (root / "pyproject.toml").is_file() and (root / "src" / "openmd").is_dir() else None
+
+
+def _spec_for(value: str, family: str | None) -> ModelSpec:
+    logical = _ALIASES.get(value, value)
+    if logical in _SPECS:
+        return _SPECS[logical]
+    explicit = Path(value).expanduser()
+    if explicit.is_dir() or explicit.is_absolute() or value.startswith((".", "~")) or "\\" in value:
+        known_family = family or "whisper"
+        template = _SPECS[{"whisper": "whisper-large-v3", "qwen3": "qwen3-asr-1.7b", "vad": "fsmn-vad-zh"}[known_family]]
+        return ModelSpec("local-" + explicit.name, value, known_family, template.required)
+    if family == "whisper":
+        # Preserve explicit legacy faster-whisper sizes while staying offline.
+        repo = value if "/" in value else f"Systran/faster-whisper-{value}"
+        return ModelSpec(value, repo, "whisper", ("model.bin", "config.json", "tokenizer.json"))
+    fallback = _SPECS["qwen3-asr-1.7b" if family == "qwen3" else "fsmn-vad-zh"]
+    return ModelSpec(value, value, family or fallback.family, fallback.required)
+
+
+def model_label(value: str) -> str:
+    """Keep logical model names useful while omitting a machine's full path."""
+    path = Path(value).expanduser()
+    return "local-" + path.name if path.is_dir() or path.is_absolute() or value.startswith((".", "~")) or "\\" in value else value
+
+
+def _missing(path: Path, spec: ModelSpec) -> tuple[str, ...]:
+    if not path.is_dir():
+        return ("directory",)
+    missing = [name for name in spec.required if not (path / name).is_file() or (path / name).stat().st_size == 0]
+    if spec.family == "qwen3":
+        weights = list(path.glob("*.safetensors"))
+        if not weights or any(weight.stat().st_size == 0 for weight in weights):
+            missing.append("*.safetensors")
+        index = path / "model.safetensors.index.json"
+        if index.is_file():
+            try:
+                weight_map = json.loads(index.read_text(encoding="utf-8"))["weight_map"]
+                if not isinstance(weight_map, dict) or not weight_map:
+                    raise ValueError("empty weight map")
+                for name in sorted(set(weight_map.values())):
+                    candidate = (path / name).resolve()
+                    if not candidate.is_relative_to(path.resolve()) or not candidate.is_file() or candidate.stat().st_size == 0:
+                        missing.append("weight shard")
+            except (OSError, ValueError, KeyError, TypeError):
+                missing.append("valid model.safetensors.index.json")
+        if not (path / "tokenizer.json").is_file() and not all((path / name).is_file() for name in ("vocab.json", "merges.txt")):
+            missing.append("tokenizer.json or vocab.json + merges.txt")
+    return tuple(dict.fromkeys(missing))
+
+
+def _snapshot_paths(root: Path) -> Iterator[Path]:
+    if not root.is_dir():
+        return
+    yield root
+    refs = root / "refs" / "main"
+    if refs.is_file():
+        revision = refs.read_text(encoding="utf-8").strip()
+        snapshot = (root / "snapshots" / revision).resolve()
+        if snapshot.is_relative_to(root.resolve()):
+            yield snapshot
+    yield from sorted((root / "snapshots").glob("*"), reverse=True)
+
+
+def _local_config() -> dict:
+    from openmd.core.local_config import load_local_config
+
+    return load_local_config()
+
+
+def resolve_model(value: str, *, family: str | None = None) -> ResolvedModel:
+    """Return a validated directory or an explicit missing result; never download."""
+    spec = _spec_for(value, family)
+    explicit = Path(value).expanduser()
+    if explicit.is_dir() or explicit.is_absolute() or value.startswith((".", "~")) or "\\" in value:
+        missing = _missing(explicit, spec)
+        return ResolvedModel(spec.logical_id, explicit.resolve() if not missing else None, "explicit_path", missing, ("explicit_path",))
+
+    candidates: list[tuple[Path, str]] = []
+    repo_parts = spec.repo.split("/")
+    compact = spec.repo.replace("/", "--")
+    configured = _local_config().get("model_roots", [])
+    roots = [*(Path(part).expanduser() for part in os.getenv("OPENMD_MODEL_ROOTS", "").split(os.pathsep) if part), *(Path(part).expanduser() for part in configured)]
+    for root in roots:
+        candidates.extend((path, "configured_root") for path in (root / spec.logical_id, root / compact, root / "models" / compact, root / ("models--" + compact), root.joinpath(*repo_parts), root / "models" / Path(*repo_parts)))
+    checkout = checkout_root()
+    if checkout:
+        candidates.append((checkout / "out" / "asr-bench" / "models" / "models" / compact, "checkout_model_cache"))
+    hf_roots = [Path(os.environ["HF_HUB_CACHE"]).expanduser()] if os.getenv("HF_HUB_CACHE") else []
+    if os.getenv("HF_HOME"):
+        hf_roots.append(Path(os.environ["HF_HOME"]).expanduser() / "hub")
+    hf_roots.append(Path.home() / ".cache" / "huggingface" / "hub")
+    candidates.extend((root / ("models--" + compact), "huggingface_cache") for root in hf_roots)
+    ms_roots = [Path(os.environ["MODELSCOPE_CACHE"]).expanduser()] if os.getenv("MODELSCOPE_CACHE") else []
+    ms_roots.append(Path.home() / ".cache" / "modelscope" / "hub")
+    for root in ms_roots:
+        candidates.extend((path, "modelscope_cache") for path in (root.joinpath(*repo_parts), root / "models" / Path(*repo_parts), root / "models" / compact))
+
+    searched: list[str] = []
+    incomplete: tuple[str, ...] = ()
+    for root, origin in candidates:
+        if origin not in searched:
+            searched.append(origin)
+        for candidate in _snapshot_paths(root):
+            missing = _missing(candidate, spec)
+            if not missing:
+                return ResolvedModel(spec.logical_id, candidate.resolve(), origin, (), tuple(searched))
+            if candidate.is_dir() and missing != ("directory",):
+                incomplete = missing
+    return ResolvedModel(spec.logical_id, None, "missing", incomplete or spec.required, tuple(searched))
+
+
+def require_model(value: str, *, family: str) -> Path:
+    resolved = resolve_model(value, family=family)
+    if resolved.path is None:
+        raise ModelNotFoundError(resolved)
+    return resolved.path
+
+
+def configured_models() -> dict[str, ResolvedModel]:
+    return {
+        "whisper-large-v3": resolve_model(os.getenv("OPENMD_FASTER_WHISPER_MODEL") or "large-v3", family="whisper"),
+        "whisper-large-v3-turbo": resolve_model(os.getenv("OPENMD_ASR_AUTO_EN_MODEL") or "large-v3-turbo", family="whisper"),
+        "qwen3-asr-1.7b": resolve_model(os.getenv("OPENMD_QWEN3_MODEL") or "Qwen/Qwen3-ASR-1.7B", family="qwen3"),
+        "fsmn-vad-zh": resolve_model(os.getenv("OPENMD_QWEN3_VAD_MODEL") or "iic/speech_fsmn_vad_zh-cn-16k-common-pytorch", family="vad"),
+    }
+
+
+@contextmanager
+def offline_model_loading() -> Iterator[None]:
+    keys = ("HF_HUB_OFFLINE", "TRANSFORMERS_OFFLINE", "MODELSCOPE_OFFLINE")
+    previous = {key: os.environ.get(key) for key in keys}
+    os.environ.update({key: "1" for key in keys})
+    try:
+        yield
+    finally:
+        for key, value in previous.items():
+            if value is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = value

openmd/runtime/services.py

@@ -0,0 +1,175 @@
+"""The sole persistent-process exception: the installed OpenCLI browser daemon.
+
+Actual commands, status checks and all other workers retain launch-time ownership.
+No Ollama lifecycle operations, model downloads or general detached launcher exist.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import shlex
+import shutil
+import subprocess
+import threading
+import time
+
+from openmd.core.opencli_output import load_opencli_json
+
+_START_LOCK = threading.Lock()
+_DAEMONS: list[subprocess.Popen] = []
+_CONTROL_COMMANDS = {"daemon", "--help", "-h", "--version", "-V", "help", "list", "completion"}
+
+
+def _opencli_launch(command, env=None) -> tuple[list[str], list[str]] | None:
+    """Recognize npm shims and native Node entries, without executing a shell."""
+    if isinstance(command, str):
+        try:
+            argv = [part.strip('"') for part in shlex.split(command, posix=False)]
+        except ValueError:
+            return None
+    elif isinstance(command, (list, tuple)):
+        argv = [os.fsdecode(part) for part in command]
+    else:
+        return None
+    if not argv:
+        return None
+    first = Path(argv[0])
+    if first.name.lower() in {"opencli", "opencli.cmd", "opencli.ps1", "opencli.exe", "opencli.bat"}:
+        resolved = shutil.which(argv[0], path=None if env is None else env.get("PATH"))
+        shim = Path(resolved or argv[0]).resolve()
+        # Unix npm installs symlink the command directly to the package entry.
+        if shim.as_posix().lower().endswith("/@jackwener/opencli/dist/src/main.js"):
+            entry = shim
+        elif shim.parent.name == ".bin":  # local install, e.g. Openmd's managed copy
+            entry = shim.parent.parent / "@jackwener/opencli/dist/src/main.js"
+        else:
+            entry = shim.parent / "node_modules/@jackwener/opencli/dist/src/main.js"
+        node = shim.parent / ("node.exe" if os.name == "nt" else "node")
+        binary = str(node) if node.is_file() else shutil.which("node", path=None if env is None else env.get("PATH"))
+        tail = argv[1:]
+    elif first.name.lower() in {"node", "node.exe"} and len(argv) > 1:
+        entry = Path(argv[1]).resolve()
+        if not entry.as_posix().lower().endswith("/@jackwener/opencli/dist/src/main.js"):
+            return None
+        binary, tail = argv[0], argv[2:]
+    else:
+        return None
+    # Status/stop/restart must never start the daemon as a side effect. The
+    # recursive owned status command below consequently bypasses this helper.
+    while tail and tail[0].startswith("--profile="):
+        tail = tail[1:]
+    if tail and tail[0] == "--profile":
+        tail = tail[2:]
+    if not tail or tail[0] in _CONTROL_COMMANDS:
+        return None
+    daemon = entry.with_name("daemon.js")
+    if not binary or not entry.is_file() or not daemon.is_file():
+        return None
+    return [str(binary), str(entry)], [str(binary), str(daemon)]
+
+
+def _daemon_running(launcher, *, env=None, cwd=None) -> bool:
+    from .interpreters import run_interruptibly
+
+    try:
+        result = run_interruptibly([*launcher, "daemon", "status"], env=env, cwd=cwd,
+                                  stdin=subprocess.DEVNULL, capture_output=True,
+                                  text=True, encoding="utf-8", errors="replace", timeout=10,
+                                  creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0))
+        payload = load_opencli_json(result.stdout)
+        if result.returncode or not isinstance(payload, dict) or not isinstance(payload.get("running"), bool):
+            raise ValueError("invalid status")
+        return payload["running"]
+    except (ValueError, TypeError, subprocess.TimeoutExpired) as exc:
+        # Do not blindly launch a second service when the status is unknown.
+        raise OSError("OpenCLI daemon status unavailable; run opencli daemon status.") from exc
+
+
+def _start_opencli_daemon_detached(daemon_argv, *, env=None):
+    """Only called with the two-item installed Node/daemon.js launch specification.
+
+    This is deliberately outside owned_popen: a command's kill-on-close Job must
+    never acquire this intentional persistent service. No Job flag is weakened.
+    """
+    binary, script = daemon_argv
+    if Path(binary).name.lower() not in {"node", "node.exe"} or not Path(script).as_posix().lower().endswith("/@jackwener/opencli/dist/src/daemon.js"):
+        raise ValueError("Only the installed OpenCLI daemon may be detached")
+    options = {"creationflags": subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP} if os.name == "nt" else {"start_new_session": True}
+    process = subprocess.Popen([binary, script], env=env, cwd=str(Path(script).parent),
+                               stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+                               stderr=subprocess.DEVNULL, close_fds=True, **options)
+    _DAEMONS[:] = [child for child in _DAEMONS if child.poll() is None]
+    _DAEMONS.append(process)
+    return process
+
+
+OPENMD_BRIDGE_PROFILE = "openmd"
+
+
+def _bridge_profiles(timeout: float = 1.0) -> list[str]:
+    """Connected Browser Bridge profile ids from the local daemon (never proxied)."""
+    import json
+    import urllib.request
+
+    opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+    request = urllib.request.Request("http://127.0.0.1:19825/status", headers={"X-OpenCLI": "1"})
+    try:
+        with opener.open(request, timeout=timeout) as response:  # noqa: S310 - loopback only
+            payload = json.loads(response.read().decode("utf-8"))
+    except (OSError, ValueError):
+        return []
+    return [str(p.get("contextId")) for p in payload.get("profiles") or [] if isinstance(p, dict) and p.get("contextId")]
+
+
+def bridge_profile_env(command, env=None):
+    """Select Openmd's built-in bridge when it is connected.
+
+    With both the standalone OpenCLI extension and Openmd's built-in bridge
+    connected, opencli refuses to guess (profile_required). Prefer ours, keep a
+    user's explicit OPENCLI_PROFILE, and leave the single-bridge case untouched.
+    Returns a new env mapping, or None when nothing needs to change.
+    """
+    base = os.environ if env is None else env
+    if base.get("OPENCLI_PROFILE") or _opencli_launch(command, env) is None:
+        return None
+    deadline = time.monotonic() + 2
+    profiles = _bridge_profiles()
+    while not profiles and time.monotonic() < deadline:  # bridges reconnect to a fresh daemon
+        time.sleep(.2)
+        profiles = _bridge_profiles()
+    if OPENMD_BRIDGE_PROFILE in profiles and len(profiles) > 1:
+        return {**base, "OPENCLI_PROFILE": OPENMD_BRIDGE_PROFILE}
+    return None
+
+
+def ensure_opencli_daemon(command, *, env=None, cwd=None) -> None:
+    launch = _opencli_launch(command, env)
+    if launch is None:
+        return
+    launcher, daemon_argv = launch
+    # Lock waits stay in short Python slices, like the owned process waiter.
+    while not _START_LOCK.acquire(timeout=.1):
+        pass
+    # Pre-start is only an optimization (keep the daemon alive across owned
+    # commands). Unknown status or a slow/failed start must not block the actual
+    # command: it then runs exactly as before and reports its own errors.
+    try:
+        try:
+            if _daemon_running(launcher, env=env, cwd=cwd):
+                return
+        except OSError:
+            return  # status unknown: never launch a second service blindly
+        process = _start_opencli_daemon_detached(daemon_argv, env=env)
+        deadline = time.monotonic() + 5
+        while time.monotonic() < deadline:
+            try:
+                if _daemon_running(launcher, env=env, cwd=cwd):
+                    return
+            except OSError:
+                pass
+            if process.poll() is not None:
+                return
+            time.sleep(.1)
+    finally:
+        _START_LOCK.release()