fix(cookbook): recover from stale llama-server shims

Reconcile Odysseus-owned Python compatibility shims when llama_cpp.server is no longer available, allowing healthy native llama-server binaries in PATH to be discovered and executed without shadowing.

Fixes #6079

routes/cookbook_helpers.py

@@ -1030,6 +1030,133 @@ def _append_llama_cpp_linux_accel_build_lines(runner_lines: list[str]) -> None:
     runner_lines.append('  fi  # end _odysseus_have_prebuilt guard')
 
 
+ODYSSEUS_LLAMA_SHIM_MARKER = "# Auto-generated by Odysseus Cookbook: a `llama-server` lookalike"
+
+
+def _append_llama_server_shim_definition_lines(runner_lines: list[str]) -> None:
+    """Define the helper shell function that generates the Odysseus compatibility shim."""
+    marker = f"'{_bash_squote(ODYSSEUS_LLAMA_SHIM_MARKER)}'"
+    runner_lines.append('_odysseus_create_llama_shim() {')
+    runner_lines.append('  local _target="$HOME/bin/llama-server"')
+    runner_lines.append(f'  local _marker={marker}')
+    runner_lines.append('  if [ -e "$_target" ] || [ -L "$_target" ]; then')
+    runner_lines.append('    if [ -f "$_target" ] && [ ! -L "$_target" ] && grep -Fxq "$_marker" "$_target" 2>/dev/null; then')
+    runner_lines.append('      : # existing Odysseus shim — safe to replace')
+    runner_lines.append('    else')
+    runner_lines.append('      echo "[odysseus] WARNING: $_target already exists and is not an Odysseus-managed shim; leaving untouched." >&2')
+    runner_lines.append('      return 1')
+    runner_lines.append('    fi')
+    runner_lines.append('  fi')
+    runner_lines.append('  mkdir -p "$HOME/bin" || return 1')
+    runner_lines.append('  local _tmp')
+    runner_lines.append('  _tmp="$(mktemp "$HOME/bin/.llama-server.odysseus.tmp.XXXXXX")" || {')
+    runner_lines.append('    echo "[odysseus] ERROR: unable to create secure temporary llama-server shim in $HOME/bin" >&2')
+    runner_lines.append('    return 1')
+    runner_lines.append('  }')
+    runner_lines.append("  if ! cat > \"$_tmp\" <<'_ODY_LLAMA_SHIM_EOF'")
+    runner_lines.append('#!/usr/bin/env bash')
+    runner_lines.append(ODYSSEUS_LLAMA_SHIM_MARKER)
+    runner_lines.append('# that translates the native CLI to `python -m llama_cpp.server`.')
+    runner_lines.append('# Lets cookbook-generated launch commands run unchanged on hosts')
+    runner_lines.append('# where only the pip llama-cpp-python package is installed.')
+    runner_lines.append('ARGS=()')
+    runner_lines.append('while [ $# -gt 0 ]; do')
+    runner_lines.append('  case "$1" in')
+    runner_lines.append('    -ngl|--gpu-layers|--n-gpu-layers) ARGS+=(--n_gpu_layers "$2"); shift 2 ;;')
+    runner_lines.append('    -c|--ctx-size) ARGS+=(--n_ctx "$2"); shift 2 ;;')
+    runner_lines.append('    -b|--batch-size) ARGS+=(--n_batch "$2"); shift 2 ;;')
+    runner_lines.append('    -ub|--ubatch-size) shift 2 ;;  # llama-cpp-python has no separate ubatch')
+    runner_lines.append('    --flash-attn) ARGS+=(--flash_attn true); shift 2 ;;')
+    runner_lines.append('    --cache-type-k) ARGS+=(--type_k "$2"); shift 2 ;;')
+    runner_lines.append('    --cache-type-v) ARGS+=(--type_v "$2"); shift 2 ;;')
+    runner_lines.append('    --n-cpu-moe) ARGS+=(--n_cpu_moe "$2"); shift 2 ;;')
+    runner_lines.append('    --mmproj) ARGS+=(--clip_model_path "$2"); shift 2 ;;')
+    runner_lines.append('    --image-max-tokens) shift 2 ;;  # native-only')
+    runner_lines.append('    --no-mmap) ARGS+=(--no_mmap true); shift ;;')
+    runner_lines.append('    --no-warmup) shift ;;  # native-only')
+    runner_lines.append('    --chat-template) ARGS+=(--chat_format "$2"); shift 2 ;;')
+    runner_lines.append('    --fit|--split-mode|--tensor-split|--main-gpu|--parallel) shift 2 ;;  # native-only')
+    runner_lines.append('    --mlock) ARGS+=(--use_mlock true); shift ;;')
+    runner_lines.append('    *) ARGS+=("$1"); shift ;;')
+    runner_lines.append('  esac')
+    runner_lines.append('done')
+    runner_lines.append('exec python3 -m llama_cpp.server "${ARGS[@]}"')
+    runner_lines.append('_ODY_LLAMA_SHIM_EOF')
+    runner_lines.append('  then')
+    runner_lines.append('    rm -f -- "$_tmp"')
+    runner_lines.append('    return 1')
+    runner_lines.append('  fi')
+    runner_lines.append('  chmod +x "$_tmp" || { rm -f -- "$_tmp"; return 1; }')
+    runner_lines.append('  mv -f -- "$_tmp" "$_target" || { rm -f -- "$_tmp"; return 1; }')
+    runner_lines.append('  hash -r')
+    runner_lines.append('  echo "[odysseus] Created llama-server shim → python -m llama_cpp.server (no native binary needed)"')
+    runner_lines.append('}')
+
+
+def _append_llama_server_shim_reconciliation_lines(runner_lines: list[str]) -> None:
+    """Reconcile an existing ~/bin/llama-server if it is owned by Odysseus Cookbook.
+
+    Invariants:
+    - Never touch an arbitrary user-owned executable or symlink.
+    - If ~/bin/llama-server is an Odysseus generated shim:
+        - If a native llama-server is present and healthy elsewhere on PATH, remove the shim
+          so the native binary is used.
+        - If python3 -m llama_cpp.server is unavailable, remove the stale shim
+          and hash -r so the fallback/build path is triggered.
+        - If no healthy native server exists and llama_cpp.server is working, preserve it.
+    """
+    marker = f"'{_bash_squote(ODYSSEUS_LLAMA_SHIM_MARKER)}'"
+    runner_lines.append('[ -r ~/.config/odysseus-llama-cpp-env ] && . ~/.config/odysseus-llama-cpp-env')
+    runner_lines.append(f'if [ -f "$HOME/bin/llama-server" ] && [ ! -L "$HOME/bin/llama-server" ] && grep -Fxq {marker} "$HOME/bin/llama-server" 2>/dev/null; then')
+    runner_lines.append('  _odysseus_has_native=""')
+    runner_lines.append('  _odysseus_saved_ifs="$IFS"')
+    runner_lines.append('  IFS=\':\'')
+    runner_lines.append('  read -r -a _odysseus_path_parts <<< "$PATH"')
+    runner_lines.append('  IFS="$_odysseus_saved_ifs"')
+    runner_lines.append('  for _dir in "${_odysseus_path_parts[@]}"; do')
+    runner_lines.append('    [ -n "$_dir" ] || continue')
+    runner_lines.append('    case "$_dir" in')
+    runner_lines.append('      "$HOME/bin"|"$HOME/bin/") continue ;;')
+    runner_lines.append('    esac')
+    runner_lines.append('    _candidate="$_dir/llama-server"')
+    runner_lines.append('    if [ -x "$_candidate" ] && "$_candidate" --version >/dev/null 2>&1; then')
+    runner_lines.append('      _odysseus_has_native=1')
+    runner_lines.append('      break')
+    runner_lines.append('    fi')
+    runner_lines.append('  done')
+    runner_lines.append('  if [ -n "$_odysseus_has_native" ]; then')
+    runner_lines.append('    echo "[odysseus] Native llama-server detected — retiring Odysseus compatibility shim in ~/bin"')
+    runner_lines.append('    rm -f "$HOME/bin/llama-server"')
+    runner_lines.append('    hash -r')
+    runner_lines.append('  elif ! python3 -c "import llama_cpp.server" 2>/dev/null; then')
+    runner_lines.append('    echo "[odysseus] Removing stale Odysseus llama-server shim (python3 -m llama_cpp.server unavailable)"')
+    runner_lines.append('    rm -f "$HOME/bin/llama-server"')
+    runner_lines.append('    hash -r')
+    runner_lines.append('  fi')
+    runner_lines.append('fi')
+
+
+def _append_llama_server_finalization_lines(runner_lines: list[str], platform_hint: str = "") -> None:
+    """Reconcile post-install launcher availability and enforce fail-closed invariant.
+
+    Guarantees that if python3 -m llama_cpp.server is usable but the `llama-server`
+    command is unresolvable, the compatibility launcher is created. If no usable
+    launcher exists after all build/install attempts, sets ODYSSEUS_PREFLIGHT_EXIT=127.
+    """
+    err_msg = (
+        f"ERROR: llama.cpp serving is not available on {platform_hint} after install attempts."
+        if platform_hint
+        else "ERROR: llama.cpp serving is not available after install/build attempts."
+    )
+    runner_lines.append('if ! command -v llama-server >/dev/null 2>&1 && python3 -c "import llama_cpp.server" 2>/dev/null; then')
+    runner_lines.append('  _odysseus_create_llama_shim')
+    runner_lines.append('fi')
+    runner_lines.append('if ! command -v llama-server &>/dev/null; then')
+    runner_lines.append(f'  echo "{err_msg}"')
+    runner_lines.append('  ODYSSEUS_PREFLIGHT_EXIT=127')
+    runner_lines.append('fi')
+
+
 def _llama_cpp_rebuild_cmd(update_source: bool = False) -> str:
     """Shell command that clears the Cookbook-managed llama.cpp build.
 

routes/cookbook_routes.py

@@ -57,9 +57,11 @@ from routes.cookbook_helpers import (
     _pip_install_no_cache, _user_shell_path_bootstrap, _venv_safe_local_pip_install_cmd,
     _diagnose_serve_output, run_ssh_command_async,
     _ollama_bind_from_cmd, _pip_install_fallback_chain, _pip_install_no_cache,
-    _user_shell_path_bootstrap, _venv_safe_local_pip_install_cmd,
     _append_pip_install_runner_lines, _pip_install_command_without_break_system_packages,
     _normalize_llama_cpp_python_cache_types,
+    _append_llama_server_shim_definition_lines,
+    _append_llama_server_shim_reconciliation_lines,
+    _append_llama_server_finalization_lines,
     ModelDownloadRequest, ServeRequest,
 )
 
@@ -2102,7 +2104,7 @@ def setup_cookbook_routes() -> APIRouter:
                 ps_lines.append('}')
             elif "llama_cpp" in req.cmd or "llama-server" in req.cmd:
                 ps_lines.append('# Auto-install llama-cpp-python if missing')
-                ps_lines.append('try { python -c "import llama_cpp" 2>$null } catch {}')
+                ps_lines.append('try { python -c "import llama_cpp.server" 2>$null } catch {}')
                 ps_lines.append('if ($LASTEXITCODE -ne 0) {')
                 ps_lines.append('  Write-Host "Installing llama-cpp-python..."')
                 ps_lines.append('  python -m pip install llama-cpp-python[server]')
@@ -2188,13 +2190,16 @@ def setup_cookbook_routes() -> APIRouter:
                 # ollama is found (otherwise macOS falls back to a slow source build).
                 # /opt/homebrew = Apple Silicon, /usr/local = Intel; harmless on Linux.
                 runner_lines.append('export PATH="$HOME/.local/bin:$HOME/bin:$HOME/llama.cpp/build/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"')
+                _append_llama_server_shim_definition_lines(runner_lines)
+                _append_llama_server_shim_reconciliation_lines(runner_lines)
                 runner_lines.append('if [ -d /data/data/com.termux ]; then')
                 runner_lines.append('  # Termux: no native build — use the Python bindings (CPU).')
-                runner_lines.append('  if ! python3 -c "import llama_cpp" 2>/dev/null; then')
+                runner_lines.append('  if ! python3 -c "import llama_cpp.server" 2>/dev/null; then')
                 runner_lines.append('    pkg install -y cmake 2>/dev/null')
                 runner_lines.append('    pip install numpy diskcache jinja2 2>/dev/null')
                 runner_lines.append('    CMAKE_ARGS="-DGGML_BLAS=OFF -DGGML_LLAMAFILE=OFF" pip install \'llama-cpp-python[server]\' --no-build-isolation --no-cache-dir 2>&1 || true')
                 runner_lines.append('  fi')
+                _append_llama_server_finalization_lines(runner_lines, platform_hint="Termux")
                 runner_lines.append('elif ! command -v llama-server &>/dev/null; then')
                 runner_lines.append('  echo "Native llama-server not found — building from source (one-time, may take a few minutes)..."')
                 runner_lines.append('  mkdir -p ~/bin')
@@ -2212,8 +2217,7 @@ def setup_cookbook_routes() -> APIRouter:
                 # would reuse the bad settings and fail again. CMAKE_BUILD_TYPE is
                 # explicit so the binary is optimized (Metal auto-enables on macOS).
                 runner_lines.append('    cd ~/llama.cpp && rm -rf build && cmake -B build -DCMAKE_BUILD_TYPE=Release \\')
-                runner_lines.append('      && cmake --build build -j"$NPROC" --target llama-server \\')
+                runner_lines.append('      && cmake --build build -j"$NPROC" --target llama-server')
-                runner_lines.append('      && ln -sf ~/llama.cpp/build/bin/llama-server ~/bin/llama-server')
                 runner_lines.append('  else')
                 _append_llama_cpp_linux_accel_build_lines(runner_lines)
                 runner_lines.append('  fi')
@@ -2237,58 +2241,12 @@ def setup_cookbook_routes() -> APIRouter:
                 runner_lines.append('      fi')
                 runner_lines.append('    fi')
                 runner_lines.append('  fi')
-                # SHORT-CIRCUIT before the build/pip fallback: if the
+                # If the native build failed, fall back to the Python bindings.
-                # native binary is missing but llama_cpp Python is already
+                runner_lines.append('  if ! command -v llama-server &>/dev/null && ! python3 -c "import llama_cpp.server" 2>/dev/null; then')
-                # installed, drop a wrapper at ~/bin/llama-server that
-                # translates llama-server CLI args to llama_cpp.server's
-                # underscore-style flags. The user's serve command stays
-                # `llama-server ...` and "just works" — no build, no cmake,
-                # no second install. This is the path that unblocks every
-                # remote where pip-installed llama-cpp-python is already
-                # working but Cookbook used to insist on a native binary.
-                runner_lines.append('  if ! command -v llama-server >/dev/null 2>&1 && python3 -c "import llama_cpp" 2>/dev/null; then')
-                runner_lines.append('    mkdir -p ~/bin')
-                runner_lines.append('    cat > ~/bin/llama-server <<\'_ODY_LLAMA_SHIM_EOF\'')
-                runner_lines.append('#!/usr/bin/env bash')
-                runner_lines.append('# Auto-generated by Odysseus Cookbook: a `llama-server` lookalike')
-                runner_lines.append('# that translates the native CLI to `python -m llama_cpp.server`.')
-                runner_lines.append('# Lets cookbook-generated launch commands run unchanged on hosts')
-                runner_lines.append('# where only the pip llama-cpp-python package is installed.')
-                runner_lines.append('ARGS=()')
-                runner_lines.append('while [ $# -gt 0 ]; do')
-                runner_lines.append('  case "$1" in')
-                runner_lines.append('    -ngl|--gpu-layers|--n-gpu-layers) ARGS+=(--n_gpu_layers "$2"); shift 2 ;;')
-                runner_lines.append('    -c|--ctx-size) ARGS+=(--n_ctx "$2"); shift 2 ;;')
-                runner_lines.append('    -b|--batch-size) ARGS+=(--n_batch "$2"); shift 2 ;;')
-                runner_lines.append('    -ub|--ubatch-size) shift 2 ;;  # llama-cpp-python has no separate ubatch')
-                runner_lines.append('    --flash-attn) ARGS+=(--flash_attn true); shift 2 ;;')
-                runner_lines.append('    --cache-type-k) ARGS+=(--type_k "$2"); shift 2 ;;')
-                runner_lines.append('    --cache-type-v) ARGS+=(--type_v "$2"); shift 2 ;;')
-                runner_lines.append('    --n-cpu-moe) ARGS+=(--n_cpu_moe "$2"); shift 2 ;;')
-                runner_lines.append('    --mmproj) ARGS+=(--clip_model_path "$2"); shift 2 ;;')
-                runner_lines.append('    --image-max-tokens) shift 2 ;;  # native-only')
-                runner_lines.append('    --no-mmap) ARGS+=(--no_mmap true); shift ;;')
-                runner_lines.append('    --no-warmup) shift ;;  # native-only')
-                runner_lines.append('    --chat-template) ARGS+=(--chat_format "$2"); shift 2 ;;')
-                runner_lines.append('    --fit|--split-mode|--tensor-split|--main-gpu|--parallel) shift 2 ;;  # native-only')
-                runner_lines.append('    --mlock) ARGS+=(--use_mlock true); shift ;;')
-                runner_lines.append('    *) ARGS+=("$1"); shift ;;')
-                runner_lines.append('  esac')
-                runner_lines.append('done')
-                runner_lines.append('exec python3 -m llama_cpp.server "${ARGS[@]}"')
-                runner_lines.append('_ODY_LLAMA_SHIM_EOF')
-                runner_lines.append('    chmod +x ~/bin/llama-server')
-                runner_lines.append('    echo "[odysseus] Created llama-server shim → python -m llama_cpp.server (no native binary needed)"')
-                runner_lines.append('  fi')
-                runner_lines.append('  # If the native build failed, fall back to the Python bindings.')
-                runner_lines.append('  if ! command -v llama-server &>/dev/null && ! python3 -c "import llama_cpp" 2>/dev/null; then')
                 runner_lines.append('    echo "llama-server build failed — installing Python bindings as fallback..."')
                 runner_lines.append(f"    {_pip_install_fallback_chain('llama-cpp-python[server]', python_cmd='pip')} || true")
                 runner_lines.append('  fi')
-                runner_lines.append('  if ! command -v llama-server &>/dev/null && ! python3 -c "import llama_cpp" 2>/dev/null; then')
+                _append_llama_server_finalization_lines(runner_lines)
-                runner_lines.append('    echo "ERROR: llama.cpp serving is not available after install/build attempts."')
-                runner_lines.append('    ODYSSEUS_PREFLIGHT_EXIT=127')
-                runner_lines.append('  fi')
                 runner_lines.append('fi')
             elif re.search(r"\bollama\s+serve\b", req.cmd):
                 handled_ollama_serve = True

tests/test_cookbook_dependency_completion_regression.py

@@ -1,4 +1,14 @@
+import os
+import subprocess
 from pathlib import Path
+import pytest
+from core.platform_compat import find_bash, git_bash_path
+from routes.cookbook_helpers import (
+    ODYSSEUS_LLAMA_SHIM_MARKER,
+    _append_llama_server_shim_definition_lines,
+    _append_llama_server_shim_reconciliation_lines,
+    _append_llama_server_finalization_lines,
+)
 
 
 ROOT = Path(__file__).resolve().parents[1]
@@ -115,3 +125,502 @@ def test_local_dependency_probe_refreshes_user_site_visibility():
     # deps (realesrgan) probe as not-installed until a restart. See #4810.
     assert "if user_site and os.path.isdir(user_site):" in source
     assert "site.addsitedir(user_site)" in source
+
+
+def test_llama_runner_path_preserves_standard_user_bin_order():
+    """The runner PATH must preserve standard user $HOME/bin precedence while
+    relying on ownership-aware reconciliation to retire Odysseus shims when
+    native builds exist."""
+    source = _read("routes/cookbook_routes.py")
+
+    assert (
+        'export PATH="$HOME/.local/bin:$HOME/bin:$HOME/llama.cpp/build/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"'
+        in source
+    )
+
+
+def _run_shell(tmp_path, lines, cwd=None, path=None, extra_env=None):
+    from core.platform_compat import find_bash, git_bash_path
+    bash = find_bash() or "bash"
+    env = dict(os.environ, HOME=git_bash_path(tmp_path))
+    if path is not None:
+        env["PATH"] = path
+    if extra_env:
+        env.update(extra_env)
+    return subprocess.run(
+        [bash, "-c", "\n".join(lines)],
+        cwd=str(cwd) if cwd else None,
+        env=env,
+        capture_output=True,
+        text=True,
+    )
+
+
+def _write_odysseus_shim(path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        f"#!/usr/bin/env bash\n{ODYSSEUS_LLAMA_SHIM_MARKER}\nexec python3 -m llama_cpp.server \"$@\"\n",
+        encoding="utf-8",
+    )
+    path.chmod(0o755)
+
+
+def _write_mock_native(path: Path, succeeds: bool = True) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if succeeds:
+        content = '#!/usr/bin/env bash\nif [ "$1" = "--version" ]; then echo "version: 0.1.0-dev"; exit 0; fi\necho "RUN_NATIVE: $@"\nexit 0\n'
+    else:
+        content = '#!/usr/bin/env bash\necho "error: missing libllama.so" >&2\nexit 127\n'
+    path.write_text(content, encoding="utf-8")
+    path.chmod(0o755)
+
+
+def _write_mock_python3(path: Path, succeeds: bool = True) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(f"#!/usr/bin/env bash\nexit {0 if succeeds else 1}\n", encoding="utf-8")
+    path.chmod(0o755)
+
+
+def test_odysseus_create_llama_shim_never_overwrites_user_regular_file(tmp_path):
+    """Creation boundary: never overwrite a non-executable user-owned regular file."""
+    user_file = tmp_path / "bin/llama-server"
+    user_file.parent.mkdir(parents=True, exist_ok=True)
+    original_content = "user configuration or binary data without marker"
+    user_file.write_text(original_content, encoding="utf-8")
+
+    lines = []
+    _append_llama_server_shim_definition_lines(lines)
+    lines.append('_odysseus_create_llama_shim')
+
+    res = _run_shell(tmp_path, lines)
+    assert res.returncode != 0, "Creation should return non-zero when target is a user file"
+    assert user_file.read_text(encoding="utf-8") == original_content, "User file must remain byte-for-byte unchanged"
+
+
+def test_odysseus_create_llama_shim_never_overwrites_user_symlink(tmp_path):
+    """Creation boundary: never follow or overwrite a user-owned symlink."""
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir(parents=True, exist_ok=True)
+    target_file = tmp_path / "user_target.txt"
+    target_file.write_text("precious user target content", encoding="utf-8")
+    user_symlink = bin_dir / "llama-server"
+    user_symlink.symlink_to(target_file)
+
+    lines = []
+    _append_llama_server_shim_definition_lines(lines)
+    lines.append('_odysseus_create_llama_shim')
+
+    res = _run_shell(tmp_path, lines)
+    assert res.returncode != 0, "Creation should return non-zero when target is a user symlink"
+    assert user_symlink.is_symlink(), "Symlink must remain intact"
+    assert target_file.read_text(encoding="utf-8") == "precious user target content", "Target file must not be modified"
+
+
+def test_odysseus_create_llama_shim_never_overwrites_dangling_symlink(tmp_path):
+    """Creation boundary: never overwrite a dangling user-owned symlink."""
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir(parents=True, exist_ok=True)
+    dangling_symlink = bin_dir / "llama-server"
+    dangling_symlink.symlink_to(tmp_path / "nonexistent_target")
+
+    lines = []
+    _append_llama_server_shim_definition_lines(lines)
+    lines.append('_odysseus_create_llama_shim')
+
+    res = _run_shell(tmp_path, lines)
+    assert res.returncode != 0, "Creation should return non-zero when target is a dangling symlink"
+    assert dangling_symlink.is_symlink(), "Dangling symlink must remain intact"
+
+
+def test_odysseus_create_llama_shim_safely_replaces_existing_odysseus_shim(tmp_path):
+    """Creation boundary: safely replace an existing Odysseus-owned compatibility shim."""
+    shim_file = tmp_path / "bin/llama-server"
+    shim_file.parent.mkdir(parents=True, exist_ok=True)
+    shim_file.write_text(f"#!/bin/bash\n{ODYSSEUS_LLAMA_SHIM_MARKER}\n# old shim body\n", encoding="utf-8")
+
+    lines = []
+    _append_llama_server_shim_definition_lines(lines)
+    lines.append('_odysseus_create_llama_shim')
+
+    res = _run_shell(tmp_path, lines)
+    assert res.returncode == 0
+    new_content = shim_file.read_text(encoding="utf-8")
+    assert ODYSSEUS_LLAMA_SHIM_MARKER in new_content
+    assert "exec python3 -m llama_cpp.server" in new_content
+
+
+def test_odysseus_create_llama_shim_secure_temp_prevents_symlink_attack(tmp_path):
+    """Creation boundary: secure mktemp prevents predictable $$ temp symlink attacks.
+
+    Given:
+    - A victim file at ~/victim containing DO_NOT_TOUCH
+    - A pre-created symlink at ~/bin/.llama-server.odysseus.tmp.$$ pointing to ~/victim
+    - _odysseus_create_llama_shim executed within that exact same bash PID ($$)
+
+    Prove:
+    - ~/victim remains unmodified
+    - Pre-existing crafted symlink is NOT followed or overwritten
+    - Legitimate shim is successfully created at ~/bin/llama-server via secure temp path
+    """
+    lines = [
+        'victim="$HOME/victim"',
+        'printf "DO_NOT_TOUCH\\n" > "$victim"',
+        'mkdir -p "$HOME/bin"',
+        'old_tmp="$HOME/bin/.llama-server.odysseus.tmp.$$";',
+        'ln -s "$victim" "$old_tmp"',
+    ]
+    _append_llama_server_shim_definition_lines(lines)
+    lines.append('_odysseus_create_llama_shim')
+    lines.append('res=$?')
+    lines.append('echo "CREATION_RES=$res"')
+
+    res = _run_shell(tmp_path, lines)
+    assert res.returncode == 0
+    assert "CREATION_RES=0" in res.stdout
+
+    victim_file = tmp_path / "victim"
+    assert victim_file.exists()
+    assert victim_file.read_text(encoding="utf-8") == "DO_NOT_TOUCH\n", "Victim file must remain untouched"
+
+    target_shim = tmp_path / "bin/llama-server"
+    assert target_shim.exists()
+    assert ODYSSEUS_LLAMA_SHIM_MARKER in target_shim.read_text(encoding="utf-8")
+    assert target_shim.stat().st_mode & 0o111 != 0, "Shim must be executable"
+
+
+def test_stale_odysseus_shim_removed_when_python_server_unusable(tmp_path):
+    """Scenario 1: Stale Odysseus shim + missing Python server -> owned shim removed."""
+    shim_file = tmp_path / "bin/llama-server"
+    _write_odysseus_shim(shim_file)
+
+    lines = []
+    _append_llama_server_shim_reconciliation_lines(lines)
+
+    res = _run_shell(tmp_path, lines)
+    assert res.returncode == 0
+    assert not shim_file.exists(), "Stale Odysseus shim must be removed when python server is unavailable"
+
+
+def test_healthy_odysseus_shim_retained_when_no_native_server(tmp_path):
+    """Scenario 2: Healthy Odysseus shim + no native server -> shim preserved."""
+    shim_file = tmp_path / "bin/llama-server"
+    _write_odysseus_shim(shim_file)
+    mock_py_dir = tmp_path / "mock_bin"
+    _write_mock_python3(mock_py_dir / "python3", succeeds=True)
+
+    lines = []
+    _append_llama_server_shim_reconciliation_lines(lines)
+
+    res = _run_shell(tmp_path, lines, path=f"{git_bash_path(mock_py_dir)}:{os.environ.get('PATH', '')}")
+    assert res.returncode == 0
+    assert shim_file.exists(), "Healthy Odysseus shim must be preserved when no native server is present"
+
+
+def test_reconciliation_does_not_retire_healthy_shim_for_broken_native_binary(tmp_path):
+    """Reconciliation health check: a broken native candidate executable must NOT retire
+    a healthy Odysseus Python shim."""
+    shim_file = tmp_path / "bin/llama-server"
+    _write_odysseus_shim(shim_file)
+    _write_mock_native(tmp_path / "llama.cpp/build/bin/llama-server", succeeds=False)
+    mock_py_dir = tmp_path / "mock_bin"
+    _write_mock_python3(mock_py_dir / "python3", succeeds=True)
+
+    lines = [f'export PATH="$HOME/llama.cpp/build/bin:{git_bash_path(mock_py_dir)}:$PATH"']
+    _append_llama_server_shim_reconciliation_lines(lines)
+
+    res = _run_shell(tmp_path, lines)
+    assert res.returncode == 0
+    assert shim_file.exists(), "Healthy Odysseus shim must NOT be retired when native binary is broken"
+
+
+def test_odysseus_shim_retired_when_native_server_healthy(tmp_path):
+    """Scenario 3: Odysseus shim + healthy native server available -> native server wins."""
+    shim_file = tmp_path / "bin/llama-server"
+    _write_odysseus_shim(shim_file)
+    _write_mock_native(tmp_path / "llama.cpp/build/bin/llama-server", succeeds=True)
+
+    lines = ['export PATH="$HOME/bin:$HOME/llama.cpp/build/bin:$PATH"']
+    _append_llama_server_shim_reconciliation_lines(lines)
+
+    res = _run_shell(tmp_path, lines)
+    assert res.returncode == 0
+    assert not shim_file.exists(), "Odysseus shim must be retired when healthy native server is available"
+
+
+def test_user_owned_bin_llama_server_never_touched(tmp_path):
+    """Scenario 4: Arbitrary user ~/bin/llama-server -> untouched and not deprioritized."""
+    user_bin = tmp_path / "bin/llama-server"
+    user_bin.parent.mkdir(parents=True, exist_ok=True)
+    user_bin.write_text("#!/bin/bash\n# Custom user build script\nexec /opt/custom/llama-server\n", encoding="utf-8")
+    user_bin.chmod(0o755)
+
+    _write_mock_native(tmp_path / "llama.cpp/build/bin/llama-server", succeeds=True)
+
+    lines = ['export PATH="$HOME/bin:$HOME/llama.cpp/build/bin:$PATH"']
+    _append_llama_server_shim_reconciliation_lines(lines)
+
+    res = _run_shell(tmp_path, lines)
+    assert res.returncode == 0
+    assert user_bin.exists(), "User-owned ~/bin/llama-server must never be deleted"
+    assert "Custom user build script" in user_bin.read_text(encoding="utf-8")
+
+
+def test_reconciliation_ignores_native_binary_outside_effective_path(tmp_path):
+    """Native candidate outside effective PATH must NOT be considered."""
+    shim_file = tmp_path / "bin/llama-server"
+    _write_odysseus_shim(shim_file)
+    # Native binary placed in /usr_custom/bin which is NOT in PATH
+    _write_mock_native(tmp_path / "usr_custom/bin/llama-server", succeeds=True)
+    mock_py_dir = tmp_path / "mock_bin"
+    _write_mock_python3(mock_py_dir / "python3", succeeds=True)
+
+    lines = []
+    _append_llama_server_shim_reconciliation_lines(lines)
+
+    # PATH only contains ~/bin and mock_py_dir — usr_custom is omitted
+    path = f"{git_bash_path(tmp_path / 'bin')}:{git_bash_path(mock_py_dir)}"
+    res = _run_shell(tmp_path, lines, path=path)
+    assert res.returncode == 0
+    assert shim_file.exists(), "Shim must NOT be retired by native binary outside effective PATH"
+
+
+def test_reconciliation_skips_home_bin_with_or_without_trailing_slash(tmp_path):
+    """Reconciliation must exclude $HOME/bin and $HOME/bin/ from native candidate discovery."""
+    shim_file = tmp_path / "bin/llama-server"
+    _write_odysseus_shim(shim_file)
+    mock_py_dir = tmp_path / "mock_bin"
+    _write_mock_python3(mock_py_dir / "python3", succeeds=True)
+
+    lines = []
+    _append_llama_server_shim_reconciliation_lines(lines)
+
+    # PATH has ~/bin/ with trailing slash
+    path = f"{git_bash_path(tmp_path / 'bin')}/:{git_bash_path(mock_py_dir)}"
+    res = _run_shell(tmp_path, lines, path=path)
+    assert res.returncode == 0
+    assert shim_file.exists(), "Shim must NOT rediscover itself when PATH has trailing slash in $HOME/bin/"
+
+
+def test_reconciliation_does_not_discover_cwd_executable_when_path_omits_dot(tmp_path):
+    """Reconciliation must NOT synthesize an empty/trailing PATH element that searches cwd.
+
+    Given:
+    - Current working directory contains an executable `llama-server`
+    - Healthy Odysseus Python shim in ~/bin/llama-server
+    - PATH does NOT contain '.' or cwd
+    - No other healthy native binary on PATH
+
+    Prove:
+    - Reconciliation does not discover ./llama-server
+    - The healthy Odysseus shim in ~/bin/llama-server is preserved
+    """
+    shim_file = tmp_path / "bin/llama-server"
+    _write_odysseus_shim(shim_file)
+    mock_py_dir = tmp_path / "mock_bin"
+    _write_mock_python3(mock_py_dir / "python3", succeeds=True)
+
+    cwd_dir = tmp_path / "workdir"
+    _write_mock_native(cwd_dir / "llama-server", succeeds=True)
+
+    lines = []
+    _append_llama_server_shim_reconciliation_lines(lines)
+
+    path = f"{git_bash_path(tmp_path / 'bin')}:{git_bash_path(mock_py_dir)}:/usr/bin:/bin"
+    res = _run_shell(tmp_path, lines, cwd=cwd_dir, path=path)
+    assert res.returncode == 0
+    assert shim_file.exists(), "Healthy Odysseus shim must NOT be retired by finding ./llama-server in cwd"
+
+
+def test_reconciliation_discovers_healthy_native_on_explicit_other_path_entry(tmp_path):
+    """Reconciliation must discover healthy native binaries placed on explicit PATH entries."""
+    shim_file = tmp_path / "bin/llama-server"
+    _write_odysseus_shim(shim_file)
+    custom_opt_bin = tmp_path / "custom_opt/bin"
+    _write_mock_native(custom_opt_bin / "llama-server", succeeds=True)
+
+    lines = []
+    _append_llama_server_shim_reconciliation_lines(lines)
+
+    path = f"{git_bash_path(tmp_path / 'bin')}:{git_bash_path(custom_opt_bin)}:/usr/bin:/bin"
+    res = _run_shell(tmp_path, lines, path=path)
+    assert res.returncode == 0
+    assert not shim_file.exists(), "Odysseus shim must be retired when healthy native server is on explicit PATH entry"
+
+
+def test_reconciliation_safely_iterates_path_with_glob_metacharacters(tmp_path):
+    """Reconciliation must not perform pathname expansion / globbing on PATH components.
+
+    Given:
+    - A directory path containing shell glob characters: ~/custom[dir]/bin
+    - A native binary ~/custom[dir]/bin/llama-server
+    - A working directory containing matching glob entries
+    - An existing Odysseus shim in ~/bin/llama-server
+
+    Prove:
+    - Reconciliation correctly parses the literal path without expanding [dir]
+    - Discovers the healthy native server and retires the Odysseus shim
+    """
+    shim_file = tmp_path / "bin/llama-server"
+    _write_odysseus_shim(shim_file)
+
+    glob_dir = tmp_path / "custom[dir]/bin"
+    _write_mock_native(glob_dir / "llama-server", succeeds=True)
+
+    cwd_dir = tmp_path / "cwd"
+    cwd_dir.mkdir(parents=True, exist_ok=True)
+    (cwd_dir / "customd").mkdir(parents=True, exist_ok=True)
+    (cwd_dir / "customi").mkdir(parents=True, exist_ok=True)
+
+    lines = []
+    _append_llama_server_shim_reconciliation_lines(lines)
+
+    path = f"{git_bash_path(tmp_path / 'bin')}:{git_bash_path(glob_dir)}:/usr/bin:/bin"
+    res = _run_shell(tmp_path, lines, cwd=cwd_dir, path=path)
+    assert res.returncode == 0
+    assert not shim_file.exists(), "Reconciliation must discover literal bracketed PATH without globbing"
+
+
+def test_fallback_install_success_creates_usable_launcher(tmp_path):
+    """Scenario 5: No native + no Python server -> fallback install succeeds
+    -> usable compatibility launcher exists and resolves command -v llama-server."""
+    mock_py_dir = tmp_path / "mock_bin"
+    _write_mock_python3(mock_py_dir / "python3", succeeds=True)
+
+    lines = [f'export PATH="$HOME/bin:{git_bash_path(mock_py_dir)}:$PATH"']
+    _append_llama_server_shim_definition_lines(lines)
+    _append_llama_server_finalization_lines(lines)
+    lines.append('command -v llama-server')
+
+    res = _run_shell(tmp_path, lines)
+    assert res.returncode == 0
+    created_shim = tmp_path / "bin/llama-server"
+    assert created_shim.exists()
+    assert ODYSSEUS_LLAMA_SHIM_MARKER in created_shim.read_text(encoding="utf-8")
+    assert str(tmp_path / "bin/llama-server") in res.stdout
+
+
+def test_failed_fallback_sets_preflight_exit_127(tmp_path):
+    """Scenario 6: No native + failed fallback installation -> ODYSSEUS_PREFLIGHT_EXIT=127."""
+    lines = [
+        'ODYSSEUS_PREFLIGHT_EXIT=""',
+        'export PATH="$HOME/bin:$PATH"',
+    ]
+    _append_llama_server_shim_definition_lines(lines)
+    _append_llama_server_finalization_lines(lines)
+    lines.append('echo "EXIT=$ODYSSEUS_PREFLIGHT_EXIT"')
+
+    res = _run_shell(tmp_path, lines)
+    assert res.returncode == 0
+    assert "EXIT=127" in res.stdout
+
+
+def test_python_server_readiness_requires_llama_cpp_server_module():
+    """Scenario 7 & 8: Python server readiness requires `import llama_cpp.server`,
+    while GPU offload capability checks still use base `import llama_cpp`."""
+    routes_source = _read("routes/cookbook_routes.py")
+    helpers_source = _read("routes/cookbook_helpers.py")
+
+    # Windows fallback readiness check requires .server
+    assert 'try { python -c "import llama_cpp.server" 2>$null } catch {}' in routes_source
+    # Termux fallback readiness check requires .server
+    assert 'if ! python3 -c "import llama_cpp.server" 2>/dev/null; then' in routes_source
+    # Build-failure fallback pip check requires .server
+    assert 'if ! command -v llama-server &>/dev/null && ! python3 -c "import llama_cpp.server" 2>/dev/null; then' in routes_source
+    # Shim reconciliation and post-install finalization require .server
+    assert 'if ! python3 -c "import llama_cpp.server" 2>/dev/null; then' in helpers_source
+    assert 'if ! command -v llama-server >/dev/null 2>&1 && python3 -c "import llama_cpp.server" 2>/dev/null; then' in helpers_source
+
+    # GPU offload support checks still intentionally inspect base llama_cpp
+    assert 'llama_cpp.llama_supports_gpu_offload()' in routes_source
+
+
+def test_darwin_native_build_does_not_force_write_bin_symlink():
+    """Darwin source build must not overwrite ~/bin/llama-server with a forced symlink."""
+    source = _read("routes/cookbook_routes.py")
+
+    assert "&& ln -sf ~/llama.cpp/build/bin/llama-server ~/bin/llama-server" not in source
+    assert 'cmake --build build -j"$NPROC" --target llama-server' in source
+
+
+@pytest.mark.asyncio
+async def test_generated_runner_preflight_retires_stale_shim_before_backend_selection(monkeypatch, tmp_path):
+    """Integration regression: The actual generated Cookbook runner must execute
+    ownership reconciliation BEFORE evaluating the backend selection (`if Termux ... elif ! command -v llama-server`).
+
+    Given:
+    - Executable stale Odysseus shim in ~/bin/llama-server (with canonical marker)
+    - Healthy native llama-server in ~/llama.cpp/build/bin/llama-server
+    - ~/bin before ~/llama.cpp/build/bin on PATH
+
+    Prove:
+    1. Generated runner contains reconciliation shell lines strictly before the backend branching
+    2. Executing the generated runner script retires the stale ~/bin/llama-server shim
+    3. Resolves to the healthy native binary without attempting source build or pip fallback.
+    """
+    from unittest.mock import AsyncMock, MagicMock
+    from routes.cookbook_helpers import ServeRequest
+    import routes.cookbook_routes as cookbook_routes
+    from starlette.requests import Request
+
+    fake_home = tmp_path / "fake_home"
+    stale_shim = fake_home / "bin/llama-server"
+    _write_odysseus_shim(stale_shim)
+    native_bin = fake_home / "llama.cpp/build/bin/llama-server"
+    _write_mock_native(native_bin, succeeds=True)
+
+    # Mock environment to generate the real runner file with isolated DB
+    tmux_log_dir = tmp_path / "tmux_logs"
+    tmux_log_dir.mkdir(parents=True)
+    monkeypatch.setattr(cookbook_routes, "TMUX_LOG_DIR", tmux_log_dir)
+    monkeypatch.setattr(cookbook_routes, "require_admin", lambda request: None)
+    monkeypatch.setattr(cookbook_routes, "_binary_available", AsyncMock(return_value=True))
+    monkeypatch.setattr(cookbook_routes, "load_stored_hf_token", lambda **kwargs: "")
+    monkeypatch.setattr("core.database.SessionLocal", MagicMock())
+
+    class _Proc:
+        returncode = 0
+        stderr = None
+        async def wait(self):
+            return 0
+    monkeypatch.setattr(cookbook_routes.asyncio, "create_subprocess_shell", AsyncMock(return_value=_Proc()))
+
+    router = cookbook_routes.setup_cookbook_routes()
+    endpoint = None
+    for route in router.routes:
+        if route.path == "/api/model/serve" and "POST" in route.methods:
+            endpoint = route.endpoint
+            break
+    assert endpoint is not None
+
+    http_req = Request({"type": "http", "method": "POST", "path": "/api/model/serve", "headers": []})
+    http_req.state.current_user = "admin"
+
+    req = ServeRequest(
+        repo_id="test/repo",
+        cmd="llama-server -m /dummy/model.gguf --port 8085",
+        remote_host=None,
+    )
+
+    resp = await endpoint(http_req, req)
+    assert resp["ok"] is True
+    session_id = resp["session_id"]
+    runner_file = tmux_log_dir / f"{session_id}_run.sh"
+    assert runner_file.exists()
+    runner_script = runner_file.read_text(encoding="utf-8")
+
+    # Assert structural ordering in the generated script:
+    # Reconciliation must appear strictly BEFORE the Termux/backend check
+    recon_idx = runner_script.find("Native llama-server detected — retiring Odysseus compatibility shim in ~/bin")
+    termux_idx = runner_script.find("if [ -d /data/data/com.termux ]; then")
+    backend_idx = runner_script.find("elif ! command -v llama-server &>/dev/null; then")
+    assert recon_idx != -1, "Reconciliation block missing from generated runner"
+    assert termux_idx != -1, "Termux check missing from generated runner"
+    assert backend_idx != -1, "Backend selection missing from generated runner"
+    assert recon_idx < termux_idx < backend_idx, "Reconciliation must execute strictly before backend selection"
+
+    # Execute the generated runner preflight in a real subshell
+    res = _run_shell(fake_home, [str(runner_file)], path=f"{git_bash_path(fake_home / 'bin')}:{git_bash_path(fake_home / 'llama.cpp/build/bin')}:/usr/bin:/bin")
+    assert res.returncode == 0
+    assert not stale_shim.exists(), "Stale ~/bin/llama-server must have been retired by the generated preflight"
+    assert "RUN_NATIVE: -m /dummy/model.gguf --port 8085" in res.stdout
+    assert "Native llama-server not found — building from source" not in res.stdout