setiastrosuitepro 1.8.0.post3__py3-none-any.whl → 1.8.2__py3-none-any.whl

setiastro/saspro/runtime_torch.py

@@ -16,16 +16,13 @@ from contextlib import contextmanager
 import platform as _plat
 from pathlib import Path as _Path
 
-def _maybe_find_torch_shm_manager(torch_mod) -> str | None:
-    # Only Linux wheels include/use this helper binary.
-    if _plat.system() != "Linux":
-        return None
+
+def _rt_dbg(msg: str, status_cb=print):
     try:
-        base = _Path(getattr(torch_mod, "__file__", "")).parent
-        p = base / "bin" / "torch_shm_manager"
-        return str(p) if p.exists() else None
+        status_cb(f"[RT] {msg}")
     except Exception:
-        return None
+        print(f"[RT] {msg}", flush=True)
+
 
 # ──────────────────────────────────────────────────────────────────────────────
 # Paths & runtime selection
@@ -67,14 +64,25 @@ def _runtime_base_dir() -> Path:
 def _current_tag() -> str:
     return f"py{sys.version_info.major}{sys.version_info.minor}"
 
-def _discover_existing_runtime_dir() -> Path | None:
+def _discover_existing_runtime_dir(status_cb=print) -> Path | None:
     """
-    Return the newest existing runtime dir that already has a venv python,
-    using the venv interpreter's REAL version instead of just the folder name.
+    Prefer an existing runtime that MATCHES the current interpreter minor.
+    Only if none exists, fall back to the highest available.
     """
     base = _runtime_base_dir()
     if not base.exists():
         return None
+
+    cur_tag = _current_tag()  # e.g. py311, py312
+    cur_dir = base / cur_tag
+    cur_vpy = cur_dir / "venv" / ("Scripts/python.exe" if platform.system() == "Windows" else "bin/python")
+
+    # 1) If matching-current exists and has a venv python, use it.
+    if cur_vpy.exists():
+        _rt_dbg(f"Found matching runtime for current interpreter: {cur_dir}", status_cb)
+        return cur_dir
+
+    # 2) Otherwise, fall back to "newest existing"
     candidates: list[tuple[int, int, Path]] = []
     for p in base.glob("py*"):
         vpy = p / "venv" / ("Scripts/python.exe" if platform.system() == "Windows" else "bin/python")
@@ -83,22 +91,21 @@ def _discover_existing_runtime_dir() -> Path | None:
         ver = _venv_pyver(vpy)
         if ver:
             candidates.append((ver[0], ver[1], p))
+
     if not candidates:
         return None
-    candidates.sort()  # pick the highest Python (major, minor)
-    return candidates[-1][2]
 
-def _user_runtime_dir() -> Path:
-    """
-    Use an existing runtime if we find one; otherwise select a directory for the
-    current interpreter version (py310/py311/py312...).
-    """
-    existing = _discover_existing_runtime_dir()
-    return existing or (_runtime_base_dir() / _current_tag())
+    candidates.sort()
+    chosen = candidates[-1][2]
+    _rt_dbg(f"No matching runtime; using newest existing: {chosen}", status_cb)
+    return chosen
+
+def _user_runtime_dir(status_cb=print) -> Path:
+    existing = _discover_existing_runtime_dir(status_cb=status_cb)
+    chosen = existing or (_runtime_base_dir() / _current_tag())
+    _rt_dbg(f"_user_runtime_dir() -> {chosen}", status_cb)
+    return chosen
 
-# ──────────────────────────────────────────────────────────────────────────────
-# Shadowing & sanity checks
-# ──────────────────────────────────────────────────────────────────────────────
 
 # ──────────────────────────────────────────────────────────────────────────────
 # Shadowing & sanity checks
@@ -172,23 +179,6 @@ def _purge_bad_torch_from_sysmodules(status_cb=print) -> None:
     except Exception:
         pass
 
-def _torch_stack_sanity_check(status_cb=print) -> None:
-    """
-    Ensure torch imports sanely AND torchvision/torchaudio are importable.
-    (Satellite engine requires torchvision; we install torchaudio too for safety.)
-    """
-    _torch_sanity_check(status_cb=status_cb)
-
-    try:
-        import torchvision  # noqa
-    except Exception as e:
-        raise RuntimeError(f"torchvision import failed: {e}") from e
-
-    try:
-        import torchaudio  # noqa
-    except Exception as e:
-        raise RuntimeError(f"torchaudio import failed: {e}") from e
-
 
 def _torch_sanity_check(status_cb=print):
     try:
@@ -238,31 +228,71 @@ def _pip_ok(venv_python: Path, args: list[str], status_cb=print) -> bool:
 
 def _ensure_numpy(venv_python: Path, status_cb=print) -> None:
     """
-    Torch wheels may not pull NumPy; ensure NumPy is present in the SAME venv.
+    Ensure NumPy exists in the runtime venv AND is ABI-compatible with common
+    torch/vision/audio wheels. In practice: enforce numpy<2.
+
     Safe to call repeatedly.
     """
     def _numpy_present() -> bool:
         code = "import importlib.util; print('OK' if importlib.util.find_spec('numpy') else 'MISS')"
         try:
             out = subprocess.check_output([str(venv_python), "-c", code], text=True).strip()
-            return (out == "OK")
+            return out == "OK"
         except Exception:
             return False
 
-    if _numpy_present():
-        return
+    def _numpy_major() -> int | None:
+        code = (
+            "import numpy as np\n"
+            "v = np.__version__.split('+',1)[0]\n"
+            "print(int(v.split('.',1)[0]))\n"
+        )
+        try:
+            out = subprocess.check_output([str(venv_python), "-c", code], text=True).strip()
+            return int(out)
+        except Exception:
+            return None
 
-    # Keep tools fresh, then install a compatible NumPy (Torch 2.x is fine with NumPy 1.26–2.x)
+    # Keep tools fresh
     _pip_ok(venv_python, ["install", "--upgrade", "pip", "setuptools", "wheel"], status_cb=status_cb)
 
-    # Prefer latest available in [1.26, 3.0)
-    if not _pip_ok(venv_python, ["install", "--prefer-binary", "--no-cache-dir", "numpy>=1.26,<3"], status_cb=status_cb):
-        # Final fallback to a broadly available pin
-        _pip_ok(venv_python, ["install", "--prefer-binary", "--no-cache-dir", "numpy==1.26.*"], status_cb=status_cb)
+    # 1) If NumPy missing → install safe pin
+    if not _numpy_present():
+        status_cb("[RT] Installing NumPy (pinning to numpy<2 for torch wheel compatibility)…")
+        if not _pip_ok(
+            venv_python,
+            ["install", "--prefer-binary", "--no-cache-dir", "numpy<2"],
+            status_cb=status_cb,
+        ):
+            # last-ditch fallback (very widely available)
+            _pip_ok(
+                venv_python,
+                ["install", "--prefer-binary", "--no-cache-dir", "numpy==1.26.*"],
+                status_cb=status_cb,
+            )
+
+    # 2) If NumPy present but major>=2 → downgrade to numpy<2
+    maj = _numpy_major()
+    if maj is not None and maj >= 2:
+        status_cb("[RT] NumPy 2.x detected in runtime venv; downgrading to numpy<2…")
+        if not _pip_ok(
+            venv_python,
+            ["install", "--prefer-binary", "--no-cache-dir", "--force-reinstall", "numpy<2"],
+            status_cb=status_cb,
+        ):
+            _pip_ok(
+                venv_python,
+                ["install", "--prefer-binary", "--no-cache-dir", "--force-reinstall", "numpy==1.26.*"],
+                status_cb=status_cb,
+            )
 
-    # Post-install verification
+    # Post verification
     if not _numpy_present():
         raise RuntimeError("Failed to install NumPy into the SASpro runtime venv.")
+    maj2 = _numpy_major()
+    if maj2 is not None and maj2 >= 2:
+        raise RuntimeError("NumPy is still 2.x in the SASpro runtime venv after pinning; torch stack may not import.")
+
 
 
 def _is_access_denied(exc: BaseException) -> bool:
@@ -631,129 +661,518 @@ def _install_torch(venv_python: Path, prefer_cuda: bool, prefer_xpu: bool, prefe
 # Public entry points
 # ──────────────────────────────────────────────────────────────────────────────
 
-def import_torch(prefer_cuda: bool = True, prefer_xpu: bool = False, prefer_dml: bool = False, status_cb=print):
+def _venv_import_probe(venv_python: Path, modname: str) -> tuple[bool, str]:
     """
-    Ensure a per-user venv exists with torch installed; return the imported module.
-    Hardened against shadow imports, broken wheels, concurrent installs, and partial markers.
+    Try importing a module INSIDE the runtime venv python.
+    Returns (ok, output_or_error_tail).
     """
-    # Before any attempt, demote shadowing paths (CWD / random folders)
-    _ban_shadow_torch_paths(status_cb=status_cb)
-    _purge_bad_torch_from_sysmodules(status_cb=status_cb)
+    code = (
+        "import importlib, sys\n"
+        f"m=importlib.import_module('{modname}')\n"
+        "print('OK', getattr(m,'__version__',None), getattr(m,'__file__',None))\n"
+    )
+    r = subprocess.run([str(venv_python), "-c", code],
+                       stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
+    out = (r.stdout or "").strip()
+    if r.returncode == 0 and out.startswith("OK"):
+        return True, out
+    return False, out[-4000:] if out else "no output"
+
 
-    add_runtime_to_sys_path(status_cb=lambda *_: None)
+def _write_torch_marker(marker: Path, status_cb=print) -> None:
+    """
+    Create torch_installed.json based on runtime venv imports.
+    Safe to call repeatedly.
+    """
+    rt = marker.parent
+    vp = _venv_paths(rt)["python"]
+
+    ok_t, out_t = _venv_import_probe(vp, "torch")
+    ok_v, out_v = _venv_import_probe(vp, "torchvision")
+    ok_a, out_a = _venv_import_probe(vp, "torchaudio")
+
+    payload = {
+        "installed": bool(ok_t),
+        "when": int(time.time()),
+        "python": None,
+        "torch": None,
+        "torchvision": None,
+        "torchaudio": None,
+        "torch_file": None,
+        "torchvision_file": None,
+        "torchaudio_file": None,
+        "probe": {
+            "torch": out_t,
+            "torchvision": out_v,
+            "torchaudio": out_a,
+        }
+    }
 
-    # Fast path: if torch already importable and sane, use it
+    # get venv python version
     try:
-        import torch  # noqa
-        _torch_stack_sanity_check(status_cb=status_cb)
-        return torch
+        r = subprocess.run([str(vp), "-c", "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')"],
+                           stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True)
+        if r.returncode == 0:
+            payload["python"] = (r.stdout or "").strip()
     except Exception:
         pass
 
-    rt = _user_runtime_dir()
-    vp = _ensure_venv(rt, status_cb=status_cb)
-    site = _site_packages(vp)
-    marker = rt / "torch_installed.json"
+    # parse "OK ver file" lines
+    def _parse_ok(s: str):
+        # format: "OK <ver> <file>"
+        try:
+            parts = s.split(" ", 2)
+            ver = parts[1] if len(parts) > 1 else None
+            f = parts[2] if len(parts) > 2 else None
+            return ver, f
+        except Exception:
+            return None, None
+
+    if ok_t:
+        payload["torch"], payload["torch_file"] = _parse_ok(out_t)
+    if ok_v:
+        payload["torchvision"], payload["torchvision_file"] = _parse_ok(out_v)
+    if ok_a:
+        payload["torchaudio"], payload["torchaudio_file"] = _parse_ok(out_a)
 
     try:
-        _ensure_numpy(vp, status_cb=status_cb)
-    except Exception:
-        # Non-fatal; we'll try again if torch complains at runtime
-        pass
+        marker.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+        status_cb(f"[RT] Wrote marker: {marker}")
+    except Exception as e:
+        status_cb(f"[RT] Failed to write marker {marker}: {e!r}")
+
+def _venv_has_torch_stack(
+    vp: Path,
+    status_cb=print,
+    *,
+    require_torchaudio: bool = True
+) -> tuple[bool, dict]:
+    """
+    Definitive check: can the RUNTIME VENV import torch/torchvision/(torchaudio)?
+    This does NOT use the frozen app interpreter to decide installation state.
+    """
+    ok_t, out_t = _venv_import_probe(vp, "torch")
+    ok_v, out_v = _venv_import_probe(vp, "torchvision")
+    ok_a, out_a = _venv_import_probe(vp, "torchaudio")
+
+    info = {
+        "torch": (ok_t, out_t),
+        "torchvision": (ok_v, out_v),
+        "torchaudio": (ok_a, out_a),
+    }
+
+    ok_all = (ok_t and ok_v and ok_a) if require_torchaudio else (ok_t and ok_v)
+    return ok_all, info
+
+def _marker_says_ready(
+    marker: Path,
+    site: Path,
+    venv_ver: tuple[int, int] | None,
+    *,
+    require_torchaudio: bool = True,
+    max_age_days: int = 180,
+) -> bool:
+    """
+    Advisory fast-path gate ONLY.
+
+    Returns True if the marker looks sane enough that an in-process import attempt
+    is worth trying *without* doing the expensive subprocess venv probes.
+
+    IMPORTANT:
+      - This must NOT be used to decide whether to install/uninstall anything.
+      - If this returns True and the in-process import fails, we fall back to the
+        definitive venv probe (_venv_has_torch_stack).
+    """
+    try:
+        if not marker.exists():
+            return False
+
+        raw = marker.read_text(encoding="utf-8", errors="replace")
+        data = json.loads(raw) if raw else {}
+        if not isinstance(data, dict):
+            return False
+
+        if not data.get("installed", False):
+            return False
+
+        # Age gate (advisory only).
+        when = data.get("when")
+        if isinstance(when, (int, float)):
+            age_s = max(0.0, time.time() - float(when))
+            if age_s > (max_age_days * 86400):
+                return False
+
+        # Marker python version should match the RUNTIME VENV python (not the app interpreter).
+        py = data.get("python")
+        if not (isinstance(py, str) and py.strip()):
+            return False
 
-    # If no marker, perform install under a lock
-    if not marker.exists():
         try:
-            with _install_lock(rt):
-                # Re-check inside lock in case another process finished
-                if not marker.exists():
-                    _install_torch(vp, prefer_cuda=prefer_cuda, prefer_xpu=prefer_xpu, prefer_dml=prefer_dml, status_cb=status_cb)
-        except Exception as e:
-            if _is_access_denied(e):
-                raise OSError(_access_denied_msg(rt)) from e
-            raise
+            maj_s, min_s = py.strip().split(".", 1)
+            marker_ver = (int(maj_s), int(min_s))
+        except Exception:
+            return False
 
-    # Ensure the venv site is first on sys.path, then demote shadowers again
-    if str(site) not in sys.path:
-        sys.path.insert(0, str(site))
-    _demote_shadow_torch_paths(status_cb=status_cb)
+        # If we can't determine venv version, treat marker as unreliable for fast-path.
+        if venv_ver is None:
+            return False
+
+        if marker_ver != venv_ver:
+            return False
+
+        # Check that recorded files (if present) live under the computed site-packages path.
+        site_s = str(site)
+        tf = data.get("torch_file")
+        tvf = data.get("torchvision_file")
+        taf = data.get("torchaudio_file")
+
+        def _under_site(p: str | None) -> bool:
+            if not p or not isinstance(p, str):
+                return False
+            return site_s in p
+
+        if not _under_site(tf):
+            return False
+        if not _under_site(tvf):
+            return False
+        if require_torchaudio and not _under_site(taf):
+            return False
+
+        return True
+    except Exception:
+        return False
+
+
+def _qt_settings():
+    """
+    Create QSettings without importing PyQt6 at module import time.
+    We only import it inside the function so runtime_torch stays usable
+    in non-GUI contexts.
+    """
+    try:
+        from PyQt6.QtCore import QSettings
+        # Must match what your app sets via QCoreApplication.setOrganizationName / setApplicationName
+        return QSettings()
+    except Exception:
+        return None
+
+
+def _qcache_get():
+    s = _qt_settings()
+    if not s:
+        return None
+    s.beginGroup("runtime_torch")
+    data = {
+        "tag": s.value("tag", "", str),
+        "rt_dir": s.value("rt_dir", "", str),
+        "site": s.value("site", "", str),
+        "python": s.value("python", "", str),
+        "torch": s.value("torch", "", str),
+        "torchvision": s.value("torchvision", "", str),
+        "torchaudio": s.value("torchaudio", "", str),
+        "when": s.value("when", 0, int),
+        "require_torchaudio": s.value("require_torchaudio", True, bool),
+    }
+    s.endGroup()
+    return data
+
+
+def _qcache_set(*, tag: str, rt_dir: Path, site: Path, python_ver: str | None,
+               torch_ver: str | None, tv_ver: str | None, ta_ver: str | None,
+               require_torchaudio: bool):
+    s = _qt_settings()
+    if not s:
+        return
+    s.beginGroup("runtime_torch")
+    s.setValue("tag", tag)
+    s.setValue("rt_dir", str(rt_dir))
+    s.setValue("site", str(site))
+    s.setValue("python", python_ver or "")
+    s.setValue("torch", torch_ver or "")
+    s.setValue("torchvision", tv_ver or "")
+    s.setValue("torchaudio", ta_ver or "")
+    s.setValue("when", int(time.time()))
+    s.setValue("require_torchaudio", bool(require_torchaudio))
+    s.endGroup()
+    s.sync()
+
+
+def _qcache_clear():
+    s = _qt_settings()
+    if not s:
+        return
+    s.beginGroup("runtime_torch")
+    s.remove("")   # remove all keys in group
+    s.endGroup()
+    s.sync()
+
+
+# module-level cache (optional but recommended)
+# module-level cache (optional but recommended)
+_TORCH_CACHED = None
+
+
+def import_torch(
+    prefer_cuda: bool = True,
+    prefer_xpu: bool = False,
+    prefer_dml: bool = False,
+    status_cb=print,
+    *,
+    require_torchaudio: bool = True,
+):
+    """
+    Ensure a per-user venv exists with torch installed; return the imported torch module.
+
+    ULTRA FAST PATH:
+      - Use QSettings cached site-packages (no subprocess at all) and attempt in-process import.
+
+    FAST PATH:
+      - If marker looks valid, compute site-packages (1 subprocess) and try in-process imports.
+      - If that works, skip expensive subprocess probes.
+
+    SLOW PATH:
+      - Probe runtime venv via subprocess (torch/torchvision/torchaudio).
+      - Install only if missing, then re-probe.
+      - Finally import in-process from venv site-packages.
 
-    # Import + sanity. If broken, force a clean repair (all OSes).
-    def _force_repair():
+    NEW RULES:
+      - Marker/QSettings are advisory only (fast path gates).
+      - If torch/torchvision(/torchaudio) exist in the runtime venv, USE THEM. Do nothing else.
+      - Only if missing in the runtime venv should we install.
+      - NEVER auto-uninstall user torch/torchvision/torchaudio. No automatic repair.
+    """
+    global _TORCH_CACHED
+    if _TORCH_CACHED is not None:
+        return _TORCH_CACHED
+
+    def _write_qcache_best_effort(rt: Path, site: Path, venv_ver: tuple[int,int] | None):
+        """
+        Write QSettings cache only after we have proven imports work in-process.
+        """
         try:
-            status_cb("Detected broken/shadowed Torch import → attempting clean repair…")
+            import torch as _t  # noqa
+            import torchvision as _tv  # noqa
+            _ta = None
+            if require_torchaudio:
+                import torchaudio as _ta  # noqa
+
+            _qcache_set(
+                tag=rt.name,  # IMPORTANT: runtime tag, not sys.version_info tag
+                rt_dir=rt,
+                site=site,
+                python_ver=(f"{venv_ver[0]}.{venv_ver[1]}" if venv_ver else ""),
+                torch_ver=getattr(_t, "__version__", None),
+                tv_ver=getattr(_tv, "__version__", None),
+                ta_ver=getattr(_ta, "__version__", None) if _ta else None,
+                require_torchaudio=require_torchaudio,
+            )
         except Exception:
             pass
 
-        # remove marker so future launches don't skip install
+    _rt_dbg(f"sys.frozen={getattr(sys,'frozen',False)}", status_cb)
+    _rt_dbg(f"sys.executable={sys.executable}", status_cb)
+    _rt_dbg(f"sys.version={sys.version}", status_cb)
+    _rt_dbg(f"current_tag={_current_tag()}", status_cb)
+    _rt_dbg(f"SASPRO_RUNTIME_DIR={os.getenv('SASPRO_RUNTIME_DIR')!r}", status_cb)
+
+    # Remove obvious shadowing paths (repo folders / cwd torch trees)
+    _ban_shadow_torch_paths(status_cb=status_cb)
+    _purge_bad_torch_from_sysmodules(status_cb=status_cb)
+
+    # ------------------------------------------------------------
+    # Choose runtime + ensure venv exists
+    # ------------------------------------------------------------
+    rt = _user_runtime_dir(status_cb=status_cb)
+    vp = _ensure_venv(rt, status_cb=status_cb)
+
+    # ------------------------------------------------------------
+    # ULTRA FAST PATH (runtime-aware): QSettings cache.
+    # Now we can compare the cache tag against the RUNTIME tag, not sys.version_info.
+    # This stays correct for "app python != runtime venv python" cases.
+    # ------------------------------------------------------------
+    try:
+        qc = _qcache_get()
+        if qc:
+            site_s = (qc.get("site") or "").strip()
+            rt_s   = (qc.get("rt_dir") or "").strip()
+            req_ta = bool(qc.get("require_torchaudio", True))
+            tag    = (qc.get("tag") or "").strip()
+
+            # Accept cache only if it matches this runtime folder tag
+            if (
+                tag == rt.name
+                and site_s and Path(site_s).exists()
+                and rt_s and Path(rt_s).exists()
+                and (req_ta == require_torchaudio)
+            ):
+                status_cb("[RT] QSettings cache hit (runtime tag match); attempting zero-subprocess import.")
+
+                if site_s not in sys.path:
+                    sys.path.insert(0, site_s)
+
+                _demote_shadow_torch_paths(status_cb=status_cb)
+                _purge_bad_torch_from_sysmodules(status_cb=status_cb)
+
+                import torch  # noqa
+                import torchvision  # noqa
+                if require_torchaudio:
+                    import torchaudio  # noqa
+
+                _TORCH_CACHED = torch
+
+                return torch
+
+    except Exception as e:
+        status_cb(f"[RT] QSettings fast-path failed: {type(e).__name__}: {e}. Continuing…")
         try:
-            marker.unlink()
+            _qcache_clear()
         except Exception:
             pass
 
-        subprocess.run([str(vp), "-m", "pip", "uninstall", "-y",
-                        "torch", "torchvision", "torchaudio"], check=False)
-        subprocess.run([str(vp), "-m", "pip", "cache", "purge"], check=False)
-        with _install_lock(rt):
-            _install_torch(
-                vp,
-                prefer_cuda=prefer_cuda,
-                prefer_xpu=prefer_xpu,
-                prefer_dml=prefer_dml,
-                status_cb=status_cb,
-            )
-        importlib.invalidate_caches()
-        _demote_shadow_torch_paths(status_cb=status_cb)
+    # site-packages path (subprocess but relatively cheap)
+    site = _site_packages(vp)
+    marker = rt / "torch_installed.json"
+    venv_ver = _venv_pyver(vp)
 
+    _rt_dbg(f"venv_ver={venv_ver}", status_cb)
+    _rt_dbg(f"rt={rt}", status_cb)
+    _rt_dbg(f"venv_python={vp}", status_cb)
+    _rt_dbg(f"marker={marker} exists={marker.exists()}", status_cb)
+    _rt_dbg(f"site={site}", status_cb)
 
+    # Best-effort ensure numpy in venv (harmless if already there)
     try:
         _ensure_numpy(vp, status_cb=status_cb)
     except Exception:
         pass
 
+    # ------------------------------------------------------------
+    # FAST PATH: if marker looks valid, try in-process import NOW.
+    # This avoids the 3 subprocess probes on every launch.
+    # ------------------------------------------------------------
     try:
-        import torch  # noqa
-        _torch_stack_sanity_check(status_cb=status_cb)
-        # write/update marker only when sane
-        if not marker.exists():
-            pyver = f"{sys.version_info.major}.{sys.version_info.minor}"
+        if _marker_says_ready(marker, site, venv_ver, require_torchaudio=require_torchaudio):
+            status_cb("[RT] Marker valid; attempting fast in-process import (skipping venv probe).")
+
+            sp = str(site)
+            if sp not in sys.path:
+                sys.path.insert(0, sp)
+
+            _demote_shadow_torch_paths(status_cb=status_cb)
+            _purge_bad_torch_from_sysmodules(status_cb=status_cb)
+
+            import torch  # noqa
+            import torchvision  # noqa
+            if require_torchaudio:
+                import torchaudio  # noqa
+
+            # refresh marker (best-effort)
             try:
-                import torch, torchvision, torchaudio
-                marker.write_text(json.dumps({
-                    "installed": True,
-                    "python": pyver,
-                    "when": int(time.time()),
-                    "torch": getattr(torch, "__version__", None),
-                    "torchvision": getattr(torchvision, "__version__", None),
-                    "torchaudio": getattr(torchaudio, "__version__", None),
-                }), encoding="utf-8")
+                _write_torch_marker(marker, status_cb=status_cb)
             except Exception:
-                marker.write_text(json.dumps({"installed": True, "python": pyver, "when": int(time.time())}), encoding="utf-8")
+                pass
 
-        return torch
+            _TORCH_CACHED = torch
+            _write_qcache_best_effort(rt, site, venv_ver)
+            return torch
+
+    except Exception as e:
+        status_cb(f"[RT] Marker fast-path failed: {type(e).__name__}: {e}. Falling back to full probe…")
+        # if marker fast path fails, your cached site-packages may also be stale
+        try:
+            _qcache_clear()
+        except Exception:
+            pass
+
+    # ------------------------------------------------------------
+    # SLOW PATH: Probe the runtime venv definitively.
+    # If it has torch stack, we're DONE (no installs, no repair).
+    # ------------------------------------------------------------
+    ok_all, info = _venv_has_torch_stack(vp, status_cb=status_cb, require_torchaudio=require_torchaudio)
+    status_cb(
+        "[RT] venv probe: "
+        f"torch={info['torch'][0]} "
+        f"torchvision={info['torchvision'][0]} "
+        f"torchaudio={info['torchaudio'][0]}"
+    )
+
+    if not ok_all:
+        missing = []
+        if not info["torch"][0]:
+            missing.append("torch")
+        if not info["torchvision"][0]:
+            missing.append("torchvision")
+        if require_torchaudio and (not info["torchaudio"][0]):
+            missing.append("torchaudio")
+
+        status_cb(f"[RT] Missing in runtime venv: {missing}. Installing…")
+
+        try:
+            with _install_lock(rt):
+                _install_torch(
+                    vp,
+                    prefer_cuda=prefer_cuda,
+                    prefer_xpu=prefer_xpu,
+                    prefer_dml=prefer_dml,
+                    status_cb=status_cb,
+                )
+                _ensure_numpy(vp, status_cb=status_cb)
+        except Exception as e:
+            if _is_access_denied(e):
+                raise OSError(_access_denied_msg(rt)) from e
+            raise
+
+        # Re-probe after install
+        ok_all, info = _venv_has_torch_stack(vp, status_cb=status_cb, require_torchaudio=require_torchaudio)
+        status_cb(
+            "[RT] venv re-probe: "
+            f"torch={info['torch'][0]} "
+            f"torchvision={info['torchvision'][0]} "
+            f"torchaudio={info['torchaudio'][0]}"
+        )
+        if not ok_all:
+            msg = "\n".join([f"{k}: ok={ok} :: {out}" for k, (ok, out) in info.items()])
+            raise RuntimeError("Torch stack still not importable in runtime venv after install:\n" + msg)
+
+    # Always write/update marker for convenience, but never trust it for decisions.
+    try:
+        _write_torch_marker(marker, status_cb=status_cb)
     except Exception:
-        _force_repair()
-        _purge_bad_torch_from_sysmodules(status_cb=status_cb)
-        _ban_shadow_torch_paths(status_cb=status_cb)
-        import torch  # retry
-        _torch_stack_sanity_check(status_cb=status_cb)
-        if not marker.exists():
-            pyver = f"{sys.version_info.major}.{sys.version_info.minor}"
-            try:
-                import torch, torchvision, torchaudio
-                marker.write_text(json.dumps({
-                    "installed": True,
-                    "python": pyver,
-                    "when": int(time.time()),
-                    "torch": getattr(torch, "__version__", None),
-                    "torchvision": getattr(torchvision, "__version__", None),
-                    "torchaudio": getattr(torchaudio, "__version__", None),
-                }), encoding="utf-8")
-            except Exception:
-                marker.write_text(json.dumps({"installed": True, "python": pyver, "when": int(time.time())}), encoding="utf-8")
+        pass
 
+    # ------------------------------------------------------------
+    # Now import torch in-process, but ONLY after putting runtime site first.
+    # ------------------------------------------------------------
+    sp = str(site)
+    if sp not in sys.path:
+        sys.path.insert(0, sp)
+
+    _demote_shadow_torch_paths(status_cb=status_cb)
+    _purge_bad_torch_from_sysmodules(status_cb=status_cb)
+
+    try:
+        import torch  # noqa
+
+        _TORCH_CACHED = torch
+        _write_qcache_best_effort(rt, site, venv_ver)
         return torch
 
+    except Exception as e:
+        # prevent repeatedly hitting a bad cached site path on next launch
+        try:
+            _qcache_clear()
+        except Exception:
+            pass
+
+        msg = "\n".join([f"{k}: ok={ok} :: {out}" for k, (ok, out) in info.items()])
+        raise RuntimeError(
+            "Runtime venv probe says torch stack exists, but in-process import failed.\n"
+            "This typically indicates a frozen-stdlib / PyInstaller packaging issue, not a bad torch install.\n\n"
+            f"Original error: {type(e).__name__}: {e}\n\n"
+            "Runtime venv probe:\n" + msg
+        ) from e
+
+
 def _find_system_python_cmd() -> list[str]:
     import platform as _plat
     if _plat.system() == "Darwin":
@@ -814,7 +1233,7 @@ def add_runtime_to_sys_path(status_cb=print) -> None:
     """
     Warm up sys.path so a fresh launch can see the runtime immediately.
     """
-    rt = _user_runtime_dir()
+    rt = _user_runtime_dir(status_cb=status_cb)
     p  = _venv_paths(rt)
     vpy = p["python"]
     if not vpy.exists():
@@ -837,3 +1256,69 @@ def add_runtime_to_sys_path(status_cb=print) -> None:
         _demote_shadow_torch_paths(status_cb=status_cb)
     except Exception:
         return
+
+def prewarm_torch_cache(
+    status_cb=print,
+    *,
+    require_torchaudio: bool = True,
+    ensure_venv: bool = True,
+    ensure_numpy: bool = False,
+    validate_marker: bool = True,
+) -> None:
+    """
+    Build and persist the QSettings cache early (startup), so the first real
+    import_torch() call can be zero-subprocess.
+
+    By default this does NOT import torch (keeps startup lighter).
+    It only computes runtime rt/vpy/site and writes QSettings.
+    """
+    try:
+        _ban_shadow_torch_paths(status_cb=status_cb)
+        _purge_bad_torch_from_sysmodules(status_cb=status_cb)
+
+        rt = _user_runtime_dir(status_cb=status_cb)
+        p = _venv_paths(rt)
+        vp = p["python"]
+
+        if ensure_venv:
+            vp = _ensure_venv(rt, status_cb=status_cb)
+
+        if not vp.exists():
+            return
+
+        if ensure_numpy:
+            try:
+                _ensure_numpy(vp, status_cb=status_cb)
+            except Exception:
+                pass
+
+        site = _site_packages(vp)
+        marker = rt / "torch_installed.json"
+        venv_ver = _venv_pyver(vp)
+
+        # Optionally only cache if marker looks valid (recommended),
+        # otherwise you may cache a site-packages that doesn't actually contain torch yet.
+        if validate_marker:
+            if not _marker_says_ready(marker, site, venv_ver, require_torchaudio=require_torchaudio):
+                status_cb("[RT] prewarm: marker not valid; skipping QSettings cache write.")
+                return
+
+        # IMPORTANT: use runtime tag, not app interpreter tag, for mixed-version scenarios
+        cache_tag = rt.name  # e.g. "py312"
+
+        _qcache_set(
+            tag=cache_tag,
+            rt_dir=rt,
+            site=site,
+            python_ver=(f"{venv_ver[0]}.{venv_ver[1]}" if venv_ver else ""),
+            torch_ver=None,
+            tv_ver=None,
+            ta_ver=None,
+            require_torchaudio=require_torchaudio,
+        )
+        status_cb("[RT] prewarm: QSettings cache written.")
+    except Exception as e:
+        try:
+            status_cb(f"[RT] prewarm failed: {type(e).__name__}: {e}")
+        except Exception:
+            pass