Skip to content

armgit / ODS

Public Imported from GitHub
0

ODS V3 Pre-Release: Public testing and refinement ahead of the official V3 launch. Turn your PC, Mac, or Linux box into a private AI server.

36.8 KB
Raw Blame
#!/bin/bash
# ============================================================================
# ODS Installer — Phase 07: Developer Tools
# ============================================================================
# Part of: installers/phases/
# Purpose: Install developer CLIs and, when selected, the OpenCode extension
#
# Expects: DRY_RUN, INSTALL_DIR, LOG_FILE, LLM_MODEL, MAX_CONTEXT,
#           ENABLE_OPENCODE,
#           PKG_MANAGER,
#           ai(), ai_ok(), ai_warn(), log()
# Provides: (developer tools installed to ~/.npm-global)
#
# Modder notes:
#   Add new developer tools or change installation methods here.
# ============================================================================

# Isolated phase reuse (tests) gets the route predicate installers/lib/
# native-llm.sh gives install-core: a host-native llama-server is in use.
declare -F ods_native_llm_requested >/dev/null 2>&1 \
    || ods_native_llm_requested() { [[ -n "${NATIVE_LLM_BASE_URL:-}" ]]; }

ods_progress 42 "devtools" "Installing developer tools"
# shellcheck source=../lib/node-runtime.sh
. "$SCRIPT_DIR/installers/lib/node-runtime.sh"

# Install Linux Node.js 22 with the host package manager when Linux Node.js
# 20+ and npm are missing. $1 names the consumer for messages. Failures are
# reported here; callers decide whether a missing runtime is fatal.
_phase07_install_linux_node() {
    local consumer="$1" tmpfile
    if ! ods_sudo_available; then
        ai_warn "sudo unavailable — skipping Linux Node.js install for $consumer."
        ai "  Install Linux Node.js 22+ yourself and re-run."
        return 0
    fi
    ai "Installing Linux Node.js for $consumer..."
    case "$PKG_MANAGER" in
        apt)
            tmpfile=$(mktemp /tmp/nodesource-setup.XXXXXX.sh)
            if curl -fsSL --max-time 300 https://deb.nodesource.com/setup_22.x -o "$tmpfile" 2>/dev/null; then
                # The downloaded file supplies the script; nested apt needs
                # EOF rather than the installer's terminal through sudo-rs.
                ods_sudo -E bash "$tmpfile" </dev/null 2>&1 | tee -a "$LOG_FILE" || ai_warn "Failed to run NodeSource apt setup script for $consumer"
            fi
            rm -f "$tmpfile"
            ods_sudo apt-get install -y nodejs </dev/null 2>&1 | tee -a "$LOG_FILE" || ai_warn "Failed to install nodejs via apt-get for $consumer"
            ;;
        dnf)
            ods_sudo dnf module install -y nodejs:22 2>&1 | tee -a "$LOG_FILE" || \
                ods_sudo dnf install -y nodejs 2>&1 | tee -a "$LOG_FILE" || ai_warn "Failed to install nodejs via dnf for $consumer"
            ;;
        pacman)
            ods_sudo pacman -S --noconfirm --needed nodejs npm 2>&1 | tee -a "$LOG_FILE" || ai_warn "Failed to install nodejs via pacman for $consumer"
            ;;
        zypper)
            ods_sudo zypper --non-interactive install nodejs22 2>&1 | tee -a "$LOG_FILE" || \
                ods_sudo zypper --non-interactive install nodejs 2>&1 | tee -a "$LOG_FILE" || ai_warn "Failed to install nodejs via zypper for $consumer"
            ;;
        *)
            ai_warn "Unknown package manager — cannot install Node.js automatically for $consumer"
            ;;
    esac
    hash -r
}

if $DRY_RUN; then
    # Pixel's host runtime needs Linux Node.js even when developer CLIs are off.
    if [[ "${ENABLE_PIXEL_RUNTIME:-false}" == true ]] && ! ods_linux_node_tools_available; then
        log "[DRY RUN] Would install Linux Node.js 22 for Portal (Pixel)"
    fi
    if [[ "${ENABLE_DEVTOOLS:-false}" == true ]]; then
        log "[DRY RUN] Would install AI developer tools (Claude Code and Codex CLI)"
    else
        log "[DRY RUN] Developer CLIs disabled; existing binaries would be preserved"
    fi
    if [[ "${ENABLE_OPENCODE:-false}" == "true" ]]; then
        log "[DRY RUN] Would install and configure the optional OpenCode browser IDE (user-level systemd service on port 3003)"
    else
        log "[DRY RUN] OpenCode extension is disabled; it would not be installed or started"
    fi
    log "[DRY RUN] Would install ODS host agent systemd service (system-mode, port 7710)"
    log "[DRY RUN] Would install ODS mDNS announcer systemd service (if zeroconf available)"
else
    # Portal (Pixel) bootstraps a pinned Node.js runtime in phase 11 and needs
    # Linux Node.js 20+ and npm whether or not the developer CLIs are selected.
    # A fresh Ubuntu (including a new WSL distro) has neither, so provision it
    # here and stop now with a clear reason instead of after the image builds.
    if [[ "${ENABLE_PIXEL_RUNTIME:-false}" == true ]] && ! ods_linux_node_tools_available; then
        _phase07_install_linux_node "Portal (Pixel)"
        if ! ods_linux_node_tools_available; then
            ai_bad "Portal (Pixel) requires Linux Node.js 20+ and npm, and they could not be installed automatically. See $LOG_FILE."
            ai "  Install Linux Node.js 22 inside this Linux system (https://nodejs.org/en/download), then rerun the installer."
            return 1 2>/dev/null || exit 1
        fi
        ai_ok "Linux Node.js $(node -p 'process.versions.node') ready for Portal (Pixel)"
    fi

    if [[ "${ENABLE_DEVTOOLS:-false}" == true ]]; then
        ai "Installing AI developer tools..."

    # Ensure Node.js/npm is available (needed for Claude Code and Codex). The
    # CLIs are optional: a failed or skipped Node.js install only skips them.
    if ! ods_linux_node_tools_available; then
        _phase07_install_linux_node "Claude Code and Codex CLI"
    fi

    if ods_linux_node_tools_available; then
        # Set up user-level npm global prefix (no sudo needed)
        NPM_GLOBAL_DIR="$HOME/.npm-global"
        if [[ ! -d "$NPM_GLOBAL_DIR" ]]; then
            mkdir -p "$NPM_GLOBAL_DIR"
            npm config set prefix "$NPM_GLOBAL_DIR" 2>/dev/null || true
        fi
        # Ensure user-level bin is on PATH for this session
        export PATH="$NPM_GLOBAL_DIR/bin:$PATH"

        # Install Claude Code (Anthropic's CLI for Claude)
        if ! command -v claude &> /dev/null; then
            npm install -g @anthropic-ai/claude-code >> "$LOG_FILE" 2>&1 && \
                ai_ok "Claude Code installed (run 'claude' to start)" || \
                ai_warn "Claude Code install failed — install later with: npm i -g @anthropic-ai/claude-code"
        else
            ai_ok "Claude Code already installed"
        fi

        # Install Codex CLI (OpenAI's terminal agent)
        if ! command -v codex &> /dev/null; then
            npm install -g @openai/codex >> "$LOG_FILE" 2>&1 && \
                ai_ok "Codex CLI installed (run 'codex' to start)" || \
                ai_warn "Codex CLI install failed — install later with: npm i -g @openai/codex"
        else
            ai_ok "Codex CLI already installed"
        fi

        # Ensure ~/.npm-global/bin is on PATH permanently
        if [[ -d "$NPM_GLOBAL_DIR/bin" ]] && ! grep -q 'npm-global' "$HOME/.bashrc" 2>/dev/null; then
            echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> "$HOME/.bashrc"
            ai "Added ~/.npm-global/bin to PATH in ~/.bashrc"
        fi
    else
        ai_warn "Linux Node.js 20+ and npm are not available — skipping Claude Code and Codex CLI install"
        ai "  Install Linux Node.js 22+ and re-run to add Claude Code / Codex."
    fi
    else
        log "Developer CLI installation disabled; existing Claude Code and Codex binaries preserved"
    fi

    if [[ "${ENABLE_OPENCODE:-false}" == "true" ]]; then
    _opencode_candidate_is_file() {
        local candidate="$1"
        [[ -n "$candidate" && "$candidate" == /* && -x "$candidate" && ! -d "$candidate" ]]
    }

    _find_opencode_bin() {
        local candidate
        candidate="$HOME/.opencode/bin/opencode"
        if _opencode_candidate_is_file "$candidate"; then
            printf '%s\n' "$candidate"
            return 0
        fi
        candidate="$(type -P opencode 2>/dev/null || true)"
        if _opencode_candidate_is_file "$candidate"; then
            printf '%s\n' "$candidate"
            return 0
        fi
        return 1
    }

    # ── OpenCode (local agentic coding platform) ──
    OPENCODE_BIN="$(_find_opencode_bin || true)"
    # shellcheck source=../lib/opencode-runtime.sh
    . "$SCRIPT_DIR/installers/lib/opencode-runtime.sh"
    if OPENCODE_BIN="$(ods_install_opencode "$OPENCODE_BIN")"; then
        ai_ok "Reviewed OpenCode release installed ($OPENCODE_BIN)"
    else
        OPENCODE_BIN=""
        ai_warn "OpenCode upgrade failed; existing binary/configuration preserved. Re-run after resolving the download or binary error."
    fi

    # Configure OpenCode to use local llama-server
    if [[ -n "$OPENCODE_BIN" && -x "$OPENCODE_BIN" ]]; then
        OPENCODE_CONFIG_DIR="$HOME/.config/opencode"
        mkdir -p "$OPENCODE_CONFIG_DIR"
        # Read OLLAMA_PORT and ODS_MODE from .env generated in phase 06
        if [[ -f "$INSTALL_DIR/.env" ]]; then
            [[ -z "${OLLAMA_PORT:-}" ]] && OLLAMA_PORT=$(grep -m1 '^OLLAMA_PORT=' "$INSTALL_DIR/.env" | cut -d= -f2-)
            # Always re-read ODS_MODE from .env — Phase 06 may have changed it
            # (e.g. to "local" for an external endpoint) but the shell variable
            # is stale.
            ODS_MODE=$(grep -m1 '^ODS_MODE=' "$INSTALL_DIR/.env" | cut -d= -f2-)
            [[ -z "${ODS_MODEL_SWITCHBOARD:-}" ]] && ODS_MODEL_SWITCHBOARD=$(grep -m1 '^ODS_MODEL_SWITCHBOARD=' "$INSTALL_DIR/.env" | cut -d= -f2-)
            [[ -z "${LITELLM_KEY:-}" ]] && LITELLM_KEY=$(grep -m1 '^LITELLM_KEY=' "$INSTALL_DIR/.env" | cut -d= -f2-)
            [[ -z "${LITELLM_PORT:-}" ]] && LITELLM_PORT=$(grep -m1 '^LITELLM_PORT=' "$INSTALL_DIR/.env" | cut -d= -f2-)
            [[ -z "${EXTERNAL_LLM_URL:-}" ]] && EXTERNAL_LLM_URL=$(grep -m1 '^EXTERNAL_LLM_URL=' "$INSTALL_DIR/.env" | cut -d= -f2-)
            [[ -z "${EXTERNAL_LLM_MODEL:-}" ]] && EXTERNAL_LLM_MODEL=$(grep -m1 '^EXTERNAL_LLM_MODEL=' "$INSTALL_DIR/.env" | cut -d= -f2-)
        fi
        # Route through LiteLLM for the switchboard, an external endpoint and a
        # host-native llama-server; direct to the in-stack llama-server otherwise.
        #
        # The gateway branches hit LiteLLM at :4000. LiteLLM is NOT auth-disabled
        # on this install — its container env carries LITELLM_MASTER_KEY from
        # .env (phase 06 wires it; the docker-compose for LiteLLM honors it),
        # and any request without a matching Authorization header gets 401.
        # OpenCode previously sent `apiKey: "no-key"` here (comment claimed
        # auth was removed for local installs — never was), and every chat
        # completion came back 401. The user-visible symptom is OpenCode
        # showing "no connected db" because its provider probe to /v1/models
        # fails auth before it can populate the model selector. Verified on
        # strix-halo + spark + mac-mini + m5-mbp 2026-05-20:
        #   $ curl -sSI http://127.0.0.1:4000/v1/models   → 401
        #   $ curl -sSI -H "Authorization: Bearer $LITELLM_KEY" ... → 200
        #
        # Use LITELLM_KEY (read above) on the gateway branches. The
        # llama-server-direct branch keeps "no-key": the in-stack llama.cpp
        # server does not validate the key. A host-native llama-server does
        # (LLAMA_SERVER_API_KEY), and only LiteLLM holds that key.
        _opencode_model_id="${LLM_MODEL}"
        _opencode_model_name="${LLM_MODEL}"
        _opencode_provider_name="llama-server (local)"
        if [[ "${ODS_MODEL_SWITCHBOARD:-enabled}" == "enabled" ]]; then
            _opencode_url="http://127.0.0.1:${LITELLM_PORT:-4000}/v1"
            _opencode_key="${LITELLM_KEY:-}"
            _opencode_model_id="ods/current"
            _opencode_model_name="ods/current"
            _opencode_provider_name="ODS switchboard"
        elif [[ -n "${EXTERNAL_LLM_URL:-}" && -n "${EXTERNAL_LLM_MODEL:-}" ]]; then
            # Generic external providers are materialized behind the same
            # authenticated LiteLLM gateway as Pixel. Pointing OpenCode at the
            # stale local tier port produces either connection failures or the
            # misleading LiteLLM "No connected db" auth error.
            _opencode_url="http://127.0.0.1:${LITELLM_PORT:-4000}/v1"
            _opencode_key="${LITELLM_KEY:-}"
            _opencode_model_id="$EXTERNAL_LLM_MODEL"
            _opencode_model_name="$EXTERNAL_LLM_MODEL"
            _opencode_provider_name="External LLM via ODS gateway"
        elif ods_native_llm_requested; then
            _opencode_url="http://127.0.0.1:${LITELLM_PORT:-4000}/v1"
            _opencode_key="${LITELLM_KEY:-}"
            _opencode_provider_name="llama-server (Windows) via ODS gateway"
        else
            _opencode_url="http://127.0.0.1:${OLLAMA_PORT:-8080}/v1"
            _opencode_key="no-key"
        fi
        if [[ -z "${_opencode_key:-}" ]]; then
            ai_bad "OpenCode gateway config requires LITELLM_KEY, but it is empty."
            exit 1
        fi
        # OpenCode reserves `limit.output` from `limit.context` when deciding
        # whether to compact. Reserving the entire context for output causes
        # a trivial completed chat to enter an unbounded compaction/continue
        # loop on 32K installs. Keep at least three quarters for the prompt.
        _opencode_context="${MAX_CONTEXT:-65536}"
        if [[ ! "$_opencode_context" =~ ^[0-9]+$ ]] || (( _opencode_context < 1024 )); then
            ai_bad "OpenCode requires a numeric context of at least 1024 tokens."
            exit 1
        fi
        _opencode_output_limit=$(( _opencode_context / 4 ))
        (( _opencode_output_limit <= 32768 )) || _opencode_output_limit=32768

        # Writes a fresh opencode.json from the template. Used for first-install
        # and as deterministic recovery when the jq rewrite path finds an
        # existing malformed file it cannot parse (issue #332).
        _opencode_write_fresh() {
            cat > "$1" <<OPENCODE_EOF
{
  "\$schema": "https://opencode.ai/config.json",
  "model": "llama-server/${_opencode_model_id}",
  "small_model": "llama-server/${_opencode_model_id}",
  "agent": {
    "build": {"model": "llama-server/${_opencode_model_id}"},
    "plan": {"model": "llama-server/${_opencode_model_id}"}
  },
  "provider": {
    "llama-server": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "${_opencode_provider_name}",
      "options": {
        "baseURL": "${_opencode_url}",
        "apiKey": "${_opencode_key}"
      },
      "models": {
        "${_opencode_model_id}": {
          "name": "${_opencode_model_name}",
          "limit": {
            "context": ${_opencode_context},
            "output": ${_opencode_output_limit}
          }
        }
      }
    }
  }
}
OPENCODE_EOF
        }

        if [[ ! -f "$OPENCODE_CONFIG_DIR/opencode.json" ]]; then
            _opencode_write_fresh "$OPENCODE_CONFIG_DIR/opencode.json"
            ai_ok "OpenCode configured for local llama-server (model: ${_opencode_model_id})"
        else
            # Reinstall: update API key and URL in existing config (key may have changed)
            _opencode_updated=false
            if command -v jq >/dev/null 2>&1; then
                _opencode_tmp="$OPENCODE_CONFIG_DIR/opencode.json.tmp.$$"
                if jq --arg url "$_opencode_url" --arg key "$_opencode_key" \
                    --arg model_id "$_opencode_model_id" \
                    --arg model_name "$_opencode_model_name" \
                    --arg provider_name "$_opencode_provider_name" \
                    --argjson context "$_opencode_context" \
                    --argjson output "$_opencode_output_limit" \
                    '. as $previous
                      | ($previous.model | if type == "string" then startswith("llama-server/") else false end) as $ods_previous
                      | .["$schema"] = "https://opencode.ai/config.json"
                      | .model = ("llama-server/" + $model_id)
                      | .small_model = ("llama-server/" + $model_id)
                      | .agent = (if .agent == null then {} else .agent end)
                      | if (.agent | type) == "object" then
                          .agent.build = (if .agent.build == null then {} else .agent.build end)
                          | .agent.plan = (if .agent.plan == null then {} else .agent.plan end)
                          | if (.agent.build | type) == "object" then
                              .agent.build.model = (if .agent.build.model == null or ($ods_previous and .agent.build.model == $previous.model) then ("llama-server/" + $model_id) else .agent.build.model end)
                            else . end
                          | if (.agent.plan | type) == "object" then
                              .agent.plan.model = (if .agent.plan.model == null or ($ods_previous and .agent.plan.model == $previous.model) then ("llama-server/" + $model_id) else .agent.plan.model end)
                            else . end
                        else . end
                      | .provider = (.provider // {})
                      | .provider["llama-server"] = (.provider["llama-server"] // {})
                      | .provider["llama-server"].npm = "@ai-sdk/openai-compatible"
                      | .provider["llama-server"].name = $provider_name
                      | .provider["llama-server"].options = {"baseURL": $url, "apiKey": $key}
                      | .provider["llama-server"].models = {
                         ($model_id): {
                           "name": $model_name,
                           "limit": {"context": $context, "output": $output}
                         }
                       }' \
                    "$OPENCODE_CONFIG_DIR/opencode.json" > "$_opencode_tmp" 2>/dev/null; then
                    mv "$_opencode_tmp" "$OPENCODE_CONFIG_DIR/opencode.json"
                    ai_ok "OpenCode config updated (model, API key, and URL refreshed)"
                    _opencode_updated=true
                else
                    rm -f "$_opencode_tmp"
                    ai_warn "OpenCode config jq rewrite failed (existing file unparseable) — regenerating from template"
                fi
            else
                _opencode_write_fresh "$OPENCODE_CONFIG_DIR/opencode.json"
                ai_ok "OpenCode config regenerated (jq unavailable; model route refreshed)"
                _opencode_updated=true
            fi
            # Recovery path (issue #332): if the update branch above failed to
            # produce a valid file (jq parse error on pre-existing corruption),
            # regenerate deterministically from the template.
            if [[ "$_opencode_updated" != "true" ]]; then
                _opencode_write_fresh "$OPENCODE_CONFIG_DIR/opencode.json"
                ai_ok "OpenCode config regenerated from template (recovered from corruption)"
            fi
        fi
        # OpenCode reads config.json, not opencode.json — always sync
        cp "$OPENCODE_CONFIG_DIR/opencode.json" "$OPENCODE_CONFIG_DIR/config.json"

        # Install OpenCode Web UI as user-level systemd service (no sudo required)
        if [[ -f "$INSTALL_DIR/opencode/opencode-web.service" ]]; then
            SYSTEMD_USER_DIR="$HOME/.config/systemd/user"
            mkdir -p "$SYSTEMD_USER_DIR"

            svc_tmp="$(mktemp "${TMPDIR:-/tmp}/opencode-web.service.XXXXXX")" || svc_tmp=""
            if [[ -z "$svc_tmp" ]]; then
                ai_warn "Failed to create secure temp file for opencode-web.service; skipping user-level unit install"
            else
                cp "$INSTALL_DIR/opencode/opencode-web.service" "$svc_tmp"
                # Escape sed special chars to prevent injection from path values
                _home_esc=$(printf '%s\n' "$HOME" | sed 's/[&/\]/\\&/g')
                _opencode_bin_esc=$(printf '%s\n' "$OPENCODE_BIN" | sed 's/[&/\]/\\&/g')
                _opencode_bin_dir_esc=$(printf '%s\n' "$(dirname "$OPENCODE_BIN")" | sed 's/[&/\]/\\&/g')
                _sed_i "s|__HOME__|${_home_esc}|g" "$svc_tmp"
                _sed_i "s|__OPENCODE_BIN__|${_opencode_bin_esc}|g" "$svc_tmp"
                _sed_i "s|__OPENCODE_BIN_DIR__|${_opencode_bin_dir_esc}|g" "$svc_tmp"
                if cp "$svc_tmp" "$SYSTEMD_USER_DIR/opencode-web.service"; then
                    ods_restart_opencode_service >> "$LOG_FILE" 2>&1 && \
                        ai_ok "OpenCode Web UI service restarted with the updated binary/configuration (port 3003)" || \
                        ai_warn "OpenCode Web UI service failed to restart"
                else
                    ai_warn "OpenCode unit update failed; previous service left unchanged"
                fi
                rm -f "$svc_tmp"
            fi

            # Enable lingering so service survives logout
            loginctl enable-linger "$(whoami)" 2>/dev/null || \
                sudo -n loginctl enable-linger "$(whoami)" 2>/dev/null || \
                ai_warn "Could not enable linger. OpenCode may stop after logout. Run: loginctl enable-linger $(whoami)"
        fi
    fi
    else
        # A rerun with --no-opencode must not leave an earlier ODS-managed
        # browser IDE running. Preserve the binary and user configuration so
        # an explicit future opt-in is reversible, but retire the managed unit.
        if ods_systemctl_user is-active --quiet opencode-web.service 2>/dev/null \
            || ods_systemctl_user is-enabled --quiet opencode-web.service 2>/dev/null; then
            ods_systemctl_user disable --now opencode-web.service >> "$LOG_FILE" 2>&1 || \
                ai_warn "Could not stop the previously enabled OpenCode extension"
        fi
        log "OpenCode extension disabled; skipped installation and startup"
    fi
fi

# The host-agent and mDNS blocks below use real sudo/systemctl calls.
# Gate them behind DRY_RUN so dry-run never touches the host.
if $DRY_RUN; then return 0; fi

# ── ODS Host Agent (extension lifecycle management) ──
# System-mode systemd unit (was --user mode pre-#573). Installs to
# /etc/systemd/system, runs as the installing user with SupplementaryGroups=docker
# so the agent can manage Docker without socket-mounting into a container.
_ods_start_session_host_agent() {
    if ! "$AGENT_PYTHON" -c "import huggingface_hub, hf_xet" >/dev/null 2>&1; then
        ai "Installing ODS host-agent model downloader dependencies..."
        if ods_ensure_python_pip "$AGENT_PYTHON" "ODS host-agent" && \
           ods_python_pip_install_user "$AGENT_PYTHON" "$LOG_FILE" "huggingface_hub[hf_xet]>=0.27"; then
            ai_ok "ODS host-agent Hugging Face downloader ready"
        else
            ai_warn "Could not install huggingface_hub[hf_xet]; model manager downloads may fail on Xet-backed Hugging Face models."
        fi
    fi

    # The installer holds its model lifecycle flock across this phase. Close
    # only the child's inherited descriptor before ods-cli daemonizes; the
    # long-lived session agent must not keep the installer's lock forever.
    if ( [[ -z "${ODS_MODEL_LIFECYCLE_LOCK_FD:-}" ]] \
            || exec {ODS_MODEL_LIFECYCLE_LOCK_FD}>&-; \
         ODS_AGENT_FORCE_SESSION=true "$INSTALL_DIR/ods-cli" agent start \
            >> "$LOG_FILE" 2>&1 ); then
        ai_ok "ODS host agent started for this session (background mode)"
        ai "  Run 'ods agent start' after reboot or login to start it again."
        return 0
    fi

    ai_warn "Could not start the session host agent. Run: ods agent start"
    return 1
}

if [[ -f "$INSTALL_DIR/bin/ods-host-agent.py" ]]; then
    AGENT_PYTHON="$(command -v python3)"
    if [[ -n "$AGENT_PYTHON" ]]; then
        if systemctl status >/dev/null 2>&1 || [[ -d /run/systemd/system ]]; then
            # Migrate any pre-existing user-mode unit (idempotent — no-op if absent).
            if [[ -f "$HOME/.config/systemd/user/ods-host-agent.service" ]]; then
                ods_systemctl_user stop ods-host-agent.service 2>/dev/null || true
                ods_systemctl_user disable ods-host-agent.service 2>/dev/null || true
                rm -f "$HOME/.config/systemd/user/ods-host-agent.service"
                ods_systemctl_user daemon-reload 2>/dev/null || true
                ai_ok "Migrated host agent from --user mode to system mode"
            fi

            # System-mode install of the host-agent + mDNS units needs root.
            # When sudo isn't usable (rootless box, or non-interactive without
            # cached/passwordless sudo), skip these OPTIONAL extras instead of
            # failing the whole install. Core ODS runs rootless; start the agent
            # as a session process so model management remains available. This
            # return exits phase 07 (the remaining system units need root).
            if ! ods_sudo_available; then
                ai_warn "sudo unavailable — skipping host-agent + mDNS systemd units (optional)."
                _ods_start_session_host_agent || true
                return 0
            fi

            # Determine the user that should own the running agent. Under
            # `sudo bash install.sh`, $(whoami) returns root — wrong; we want
            # the original invoking user. SUDO_USER is set by sudo and is
            # empty otherwise. INSTALL_USER override wins if explicitly set.
            if [[ -n "${INSTALL_USER:-}" ]]; then
                _agent_user="$INSTALL_USER"
            elif [[ -n "${SUDO_USER:-}" ]]; then
                _agent_user="$SUDO_USER"
            else
                _agent_user="$(whoami)"
            fi

            # Surface (don't block) the case where the agent will run as root.
            # Happens under `sudo su` → `bash install.sh` (SUDO_USER unset, whoami=root).
            # Some appliance/single-user installs may want this; warn so the operator
            # can override with INSTALL_USER if it's unintentional.
            if [[ "$_agent_user" == "root" ]]; then
                ai_warn "Resolved install user is 'root' — host agent will run as root."
                ai_warn "  Set INSTALL_USER=<non-root user> before re-running install if this is unintentional."
            fi

            if ! "$AGENT_PYTHON" -c "import huggingface_hub, hf_xet" >/dev/null 2>&1; then
                ai "Installing ODS host-agent model downloader dependencies..."
                if ods_ensure_python_pip "$AGENT_PYTHON" "ODS host-agent" && {
                    sudo -u "$_agent_user" env HOME="$HOME" \
                        "$AGENT_PYTHON" -m pip install --user -q "huggingface_hub[hf_xet]>=0.27" \
                        2>&1 | tee -a "$LOG_FILE" >/dev/null || \
                    sudo -u "$_agent_user" env HOME="$HOME" \
                        "$AGENT_PYTHON" -m pip install --user --break-system-packages -q "huggingface_hub[hf_xet]>=0.27" \
                        2>&1 | tee -a "$LOG_FILE" >/dev/null
                }; then
                    ai_ok "ODS host-agent Hugging Face downloader ready"
                else
                    ai_warn "Could not install huggingface_hub[hf_xet]; model manager downloads may fail on Xet-backed Hugging Face models."
                fi
            fi

            if [[ -f "$INSTALL_DIR/scripts/systemd/ods-host-agent.service" ]]; then
                svc_tmp="$(mktemp "${TMPDIR:-/tmp}/ods-host-agent.service.XXXXXX")" || svc_tmp=""
                if [[ -z "$svc_tmp" ]]; then
                    ai_warn "Failed to create secure temp file for ods-host-agent.service; skipping systemd unit install"
                else
                    cp "$INSTALL_DIR/scripts/systemd/ods-host-agent.service" "$svc_tmp"
                    # Substitute placeholders — use sed directly with | delimiter
                    # (paths contain / but never |, so | is a safe delimiter).
                    # Dual-form for BSD/GNU sed compatibility.
                    sed -i "s|__INSTALL_DIR__|${INSTALL_DIR}|g" "$svc_tmp" 2>/dev/null || \
                        sed -i '' "s|__INSTALL_DIR__|${INSTALL_DIR}|g" "$svc_tmp"
                    sed -i "s|__HOME__|${HOME}|g" "$svc_tmp" 2>/dev/null || \
                        sed -i '' "s|__HOME__|${HOME}|g" "$svc_tmp"
                    sed -i "s|__PYTHON3__|${AGENT_PYTHON}|g" "$svc_tmp" 2>/dev/null || \
                        sed -i '' "s|__PYTHON3__|${AGENT_PYTHON}|g" "$svc_tmp"
                    sed -i "s|__INSTALL_USER__|${_agent_user}|g" "$svc_tmp" 2>/dev/null || \
                        sed -i '' "s|__INSTALL_USER__|${_agent_user}|g" "$svc_tmp"
                    # Verify placeholders were actually rendered
                    if grep -q '__INSTALL_DIR__\|__HOME__\|__PYTHON3__\|__INSTALL_USER__' "$svc_tmp"; then
                        ai_warn "Host agent systemd unit has unrendered placeholders — check $svc_tmp"
                    else
                        sudo install -m 644 "$svc_tmp" /etc/systemd/system/ods-host-agent.service
                    fi
                    rm -f "$svc_tmp"
                fi
            fi
            sudo systemctl daemon-reload 2>/dev/null || true
            # Pipe through tee (matching the file's existing sudo+log idiom at L31-45)
            # so the redirect runs in the user's shell rather than under sudo (avoids
            # SC2024). pipefail is set in install-core.sh, so the if branches on the
            # actual systemctl exit status, not tee's.
            if sudo systemctl enable --now ods-host-agent.service 2>&1 | tee -a "$LOG_FILE" >/dev/null; then
                ai_ok "ODS host agent installed (systemd system-mode, user=${_agent_user}, port 7710)"
            else
                ai_warn "ODS host agent service failed to start — run: ods agent start"
            fi
            # Force-restart so the running process matches the binary the installer
            # just rewrote. enable --now is a no-op when the unit was already active,
            # which would leave an old daemon holding a deleted inode and serving
            # stale code after a reinstall. See issue #334. Use is-enabled (not
            # is-active) so a temporarily-down daemon during a fresh install still
            # triggers the restart rather than skipping it.
            if sudo systemctl is-enabled ods-host-agent.service >/dev/null 2>&1; then
                if sudo systemctl restart ods-host-agent.service 2>&1 | tee -a "$LOG_FILE" >/dev/null; then
                    ai_ok "ODS host agent restarted (loaded new binary)"
                else
                    ai_warn "ODS host agent restart failed (non-fatal) — run: sudo systemctl restart ods-host-agent.service"
                fi
            fi
            # loginctl enable-linger no longer needed for host agent (system-mode unit)

        else
            ai_warn "No systemd detected — starting the host agent without a system service."
            _ods_start_session_host_agent || true
        fi
    else
        ai_warn "python3 not found — ods host agent not installed"
    fi
fi

# ── ODS mDNS Announcer (publishes ods.local on the LAN) ──
# Makes the device discoverable from any phone/laptop on the same network
# without typing an IP. See docs/MDNS.md for details. Linux-only; macOS
# announces hostname.local automatically via Bonjour, the script is a no-op
# there. Windows support TBD.
if [[ -f "$INSTALL_DIR/bin/ods-mdns.py" ]] && [[ "$(uname -s)" == "Linux" ]]; then
    # Install python3-zeroconf via the system package manager. Non-fatal —
    # mDNS is a quality-of-life feature; if zeroconf isn't available the
    # device is still reachable by IP.
    #
    # Two-tier strategy:
    #   1. Try the distro package manager first (best: integrates with apt
    #      upgrades, doesn't require pip / network in offline mode).
    #   2. Fall back to `pip install --user zeroconf` if the package isn't
    #      in the distro's repos (e.g. minimal images, stale apt cache,
    #      Ubuntu universe disabled) — without this, the install logs a
    #      warning and the mDNS announcer never starts even though the
    #      Python module is one pip away.
    _install_zeroconf_via_pkg() {
        # Needs root; skip cleanly when sudo isn't available (falls back to pip
        # --user below, which needs no root).
        ods_sudo_available || return 99
        case "$PKG_MANAGER" in
            apt)    ods_sudo apt-get install -y python3-zeroconf </dev/null 2>&1 | tee -a "$LOG_FILE" ;;
            dnf)    ods_sudo dnf install -y python3-zeroconf 2>&1 | tee -a "$LOG_FILE" ;;
            pacman) ods_sudo pacman -S --noconfirm --needed python-zeroconf 2>&1 | tee -a "$LOG_FILE" ;;
            zypper) ods_sudo zypper --non-interactive install python3-zeroconf 2>&1 | tee -a "$LOG_FILE" ;;
            *)      return 99 ;;
        esac
    }
    _install_zeroconf_via_pip() {
        # `--user` writes into ~/.local/lib/python3.x/site-packages so we
        # don't need sudo and don't fight PEP 668 (Debian/Ubuntu mark the
        # system site-packages as externally-managed). The mDNS announcer
        # runs as $USER, not root, so --user is the right install scope.
        if command -v pip3 >/dev/null 2>&1; then
            pip3 install --user --quiet --no-warn-script-location zeroconf 2>&1 | tee -a "$LOG_FILE"
        else
            return 99
        fi
    }
    if ! python3 -c "import zeroconf" 2>/dev/null; then
        ai "Installing python3-zeroconf (for mDNS announcer)..."
        if _install_zeroconf_via_pkg && python3 -c "import zeroconf" 2>/dev/null; then
            ai_ok "Installed python3-zeroconf via $PKG_MANAGER"
        elif python3 -c "import zeroconf" 2>/dev/null; then
            : # Package manager returned non-zero, but the module is importable.
        elif _install_zeroconf_via_pip && python3 -c "import zeroconf" 2>/dev/null; then
            ai_ok "Installed zeroconf via pip --user (system package manager unavailable / failed)"
        else
            ai_warn "Failed to install zeroconf via $PKG_MANAGER AND pip --user — mDNS announcer will not start (non-fatal; device still reachable by IP)"
        fi
    fi

    # Install the systemd unit alongside ods-host-agent. Reuses the same
    # __PLACEHOLDER__ substitution pattern, the same user resolution
    # (INSTALL_USER → SUDO_USER → whoami), and the same sudo discipline.
    if python3 -c "import zeroconf" 2>/dev/null && \
       ods_sudo_available && \
       (systemctl status >/dev/null 2>&1 || [[ -d /run/systemd/system ]]) && \
       [[ -f "$INSTALL_DIR/scripts/systemd/ods-mdns.service" ]]; then
        MDNS_PYTHON="$(command -v python3)"
        # Reuse $_agent_user from the host-agent block above if set; otherwise
        # resolve fresh. Falls back to the same heuristic.
        if [[ -z "${_agent_user:-}" ]]; then
            if [[ -n "${INSTALL_USER:-}" ]]; then
                _agent_user="$INSTALL_USER"
            elif [[ -n "${SUDO_USER:-}" ]]; then
                _agent_user="$SUDO_USER"
            else
                _agent_user="$(whoami)"
            fi
        fi
        svc_tmp="$(mktemp "${TMPDIR:-/tmp}/ods-mdns.service.XXXXXX")" || svc_tmp=""
        if [[ -z "$svc_tmp" ]]; then
            ai_warn "Failed to create secure temp file for ods-mdns.service; skipping systemd unit install"
        else
            cp "$INSTALL_DIR/scripts/systemd/ods-mdns.service" "$svc_tmp"
            sed -i "s|__INSTALL_DIR__|${INSTALL_DIR}|g" "$svc_tmp" 2>/dev/null || \
                sed -i '' "s|__INSTALL_DIR__|${INSTALL_DIR}|g" "$svc_tmp"
            sed -i "s|__HOME__|${HOME}|g" "$svc_tmp" 2>/dev/null || \
                sed -i '' "s|__HOME__|${HOME}|g" "$svc_tmp"
            sed -i "s|__PYTHON3__|${MDNS_PYTHON}|g" "$svc_tmp" 2>/dev/null || \
                sed -i '' "s|__PYTHON3__|${MDNS_PYTHON}|g" "$svc_tmp"
            sed -i "s|__INSTALL_USER__|${_agent_user}|g" "$svc_tmp" 2>/dev/null || \
                sed -i '' "s|__INSTALL_USER__|${_agent_user}|g" "$svc_tmp"
            if grep -q '__INSTALL_DIR__\|__HOME__\|__PYTHON3__\|__INSTALL_USER__' "$svc_tmp"; then
                ai_warn "ods-mdns systemd unit has unrendered placeholders — check $svc_tmp"
            else
                sudo install -m 644 "$svc_tmp" /etc/systemd/system/ods-mdns.service
                sudo systemctl daemon-reload 2>/dev/null || true
                if sudo systemctl enable --now ods-mdns.service 2>&1 | tee -a "$LOG_FILE" >/dev/null; then
                    _device_name="$(grep -E '^ODS_DEVICE_NAME=' "$INSTALL_DIR/.env" 2>/dev/null | cut -d= -f2 | tr -d '"' || true)"
                    _device_name="${_device_name:-ods}"
                    # Be honest about what mDNS does on its own: it publishes the
                    # name. Whether that name LOADS anything in a browser depends
                    # on ods-proxy being on :80 and ODS_PROXY_BIND=0.0.0.0. Those
                    # are operator choices made elsewhere (and surfaced in the
                    # first-boot wizard); don't claim the URL works yet.
                    ai_ok "ODS mDNS announcer installed — '${_device_name}.local' now resolves on the LAN"
                    ai "  Enable ods-proxy (ODS_PROXY_BIND defaults to 0.0.0.0) to make http://${_device_name}.local serve chat. See docs/ODS-PROXY.md."
                else
                    ai_warn "ODS mDNS announcer failed to start (non-fatal — device is still reachable by IP)"
                fi
            fi
            rm -f "$svc_tmp"
        fi
    fi
fi