fix: guard linux package native cpu baseline (#71)

Author: siddsachar

.github/workflows/release.yml

@@ -132,7 +132,7 @@ jobs:
       - name: Install Linux build/runtime libraries
         run: |
           sudo apt-get update
-          sudo apt-get install -y --no-install-recommends rsync libgl1 libegl1 libglib2.0-0 libxcb-cursor0
+          sudo apt-get install -y --no-install-recommends rsync binutils libgl1 libegl1 libglib2.0-0 libxcb-cursor0
 
       - name: Validate Linux installer scripts
         run: bash -n build_linux_app.sh installer/build_linux_app.sh installer/install-linux.sh

RELEASE_NOTES.md

@@ -39,14 +39,15 @@ This release adds Thoth's **Buddy companion foundation**, a local-first animated
 
 - **Linux launcher install-path fix** — the generated Linux launcher resolves installed symlink chains before computing the app root, so `~/.local/bin/thoth` starts the packaged app from `~/.local/share/thoth/current`; release CI smokes through the installed user launcher path.
 - **Linux packaged startup resilience** — packaged Linux launches now report startup log tails, child-process exit details, configurable `THOTH_STARTUP_TIMEOUT`, and targeted hints for native OpenCV/FAISS/NumPy dependency failures. Camera and screenshot capture degrade gracefully if OpenCV/MSS cannot import instead of blocking app startup.
+- **Linux native CPU-baseline compatibility** — packaged Python builds now keep NumPy below the newer Linux x86_64 wheel line that can require `x86-64-v2` CPU instructions, and Linux package builds scan embedded native libraries for `x86-64-v2/v3/v4` requirements before upload to prevent startup crashes on older x86_64 machines.
 - **Linux installer UX hardening** — source-checkout builds support the root-level `bash build_linux_app.sh <version>` support command, install success messages print `~/.local/bin/thoth` when `~/.local/bin` is not on `PATH`, and maintainer docs distinguish unreleased tarball testing from the one-line installer that resolves published GitHub Release assets.
 - **Optional native package diagnostics** — startup detects installed-but-broken optional native packages such as TorchCodec, logs a concrete recovery command, and makes Transformers treat broken TorchCodec as unavailable instead of letting optional audio/video helpers crash Thoth during startup.
 - **Windows embedded-Python repair hardening** — Windows installer repair/upgrade replaces the bundled `{app}\python` runtime before copying the new payload, preventing manually installed or corrupted packages from surviving an over-the-top reinstall.
 
 ### Tests & Release Checks
 
 - **Buddy coverage** — focused tests cover core event/config/asset behavior, Hatch motion activation, UTF-8 config loading, UI wiring, event source hooks, runtime fallback behavior, dockable in-app behavior, built-in motion semantics, and packaging inclusion. Manual-style browser smokes verify docked, undocked, and overlay playback from the bundled pack.
-- **Reliability coverage** — startup hardening tests cover broken TorchCodec detection, Linux native dependency recovery hints, launcher log-tail diagnostics, Windows installer embedded-Python replacement, app import smoke, Settings -> Models catalog bounds and picker guidance, status-tool model validation, safe timer cleanup, and installed Linux launcher symlink/default invocation resolution.
+- **Reliability coverage** — startup hardening tests cover broken TorchCodec detection, Linux native dependency recovery hints, NumPy `x86-64-v2` startup failures, launcher log-tail diagnostics, Windows installer embedded-Python replacement, app import smoke, Settings -> Models catalog bounds and picker guidance, status-tool model validation, safe timer cleanup, and installed Linux launcher symlink/default invocation resolution.
 - **Provider/Vision coverage** — provider tests cover ChatGPT / Codex Vision Quick Choice capability retention and Codex Responses multimodal image payload preservation.
 - **Release smoke** — release and CI workflows build Windows, macOS, and Linux artifacts for v3.21.0, run focused startup/provider suites before installer builds, and smoke the installed Linux launcher path.
 - **Test layout cleanup** — root-level test files now live under `tests/`, pytest discovers that folder by default, CI/release workflows call the moved paths, and installer regressions assert the `tests/` tree is not shipped in Windows, Linux, or macOS packages.
@@ -66,7 +67,7 @@ This release adds Thoth's **Buddy companion foundation**, a local-first animated
 | `buddy/`, `static/buddy/`, `ui/buddy.py` | Buddy event/config/runtime surfaces, bundled motion packs, in-app docked/undocked UI, and desktop overlay route/runtime assets |
 | `ui/settings.py`, `ui/model_catalog.py`, `providers/selection.py`, `providers/catalog.py`, `providers/codex.py`, `models.py` | Settings -> Models stability, picker clarity, Codex Vision capability retention, and provider/model catalog refinements |
 | `providers/transports/codex_responses.py`, `vision.py`, `tools/thoth_status_tool.py` | Codex multimodal image payload preservation, startup-safe Vision capture backends, and controlled Brain/Vision setting updates |
-| `launcher.py`, `startup_diagnostics.py`, `installer/thoth_setup.iss`, `installer/install_deps.bat` | Startup diagnostics, Linux readiness failure context, Windows embedded-Python repair, and optional native package recovery hints |
+| `launcher.py`, `startup_diagnostics.py`, `requirements.txt`, `installer/thoth_setup.iss`, `installer/install_deps.bat` | Startup diagnostics, Linux readiness failure context, Linux native CPU-baseline packaging guard, Windows embedded-Python repair, and optional native package recovery hints |
 | `installer/build_linux_app.sh`, `installer/install-linux.sh`, `build_linux_app.sh`, `.github/workflows/release.yml`, `.github/workflows/ci.yml` | Linux launcher symlink resolution, root build wrapper, installed launcher smoke, and release/CI packaging checks |
 | `docs/RELEASING.md`, `installer/README.md`, `README.md`, `docs/ARCHITECTURE.md` | Release checklist, installer, architecture, and user-facing Linux/provider/model guidance updates |
 | `tests/`, `pytest.ini` | Focused startup/Linux/provider/model-selection regressions, release-smoke coverage, moved test discovery, and installer exclusion guards |

installer/build_linux_app.sh

@@ -85,6 +85,12 @@ info "[2/6] Installing Python packages from requirements.txt..."
 "$PYTHON_PREFIX/bin/python3" -m pip install -r "$PROJECT_DIR/requirements.txt" --quiet 2>&1 | tail -5
 ok "Python packages installed"
 
+if [ "$PACKAGE_ARCH" = "x86_64" ]; then
+    info "Checking native CPU baselines for older x86_64 compatibility..."
+    "$PYTHON_PREFIX/bin/python3" "$PROJECT_DIR/scripts/check_linux_native_baseline.py" --arch "$PACKAGE_ARCH"
+    ok "Native CPU baselines are package-compatible"
+fi
+
 if [ "$BUNDLE_PLAYWRIGHT" = "1" ]; then
     info "Installing Playwright Chromium into package..."
     export PLAYWRIGHT_BROWSERS_PATH="$PYTHON_PREFIX/playwright-browsers"

launcher.py

@@ -221,10 +221,16 @@ def _startup_failure_hints(log_text: str, python_executable: str | None = None)
             "Detected a FAISS native import failure during startup.",
             "Recovery: reinstall Thoth's packaged runtime or install the Linux libraries named in the traceback.",
         ])
-    if "numpy.dtype size changed" in text or "numpy.core.multiarray failed to import" in text:
+    if (
+        "numpy.dtype size changed" in text
+        or "numpy.core.multiarray failed to import" in text
+        or "numpy was built with baseline optimizations" in text
+        or "x86_v2" in text
+    ):
         hints.extend([
-            "Detected a NumPy/native wheel ABI mismatch during startup.",
-            "Recovery: reinstall or repair Thoth so the embedded Python runtime and wheels are replaced together.",
+            "Detected a NumPy/native wheel startup failure.",
+            "On older x86_64 CPUs this can happen if the packaged NumPy wheel requires x86-64-v2 instructions.",
+            "Recovery: install a Thoth Linux build that pins NumPy below the x86-64-v2 wheel line, or rebuild the Linux tarball from this checkout.",
         ])
     return hints
 

requirements.txt

@@ -72,7 +72,11 @@ plyer
 youtube-search
 
 # ── Common (used directly, also pulled transitively) ────────────────────────
-numpy
+# NumPy 2.3+ Linux x86_64 wheels can require x86-64-v2 CPU instructions. Keep
+# packaged Python 3.12/3.13 builds on the older baseline; Python 3.14 needs the
+# current line while wheel support is still catching up.
+numpy<2.3; python_version < "3.14"
+numpy; python_version >= "3.14"
 requests
 pydantic
 pyyaml

scripts/check_linux_native_baseline.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""Verify Linux package native wheels do not require a newer x86_64 baseline."""
+
+from __future__ import annotations
+
+import argparse
+import platform
+import re
+import shutil
+import site
+import subprocess
+import sys
+from collections.abc import Iterable
+from pathlib import Path
+
+_X86_BASELINE_MARKERS = {"X86_V2", "X86_V3", "X86_V4"}
+
+
+def _normalized_arch(value: str | None = None) -> str:
+    arch = (value or platform.machine() or "").lower().replace("-", "_")
+    if arch in {"amd64", "x64"}:
+        return "x86_64"
+    if arch == "arm64":
+        return "aarch64"
+    return arch
+
+
+def _numpy_cpu_baseline() -> list[str]:
+    try:
+        try:
+            import numpy._core._multiarray_umath as umath
+        except ModuleNotFoundError:
+            import numpy.core._multiarray_umath as umath  # type: ignore[no-redef]
+    except Exception as exc:
+        raise RuntimeError(f"could not import NumPy CPU metadata: {exc}") from exc
+
+    baseline = getattr(umath, "__cpu_baseline__", None)
+    if baseline is None:
+        raise RuntimeError("NumPy does not expose __cpu_baseline__ metadata")
+    return [str(feature).upper().replace("-", "_") for feature in baseline]
+
+
+def _blocked_x86_baselines(features: Iterable[str]) -> list[str]:
+    normalized = {str(feature).upper().replace("-", "_") for feature in features}
+    return sorted(feature for feature in normalized if feature in _X86_BASELINE_MARKERS)
+
+
+def _blocked_readelf_baselines(output: str) -> list[str]:
+    normalized = output.upper().replace("-", "_")
+    blocked: set[str] = set()
+    for marker in _X86_BASELINE_MARKERS:
+        if marker in normalized:
+            blocked.add(marker)
+    for version in re.findall(r"X86_64_V([234])", normalized):
+        blocked.add(f"X86_V{version}")
+    return sorted(blocked)
+
+
+def _native_search_roots() -> list[Path]:
+    roots = {Path(sys.prefix).resolve()}
+    for path in site.getsitepackages():
+        try:
+            roots.add(Path(path).resolve())
+        except OSError:
+            continue
+    return sorted(roots)
+
+
+def _native_binaries(roots: Iterable[Path]) -> list[Path]:
+    binaries: set[Path] = set()
+    for root in roots:
+        if not root.exists():
+            continue
+        for pattern in ("*.so", "*.so.*"):
+            binaries.update(path for path in root.rglob(pattern) if path.is_file())
+    return sorted(binaries)
+
+
+def _scan_elf_baselines(readelf: str, binaries: Iterable[Path]) -> list[tuple[Path, list[str]]]:
+    failures: list[tuple[Path, list[str]]] = []
+    for binary in binaries:
+        result = subprocess.run(
+            [readelf, "-n", str(binary)],
+            text=True,
+            capture_output=True,
+            check=False,
+            timeout=20,
+        )
+        output = f"{result.stdout}\n{result.stderr}"
+        blocked = _blocked_readelf_baselines(output)
+        if blocked:
+            failures.append((binary, blocked))
+    return failures
+
+
+def _print_failures(failures: Iterable[tuple[Path, list[str]]]) -> None:
+    print("ERROR: Linux package contains native binaries requiring newer x86_64 CPU baselines:", file=sys.stderr)
+    for binary, blocked in failures:
+        print(f"  {binary}: {', '.join(blocked)}", file=sys.stderr)
+    print("Use baseline-compatible wheels or pin the dependency before publishing the Linux package.", file=sys.stderr)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--arch",
+        default=None,
+        help="Package architecture to validate. Defaults to platform.machine().",
+    )
+    parser.add_argument(
+        "--skip-elf-scan",
+        action="store_true",
+        help="Skip readelf scanning and only run package-specific metadata checks.",
+    )
+    args = parser.parse_args(argv)
+
+    arch = _normalized_arch(args.arch)
+    if arch != "x86_64":
+        print(f"Linux native CPU baseline check skipped for arch={arch}")
+        return 0
+
+    failures: list[tuple[Path, list[str]]] = []
+
+    try:
+        numpy_baseline = _numpy_cpu_baseline()
+    except RuntimeError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+    numpy_blocked = _blocked_x86_baselines(numpy_baseline)
+    if numpy_blocked:
+        failures.append((Path("numpy.__cpu_baseline__"), numpy_blocked))
+
+    if not args.skip_elf_scan:
+        readelf = shutil.which("readelf")
+        if not readelf:
+            print("ERROR: readelf is required for Linux native baseline verification", file=sys.stderr)
+            return 1
+        failures.extend(_scan_elf_baselines(readelf, _native_binaries(_native_search_roots())))
+
+    if failures:
+        _print_failures(failures)
+        return 1
+
+    print(f"Linux native CPU baseline OK for x86_64 package; NumPy baseline={', '.join(numpy_baseline) or 'none'}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/test_linux_support.py

@@ -8,6 +8,7 @@
 import launcher
 import pytest
 import updater
+from scripts import check_linux_native_baseline
 
 
 def _linux_launcher_template() -> str:
@@ -123,6 +124,7 @@ def test_linux_tarball_installs_into_xdg_tree(monkeypatch, tmp_path):
 
 def test_linux_build_script_declares_expected_package_contract():
     script = Path("installer/build_linux_app.sh").read_text(encoding="utf-8")
+    requirements = Path("requirements.txt").read_text(encoding="utf-8")
 
     assert "unknown-linux-gnu-install_only" in script
     assert 'PACKAGE_NAME="Thoth-${VERSION}-Linux-${PACKAGE_ARCH}"' in script
@@ -137,10 +139,41 @@ def test_linux_build_script_declares_expected_package_contract():
     assert "THOTH_SUPPRESS_INSTALL_PATH_HINT" in script
     assert "export PATH=\"$HOME/.local/bin:$PATH\"" in script
     assert "Run: $LAUNCH_CMD" in script
+    assert 'numpy<2.3; python_version < "3.14"' in requirements
+    assert "scripts/check_linux_native_baseline.py" in script
+    assert "Checking native CPU baselines" in script
     for package in ("tools", "channels", "bundled_skills", "providers", "mcp_client", "migration"):
         assert package in script
 
 
+def test_linux_native_baseline_check_blocks_x86_v2_metadata():
+    blocked = check_linux_native_baseline._blocked_x86_baselines(["SSE", "SSE2", "X86_V2"])
+
+    assert blocked == ["X86_V2"]
+
+
+def test_linux_native_baseline_check_allows_legacy_x86_metadata():
+    blocked = check_linux_native_baseline._blocked_x86_baselines(["SSE", "SSE2"])
+
+    assert blocked == []
+
+
+def test_linux_native_baseline_check_blocks_readelf_x86_v3_output():
+    output = "Properties: x86 ISA needed: x86-64-baseline, x86-64-v3"
+
+    blocked = check_linux_native_baseline._blocked_readelf_baselines(output)
+
+    assert blocked == ["X86_V3"]
+
+
+def test_linux_native_baseline_check_allows_readelf_baseline_output():
+    output = "Properties: x86 ISA needed: x86-64-baseline"
+
+    blocked = check_linux_native_baseline._blocked_readelf_baselines(output)
+
+    assert blocked == []
+
+
 def test_linux_root_build_wrapper_delegates_to_installer_script():
     script = Path("build_linux_app.sh").read_text(encoding="utf-8")
 
@@ -276,6 +309,7 @@ def test_release_workflows_reference_linux_artifact():
     assert "installer/install-linux.sh" in ci
     assert "Thoth-*-Linux-*.tar.gz" in release
     assert "libxcb-cursor0" in release
+    assert "binutils" in release
     linux_smoke = release[release.index("Smoke Linux package"):]
     assert "--no-root-check" not in linux_smoke
     assert "HOME=\"$RUNNER_TEMP/thoth-linux-home\"" in linux_smoke

tests/test_startup_hardening.py

@@ -56,6 +56,16 @@ def test_launcher_hints_for_linux_opencv_native_failure():
     assert any("libgl1" in hint for hint in hints)
 
 
+def test_launcher_hints_for_numpy_x86_v2_failure():
+    hints = launcher._startup_failure_hints(
+        "RuntimeError: NumPy was built with baseline optimizations: "
+        "(X86_V2) but your machine doesn't support: (X86_V2)."
+    )
+
+    assert any("NumPy/native wheel startup failure" in hint for hint in hints)
+    assert any("x86-64-v2" in hint for hint in hints)
+
+
 def test_launcher_logs_app_tail_on_startup_failure(tmp_path, caplog):
     log_path = tmp_path / "thoth_app.log"
     log_path.write_text("line one\nTraceback\nImportError: libGL.so.1 missing\n", encoding="utf-8")