jishushell 0.4.2-beta2 → 0.4.10

package/install/jishu-install-china.sh

@@ -0,0 +1,3092 @@
+#!/bin/bash
+set -euo pipefail
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# JishuShell Installer
+#
+# Self-contained installer for all JishuShell dependencies:
+#   Node.js (via nvm), Docker, Nomad, OpenClaw Docker image
+#
+# Can also be sourced by other scripts (post-install.sh, jishu-uninstall.sh)
+# to reuse shared functions — main() only runs when executed directly.
+#
+# Usage:
+#   bash jishu-install.sh [options]       — run the full installer
+#   source jishu-install.sh               — import functions only
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Guard against double-sourcing
+if [[ -n "${_JISHU_INSTALL_LOADED:-}" ]]; then
+    return 0 2>/dev/null || true
+fi
+_JISHU_INSTALL_LOADED=1
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Temporary File Management (trap cleanup)
+# ═══════════════════════════════════════════════════════════════════════════════
+TMPFILES=()
+_SUDO_KEEPALIVE_PID=""
+
+cleanup_tmpfiles() {
+    local f
+    for f in "${TMPFILES[@]:-}"; do
+        rm -rf "$f" 2>/dev/null || true
+    done
+    # Kill sudo keepalive background process if running
+    if [[ -n "${_SUDO_KEEPALIVE_PID:-}" ]]; then
+        kill "$_SUDO_KEEPALIVE_PID" 2>/dev/null || true
+    fi
+}
+trap cleanup_tmpfiles EXIT
+
+mktempfile() {
+    local f
+    f="$(mktemp)"
+    TMPFILES+=("$f")
+    echo "$f"
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Download Tool Detection
+# ═══════════════════════════════════════════════════════════════════════════════
+DOWNLOADER=""
+detect_downloader() {
+    if command -v curl &> /dev/null; then
+        DOWNLOADER="curl"
+        return 0
+    fi
+    if command -v wget &> /dev/null; then
+        DOWNLOADER="wget"
+        return 0
+    fi
+    ui_error "Missing downloader (curl or wget required)"
+    exit 1
+}
+
+download_file() {
+    local url="$1"
+    local output="$2"
+    if [[ -z "$DOWNLOADER" ]]; then
+        detect_downloader
+    fi
+    if [[ "$DOWNLOADER" == "curl" ]]; then
+        curl -fsSL --proto '=https' --tlsv1.2 --retry 3 --retry-delay 1 --retry-connrefused -o "$output" "$url"
+        return
+    fi
+    wget -q --https-only --secure-protocol=TLSv1_2 --tries=3 --timeout=20 -O "$output" "$url"
+}
+
+# retry_net <description> <max_attempts> <cmd> [args...]
+# Runs cmd up to max_attempts times; waits 5s, 10s between retries.
+# Network-related exit codes (6,7,28,35,56 for curl; DNS/timeout) are all retried.
+retry_net() {
+    local desc="$1"
+    local max="${2:-3}"
+    shift 2
+    local attempt=1
+    local delay=5
+    while true; do
+        if "$@"; then
+            return 0
+        fi
+        local rc=$?
+        if [[ $attempt -ge $max ]]; then
+            ui_error "${desc} failed after ${max} attempts (last exit code: ${rc})"
+            return $rc
+        fi
+        ui_warn "${desc} failed (attempt ${attempt}/${max}, exit ${rc}) — retrying in ${delay}s..."
+        sleep "$delay"
+        attempt=$(( attempt + 1 ))
+        delay=$(( delay * 2 ))
+    done
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Non-interactive Shell Detection
+# ═══════════════════════════════════════════════════════════════════════════════
+is_non_interactive_shell() {
+    if [[ "${NO_PROMPT:-0}" == "1" ]]; then
+        return 0
+    fi
+    if [[ ! -t 0 || ! -t 1 ]]; then
+        return 0
+    fi
+    return 1
+}
+
+is_promptable() {
+    if [[ "${NO_PROMPT:-0}" == "1" ]]; then
+        return 1
+    fi
+    if [[ -r /dev/tty && -w /dev/tty ]]; then
+        return 0
+    fi
+    return 1
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Holiday Taglines (fun Easter eggs)
+# ═══════════════════════════════════════════════════════════════════════════════
+HOLIDAY_NEW_YEAR="New year, new config—same old EADDRINUSE, but this time we resolve it like grown-ups."
+HOLIDAY_CHRISTMAS="Ho ho ho—Santa's little helper is here to ship joy, roll back chaos, and stash the keys safely."
+HOLIDAY_HALLOWEEN="Spooky season: beware haunted dependencies, cursed caches, and the ghost of node_modules past."
+HOLIDAY_THANKSGIVING="Grateful for stable ports, working DNS, and a bot that reads the logs so nobody has to."
+
+append_holiday_taglines() {
+    local month_day
+    month_day="$(date -u +%m-%d 2>/dev/null || date +%m-%d)"
+    case "$month_day" in
+        "01-01") TAGLINE="${HOLIDAY_NEW_YEAR}" ;;
+        "12-25") TAGLINE="${HOLIDAY_CHRISTMAS}" ;;
+        "10-31") TAGLINE="${HOLIDAY_HALLOWEEN}" ;;
+        "11-27"|"11-28") TAGLINE="${HOLIDAY_THANKSGIVING}" ;;
+    esac
+}
+
+pick_tagline() {
+    if [[ -n "${JISHU_TAGLINE:-}" ]]; then
+        TAGLINE="${JISHU_TAGLINE}"
+        return
+    fi
+    append_holiday_taglines
+    if [[ -z "${TAGLINE:-}" ]]; then
+        TAGLINE="   All your agents, one JishuShell."
+    fi
+}
+
+# Script directory (BASH_SOURCE[0] is unset when piped via curl|bash, fall back to $0)
+JISHU_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd 2>/dev/null || pwd)"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# ──── BEGIN VERSIONS ────
+NODE_VERSION="${JISHU_NODE_VERSION:-22}"
+NVM_VERSION="${JISHU_NVM_VERSION:-0.40.4}"
+NOMAD_VERSION="${JISHU_NOMAD_VERSION:-1.11.3}"
+JISHUSHELL_PORT="${JISHUSHELL_PORT:-8090}"
+
+# ──── NPM Registry Configuration ────
+# Pass --registry <url> to override the npm registry for all installs.
+NPM_REGISTRY="${NPM_REGISTRY:-}"
+# Resolve the real (non-root) user when running via sudo.
+# REAL_USER / REAL_HOME are used wherever paths must belong to the target user.
+if [[ $EUID -eq 0 && -n "${SUDO_USER:-}" && "${SUDO_USER}" != "root" ]]; then
+    REAL_USER="${SUDO_USER}"
+    REAL_HOME="$(getent passwd "${SUDO_USER}" | cut -d: -f6 2>/dev/null || echo "")"
+elif [[ $EUID -eq 0 ]]; then
+    # Running as root without sudo — try to detect the first non-root UID-1000 user
+    # (common default user on Raspberry Pi, Ubuntu, etc.)
+    _fallback_user="$(getent passwd 1000 2>/dev/null | cut -d: -f1 || true)"
+    if [[ -n "${_fallback_user}" && "${_fallback_user}" != "root" ]]; then
+        REAL_USER="${_fallback_user}"
+        REAL_HOME="$(getent passwd "${_fallback_user}" | cut -d: -f6 2>/dev/null || echo "")"
+    else
+        REAL_USER="$(id -un)"
+        REAL_HOME="${HOME}"
+    fi
+    unset _fallback_user
+else
+    REAL_USER="$(id -un)"
+    REAL_HOME="${HOME}"
+fi
+[[ -z "${REAL_HOME}" ]] && REAL_HOME="${HOME}"
+REAL_GID="$(id -g "${REAL_USER}" 2>/dev/null || echo "")"
+
+# JISHUSHELL_HOME always lives in the real user's home so data is accessible
+# regardless of whether the process runs as root or as that user.
+if [[ -z "${JISHUSHELL_HOME:-}" ]]; then
+    JISHUSHELL_HOME="${REAL_HOME}/.jishushell"
+fi
+JISHUSHELL_BIN_DIR="${JISHUSHELL_BIN_DIR:-$JISHUSHELL_HOME/bin}"
+# ──── END VERSIONS ────
+
+# Pick tagline
+TAGLINE=""
+pick_tagline
+
+# Colors
+BOLD='\033[1m'
+ACCENT='\033[38;2;66;135;245m'
+ACCENT_CORAL='\033[38;2;255;77;77m'
+INFO='\033[38;2;136;146;176m'
+SUCCESS='\033[38;2;0;229;204m'
+WARN='\033[38;2;255;176;32m'
+ERROR='\033[38;2;230;57;70m'
+MUTED='\033[38;2;90;100;128m'
+NC='\033[0m'
+
+# Shared state
+VERBOSE="${VERBOSE:-0}"
+DRY_RUN="${DRY_RUN:-0}"
+SKIP_NODE="${SKIP_NODE:-0}"
+SKIP_DOCKER="${SKIP_DOCKER:-0}"
+SKIP_NOMAD="${SKIP_NOMAD:-0}"
+SKIP_OPENCLAW="${SKIP_OPENCLAW:-0}"  # default=0 (install); use --skip 4 or --skip-openclaw to skip
+SKIP_JISHUSHELL="${SKIP_JISHUSHELL:-0}"          # 1=skip install_jishushell
+SKIP_JISHUSHELL_SERVICE="${SKIP_JISHUSHELL_SERVICE:-0}"  # 1=skip service registration
+OPENCLAW_NPM_VERSION="${OPENCLAW_NPM_VERSION:-latest}"   # openclaw npm package version
+OPENCLAW_DOCKER_TAG="${OPENCLAW_DOCKER_TAG:-jishushell-openclaw:local}"  # locally built image with Python
+OPENCLAW_IMAGE=""                                        # set dynamically after pull/build
+AUTO_YES="${AUTO_YES:-0}"
+DOCKER_CMD_PREFIX=""          # Set to "sg docker -c" when group activated via sg
+DOCKER_GROUP_JUST_ADDED=0     # 1 if usermod was called this run
+DOCKER_USE_SUDO=0             # 1 if sudo docker should be used as fallback
+NETWORK_CHINA=0               # 1 if www.google.com is unreachable (use Alibaba mirrors)
+NETWORK_OVERRIDE=0            # 1 if --network was explicitly passed (skip auto-detection)
+
+PKG_UPDATED=0
+
+INSTALL_STAGE_TOTAL="${INSTALL_STAGE_TOTAL:-6}"
+INSTALL_STAGE_CURRENT="${INSTALL_STAGE_CURRENT:-0}"
+JISHU_LOG_FILE=""
+_JISHU_RAW_LOG=""
+_JISHU_TEE_PID=""
+_JISHU_LOG_FIFO=""
+_JISHU_DETAIL_LOG=""
+
+# Legacy environment variable mapping
+map_legacy_env() {
+    local key="$1"
+    local legacy="$2"
+    if [[ -z "${!key:-}" && -n "${!legacy:-}" ]]; then
+        printf -v "$key" '%s' "${!legacy}"
+    fi
+}
+
+# (legacy env var mappings reserved for future renames)
+
+# ─── UI helpers ───────────────────────────────────────────────────────────────
+ui_info() {
+    echo -e "${MUTED}·${NC} $*"
+}
+
+ui_success() {
+    echo -e "${SUCCESS}✓${NC} $*"
+}
+
+ui_warn() {
+    echo -e "${WARN}!${NC} $*"
+}
+
+ui_error() {
+    echo -e "${ERROR}✗${NC} $*" >&2
+}
+
+ui_stage() {
+    local title="$1"
+    INSTALL_STAGE_CURRENT=$((INSTALL_STAGE_CURRENT + 1))
+    echo ""
+    echo -e "${ACCENT}${BOLD}[${INSTALL_STAGE_CURRENT}/${INSTALL_STAGE_TOTAL}] ${title}${NC}"
+}
+
+ui_section() {
+    echo -e "\n${ACCENT}${BOLD}── $* ──${NC}"
+}
+
+ui_kv() {
+    local key="$1" value="$2"
+    printf "${MUTED}%-18s${NC} %s\n" "$key:" "$value"
+}
+
+# ─── Detail-log helpers ───────────────────────────────────────────────────────
+# Appends one line directly to the detail log file (bypasses the terminal pipe).
+log_detail() {
+    [[ -n "${_JISHU_DETAIL_LOG:-}" ]] || return 0
+    printf '%s\n' "$*" >> "${_JISHU_DETAIL_LOG}"
+}
+
+# Runs a command, capturing stdout+stderr to the detail log file only.
+# Nothing is written to the terminal — use ui_* helpers for status messages.
+# Returns the command's exit code.
+log_cmd() {
+    local _rc=0
+    if [[ -z "${_JISHU_DETAIL_LOG:-}" ]]; then
+        "$@" 2>&1
+        return
+    fi
+    log_detail ""
+    log_detail "[$(date '+%H:%M:%S')] \$ $*"
+    # Capture output to detail log only (not forwarded to the terminal)
+    local _tmp
+    _tmp="$(mktemp)"
+    "$@" > "${_tmp}" 2>&1 || _rc=$?
+    if [[ -s "${_tmp}" ]]; then
+        sed 's/^/  /' "${_tmp}" >> "${_JISHU_DETAIL_LOG}"  # → detail log only
+    fi
+    rm -f "${_tmp}"
+    log_detail "  \u2192 exit ${_rc}"
+    return $_rc
+}
+
+# Like log_cmd but prepends \$SUDO when set (mirrors run_sudo behaviour).
+_log_sudo() {
+    if [[ -n "${SUDO:-}" ]]; then
+        log_cmd "${SUDO}" "$@"
+    else
+        log_cmd "$@"
+    fi
+}
+
+# ─── User confirmation prompt ────────────────────────────────────────────────
+# Usage: confirm "Delete everything?" && do_delete
+# Respects AUTO_YES=1 to skip prompts.
+confirm() {
+    local prompt="$1"
+    if [[ "${AUTO_YES:-0}" == "1" ]]; then
+        ui_info "$prompt → auto-confirmed (--yes)"
+        return 0
+    fi
+    local answer answer_lc
+    read -r -p "$(echo -e "${WARN}  ${prompt} [y/N]: ${NC}")" answer </dev/tty || answer="n"
+    answer_lc="$(echo "$answer" | tr '[:upper:]' '[:lower:]')"
+    case "$answer_lc" in
+        y|yes) return 0 ;;
+        *)     return 1 ;;
+    esac
+}
+
+# ─── Utility functions ────────────────────────────────────────────────────────
+
+# Detect OS and package manager.
+# Sets: OS_ID, OS_VERSION, OS_NAME, PKG_MANAGER
+detect_os() {
+    if [[ "$(uname -s)" == "Darwin" ]]; then
+        OS="macos"
+        OS_ID="macos"
+        OS_VERSION="$(sw_vers -productVersion 2>/dev/null || echo "unknown")"
+        OS_NAME="macOS ${OS_VERSION}"
+        if command -v brew &>/dev/null; then
+            PKG_MANAGER="brew"
+        else
+            PKG_MANAGER="none"
+            ui_warn "Homebrew not found — some optional installs may be skipped"
+        fi
+        ui_success "OS: ${OS_NAME} (package manager: ${PKG_MANAGER})"
+        return 0
+    fi
+
+    if [[ ! -f /etc/os-release ]]; then
+        ui_error "Cannot detect OS: /etc/os-release not found"
+        ui_error "This installer supports Linux and macOS"
+        exit 1
+    fi
+
+    # shellcheck source=/dev/null
+    . /etc/os-release
+
+    OS_ID="${ID:-unknown}"
+    OS_VERSION="${VERSION_ID:-unknown}"
+    OS_NAME="${PRETTY_NAME:-$OS_ID $OS_VERSION}"
+
+    case "$OS_ID" in
+        ubuntu|debian|linuxmint|pop)
+            PKG_MANAGER="apt"
+            ;;
+        centos|rhel|rocky|almalinux|fedora|amzn)
+            if command -v dnf &>/dev/null; then
+                PKG_MANAGER="dnf"
+            else
+                PKG_MANAGER="yum"
+            fi
+            ;;
+        *)
+            ui_warn "Untested distribution: $OS_ID — attempting auto-detect"
+            if command -v apt-get &>/dev/null; then
+                PKG_MANAGER="apt"
+            elif command -v dnf &>/dev/null; then
+                PKG_MANAGER="dnf"
+            elif command -v yum &>/dev/null; then
+                PKG_MANAGER="yum"
+            else
+                ui_error "No supported package manager found (apt/dnf/yum)"
+                exit 1
+            fi
+            ;;
+    esac
+
+    OS="linux"
+    ui_success "OS: ${OS_NAME} (package manager: ${PKG_MANAGER})"
+}
+
+# Detect CPU architecture.  Sets: ARCH (amd64 | arm64)
+detect_arch() {
+    ARCH="$(uname -m)"
+    case "$ARCH" in
+        x86_64|amd64)    ARCH="amd64" ;;
+        aarch64|arm64)   ARCH="arm64" ;;
+        *)
+            ui_error "Unsupported CPU architecture: $ARCH"
+            exit 1
+            ;;
+    esac
+    ui_success "Architecture: ${ARCH}"
+}
+
+# Detect network environment by pinging www.google.com.  Sets: NETWORK_CHINA (0=global, 1=China)
+detect_network() {
+    if [[ "${NETWORK_OVERRIDE:-0}" == "1" ]]; then
+        if [[ "$NETWORK_CHINA" == "1" ]]; then
+            ui_info "Network: forced china (--network china) — Alibaba mirrors will be used"
+        else
+            ui_info "Network: forced global (--network global)"
+        fi
+        return 0
+    fi
+    ui_info "Checking network connectivity (ping www.google.com)..."
+    if ping -c 1 -W 3 www.google.com &>/dev/null 2>&1; then
+        NETWORK_CHINA=0
+        ui_success "Network: global reachable"
+    else
+        NETWORK_CHINA=1
+        ui_warn "Network: www.google.com unreachable — Alibaba mirrors will be used for Docker and OpenClaw"
+    fi
+}
+
+# Verify sudo access.  Sets: SUDO ("" if root, "sudo" otherwise)
+check_sudo() {
+    if [[ $EUID -eq 0 ]]; then
+        SUDO=""
+        return 0
+    fi
+
+    if ! command -v sudo &>/dev/null; then
+        ui_error "Not running as root and sudo is not installed. Re-run as root."
+        exit 1
+    fi
+
+    if ! sudo -n true 2>/dev/null; then
+        ui_info "Some steps require sudo — you may be prompted for your password."
+        if ! sudo -v </dev/tty; then
+            ui_error "Failed to obtain sudo privileges"
+            exit 1
+        fi
+    fi
+
+    SUDO="sudo"
+    ui_success "sudo privileges confirmed"
+
+    # Keep sudo credentials alive for the entire install (refreshes every 60s).
+    # This ensures 'sudo docker' works even after a long Docker install step
+    # without prompting for the password again.
+    if [[ -z "${_SUDO_KEEPALIVE_PID:-}" ]]; then
+        ( while true; do sudo -n true 2>/dev/null; sleep 60; done ) &
+        _SUDO_KEEPALIVE_PID=$!
+        disown "$_SUDO_KEEPALIVE_PID" 2>/dev/null || true
+    fi
+}
+
+extract_semver() {
+    grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -n1
+}
+
+# Semantic version comparison: returns 0 if $1 >= $2
+version_gte() {
+    local v1="$1" v2="$2"
+    if [[ "$(printf '%s\n%s' "$v1" "$v2" | sort -V | head -n1)" == "$v2" ]]; then
+        return 0
+    fi
+    return 1
+}
+
+# Run a command, honouring --dry-run.
+# When the detail log is active, command output is captured there (silent on terminal).
+run_cmd() {
+    if [[ "$DRY_RUN" == "1" ]]; then
+        ui_info "[dry-run] $*"
+        return 0
+    fi
+    log_detail ""
+    log_detail "[$(date '+%H:%M:%S')] \$ $*"
+    if [[ -n "${_JISHU_DETAIL_LOG:-}" ]]; then
+        local _rc=0 _tmp
+        _tmp="$(mktemp)"
+        "$@" > "${_tmp}" 2>&1 || _rc=$?
+        [[ -s "${_tmp}" ]] && sed 's/^/  /' "${_tmp}" >> "${_JISHU_DETAIL_LOG}"
+        rm -f "${_tmp}"
+        log_detail "  \u2192 exit ${_rc}"
+        return $_rc
+    fi
+    "$@"
+}
+
+# Run a command with sudo, honouring --dry-run.
+# When the detail log is active, command output is captured there (silent on terminal).
+run_sudo() {
+    if [[ "$DRY_RUN" == "1" ]]; then
+        ui_info "[dry-run] ${SUDO:+sudo }$*"
+        return 0
+    fi
+    log_detail ""
+    log_detail "[$(date '+%H:%M:%S')] \$ ${SUDO:+${SUDO} }$*"
+    if [[ -n "${_JISHU_DETAIL_LOG:-}" ]]; then
+        local _rc=0 _tmp
+        _tmp="$(mktemp)"
+        ${SUDO} "$@" > "${_tmp}" 2>&1 || _rc=$?
+        [[ -s "${_tmp}" ]] && sed 's/^/  /' "${_tmp}" >> "${_JISHU_DETAIL_LOG}"
+        rm -f "${_tmp}"
+        log_detail "  \u2192 exit ${_rc}"
+        return $_rc
+    fi
+    ${SUDO} "$@"
+}
+
+# Wait for apt/dpkg locks to be released
+wait_for_apt_lock() {
+    if [[ "${PKG_MANAGER:-}" != "apt" ]]; then
+        return 0
+    fi
+
+    local max_wait=60
+    local waited=0
+
+    while fuser /var/lib/dpkg/lock-frontend &>/dev/null 2>&1 || \
+          fuser /var/lib/apt/lists/lock &>/dev/null 2>&1; do
+        if [[ $waited -eq 0 ]]; then
+            ui_info "Waiting for apt lock to be released..."
+        fi
+        sleep 2
+        waited=$((waited + 2))
+        if [[ $waited -ge $max_wait ]]; then
+            ui_error "Timed out waiting for apt lock (${max_wait}s). Check for other running package managers."
+            exit 1
+        fi
+    done
+}
+
+# Run the package index update once per invocation.
+# Safe to call multiple times — only executes on the first call.
+pkg_update() {
+    if [[ "$PKG_UPDATED" == "1" ]]; then
+        return 0
+    fi
+
+    if [[ "$DRY_RUN" == "1" ]]; then
+        ui_info "[dry-run] Would update package index"
+        PKG_UPDATED=1
+        return 0
+    fi
+
+    wait_for_apt_lock
+
+    ui_info "Updating package index..."
+    case "$PKG_MANAGER" in
+        apt)
+            if ! retry_net "apt-get update" 3 _log_sudo apt-get update; then
+                ui_warn "apt-get update failed — package index may be stale, continuing anyway"
+            fi
+            ;;
+        dnf)
+            retry_net "dnf check-update" 3 _log_sudo dnf check-update 2>/dev/null || true
+            ;;
+        yum)
+            retry_net "yum check-update" 3 _log_sudo yum check-update 2>/dev/null || true
+            ;;
+        brew)
+            retry_net "brew update" 3 log_cmd brew update 2>/dev/null || true
+            ;;
+        none)
+            ;;
+    esac
+
+    PKG_UPDATED=1
+}
+
+# Install system packages, ensuring the index is up to date first.
+pkg_install() {
+    pkg_update
+    wait_for_apt_lock
+    case "$PKG_MANAGER" in
+        apt)
+            if ! retry_net "apt-get install $*" 3 run_sudo apt-get install -y "$@"; then
+                ui_error "apt-get install failed for: $*"
+                return 1
+            fi
+            ;;
+        dnf)
+            if ! retry_net "dnf install $*" 3 run_sudo dnf install -y "$@"; then
+                ui_error "dnf install failed for: $*"
+                return 1
+            fi
+            ;;
+        yum)
+            if ! retry_net "yum install $*" 3 run_sudo yum install -y "$@"; then
+                ui_error "yum install failed for: $*"
+                return 1
+            fi
+            ;;
+        brew)
+            if ! retry_net "brew install $*" 3 brew install "$@" 2>/dev/null; then
+                ui_warn "brew install failed for: $* (may already be installed)"
+            fi
+            ;;
+        none)
+            ui_warn "No package manager available — skipping install of: $*"
+            ;;
+    esac
+}
+
+# Check whether a system package is installed
+_pkg_is_installed() {
+    local pkg="$1"
+    case "$PKG_MANAGER" in
+        apt)    dpkg -l "$pkg" 2>/dev/null | grep -q '^ii' ;;
+        dnf)    rpm -q "$pkg" &>/dev/null ;;
+        yum)    rpm -q "$pkg" &>/dev/null ;;
+    esac
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# npm install failure detection and auto-fix
+# ═══════════════════════════════════════════════════════════════════════════════
+npm_log_indicates_missing_build_tools() {
+    local log="$1"
+    if [[ -z "$log" || ! -f "$log" ]]; then
+        return 1
+    fi
+    grep -Eiq "(not found: make|make: command not found|cmake: command not found|CMAKE_MAKE_PROGRAM is not set|Could not find CMAKE|gyp ERR! find Python|no developer tools were found|is not able to compile a simple test program|Failed to build|It seems that \"make\" is not installed|It seems that the used \"cmake\" doesn't work properly)" "$log"
+}
+
+# Detect Arch-based distributions
+is_arch_linux() {
+    if [[ -f /etc/os-release ]]; then
+        local os_id
+        os_id="$(grep -E '^ID=' /etc/os-release 2>/dev/null | cut -d'=' -f2 | tr -d '"' || true)"
+        case "$os_id" in
+            arch|manjaro|endeavouros|arcolinux|garuda|archarm|cachyos|archcraft)
+                return 0
+        esac
+        local os_id_like
+        os_id_like="$(grep -E '^ID_LIKE=' /etc/os-release 2>/dev/null | cut -d'=' -f2 | tr -d '"' || true)"
+        if [[ "$os_id_like" == *arch* ]]; then
+            return 0
+        fi
+    fi
+    if command -v pacman &> /dev/null; then
+        return 0
+    fi
+    return 1
+}
+
+install_build_tools_linux() {
+    if command -v apt-get &> /dev/null; then
+        if is_root; then
+            run_quiet_step "Updating package index" apt-get update -qq
+            run_quiet_step "Installing build tools" apt-get install -y -qq build-essential python3 make g++ cmake
+        else
+            run_quiet_step "Updating package index" sudo apt-get update -qq
+            run_quiet_step "Installing build tools" sudo apt-get install -y -qq build-essential python3 make g++ cmake
+        fi
+        return 0
+    fi
+    if command -v pacman &> /dev/null || is_arch_linux; then
+        if is_root; then
+            run_quiet_step "Installing build tools" pacman -Sy --noconfirm base-devel python make cmake gcc
+        else
+            run_quiet_step "Installing build tools" sudo pacman -Sy --noconfirm base-devel python make cmake gcc
+        fi
+        return 0
+    fi
+    if command -v dnf &> /dev/null; then
+        if is_root; then
+            run_quiet_step "Installing build tools" dnf install -y -q gcc gcc-c++ make cmake python3
+        else
+            run_quiet_step "Installing build tools" sudo dnf install -y -q gcc gcc-c++ make cmake python3
+        fi
+        return 0
+    fi
+    if command -v yum &> /dev/null; then
+        if is_root; then
+            run_quiet_step "Installing build tools" yum install -y -q gcc gcc-c++ make cmake python3
+        else
+            run_quiet_step "Installing build tools" sudo yum install -y -q gcc gcc-c++ make cmake python3
+        fi
+        return 0
+    fi
+    if command -v apk &> /dev/null; then
+        if is_root; then
+            run_quiet_step "Installing build tools" apk add --no-cache build-base python3 cmake
+        else
+            run_quiet_step "Installing build tools" sudo apk add --no-cache build-base python3 cmake
+        fi
+        return 0
+    fi
+    ui_warn "Could not detect package manager for auto-installing build tools"
+    return 1
+}
+
+install_build_tools_macos() {
+    local ok=true
+    if ! xcode-select -p >/dev/null 2>&1; then
+        ui_info "Installing Xcode Command Line Tools (required for make/clang)"
+        xcode-select --install >/dev/null 2>&1 || true
+        if ! xcode-select -p >/dev/null 2>&1; then
+            ui_warn "Xcode Command Line Tools are not ready yet"
+            ui_info "Complete the installer dialog, then re-run this installer"
+            ok=false
+        fi
+    fi
+    if ! command -v cmake >/dev/null 2>&1; then
+        if command -v brew >/dev/null 2>&1; then
+            run_quiet_step "Installing cmake" brew install cmake
+        else
+            ui_warn "Homebrew not available; cannot auto-install cmake"
+            ok=false
+        fi
+    fi
+    if ! command -v make >/dev/null 2>&1; then
+        ui_warn "make is still unavailable"
+        ok=false
+    fi
+    if ! command -v cmake >/dev/null 2>&1; then
+        ui_warn "cmake is still unavailable"
+        ok=false
+    fi
+    [[ "$ok" == "true" ]]
+}
+
+is_root() {
+    [[ $EUID -eq 0 ]]
+}
+
+run_quiet_step() {
+    local title="$1"
+    shift
+    if [[ "$DRY_RUN" == "1" ]]; then
+        ui_info "[dry-run] $title"
+        return 0
+    fi
+    log_detail ""
+    log_detail "[$(date '+%H:%M:%S')] \$ $*  # ${title}"
+    if "$@"; then
+        return 0
+    fi
+    ui_error "${title} failed"
+    return 1
+}
+
+auto_install_build_tools_for_npm_failure() {
+    local log="$1"
+    if ! npm_log_indicates_missing_build_tools "$log"; then
+        return 1
+    fi
+    ui_warn "Detected missing native build tools; attempting automatic setup"
+    if [[ "$OS" == "linux" ]]; then
+        install_build_tools_linux || return 1
+    elif [[ "$OS" == "macos" ]]; then
+        install_build_tools_macos || return 1
+    else
+        return 1
+    fi
+    ui_success "Build tools setup complete"
+    return 0
+}
+
+extract_npm_error_code() {
+    local log="$1"
+    sed -n -E 's/^npm (ERR!|error) code[[:space:]]+([^[:space:]]+).*$/\2/p' "$log" | head -n1
+}
+
+print_npm_failure_diagnostics() {
+    local spec="$1"
+    local log="$2"
+    local error_code=""
+    ui_warn "npm install failed for ${spec}"
+    error_code="$(extract_npm_error_code "$log")"
+    if [[ -n "$error_code" ]]; then
+        echo "  npm code: ${error_code}"
+    fi
+    if [[ -s "$log" ]]; then
+        echo "  Last lines of log:"
+        tail -n 20 "$log" | sed 's/^/    /' || true
+    fi
+}
+
+# ─── Prerequisites ────────────────────────────────────────────────────────────
+ensure_prerequisites() {
+    local missing=()
+
+    for cmd in curl tar; do
+        if ! command -v "$cmd" &>/dev/null; then
+            missing+=("$cmd")
+        fi
+    done
+
+    if [[ ${#missing[@]} -gt 0 ]]; then
+        ui_info "Installing prerequisites: ${missing[*]}"
+        pkg_install "${missing[@]}"
+    fi
+
+    if ! command -v curl &>/dev/null; then
+        ui_error "Failed to install curl. Please install it manually and retry."
+        exit 1
+    fi
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Component installation functions
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# ─── 1. Node.js (via nvm) ────────────────────────────────────────────────────
+
+_load_nvm() {
+    export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+    if [[ -s "$NVM_DIR/nvm.sh" ]]; then
+        # shellcheck source=/dev/null
+        \. "$NVM_DIR/nvm.sh"
+        return 0
+    fi
+    return 1
+}
+
+install_node() {
+    ui_stage "Node.js (via nvm)"
+
+    _load_nvm 2>/dev/null || true
+
+    if command -v node &>/dev/null; then
+        local current_version
+        current_version="$(node --version 2>/dev/null | sed 's/^v//')"
+        local current_major="${current_version%%.*}"
+
+        if [[ "$current_major" -ge "$NODE_VERSION" ]]; then
+            ui_success "Node.js already installed: v${current_version} (satisfies >= v${NODE_VERSION})"
+            if command -v npm &>/dev/null; then
+                ui_success "npm: $(npm --version 2>/dev/null)"
+            fi
+            _ensure_nvm_shell_config
+            return 0
+        else
+            ui_warn "Node.js version too old: v${current_version} (need >= v${NODE_VERSION})"
+            ui_info "Upgrading Node.js via nvm..."
+        fi
+    else
+        ui_info "Node.js not found — installing via nvm..."
+    fi
+
+    _do_install_node
+}
+
+_do_install_node() {
+    ui_info "Installing nvm v${NVM_VERSION} and Node.js ${NODE_VERSION}..."
+
+    if [[ "$DRY_RUN" == "1" ]]; then
+        ui_info "[dry-run] Would install nvm v${NVM_VERSION}"
+        ui_info "[dry-run] Would run: nvm install ${NODE_VERSION}"
+        return 0
+    fi
+
+    local nvm_install_script
+    nvm_install_script="$(mktemp)"
+    trap "rm -f '$nvm_install_script'" RETURN
+
+    local nvm_url
+    if [[ "${NETWORK_CHINA:-0}" == "1" ]]; then
+        # Gitee mirror of nvm-sh/nvm (Chinese CDN)
+        nvm_url="https://gitee.com/mirrors/nvm/raw/v${NVM_VERSION}/install.sh"
+        ui_info "China network — downloading nvm from Gitee mirror"
+    else
+        nvm_url="https://raw.githubusercontent.com/nvm-sh/nvm/v${NVM_VERSION}/install.sh"
+    fi
+    if ! retry_net "Download nvm install script" 3 curl -fsSL "$nvm_url" -o "$nvm_install_script"; then
+        ui_error "Failed to download nvm install script from: $nvm_url"
+        return 1
+    fi
+
+    if [[ "${NETWORK_CHINA:-0}" == "1" ]]; then
+        # Point nvm at the npmmirror.com Node.js CDN (much faster in China)
+        export NVM_NODEJS_ORG_MIRROR="https://npmmirror.com/mirrors/node"
+        ui_info "China network — nvm will download Node.js from npmmirror.com"
+    fi
+
+    if ! bash "$nvm_install_script"; then
+        ui_error "nvm install script failed"
+        return 1
+    fi
+
+    rm -f "$nvm_install_script"
+    trap - RETURN
+
+    if ! _load_nvm; then
+        ui_error "nvm was installed but could not be loaded (NVM_DIR=$NVM_DIR)"
+        return 1
+    fi
+
+    ui_success "nvm loaded: $(nvm --version 2>/dev/null)"
+
+    ui_info "Running: nvm install ${NODE_VERSION}"
+    if ! retry_net "nvm install ${NODE_VERSION}" 3 nvm install "${NODE_VERSION}"; then
+        ui_error "nvm install ${NODE_VERSION} failed"
+        return 1
+    fi
+
+    nvm alias default "${NODE_VERSION}" >/dev/null 2>&1 || true
+
+    local installed_version
+    installed_version="$(node --version 2>/dev/null)"
+    if [[ -z "$installed_version" ]]; then
+        ui_error "Node.js installation verification failed"
+        return 1
+    fi
+    ui_success "Node.js installed: ${installed_version}"
+
+    if command -v npm &>/dev/null; then
+        ui_success "npm: $(npm --version 2>/dev/null)"
+    else
+        ui_warn "npm was not found after installation — check manually"
+    fi
+
+    _ensure_nvm_shell_config
+}
+
+_ensure_nvm_shell_config() {
+    local init_block
+    init_block='\nexport NVM_DIR="$HOME/.nvm"\n[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"\n[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"'
+
+    local rc_files=("$HOME/.bashrc" "$HOME/.bash_profile" "$HOME/.profile" "$HOME/.zshrc")
+    local added=0
+    for rc in "${rc_files[@]}"; do
+        if [[ -f "$rc" ]] && ! grep -q 'NVM_DIR' "$rc" 2>/dev/null; then
+            printf '%b\n' "$init_block" >> "$rc"
+            ui_info "nvm init added to $rc"
+            added=1
+        fi
+    done
+    if [[ $added -eq 0 ]]; then
+        :
+    fi
+}
+
+# ─── 2. Docker ───────────────────────────────────────────────────────────────
+
+install_docker() {
+    ui_stage "Docker"
+
+    local need_install_docker=0
+    local need_install_compose=0
+
+    if command -v docker &>/dev/null; then
+        local docker_version
+        docker_version="$(docker version --format '{{.Server.Version}}' 2>/dev/null | extract_semver || \
+                         docker --version 2>/dev/null | extract_semver || \
+                         echo "unknown")"
+
+        if [[ "$docker_version" != "unknown" ]]; then
+            ui_success "Docker already installed: v${docker_version}"
+        else
+            ui_warn "Docker command found but version unavailable (daemon may not be running)"
+            _ensure_docker_running
+        fi
+        # Always ensure mirrors are configured when NETWORK_CHINA=1,
+        # even if Docker was already installed before this run.
+        _configure_docker_mirror
+    else
+        need_install_docker=1
+    fi
+
+    if docker compose version &>/dev/null 2>&1; then
+        :
+    elif command -v docker-compose &>/dev/null; then
+        :
+    elif [[ "$OS" == "macos" ]]; then
+        :
+    else
+        need_install_compose=1
+    fi
+
+    if [[ $need_install_docker -eq 0 && $need_install_compose -eq 0 ]]; then
+        _ensure_docker_running
+        _ensure_docker_group
+        return 0
+    fi
+
+    if [[ $need_install_docker -eq 1 ]]; then
+        ui_info "Docker not found — installing..."
+        # _do_install_docker installs docker-compose-plugin in the same apt command,
+        # so Compose V2 will be available immediately after — no separate step needed.
+        if ! _do_install_docker; then
+            ui_warn "Official Docker install script failed — trying system package manager fallback..."
+            if ! _do_install_docker_apt_fallback; then
+                ui_error "All Docker installation methods failed — skipping group setup"
+                return 1
+            fi
+        fi
+        # Compose is bundled; skip the separate install step
+        need_install_compose=0
+    fi
+
+    if [[ $need_install_compose -eq 1 ]]; then
+        if ! docker compose version &>/dev/null 2>&1; then
+            ui_info "Docker Compose V2 not detected — installing plugin..."
+            if ! _do_install_compose_plugin; then
+                ui_warn "Docker Compose V2 plugin installation failed — Compose features may be unavailable"
+            fi
+        fi
+    fi
+
+    _ensure_docker_running
+    _configure_docker_mirror
+    _ensure_docker_group
+}
+
+_do_install_docker() {
+    if [[ "$DRY_RUN" == "1" ]]; then
+        ui_info "[dry-run] Would install Docker via get.docker.com"
+        return 0
+    fi
+
+    if [[ "$OS" == "macos" ]]; then
+        ui_warn "Automated Docker installation is not supported on macOS"
+        ui_info "Please install Docker Desktop from https://www.docker.com/products/docker-desktop/"
+        if command -v brew &>/dev/null; then
+            ui_info "Or via Homebrew: brew install --cask docker"
+        fi
+        ui_info "After installation, open Docker Desktop and wait for the daemon to start, then re-run this script"
+        return 1
+    fi
+
+    # Step 1: download
+    local docker_script
+    docker_script="$(mktemp)"
+    mv "$docker_script" "${docker_script}.sh"
+    docker_script="${docker_script}.sh"
+    ui_info "Downloading Docker install script from https://get.docker.com ..."
+    if ! retry_net "Download Docker install script" 3 curl -fsSL https://get.docker.com -o "$docker_script"; then
+        ui_error "Failed to download Docker install script"
+        rm -f "$docker_script"
+        return 1
+    fi
+
+    # Step 2: preview (first 5 lines so the user can see what will run)
+    ui_info "Install script preview (first 5 lines):"
+    head -n 5 "$docker_script" | sed 's/^/    /' || true
+
+    # Step 3: run with sudo sh (as recommended by get.docker.com)
+    local _docker_mirror_flag=""
+    if [[ "${NETWORK_CHINA:-0}" == "1" ]]; then
+        _docker_mirror_flag="--mirror Aliyun"
+        ui_info "China network detected — using Alibaba mirror (mirrors.aliyun.com)"
+    fi
+    ui_info "Running: sudo sh install-docker.sh ${_docker_mirror_flag}..."
+    # shellcheck disable=SC2086
+    if ! ${SUDO} sh "$docker_script" ${_docker_mirror_flag}; then
+        ui_error "Docker install script failed"
+        rm -f "$docker_script"
+        return 1
+    fi
+    rm -f "$docker_script"
+
+    # ── Post-install steps ────────────────────────────────────────────────────
+    # Always add REAL_USER (the non-root user who invoked sudo), not whoami which
+    # may return "root" when running via "sudo bash install.sh".
+    local user="${REAL_USER:-$(whoami)}"
+
+    # 1. sudo usermod -aG docker $REAL_USER
+    ui_info "Running: sudo usermod -aG docker ${user}"
+    if ${SUDO} usermod -aG docker "${user}"; then
+        ui_success "User ${user} added to docker group"
+        DOCKER_GROUP_JUST_ADDED=1
+    else
+        ui_warn "usermod failed — run manually: sudo usermod -aG docker ${user}"
+    fi
+
+    # 2. sudo systemctl start docker
+    ui_info "Running: sudo systemctl start docker"
+    ${SUDO} systemctl start docker 2>/dev/null || \
+        ${SUDO} service docker start 2>/dev/null || true
+
+    _ensure_docker_running
+
+    # 3. newgrp docker  (in a script 'sg docker -c' is the non-interactive equivalent)
+    #    Activates group membership without requiring re-login
+    ui_info "Activating docker group (newgrp docker equivalent via 'sg docker') ..."
+    if command -v sg &>/dev/null && sg docker -c "docker info" &>/dev/null 2>&1; then
+        DOCKER_CMD_PREFIX="sg docker -c"
+        ui_success "docker group activated for this session"
+    else
+        DOCKER_USE_SUDO=1
+        ui_info "sg docker unavailable — using sudo docker for this session"
+    fi
+
+    # 4. docker ps
+    ui_info "Running: docker ps"
+    local docker_ps_out
+    if [[ -n "${DOCKER_CMD_PREFIX:-}" ]]; then
+        docker_ps_out="$(${DOCKER_CMD_PREFIX} "docker ps" 2>&1)" && {
+            ui_success "docker ps succeeded:"
+            echo "$docker_ps_out" | sed 's/^/    /'
+        } || ui_warn "docker ps returned non-zero (daemon may still be warming up)"
+    elif ${SUDO} docker ps &>/dev/null 2>&1; then
+        docker_ps_out="$(${SUDO} docker ps 2>&1)"
+        ui_success "docker ps succeeded (via sudo):"
+        echo "$docker_ps_out" | sed 's/^/    /'
+    else
+        ui_warn "docker ps failed — run 'sudo docker ps' to check daemon status"
+    fi
+
+    if ! command -v docker &>/dev/null; then
+        ui_error "Docker installation verification failed"
+        return 1
+    fi
+
+    local installed_version
+    installed_version="$(docker --version 2>/dev/null | extract_semver || echo "unknown")"
+    ui_success "Docker installed: v${installed_version}"
+}
+
+# Fallback Docker installer that uses the system package manager (apt/dnf/yum).
+# Called when the get.docker.com script fails (network issues, GPG errors, etc.).
+_do_install_docker_apt_fallback() {
+    if [[ "$DRY_RUN" == "1" ]]; then
+        ui_info "[dry-run] Would install Docker via system package manager (apt/dnf/yum)"
+        return 0
+    fi
+
+    if [[ "$OS" == "macos" ]]; then
+        ui_warn "No apt/dnf fallback available on macOS — please install Docker Desktop manually"
+        return 1
+    fi
+
+    case "${PKG_MANAGER:-apt}" in
+        apt)
+            ui_info "Attempting: apt-get install docker.io ..."
+            ${SUDO} apt-get update -qq 2>/dev/null || true
+            if ${SUDO} apt-get install -y docker.io docker-compose; then
+                ui_success "Docker installed via apt (docker.io)"
+                # Ensure service is started
+                ${SUDO} systemctl start docker 2>/dev/null || \
+                    ${SUDO} service docker start 2>/dev/null || true
+                _ensure_docker_running
+                return 0
+            fi
+            ui_error "apt-get install docker.io failed"
+            return 1
+            ;;
+        dnf|yum)
+            ui_info "Attempting: ${PKG_MANAGER} install docker ..."
+            if ${SUDO} "${PKG_MANAGER}" install -y docker; then
+                ui_success "Docker installed via ${PKG_MANAGER}"
+                ${SUDO} systemctl start docker 2>/dev/null || true
+                _ensure_docker_running
+                return 0
+            fi
+            ui_error "${PKG_MANAGER} install docker failed"
+            return 1
+            ;;
+        *)
+            ui_error "No fallback Docker install method for package manager: ${PKG_MANAGER:-unknown}"
+            return 1
+            ;;
+    esac
+}
+
+_do_install_compose_plugin() {
+    if [[ "$DRY_RUN" == "1" ]]; then
+        ui_info "[dry-run] Would install docker-compose-plugin"
+        return 0
+    fi
+
+    case "$PKG_MANAGER" in
+        apt)     pkg_install docker-compose-plugin ;;
+        dnf|yum) pkg_install docker-compose-plugin ;;
+    esac
+
+    if docker compose version &>/dev/null 2>&1; then
+        ui_success "Docker Compose V2 installed: $(docker compose version --short 2>/dev/null)"
+    else
+        ui_warn "Docker Compose V2 plugin installed but not yet active — please check manually"
+    fi
+}
+
+# Configure Docker daemon registry mirrors when NETWORK_CHINA=1.
+# Writes /etc/docker/daemon.json; completely replaces registry-mirrors key.
+_configure_docker_mirror() {
+    if [[ "${NETWORK_CHINA:-0}" != "1" ]]; then
+        return 0
+    fi
+    if [[ "$DRY_RUN" == "1" ]]; then
+        ui_info "[dry-run] Would configure Docker daemon mirrors for China"
+        return 0
+    fi
+
+    local daemon_json="/etc/docker/daemon.json"
+    local mirrors_json='["https://docker.m.daocloud.io","https://hub-mirror.c.163.com","https://mirror.baidubce.com"]'
+
+    ui_info "Configuring Docker daemon registry mirrors (China)..."
+    ${SUDO} mkdir -p /etc/docker
+
+    # Merge into existing config preserving other keys, then overwrite registry-mirrors.
+    # Note: node -e uses double-quoted string so shell variables expand correctly.
+    local tmp_cfg
+    tmp_cfg="$(mktemp)"
+    if [[ -f "$daemon_json" ]]; then
+        node -e "
+            const fs = require('fs');
+            let cfg = {};
+            try { cfg = JSON.parse(fs.readFileSync('${daemon_json}', 'utf8')); } catch (e) {}
+            cfg['registry-mirrors'] = ${mirrors_json};
+            fs.writeFileSync('${tmp_cfg}', JSON.stringify(cfg, null, 2) + '\\n');
+        " 2>/dev/null || printf '{"registry-mirrors":%s}\n' "${mirrors_json}" > "$tmp_cfg"
+    else
+        printf '{"registry-mirrors":%s}\n' "${mirrors_json}" > "$tmp_cfg"
+    fi
+    ${SUDO} cp "$tmp_cfg" "$daemon_json"
+    rm -f "$tmp_cfg"
+
+    # Reload daemon to apply new config
+    if command -v systemctl &>/dev/null; then
+        ${SUDO} systemctl daemon-reload 2>/dev/null || true
+        ${SUDO} systemctl restart docker 2>/dev/null || true
+        sleep 2
+    fi
+    ui_success "Docker daemon mirrors configured: daocloud.io, 163.com, baidubce.com"
+}
+
+_ensure_docker_running() {
+    if [[ "$DRY_RUN" == "1" ]]; then
+        return 0
+    fi
+
+    if [[ "$OS" == "macos" ]]; then
+        local waited=0
+        while ! docker info &>/dev/null 2>&1; do
+            if [[ $waited -ge 15 ]]; then
+                ui_warn "Docker daemon did not become ready within 15 seconds"
+                ui_info "Make sure Docker Desktop is open and running"
+                return 1
+            fi
+            sleep 1
+            (( waited++ )) || true
+        done
+        [[ $waited -lt 15 ]] && ui_success "Docker daemon is ready"
+        return 0
+    fi
+
+    if command -v systemctl &>/dev/null; then
+        # Reset any failed state left by previous install attempts
+        ${SUDO} systemctl reset-failed docker.socket docker.service 2>/dev/null || true
+
+        # Start socket-activated unit first (prevents "dependency failed" errors)
+        if ! systemctl is-active --quiet docker.socket 2>/dev/null; then
+            ui_info "Starting Docker socket..."
+            run_sudo systemctl start docker.socket 2>/dev/null || true
+            sleep 1
+        fi
+
+        if ! systemctl is-active --quiet docker 2>/dev/null; then
+            ui_info "Starting Docker service..."
+            if ! ${SUDO} systemctl start docker; then
+                ui_error "Failed to start Docker service — check: sudo journalctl -xe"
+            else
+                ui_success "Docker service started"
+            fi
+        fi
+        if ! systemctl is-enabled --quiet docker 2>/dev/null; then
+            ui_info "Enabling Docker on startup..."
+            ${SUDO} systemctl enable docker 2>/dev/null || true
+        fi
+        if ! systemctl is-enabled --quiet docker.socket 2>/dev/null; then
+            ${SUDO} systemctl enable docker.socket 2>/dev/null || true
+        fi
+
+        # Wait up to 15s for Docker daemon to be ready to accept connections
+        local waited=0
+        while ! ${SUDO} docker info &>/dev/null 2>&1; do
+            if [[ $waited -ge 15 ]]; then
+                ui_warn "Docker daemon did not become ready within 15 seconds"
+                break
+            fi
+            sleep 1
+            (( waited++ )) || true
+        done
+        [[ $waited -lt 15 ]] && ui_success "Docker daemon is ready"
+    else
+        if ! ${SUDO} service docker status &>/dev/null; then
+            ui_info "Starting Docker service..."
+            run_sudo service docker start || true
+        fi
+    fi
+}
+
+_ensure_docker_group() {
+    if [[ "$DRY_RUN" == "1" || $EUID -eq 0 || "$OS" == "macos" ]]; then
+        return 0
+    fi
+
+    # Always operate on the real (non-root) user — not whoami, which may return
+    # "root" when the script was launched with "sudo bash install.sh".
+    local user="${REAL_USER:-$(id -un)}"
+
+    # Ensure docker group exists (may be missing when Docker was installed differently)
+    if ! getent group docker &>/dev/null 2>&1; then
+        ui_info "Creating docker group..."
+        run_sudo groupadd docker 2>/dev/null || true
+    fi
+
+    # Use getent to check group membership rather than the shell-builtin `groups`
+    # command, which reflects the login-session groups and may not include groups
+    # added earlier in the same install run (especially under sudo).
+    if ! getent group docker 2>/dev/null | grep -qw "${user}"; then
+        ui_info "Adding ${user} to the docker group..."
+        if ${SUDO} usermod -aG docker "${user}"; then
+            ui_success "User ${user} added to docker group"
+        else
+            ui_warn "Failed to add ${user} to docker group — run manually: sudo usermod -aG docker ${user}"
+        fi
+        DOCKER_GROUP_JUST_ADDED=1
+    else
+        ui_info "User ${user} is already in the docker group"
+    fi
+
+    # Check if docker is already accessible directly
+    if docker info &>/dev/null 2>&1; then
+        return 0
+    fi
+
+    # Try activating the docker group for the current session via "sg docker"
+    # This avoids requiring the user to log out and back in within the same install run
+    if command -v sg &>/dev/null 2>/dev/null && sg docker -c "docker info" &>/dev/null 2>&1; then
+        DOCKER_CMD_PREFIX="sg docker -c"
+        ui_success "Docker group activated for this session (via 'sg docker')"
+        ui_info "Future terminals will have Docker access automatically"
+        return 0
+    fi
+
+    # sg docker failed or unavailable — try ACL grant on the docker socket
+    # (requires the 'acl' package; harmless if absent)
+    if command -v setfacl &>/dev/null 2>&1 && [[ -S /var/run/docker.sock ]]; then
+        ui_info "Trying ACL grant on /var/run/docker.sock for ${user} ..."
+        if ${SUDO} setfacl -m "user:${user}:rw" /var/run/docker.sock 2>/dev/null; then
+            if docker info &>/dev/null 2>&1; then
+                ui_success "Docker access granted via socket ACL (current session)"
+                ui_info "Future terminals will have Docker access automatically (group membership active on next login)"
+                return 0
+            fi
+        fi
+    fi
+
+    # Last resort — fall back to sudo docker for this session
+    # This ensures OpenClaw image pull can proceed without requiring re-login
+    DOCKER_USE_SUDO=1
+    if [[ "${DOCKER_GROUP_JUST_ADDED:-0}" == "1" ]]; then
+        ui_warn "Docker group assigned but not yet active in this shell session."
+        ui_warn "Please log out and log back in (or run: newgrp docker) for group membership to take effect."
+    fi
+    ui_info "Using 'sudo docker' for this session; future terminals will have direct access."
+}
+
+# Run a docker command, with automatic fallback priority:
+#   1. "sg docker -c"  — group activated in-session (DOCKER_CMD_PREFIX set)
+#   2. sudo docker     — sudo fallback when group not yet active (DOCKER_USE_SUDO=1)
+#   3. docker          — direct access (group already active or running as root)
+#
+# Usage:  docker_exec info
+#         docker_exec pull image:tag
+#         docker_exec image inspect tag
+docker_exec() {
+    if [[ -n "${DOCKER_CMD_PREFIX:-}" ]]; then
+        # sg docker -c expects a single string argument
+        ${DOCKER_CMD_PREFIX} "docker $*"
+    elif [[ "${DOCKER_USE_SUDO:-0}" == "1" ]]; then
+        ${SUDO} docker "$@"
+    else
+        docker "$@"
+    fi
+}
+
+# ─── 3. Nomad ────────────────────────────────────────────────────────────────
+
+install_nomad() {
+    ui_stage "Nomad"
+
+    local local_bin="${JISHUSHELL_BIN_DIR}/nomad"
+
+    # In China, skip the HashiCorp apt/yum repo (GPG key download is unreliable)
+    # and go straight to the binary download fallback.
+    if [[ "${NETWORK_CHINA:-0}" == "1" ]]; then
+        ui_info "China network — skipping HashiCorp repo, using binary download directly"
+        _install_nomad_binary || return 1
+        _ensure_jishushell_bin_in_path
+        start_nomad
+        install_nomad_systemd
+        return 0
+    fi
+
+    # ── 1. Check local user-space install ────────────────────────────────────
+    if [[ -e "$local_bin" ]]; then
+        if [[ ! -f "$local_bin" ]]; then
+            ui_warn "Path ${local_bin} exists but is not a regular file — removing..."
+            rm -rf "$local_bin" 2>/dev/null || true
+        elif [[ ! -x "$local_bin" ]]; then
+            ui_warn "Nomad found at ${local_bin} but is not executable — fixing permissions..."
+            if ! chmod 755 "$local_bin" 2>/dev/null; then
+                ui_warn "Could not fix permissions — removing and reinstalling"
+                rm -f "$local_bin"
+            fi
+        fi
+
+        if [[ -x "$local_bin" ]]; then
+            local current_version
+            current_version="$("$local_bin" version 2>/dev/null | head -n1 | extract_semver || echo "")"
+
+            if [[ -z "$current_version" ]]; then
+                ui_warn "Nomad at ${local_bin} is not functional (wrong arch or corrupt) — reinstalling..."
+                rm -f "$local_bin"
+            elif version_gte "$current_version" "$NOMAD_VERSION"; then
+                ui_success "Nomad already installed: v${current_version} → ${local_bin}"
+                _ensure_jishushell_bin_in_path
+                return 0
+            else
+                ui_warn "Nomad version too old: v${current_version} (need >= v${NOMAD_VERSION}) — upgrading..."
+                rm -f "$local_bin"
+            fi
+        fi
+    fi
+
+    # ── 2. Check system nomad (informational only) ────────────────────────────
+    if [[ ! -e "$local_bin" ]] && command -v nomad &>/dev/null; then
+        local sys_ver
+        sys_ver="$(nomad version 2>/dev/null | head -n1 | extract_semver || echo "?")"
+        ui_info "System Nomad found (v${sys_ver}) — installing local copy to ${local_bin} for JishuShell..."
+    else
+        ui_info "Installing Nomad v${NOMAD_VERSION} to ${local_bin}..."
+    fi
+
+    _do_install_nomad
+}
+
+_do_install_nomad() {
+    if [[ "$DRY_RUN" == "1" ]]; then
+        ui_info "[dry-run] Would install Nomad v${NOMAD_VERSION} to ${JISHUSHELL_BIN_DIR}/nomad"
+        ui_info "[dry-run] Would add ${JISHUSHELL_BIN_DIR} to PATH in shell configs"
+        return 0
+    fi
+
+    # Install directly to ~/.jishushell/bin — no sudo required
+    _install_nomad_binary
+}
+
+_install_nomad_via_repo() {
+    case "$PKG_MANAGER" in
+        apt)
+            if ! pkg_install gpg; then
+                return 1
+            fi
+
+            local keyring="/usr/share/keyrings/hashicorp-archive-keyring.gpg"
+            if [[ ! -f "$keyring" ]]; then
+                ui_info "Adding HashiCorp GPG key..."
+                if ! retry_net "Download HashiCorp GPG key" 3 bash -c "curl -fsSL https://apt.releases.hashicorp.com/gpg | ${SUDO} gpg --dearmor -o '$keyring' 2>/dev/null"; then
+                    return 1
+                fi
+            fi
+
+            local sources_file="/etc/apt/sources.list.d/hashicorp.list"
+            if [[ ! -f "$sources_file" ]]; then
+                ui_info "Adding HashiCorp APT repository..."
+                echo "deb [signed-by=${keyring}] https://apt.releases.hashicorp.com $(lsb_release -cs 2>/dev/null || echo stable) main" | \
+                    ${SUDO} tee "$sources_file" >/dev/null
+            fi
+
+            wait_for_apt_lock
+            run_sudo apt-get update
+            run_sudo apt-get install -y nomad
+            ;;
+        dnf|yum)
+            local repo_file="/etc/yum.repos.d/hashicorp.repo"
+            if [[ ! -f "$repo_file" ]]; then
+                ui_info "Adding HashiCorp YUM repository..."
+                ${SUDO} tee "$repo_file" >/dev/null <<'REPO'
+[hashicorp]
+name=HashiCorp Stable - $basearch
+baseurl=https://rpm.releases.hashicorp.com/RHEL/$releasever/$basearch/stable
+enabled=1
+gpgcheck=1
+gpgkey=https://rpm.releases.hashicorp.com/gpg
+REPO
+            fi
+
+            run_sudo "$PKG_MANAGER" install -y nomad
+            ;;
+        *)
+            return 1
+            ;;
+    esac
+
+    if command -v nomad &>/dev/null; then
+        local ver
+        ver="$(nomad version 2>/dev/null | head -n1 | extract_semver || echo "unknown")"
+        ui_success "Nomad installed (via system package): v${ver}"
+        return 0
+    fi
+
+    return 1
+}
+
+_install_nomad_binary() {
+    local dest="${JISHUSHELL_BIN_DIR}/nomad"
+
+    # Ensure destination directory exists (no sudo needed — it's in $HOME)
+    if ! mkdir -p "${JISHUSHELL_BIN_DIR}"; then
+        ui_error "Failed to create directory: ${JISHUSHELL_BIN_DIR}"
+        return 1
+    fi
+
+    # Remove stale/non-executable leftover
+    if [[ -e "$dest" && ! -x "$dest" ]]; then
+        ui_warn "Removing non-executable Nomad binary at ${dest}"
+        rm -f "$dest" 2>/dev/null || true
+    fi
+
+    local platform
+    platform="$(uname -s | tr '[:upper:]' '[:lower:]')"
+    local download_url="https://releases.hashicorp.com/nomad/${NOMAD_VERSION}/nomad_${NOMAD_VERSION}_${platform}_${ARCH}.zip"
+    local tmp_dir
+    tmp_dir="$(mktemp -d)"
+
+    ui_info "Downloading Nomad v${NOMAD_VERSION} (${platform}/${ARCH})..."
+
+    if ! retry_net "Download Nomad binary" 3 curl -fsSL "$download_url" -o "${tmp_dir}/nomad.zip"; then
+        ui_error "Failed to download Nomad: $download_url"
+        rm -rf "$tmp_dir"
+        return 1
+    fi
+
+    local checksums_url="https://releases.hashicorp.com/nomad/${NOMAD_VERSION}/nomad_${NOMAD_VERSION}_SHA256SUMS"
+    if retry_net "Download Nomad checksums" 3 curl -fsSL "$checksums_url" -o "${tmp_dir}/SHA256SUMS" 2>/dev/null; then
+        local expected_hash
+        expected_hash="$(grep "nomad_${NOMAD_VERSION}_${platform}_${ARCH}.zip" "${tmp_dir}/SHA256SUMS" | awk '{print $1}')"
+        if [[ -n "$expected_hash" ]]; then
+            local actual_hash
+            if command -v sha256sum &>/dev/null; then
+                actual_hash="$(sha256sum "${tmp_dir}/nomad.zip" | awk '{print $1}')"
+            else
+                actual_hash="$(shasum -a 256 "${tmp_dir}/nomad.zip" | awk '{print $1}')"
+            fi
+            if [[ "$expected_hash" != "$actual_hash" ]]; then
+                ui_error "Nomad checksum mismatch — download may have been tampered with!"
+                ui_error "  Expected: $expected_hash"
+                ui_error "  Got:      $actual_hash"
+                rm -rf "$tmp_dir"
+                return 1
+            fi
+            ui_info "Checksum verified ✓"
+        fi
+    else
+        ui_error "Could not download Nomad checksum file — aborting installation for security"
+        ui_error "If this is a network issue, retry. To skip verification (not recommended), use --skip-verify."
+        rm -rf "$tmp_dir"
+        return 1
+    fi
+
+    if ! command -v unzip &>/dev/null; then
+        ui_info "Installing unzip..."
+        pkg_install unzip
+    fi
+
+    if ! unzip -o "${tmp_dir}/nomad.zip" nomad -d "${tmp_dir}" >/dev/null 2>&1; then
+        # Fallback: extract all (some zips don't support file-specific extraction)
+        if ! unzip -o "${tmp_dir}/nomad.zip" -d "${tmp_dir}" >/dev/null 2>&1; then
+            ui_error "Failed to extract Nomad archive"
+            rm -rf "$tmp_dir"
+            return 1
+        fi
+    fi
+
+    if [[ ! -f "${tmp_dir}/nomad" ]]; then
+        ui_error "Nomad binary not found in downloaded archive"
+        rm -rf "$tmp_dir"
+        return 1
+    fi
+
+    # Atomic install: write to temp name then rename to avoid partial reads during install
+    local dest_tmp="${dest}.tmp.$$"
+    if ! cp "${tmp_dir}/nomad" "$dest_tmp"; then
+        ui_error "Failed to copy Nomad binary to ${JISHUSHELL_BIN_DIR}"
+        rm -rf "$tmp_dir" "$dest_tmp" 2>/dev/null || true
+        return 1
+    fi
+    chmod 755 "$dest_tmp"
+    if ! mv -f "$dest_tmp" "$dest"; then
+        ui_error "Failed to move Nomad binary to ${dest}"
+        rm -f "$dest_tmp" 2>/dev/null || true
+        rm -rf "$tmp_dir"
+        return 1
+    fi
+    rm -rf "$tmp_dir"
+
+    # Verify the installed binary is executable and actually runs
+    if [[ ! -x "$dest" ]]; then
+        ui_error "Nomad binary at ${dest} is not executable after install"
+        return 1
+    fi
+
+    local installed_version
+    installed_version="$("$dest" version 2>/dev/null | head -n1 | extract_semver || echo "")"
+    if [[ -z "$installed_version" ]]; then
+        ui_error "Nomad binary at ${dest} does not run — possibly wrong architecture (${ARCH})"
+        rm -f "$dest" 2>/dev/null || true
+        return 1
+    fi
+
+    _ensure_jishushell_bin_in_path
+    ui_success "Nomad installed: v${installed_version} → ${dest}"
+}
+
+# Add ~/.jishushell/bin to PATH in shell startup files and current session
+_ensure_jishushell_bin_in_path() {
+    local bin_dir="${JISHUSHELL_BIN_DIR}"
+    local marker="# jishushell-bin-path"
+    local init_line="export PATH=\"${bin_dir}:\$PATH\""
+
+    # Export for the current running shell immediately
+    export PATH="${bin_dir}:${PATH}"
+
+    if [[ "$DRY_RUN" == "1" ]]; then
+        ui_info "[dry-run] Would add ${bin_dir} to PATH in shell startup files"
+        return 0
+    fi
+
+    local rc_files=("$HOME/.bashrc" "$HOME/.bash_profile" "$HOME/.profile" "$HOME/.zshrc")
+    local added=0
+    for rc in "${rc_files[@]}"; do
+        if [[ -f "$rc" ]] && ! grep -qF "$marker" "$rc" 2>/dev/null; then
+            printf '\n%s\n%s\n' "$marker" "$init_line" >> "$rc"
+            ui_info "Added ${bin_dir} to PATH in ${rc}"
+            added=1
+        fi
+    done
+
+    if [[ $added -eq 0 ]]; then
+        ui_info "JishuShell bin PATH already configured"
+    fi
+    ui_info "Tip: run 'source ~/.bashrc' or open a new terminal to activate PATH"
+}
+
+# Check if a TCP port is in LISTEN state (cross-platform: Linux ss, macOS lsof)
+_port_is_listening() {
+    local port="$1"
+    if command -v ss &>/dev/null; then
+        ss -tlnp 2>/dev/null | grep -q ":${port} "
+    elif command -v lsof &>/dev/null; then
+        lsof -iTCP:"${port}" -sTCP:LISTEN &>/dev/null 2>&1
+    else
+        nc -z 127.0.0.1 "${port}" &>/dev/null 2>&1
+    fi
+}
+
+# Write nomad.hcl if it does not already exist.
+# Safe to call multiple times — never overwrites an existing config.
+_ensure_nomad_hcl() {
+    local nomad_config_dir="${JISHUSHELL_HOME}/nomad"
+    local nomad_data_dir="${JISHUSHELL_HOME}/nomad/data"
+    local nomad_alloc_dir="${JISHUSHELL_HOME}/nomad/data/alloc"
+    local config_file="${nomad_config_dir}/nomad.hcl"
+
+    [[ -f "$config_file" ]] && return 0
+
+    mkdir -p "$nomad_config_dir" "$nomad_data_dir" "$nomad_alloc_dir"
+    # Dirs are created by the current user — no sudo needed
+    chown -R "${REAL_USER}:${REAL_GID:-${REAL_USER}}" "${JISHUSHELL_HOME}" 2>/dev/null || true
+
+    cat > "$config_file" << NOMAD_HCL
+data_dir = "${nomad_data_dir}"
+
+bind_addr = "127.0.0.1"
+
+leave_on_terminate = false
+
+advertise {
+  http = "127.0.0.1"
+  rpc  = "127.0.0.1"
+  serf = "127.0.0.1"
+}
+
+server {
+  enabled = true
+  bootstrap_expect = 1
+}
+
+client {
+  enabled = true
+  servers = ["127.0.0.1:4647"]
+  alloc_dir = "${nomad_alloc_dir}"
+
+  drain_on_shutdown {
+    deadline           = "30s"
+    force              = true
+    ignore_system_jobs = true
+  }
+}
+
+plugin "docker" {
+  config {
+    disable_log_collection = true
+    volumes {
+      enabled = true
+    }
+  }
+}
+
+acl {
+  enabled = true
+}
+NOMAD_HCL
+}
+
+# Start Nomad agent (matches setup-manager.ts startNomad())
+start_nomad() {
+    local nomad_bin="${JISHUSHELL_BIN_DIR}/nomad"
+    local nomad_config_dir="${JISHUSHELL_HOME}/nomad"
+    local config_file="${nomad_config_dir}/nomad.hcl"
+
+    # Check if already running (port 4646)
+    if _port_is_listening 4646; then
+        ui_success "Nomad is already running on port 4646"
+        return 0
+    fi
+
+    if [[ "$DRY_RUN" == "1" ]]; then
+        ui_info "[dry-run] Would write ${config_file} and start nomad agent"
+        return 0
+    fi
+
+    # On Linux with systemd: the single path for starting Nomad.
+    # First kill any stale non-systemd Nomad processes that may hold the port.
+    if command -v systemctl &>/dev/null && systemctl is-enabled nomad &>/dev/null 2>&1; then
+        local stale_pids
+        stale_pids="$(pgrep -f 'nomad agent' 2>/dev/null || true)"
+        if [[ -n "$stale_pids" ]]; then
+            local systemd_pid
+            systemd_pid="$(systemctl show nomad --property=MainPID --value 2>/dev/null || echo "")"
+            local pid
+            for pid in $stale_pids; do
+                if [[ "$pid" != "$systemd_pid" ]]; then
+                    ui_info "Killing stale Nomad process (PID ${pid}) before systemd start..."
+                    kill "$pid" 2>/dev/null || true
+                fi
+            done
+            sleep 1
+        fi
+
+        ui_info "Starting Nomad via systemd..."
+        ${SUDO} systemctl start nomad 2>/dev/null || true
+        local i
+        for i in $(seq 1 30); do
+            sleep 1
+            if _port_is_listening 4646; then
+                ui_success "Nomad started (systemd)"
+                return 0
+            fi
+        done
+        ui_warn "Nomad did not start within 30s — port 4646 not listening"
+        ui_info "Check: sudo journalctl -u nomad -n 30"
+        return 1
+    fi
+
+    # On macOS with launchd: plist is already loaded with RunAtLoad=true, so launchd
+    # started Nomad. Just wait for the port — do NOT spawn a competing nohup process.
+    local plist_path="${HOME}/Library/LaunchAgents/com.jishushell.nomad.plist"
+    if [[ "$OS" == "macos" ]] && [[ -f "$plist_path" ]]; then
+        ui_info "Waiting for Nomad (launchd)..."
+        local i
+        for i in $(seq 1 30); do
+            sleep 1
+            if _port_is_listening 4646; then
+                ui_success "Nomad started"
+                return 0
+            fi
+        done
+        ui_warn "Nomad did not start within 30s — port 4646 not listening"
+        ui_info "Check log: ${JISHUSHELL_HOME}/nomad/nomad.log"
+        return 1
+    fi
+
+    # Fallback: non-systemd environments (minimal containers without launchd).
+    _ensure_nomad_hcl
+
+    ui_info "Starting Nomad agent..."
+    local log_path="${nomad_config_dir}/nomad.log"
+    # Run as the current (non-root) user — Nomad only binds to 127.0.0.1:4646/4647/4648
+    # (non-privileged ports), and all data dirs live under ~/.jishushell/, so root is not needed.
+    nohup "${nomad_bin}" agent -config="${config_file}" > "${log_path}" 2>&1 &
+
+    local i
+    for i in $(seq 1 30); do
+        sleep 1
+        if _port_is_listening 4646; then
+            ui_success "Nomad started"
+            return 0
+        fi
+    done
+
+    ui_warn "Nomad did not start within 30s — port 4646 not listening"
+    ui_info "Check log: ${log_path}"
+    return 1
+}
+
+# Install Nomad as a system service (systemd on Linux, launchd on macOS)
+install_nomad_systemd() {
+    local nomad_bin="${JISHUSHELL_BIN_DIR}/nomad"
+    local nomad_config_dir="${JISHUSHELL_HOME}/nomad"
+    local config_file="${nomad_config_dir}/nomad.hcl"
+
+    if [[ "$OS" == "macos" ]]; then
+        _install_nomad_launchd
+        return $?
+    fi
+
+    if [[ "$(uname -s)" != "Linux" ]]; then
+        return 0
+    fi
+
+    if [[ "$DRY_RUN" == "1" ]]; then
+        ui_info "[dry-run] Would install /etc/systemd/system/nomad.service"
+        return 0
+    fi
+
+    _ensure_nomad_hcl
+
+    local service_content="[Unit]
+Description=Nomad Agent
+After=network-online.target docker.service
+Wants=network-online.target
+
+[Service]
+User=${REAL_USER}
+SupplementaryGroups=docker
+Type=simple
+EnvironmentFile=-/etc/jishushell/nomad.env
+ExecStart=${nomad_bin} agent -config=${config_file}
+Restart=on-failure
+RestartSec=3
+ProtectSystem=full
+PrivateTmp=true
+NoNewPrivileges=true
+
+[Install]
+WantedBy=multi-user.target"
+
+    # Only update the service file if it changed (avoids unnecessary restarts)
+    local svc_path="/etc/systemd/system/nomad.service"
+    local need_reload=0
+    if [[ ! -f "$svc_path" ]] || ! echo "$service_content" | diff -q - "$svc_path" &>/dev/null; then
+        ${SUDO} mkdir -p /etc/jishushell
+        echo "$service_content" > /tmp/nomad.service.$$
+        ${SUDO} mv /tmp/nomad.service.$$ "$svc_path"
+        need_reload=1
+    fi
+
+    # Ensure Nomad data dirs are owned by the real user before the service starts
+    chown -R "${REAL_USER}:${REAL_GID:-${REAL_USER}}" "${JISHUSHELL_HOME}" 2>/dev/null || true
+
+    if [[ $need_reload -eq 1 ]]; then
+        ${SUDO} systemctl daemon-reload
+    fi
+
+    # Enable but do NOT start here — start_nomad() handles startup + waiting.
+    # This avoids double-waiting (install_nomad_systemd 15s + start_nomad 30s).
+    if ! systemctl is-enabled nomad &>/dev/null 2>&1; then
+        ${SUDO} systemctl enable nomad 2>/dev/null || \
+            ui_warn "Could not enable nomad systemd service — Nomad may not auto-start on reboot"
+    fi
+}
+
+_install_nomad_launchd() {
+    local nomad_bin="${JISHUSHELL_BIN_DIR}/nomad"
+    local nomad_config_dir="${JISHUSHELL_HOME}/nomad"
+    local config_file="${nomad_config_dir}/nomad.hcl"
+    local plist_label="com.jishushell.nomad"
+    local plist_path="${HOME}/Library/LaunchAgents/${plist_label}.plist"
+    local log_path="${nomad_config_dir}/nomad.log"
+
+    if [[ "$DRY_RUN" == "1" ]]; then
+        ui_info "[dry-run] Would install launchd agent: ${plist_path}"
+        return 0
+    fi
+
+    mkdir -p "${HOME}/Library/LaunchAgents"
+
+    local docker_sock="${HOME}/.docker/run/docker.sock"
+    if [[ ! -S "$docker_sock" ]]; then
+        docker_sock="/var/run/docker.sock"
+    fi
+
+    cat > "$plist_path" << PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${plist_label}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${nomad_bin}</string>
+        <string>agent</string>
+        <string>-config=${config_file}</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>DOCKER_HOST</key>
+        <string>unix://${docker_sock}</string>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+    </dict>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>${log_path}</string>
+    <key>StandardErrorPath</key>
+    <string>${log_path}</string>
+</dict>
+</plist>
+PLIST
+
+    _ensure_nomad_hcl
+
+    launchctl unload "$plist_path" 2>/dev/null || true
+    if launchctl load -w "$plist_path" 2>/dev/null; then
+        ui_success "Nomad launchd agent installed and started"
+    else
+        ui_warn "Could not load nomad launchd agent"
+    fi
+}
+
+# ─── 4. OpenClaw (docker pull official image) ─────────────────────────────────
+# For Docker mode: pull the official OpenClaw image from ghcr.io.
+# For non-Docker modes (process manager / raw_exec): npm install as before.
+
+_save_openclaw_image_to_panel() {
+    local image="$1"
+    local panel_file="${JISHUSHELL_HOME}/panel.json"
+    node -e "
+const fs = require('fs');
+const p = '${panel_file}';
+let cfg = {};
+try { cfg = JSON.parse(fs.readFileSync(p, 'utf8')); } catch {}
+cfg.openclaw_image = '${image}';
+fs.mkdirSync(require('path').dirname(p), { recursive: true });
+fs.writeFileSync(p, JSON.stringify(cfg, null, 2));
+" 2>/dev/null || true
+}
+
+_read_openclaw_image_from_panel() {
+    local panel_file="${JISHUSHELL_HOME}/panel.json"
+    node -e "
+const fs = require('fs');
+const p = '${panel_file}';
+try {
+  const cfg = JSON.parse(fs.readFileSync(p, 'utf8'));
+  if (typeof cfg.openclaw_image === 'string' && cfg.openclaw_image.trim()) {
+    process.stdout.write(cfg.openclaw_image.trim());
+  }
+} catch {}
+" 2>/dev/null || true
+}
+
+# Install OpenClaw npm package on the host (for process manager / raw_exec modes).
+# Skipped when using official Docker image.
+_install_openclaw_npm() {
+    local pkg_dir="${JISHUSHELL_HOME}/packages/openclaw"
+
+    local local_bin="${pkg_dir}/bin/openclaw"
+    local local_pkg="${pkg_dir}/lib/node_modules/openclaw/package.json"
+    local _need_install=0
+    if [[ -f "$local_bin" ]]; then
+        local current_ver
+        current_ver="$(node -p "require('${local_pkg}').version" 2>/dev/null || echo "")"
+        if [[ "${OPENCLAW_NPM_VERSION}" != "latest" && "${current_ver}" != "${OPENCLAW_NPM_VERSION}" ]]; then
+            ui_info "OpenClaw installed version (v${current_ver:-unknown}) differs from requested (${OPENCLAW_NPM_VERSION}) — reinstalling..."
+            _need_install=1
+        else
+            ui_success "OpenClaw npm package already installed: v${current_ver:-unknown}"
+        fi
+    else
+        _need_install=1
+    fi
+    if [[ "$_need_install" == "1" ]]; then
+        if ! command -v npm &>/dev/null; then
+            ui_error "npm not found — install Node.js first"
+            return 1
+        fi
+        ui_info "Installing OpenClaw npm package (openclaw@${OPENCLAW_NPM_VERSION})..."
+        local _oc_registry=""
+        if [[ "${NETWORK_CHINA:-0}" == "1" ]]; then
+            _oc_registry="--registry https://registry.npmmirror.com"
+            ui_info "China network — using Alibaba npm registry (npmmirror.com)"
+        fi
+        mkdir -p "$pkg_dir"
+        log_detail ""
+        log_detail "[$(date '+%H:%M:%S')] npm install -g --prefix ${pkg_dir} openclaw@${OPENCLAW_NPM_VERSION}${_oc_registry:+ ${_oc_registry}}"
+        # shellcheck disable=SC2086
+        if ! retry_net "npm install -g --prefix openclaw@${OPENCLAW_NPM_VERSION}" 3 \
+            log_cmd env -u npm_config_global -u npm_config_prefix -u npm_config_location \
+                npm install -g --prefix "$pkg_dir" ${_oc_registry} "openclaw@${OPENCLAW_NPM_VERSION}"; then
+            ui_error "Failed to install OpenClaw npm package"
+            return 1
+        fi
+    fi
+}
+
+install_openclaw() {
+    ui_stage "OpenClaw"
+
+    if [[ "${SKIP_OPENCLAW}" == "1" ]]; then
+        ui_info "Skipped (--skip-openclaw / default)"
+        return 0
+    fi
+
+    if ! command -v docker &>/dev/null; then
+        ui_error "Docker is not installed — cannot build OpenClaw image"
+        return 1
+    fi
+
+    if [[ "$DRY_RUN" == "1" ]]; then
+        ui_info "[dry-run] Would: npm install -g --prefix openclaw@${OPENCLAW_NPM_VERSION}"
+        ui_info "[dry-run] Would: docker build -t jishushell-openclaw:<version> (npm package + Python)"
+        return 0
+    fi
+
+    # ── Step 1: Install OpenClaw npm package (used as docker build context) ──
+    _install_openclaw_npm || return 1
+
+    # Resolve versioned tag from installed package (e.g. jishushell-openclaw:2026.3.31)
+    local pkg_dir="${JISHUSHELL_HOME}/packages/openclaw"
+    local oc_ver
+    oc_ver="$(node -p "require('${pkg_dir}/lib/node_modules/openclaw/package.json').version" 2>/dev/null || echo "")"
+    local docker_tag="${OPENCLAW_DOCKER_TAG}"
+    if [[ -n "$oc_ver" ]]; then
+        docker_tag="jishushell-openclaw:${oc_ver}"
+    fi
+    local configured_tag=""
+
+    # ── Step 2: Ensure Docker daemon is accessible ────────────────────────────
+    if ! docker_exec info &>/dev/null 2>&1; then
+        if command -v sg &>/dev/null 2>/dev/null && sg docker -c "docker info" &>/dev/null 2>&1; then
+            DOCKER_CMD_PREFIX="sg docker -c"
+            ui_info "Docker group activated via 'sg docker'"
+        elif ${SUDO} docker info &>/dev/null 2>&1; then
+            DOCKER_USE_SUDO=1
+            ui_info "Using 'sudo docker' (docker group not yet active in this shell)"
+        else
+            ui_warn "Docker daemon is not reachable"
+            if [[ "$OS" == "macos" ]]; then
+                ui_warn "Make sure Docker Desktop is running"
+            else
+                ui_warn "Ensure Docker is running: sudo systemctl start docker"
+            fi
+            return 1
+        fi
+    fi
+
+    # ── Step 3: Reuse the currently configured image when it already exists
+    # locally. This keeps repeated installs idempotent and avoids rebuilding
+    # when panel.json already points at a valid pinned image.
+    configured_tag="$(_read_openclaw_image_from_panel)"
+    if [[ -n "${configured_tag}" ]] && docker_exec image inspect "${configured_tag}" &>/dev/null 2>&1; then
+        OPENCLAW_IMAGE="${configured_tag}"
+        ui_success "Docker image ${configured_tag} already exists — reusing configured image"
+        return 0
+    fi
+
+    # ── Step 4: Skip if the requested build tag already exists ───────────────
+    if docker_exec image inspect "${docker_tag}" &>/dev/null 2>&1; then
+        OPENCLAW_IMAGE="${docker_tag}"
+        _save_openclaw_image_to_panel "${docker_tag}"
+        ui_success "Docker image ${docker_tag} already exists — skipping"
+        return 0
+    fi
+
+    # ── Step 5: Build Docker image (npm package + Python) ────────────────────
+    local pkg_dir="${JISHUSHELL_HOME}/packages/openclaw"
+
+    # Write Dockerfile into the npm package directory (build context)
+    # When NETWORK_CHINA=1, inject Alibaba apt mirror before apt-get update
+    if [[ "${NETWORK_CHINA:-0}" == "1" ]]; then
+        ui_info "China network — injecting Alibaba apt mirror into Dockerfile"
+        cat > "${pkg_dir}/Dockerfile" << 'DOCKERFILE'
+FROM node:22-slim
+USER root
+RUN sed -i 's/deb.debian.org/mirrors.aliyun.com/g; s/security.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debian.sources 2>/dev/null || \
+    sed -i 's/deb.debian.org/mirrors.aliyun.com/g; s/security.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list 2>/dev/null || true
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    procps hostname curl git lsof openssl \
+    python3 python3-pip python3-venv python3-dev && \
+    ln -sf /usr/bin/python3 /usr/local/bin/python && \
+    rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+COPY --chown=node:node lib/node_modules/ ./node_modules/
+RUN ln -sf /app/node_modules/openclaw/openclaw.mjs /app/openclaw.mjs && \
+    ln -sf /app/node_modules/openclaw/openclaw.mjs /usr/local/bin/openclaw && \
+    cp /app/node_modules/openclaw/package.json /app/package.json 2>/dev/null || true
+USER node
+CMD ["node", "openclaw.mjs", "gateway", "--allow-unconfigured"]
+DOCKERFILE
+    else
+        cat > "${pkg_dir}/Dockerfile" << 'DOCKERFILE'
+FROM node:22-slim
+USER root
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    procps hostname curl git lsof openssl \
+    python3 python3-pip python3-venv python3-dev && \
+    ln -sf /usr/bin/python3 /usr/local/bin/python && \
+    rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+COPY --chown=node:node lib/node_modules/ ./node_modules/
+RUN ln -sf /app/node_modules/openclaw/openclaw.mjs /app/openclaw.mjs && \
+    ln -sf /app/node_modules/openclaw/openclaw.mjs /usr/local/bin/openclaw && \
+    cp /app/node_modules/openclaw/package.json /app/package.json 2>/dev/null || true
+USER node
+CMD ["node", "openclaw.mjs", "gateway", "--allow-unconfigured"]
+DOCKERFILE
+    fi
+
+    ui_info "Building Docker image: ${docker_tag} (npm package + Python)..."
+    log_detail ""
+    log_detail "[$(date '+%H:%M:%S')] docker build -t ${docker_tag} ${pkg_dir}"
+    if log_cmd docker_exec build --network=host -t "${docker_tag}" "${pkg_dir}"; then
+        OPENCLAW_IMAGE="${docker_tag}"
+        _save_openclaw_image_to_panel "${docker_tag}"
+        local _local_tag="jishushell-openclaw:local"
+        if [[ "${docker_tag}" != "${_local_tag}" ]]; then
+            docker_exec tag "${docker_tag}" "${_local_tag}" 2>/dev/null || true
+        fi
+        rm -f "${pkg_dir}/Dockerfile"
+        ui_success "OpenClaw Docker image built: ${docker_tag} (with Python)"
+    else
+        rm -f "${pkg_dir}/Dockerfile"
+        ui_error "Failed to build OpenClaw Docker image"
+        return 1
+    fi
+}
+
+_prompt_openclaw_skip() {
+    if [[ ! -t 0 || ! -t 1 ]]; then
+        SKIP_OPENCLAW=0
+        ui_info "Non-interactive shell detected — OpenClaw will be installed by default"
+        return 0
+    fi
+
+    local answer
+    echo ""
+    echo -e "${ACCENT}${BOLD}OpenClaw${NC}"
+    echo -e "${INFO}  Installs the OpenClaw npm package and builds a Docker image with Python.${NC}"
+    echo -e "${INFO}  Requires Docker to be running; the build may take a few minutes.${NC}"
+    echo ""
+    local answer answer_lc
+    read -r -p "$(echo -e "${MUTED}  Install OpenClaw and build Docker image? [Y/n]: ${NC}")" answer </dev/tty || answer="y"
+    answer_lc="$(echo "$answer" | tr '[:upper:]' '[:lower:]')"
+    case "$answer_lc" in
+        n|no) SKIP_OPENCLAW=1 ;;
+        *)    SKIP_OPENCLAW=0 ;;
+    esac
+}
+
+# show_install_plan [--with-jishushell]
+show_install_plan() {
+    local with_jishushell=0
+    [[ "${1:-}" == "--with-jishushell" ]] && with_jishushell=1
+
+    detect_network
+
+    echo ""
+    echo -e "${ACCENT}${BOLD}Install Plan${NC}"
+    echo -e "${MUTED}────────────────────────────────${NC}"
+    ui_kv "OS"              "$OS_NAME"
+    ui_kv "Package manager" "$PKG_MANAGER"
+    ui_kv "Architecture"    "$ARCH"
+    ui_kv "Network"         "$(if [[ $NETWORK_CHINA -eq 1 ]]; then echo 'China (Alibaba mirrors)'; else echo 'Global'; fi)"
+    echo ""
+    ui_kv "Node.js"     "$(if [[ $SKIP_NODE   -eq 1 ]]; then echo 'skip'; else echo "v${NODE_VERSION} via nvm v${NVM_VERSION}"; fi)"
+    ui_kv "Docker"      "$(if [[ $SKIP_DOCKER -eq 1 ]]; then echo 'skip'; else echo 'latest stable'; fi)"
+    ui_kv "Nomad"       "$(if [[ $SKIP_NOMAD  -eq 1 ]]; then echo 'skip'; else echo "v${NOMAD_VERSION}"; fi)"
+    ui_kv "OpenClaw"    "$(if [[ \"${SKIP_OPENCLAW}\" == \"1\" ]]; then echo 'skip'; else echo \"openclaw@${OPENCLAW_NPM_VERSION} + docker build ${OPENCLAW_DOCKER_TAG}\"; fi)"
+    if [[ $with_jishushell -eq 1 ]]; then
+        local _plan_jishu
+        if [[ $SKIP_JISHUSHELL -eq 1 ]]; then
+            _plan_jishu="skip"
+        else
+            local _plan_tgz=""
+            for _c in "${JISHU_SCRIPT_DIR}"/jishushell-*.tgz; do
+                [[ -f "$_c" ]] && { _plan_tgz="$(basename "$_c")"; break; }
+            done
+            _plan_jishu="${_plan_tgz:+npm install -g ${_plan_tgz} (local)}${_plan_tgz:-npm install -g jishushell}"
+        fi
+        ui_kv "JishuShell"         "$_plan_jishu"
+        ui_kv "JishuShell service" "$(if [[ $SKIP_JISHUSHELL_SERVICE -eq 1 ]]; then echo 'skip'; else echo 'register autostart'; fi)"
+    fi
+
+    if [[ "$DRY_RUN" == "1" ]]; then
+        echo ""
+        ui_warn "Dry-run mode: no changes will be made to this system"
+    fi
+    echo ""
+}
+
+# show_summary [--with-jishushell]
+show_summary() {
+    local with_jishushell=0
+    [[ "${1:-}" == "--with-jishushell" ]] && with_jishushell=1
+
+    echo ""
+    echo -e "${ACCENT}${BOLD}Summary${NC}"
+    echo -e "${MUTED}────────────────────────────────${NC}"
+
+    local all_ok=1
+
+    if [[ $SKIP_NODE -eq 0 ]]; then
+        if command -v node &>/dev/null; then
+            ui_kv "Node.js"  "✓ $(node --version 2>/dev/null)"
+        else
+            ui_kv "Node.js"  "✗ not installed"
+            all_ok=0
+        fi
+    fi
+
+    if [[ $SKIP_DOCKER -eq 0 ]]; then
+        if command -v docker &>/dev/null; then
+            local _docker_ver
+            _docker_ver="$(docker version --format '{{.Server.Version}}' 2>/dev/null | extract_semver || docker --version 2>/dev/null | extract_semver || echo 'installed')"
+            ui_kv "Docker"   "✓ v${_docker_ver}"
+        else
+            ui_kv "Docker"   "✗ not installed"
+            all_ok=0
+        fi
+    fi
+
+    if [[ $SKIP_NOMAD -eq 0 ]]; then
+        local _nomad_bin="${JISHUSHELL_BIN_DIR}/nomad"
+        if [[ -x "$_nomad_bin" ]]; then
+            local _nomad_ver
+            _nomad_ver="$("$_nomad_bin" version 2>/dev/null | head -n1 | extract_semver || echo 'installed')"
+            ui_kv "Nomad"    "✓ v${_nomad_ver} (${_nomad_bin})"
+        elif command -v nomad &>/dev/null; then
+            local _nomad_ver
+            _nomad_ver="$(nomad version 2>/dev/null | head -n1 | extract_semver || echo 'installed')"
+            ui_kv "Nomad"    "✓ v${_nomad_ver} (system: $(command -v nomad))"
+        else
+            ui_kv "Nomad"    "✗ not installed"
+            all_ok=0
+        fi
+    fi
+
+    if [[ "${SKIP_OPENCLAW}" != "1" ]]; then
+        if [[ -n "${OPENCLAW_IMAGE}" ]] && docker_exec image inspect "${OPENCLAW_IMAGE}" &>/dev/null 2>&1; then
+            ui_kv "OpenClaw" "✓ ${OPENCLAW_IMAGE}"
+        elif [[ "$DRY_RUN" == "1" ]]; then
+            ui_kv "OpenClaw" "- dry-run"
+        else
+            ui_kv "OpenClaw" "✗ image not found locally"
+            all_ok=0
+        fi
+    fi
+
+    if [[ $with_jishushell -eq 1 && $SKIP_JISHUSHELL -eq 0 ]]; then
+        local _wrapper="${JISHUSHELL_BIN_DIR}/jishushell-panel-start"
+        if [[ -x "$_wrapper" ]]; then
+            ui_kv "JishuShell" "✓ ${_wrapper}"
+        elif command -v jishushell &>/dev/null; then
+            ui_kv "JishuShell" "✓ $(command -v jishushell)"
+        else
+            ui_kv "JishuShell" "✗ not found"
+            all_ok=0
+        fi
+    fi
+
+    echo ""
+    if [[ $all_ok -eq 1 ]]; then
+        echo -e "${SUCCESS}${BOLD}All components installed successfully!${NC}"
+    else
+        echo -e "${WARN}${BOLD}One or more components failed — review the log above.${NC}"
+    fi
+    # Remind the user to re-login if docker group was added and sg could not
+    # activate it in-session (DOCKER_CMD_PREFIX would be set if sg succeeded).
+    if [[ "${DOCKER_GROUP_JUST_ADDED:-0}" == "1" && -z "${DOCKER_CMD_PREFIX:-}" ]]; then
+        echo ""
+        echo -e "${WARN}${BOLD}Action required — Docker group membership:${NC}"
+        echo -e "${WARN}  User '${REAL_USER:-$(id -un)}' was added to the 'docker' group, but the"
+        echo -e "${WARN}  change is not active in the current shell session.${NC}"
+        echo -e "${WARN}  Please log out and log back in, or run:${NC}"
+        echo -e "${ACCENT}    newgrp docker${NC}"
+        echo -e "${WARN}  to use Docker without sudo.${NC}"
+    fi
+    if [[ -n "${JISHU_LOG_FILE:-}" ]]; then
+        echo ""
+        ui_kv "Log file" "${JISHU_LOG_FILE}"
+    fi
+    echo ""
+    if [[ $all_ok -eq 1 && $with_jishushell -eq 1 && $SKIP_JISHUSHELL -eq 0 ]]; then
+        # Detect the primary non-loopback LAN IP address.
+        # Use || true on every substitution to prevent set -e from firing when
+        # the command does not exist on this OS (e.g. "ip" is Linux-only).
+        local _local_ip=""
+        if [[ "$(uname -s)" == "Darwin" ]]; then
+            local _iface
+            _iface="$(route -n get 1.1.1.1 2>/dev/null | awk '/interface:/{print $2}')" || true
+            if [[ -n "$_iface" ]]; then
+                _local_ip="$(ipconfig getifaddr "$_iface" 2>/dev/null)" || true
+            fi
+            if [[ -z "$_local_ip" ]]; then
+                _local_ip="$(ipconfig getifaddr en0 2>/dev/null)" || true
+            fi
+            if [[ -z "$_local_ip" ]]; then
+                _local_ip="$(ipconfig getifaddr en1 2>/dev/null)" || true
+            fi
+        else
+            _local_ip="$(ip -4 route get 1.1.1.1 2>/dev/null | awk '{for(i=1;i<=NF;i++) if($i=="src") {print $(i+1); exit}}')" || true
+            if [[ -z "$_local_ip" ]]; then
+                _local_ip="$(hostname -I 2>/dev/null | awk '{print $1}')" || true
+            fi
+        fi
+
+        echo -e "${SUCCESS}${BOLD}  ╔══════════════════════════════════════════════════════╗${NC}"
+        echo -e "${SUCCESS}${BOLD}  ║  Installation complete!                              ║${NC}"
+        echo -e "${SUCCESS}${BOLD}  ║                                                      ║${NC}"
+        echo -e "${SUCCESS}${BOLD}  ║  Open your browser and navigate to:                  ║${NC}"
+        echo -e "${SUCCESS}${BOLD}  ║    http://localhost:${JISHUSHELL_PORT}/$(printf '%*s' $((32 - ${#JISHUSHELL_PORT})) '')║${NC}"
+        if [[ -n "$_local_ip" ]]; then
+        echo -e "${SUCCESS}${BOLD}  ║    http://${_local_ip}:${JISHUSHELL_PORT}/$(printf '%*s' $((28 - ${#_local_ip} - ${#JISHUSHELL_PORT})) '')║${NC}"
+        fi
+        echo -e "${SUCCESS}${BOLD}  ╚══════════════════════════════════════════════════════╝${NC}"
+        echo ""
+    fi
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Core install orchestration
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# ─── 6. JishuShell backend (npm install -g jishushell) ───────────────────────
+
+install_jishushell() {
+    ui_stage "JishuShell"
+
+    if [[ $SKIP_JISHUSHELL -eq 1 ]]; then
+        ui_info "Skipped (--skip-jishushell)"
+        return 0
+    fi
+
+    if [[ "$DRY_RUN" == "1" ]]; then
+        local _dry_reg=""
+        [[ -n "${NPM_REGISTRY:-}" ]] && _dry_reg=" --registry ${NPM_REGISTRY}"
+        local _dry_tgz=""
+        for _c in "${JISHU_SCRIPT_DIR}"/jishushell-*.tgz; do
+            [[ -f "$_c" ]] && { _dry_tgz="$_c"; break; }
+        done
+        if [[ -n "$_dry_tgz" ]]; then
+            ui_info "[dry-run] Would: npm install -g ${_dry_tgz}  (local package)"
+        else
+            ui_info "[dry-run] Would: npm install -g jishushell${_dry_reg}"
+        fi
+        ui_info "[dry-run] Would write wrapper: ${JISHUSHELL_BIN_DIR}/jishushell-panel-start"
+        return 0
+    fi
+
+    local node_bin
+    node_bin="$(command -v node 2>/dev/null || true)"
+    # When running as root via sudo, node may only be in the real user's nvm.
+    if [[ -z "$node_bin" && -n "${REAL_HOME}" ]]; then
+        local nvm_node_dir="${REAL_HOME}/.nvm/versions/node"
+        if [[ -d "$nvm_node_dir" ]]; then
+            node_bin="$(find "$nvm_node_dir" -name node -type f 2>/dev/null | sort -V | tail -1 || true)"
+        fi
+    fi
+    if [[ -z "$node_bin" ]]; then
+        ui_error "Cannot locate node — wrapper cannot be written"
+        return 1
+    fi
+
+    # Locate npm sibling to the node binary (works with nvm-managed installs)
+    local npm_bin
+    npm_bin="$(dirname "$node_bin")/npm"
+    if [[ ! -x "$npm_bin" ]]; then
+        npm_bin="$(command -v npm 2>/dev/null || true)"
+    fi
+    if [[ -z "$npm_bin" ]]; then
+        ui_error "Cannot locate npm — cannot install jishushell"
+        return 1
+    fi
+
+    local npm_registry_args=();
+    if [[ -n "${NPM_REGISTRY:-}" ]]; then
+        if [[ ! "$NPM_REGISTRY" =~ ^https?:// ]]; then
+            ui_error "NPM_REGISTRY must be a valid URL starting with http:// or https://"
+            return 1
+        fi
+        npm_registry_args=("--registry" "${NPM_REGISTRY}")
+        ui_info "Installing jishushell from ${NPM_REGISTRY}..."
+    elif [[ "${NETWORK_CHINA:-0}" == "1" ]]; then
+        npm_registry_args=("--registry" "https://registry.npmmirror.com")
+        ui_info "China network — installing jishushell from npmmirror.com..."
+    else
+        ui_info "Installing jishushell from public npm registry..."
+    fi
+
+    # When jishushell is already installed (e.g. running as npm postinstall hook),
+    # skip the npm install step and only write the wrapper + service.
+    if [[ "${JISHUSHELL_SKIP_NPM_INSTALL:-0}" != "1" ]]; then
+        # Prefer a local .tgz package in the same directory as this script.
+        local tgz_path=""
+        local _tgz_candidate
+        for _tgz_candidate in "${JISHU_SCRIPT_DIR}"/jishushell-*.tgz; do
+            if [[ -f "$_tgz_candidate" ]]; then
+                tgz_path="$_tgz_candidate"
+                break
+            fi
+        done
+
+        # Export a sentinel so post-install.sh (triggered by npm's postinstall
+        # lifecycle hook) knows it was launched from inside jishu-install.sh and
+        # must not re-run Docker/Nomad/OpenClaw installation steps again.
+        export JISHU_RUNNING_IN_INSTALLER=1
+
+        if [[ -n "$tgz_path" ]]; then
+            ui_info "Found local package: ${tgz_path} — installing offline..."
+            log_detail "[$(date '+%H:%M:%S')] ${npm_bin} install -g ${tgz_path}"
+            if ! log_cmd "$npm_bin" install -g "${tgz_path}"; then
+                unset JISHU_RUNNING_IN_INSTALLER
+                ui_error "npm install -g ${tgz_path} failed"
+                return 1
+            fi
+        else
+            log_detail "[$(date '+%H:%M:%S')] ${npm_bin} install -g jishushell ${npm_registry_args[*]:-}"
+            if ! log_cmd "$npm_bin" install -g jishushell ${npm_registry_args[@]+"${npm_registry_args[@]}"}; then
+                unset JISHU_RUNNING_IN_INSTALLER
+                ui_error "npm install -g jishushell failed"
+                return 1
+            fi
+        fi
+        unset JISHU_RUNNING_IN_INSTALLER
+    else
+        ui_info "Skipping npm install (already installed by caller)"
+    fi
+
+    # Resolve the installed cli.js path via the npm that did the install
+    local npm_root
+    npm_root="$("$npm_bin" root -g 2>/dev/null || true)"
+    if [[ -z "$npm_root" ]]; then
+        ui_error "Cannot locate npm root — wrapper cannot be written"
+        return 1
+    fi
+    local jishushell_bin="${npm_root}/jishushell/dist/cli.js"
+    ui_success "JishuShell installed ($(${node_bin} -p "require('${npm_root}/jishushell/package.json').version" 2>/dev/null || echo 'version unknown'))"
+    local wrapper="${JISHUSHELL_BIN_DIR}/jishushell-panel-start"
+    mkdir -p "${JISHUSHELL_BIN_DIR}"
+
+    # The wrapper resolves node at runtime — it does NOT hardcode the path so
+    # the binary stays valid if nvm is upgraded or node is reinstalled.
+    cat > "$wrapper" << WRAPPER
+#!/usr/bin/env bash
+set -euo pipefail
+
+_find_node() {
+    command -v node 2>/dev/null && return
+    local nvm_dir="\${NVM_DIR:-\${HOME}/.nvm}"
+    [ -s "\$nvm_dir/nvm.sh" ] && . "\$nvm_dir/nvm.sh" --no-use 2>/dev/null || true
+    command -v node 2>/dev/null && return
+    local ndir="\${HOME}/.nvm/versions/node"
+    [ -d "\$ndir" ] && find "\$ndir" -name node -type f 2>/dev/null | sort -V | tail -1 || true
+}
+NODE_BIN="\$(_find_node || true)"
+if [ -z "\$NODE_BIN" ]; then
+    NODE_BIN="/opt/homebrew/bin/node"
+fi
+if [ ! -x "\$NODE_BIN" ]; then
+    echo "[jishushell-panel-start] ERROR: cannot locate node binary" >&2
+    exit 1
+fi
+
+# Data directory: honour explicit env override, otherwise use the real
+# user home embedded at install time (avoids /root when run as root).
+JISHUSHELL_HOME="\${JISHUSHELL_HOME:-${REAL_HOME}/.jishushell}"
+NOMAD_ENV="\${JISHUSHELL_HOME}/nomad.env"
+
+[ -f "\$NOMAD_ENV" ] && source "\$NOMAD_ENV"
+
+if [ ! -f "${jishushell_bin}" ]; then
+    echo "[jishushell-panel-start] ERROR: could not find jishushell at ${jishushell_bin}" >&2
+    exit 1
+fi
+
+exec "\$NODE_BIN" "${jishushell_bin}" "\$@"
+WRAPPER
+    chmod +x "$wrapper"
+    ui_success "JishuShell installed — wrapper: ${wrapper}"
+}
+
+install_jishushell_service() {
+    ui_stage "JishuShell service"
+
+    if [[ $SKIP_JISHUSHELL_SERVICE -eq 1 ]]; then
+        ui_info "Skipped (--skip-jishushell-service)"
+        return 0
+    fi
+
+    local wrapper="${JISHUSHELL_BIN_DIR}/jishushell-panel-start"
+    local log_path="${JISHUSHELL_HOME}/jishushell.log"
+
+    if [[ "$DRY_RUN" == "1" ]]; then
+        ui_info "[dry-run] Would register jishushell as a system service"
+        return 0
+    fi
+
+    if [[ "$OS" == "macos" ]]; then
+        local plist_label="com.jishushell.panel"
+        local plist_path="${HOME}/Library/LaunchAgents/${plist_label}.plist"
+
+        mkdir -p "${HOME}/Library/LaunchAgents"
+        cat > "$plist_path" << PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${plist_label}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${wrapper}</string>
+        <string>serve</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>${log_path}</string>
+    <key>StandardErrorPath</key>
+    <string>${log_path}</string>
+</dict>
+</plist>
+PLIST
+
+        launchctl unload "$plist_path" 2>/dev/null || true
+        if launchctl load -w "$plist_path" 2>/dev/null; then
+            ui_success "JishuShell backend service installed and started"
+        else
+            ui_warn "Could not load jishushell launchd agent"
+        fi
+        return 0
+    fi
+
+    if [[ "$(uname -s)" != "Linux" ]]; then
+        return 0
+    fi
+
+    local service_content="[Unit]
+Description=JishuShell Backend
+After=network-online.target nomad.service
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=${REAL_USER}
+SupplementaryGroups=docker
+EnvironmentFile=-/etc/jishushell/nomad.env
+ExecStart=${wrapper} serve
+Restart=on-failure
+RestartSec=3
+Environment=HOME=${REAL_HOME}
+Environment=JISHUSHELL_HOME=${JISHUSHELL_HOME}
+ProtectSystem=strict
+PrivateTmp=true
+NoNewPrivileges=true
+ReadWritePaths=${JISHUSHELL_HOME} /etc/jishushell
+
+[Install]
+WantedBy=multi-user.target"
+
+    # Only update the service file if it changed (avoids unnecessary restarts)
+    local svc_path="/etc/systemd/system/jishushell.service"
+    local need_reload=0
+    if [[ ! -f "$svc_path" ]] || ! echo "$service_content" | diff -q - "$svc_path" &>/dev/null; then
+        echo "$service_content" > /tmp/jishushell.service.$$
+        ${SUDO} mv /tmp/jishushell.service.$$ "$svc_path"
+        need_reload=1
+    fi
+
+    if [[ $need_reload -eq 1 ]]; then
+        ${SUDO} systemctl daemon-reload
+    fi
+
+    # Enable the service (auto-start on boot).
+    # Use 'enable --now' to also start it immediately — jishushell is the final
+    # component so there is no double-wait concern unlike Nomad.
+    if ! systemctl is-enabled jishushell &>/dev/null 2>&1; then
+        if ${SUDO} systemctl enable --now jishushell 2>/dev/null; then
+            ui_success "JishuShell systemd service installed and started"
+        else
+            ui_warn "Could not enable jishushell systemd service"
+        fi
+    elif [[ $need_reload -eq 1 ]]; then
+        # Service file changed — restart to pick up new config
+        ${SUDO} systemctl restart jishushell 2>/dev/null || true
+        ui_success "JishuShell systemd service updated and restarted"
+    else
+        ui_success "JishuShell systemd service already installed"
+    fi
+}
+
+# ─── run_install_components ───────────────────────────────────────────────────
+# Runs the standard install sequence.  Returns non-zero if any component fails.
+run_install_components() {
+    local with_jishushell=0
+    [[ "${1:-}" == "--with-jishushell" ]] && with_jishushell=1
+
+    local has_error=0
+
+    if [[ $SKIP_NODE -eq 0 ]]; then
+        if ! install_node; then
+            ui_error "Node.js installation failed"
+            has_error=1
+        fi
+    else
+        ui_stage "Node.js"
+        ui_info "Skipped (--skip-node)"
+    fi
+
+    local docker_ok=0
+    if [[ $SKIP_DOCKER -eq 0 ]]; then
+        if ! install_docker; then
+            ui_error "Docker installation failed"
+            has_error=1
+        else
+            docker_ok=1
+        fi
+    else
+        ui_stage "Docker"
+        ui_info "Skipped (--skip-docker)"
+        command -v docker &>/dev/null && docker_ok=1
+    fi
+
+    if [[ $SKIP_NOMAD -eq 0 ]]; then
+        if ! install_nomad; then
+            ui_error "Nomad installation failed"
+            has_error=1
+        else
+            install_nomad_systemd || true
+            # Ensure Nomad is actually running (mirrors install.ts startNomad() call).
+            # start_nomad() is idempotent: on Linux it defers to systemd (no competing nohup);
+            # on macOS/non-systemd it starts a background process.
+            # A slow start (timeout) is non-fatal — systemd will retry on next boot and
+            # 'jishushell doctor --fix' can recover it.  Do not fail the entire npm install
+            # just because Nomad took longer than expected to bind its port.
+            if ! start_nomad; then
+                ui_warn "Nomad could not be started — run 'jishushell doctor --fix' to diagnose"
+            fi
+        fi
+    else
+        ui_stage "Nomad"
+        ui_info "Skipped (--skip-nomad)"
+    fi
+
+    if [[ $docker_ok -eq 1 ]]; then
+        if ! install_openclaw; then
+            ui_error "OpenClaw installation failed"
+            has_error=1
+        fi
+    else
+        ui_stage "OpenClaw"
+        ui_warn "Skipped — Docker is not available (installation failed or not installed)"
+    fi
+
+    if [[ $with_jishushell -eq 1 ]]; then
+        if [[ $SKIP_JISHUSHELL -eq 1 ]]; then
+            ui_stage "JishuShell"
+            ui_info "Skipped (--skip-jishushell)"
+        elif ! install_jishushell; then
+            ui_error "JishuShell installation failed"
+            has_error=1
+        fi
+
+        if [[ $SKIP_JISHUSHELL -eq 0 && $SKIP_JISHUSHELL_SERVICE -eq 1 ]]; then
+            ui_stage "JishuShell service"
+            ui_info "Skipped (--skip-jishushell-service)"
+        elif [[ $SKIP_JISHUSHELL -eq 0 ]]; then
+            install_jishushell_service || true
+        fi
+    fi
+
+    # ── Fix .jishushell ownership & permissions ───────────────────────────────
+    # Ensure the data dir is readable/writable by both root and the real user.
+    # - Root owns the dir (service runs as root)
+    # - REAL_USER is in the owning group; dirs are g+rwx so normal-user tools work
+    if [[ -d "${JISHUSHELL_HOME}" && -n "${REAL_USER}" ]]; then
+        ui_info "Fixing ${JISHUSHELL_HOME} ownership for ${REAL_USER}..."
+        # Both Nomad and JishuShell now run as REAL_USER — make REAL_USER own everything
+        ${SUDO} chown -R "${REAL_USER}:${REAL_GID:-${REAL_USER}}" "${JISHUSHELL_HOME}" 2>/dev/null || true
+        # Dirs: rwxr-xr-x
+        ${SUDO} find "${JISHUSHELL_HOME}" -type d -exec chmod 755 {} + 2>/dev/null || true
+        # Files: rw-r--r-- by default
+        ${SUDO} find "${JISHUSHELL_HOME}" -type f -exec chmod 644 {} + 2>/dev/null || true
+        # Executables in bin/ must keep the execute bit
+        ${SUDO} find "${JISHUSHELL_BIN_DIR}" -type f -exec chmod 755 {} + 2>/dev/null || true
+        # Sensitive files: owner-only read (600)
+        for f in auth.json jwt-secret panel.json nomad.env encryption-key; do
+            local fp="${JISHUSHELL_HOME}/${f}"
+            [[ -f "$fp" ]] && ${SUDO} chmod 600 "$fp" 2>/dev/null || true
+        done
+        # Sync nomad.env from /etc/jishushell if missing in JISHUSHELL_HOME
+        if [[ ! -f "${JISHUSHELL_HOME}/nomad.env" && -f /etc/jishushell/nomad.env ]]; then
+            ${SUDO} cp /etc/jishushell/nomad.env "${JISHUSHELL_HOME}/nomad.env"
+            ${SUDO} chown "${REAL_USER}:${REAL_GID:-${REAL_USER}}" "${JISHUSHELL_HOME}/nomad.env"
+            ${SUDO} chmod 600 "${JISHUSHELL_HOME}/nomad.env"
+        fi
+        ui_success "Permissions set: ${REAL_USER}:${REAL_USER} on ${JISHUSHELL_HOME}"
+    fi
+
+    return $has_error
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Installer entry point — argument parsing, banner, main
+# ═══════════════════════════════════════════════════════════════════════════════
+
+parse_args() {
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --verbose)        VERBOSE=1 ;;
+            --dry-run)        DRY_RUN=1 ;;
+            --skip-node)      SKIP_NODE=1 ;;
+            --skip-docker)    SKIP_DOCKER=1 ;;
+            --skip-nomad)     SKIP_NOMAD=1 ;;
+            --skip-openclaw)           SKIP_OPENCLAW=1 ;;
+            --openclaw-version)
+                shift
+                OPENCLAW_NPM_VERSION="${1:?--openclaw-version requires a version argument (e.g. 3.24)}"
+                ;;
+            --skip-jishushell)         SKIP_JISHUSHELL=1 ;;
+            --skip-jishushell-service) SKIP_JISHUSHELL_SERVICE=1 ;;
+            --skip)
+                shift
+                IFS=',' read -ra _steps <<< "${1:-}"
+                for _s in "${_steps[@]}"; do
+                    case "$_s" in
+                        1) SKIP_NODE=1 ;;
+                        2) SKIP_DOCKER=1 ;;
+                        3) SKIP_NOMAD=1 ;;
+                        4) SKIP_OPENCLAW=1 ;;
+                        5) SKIP_JISHUSHELL=1 ;;
+                        6) SKIP_JISHUSHELL_SERVICE=1 ;;
+                        *) ui_warn "Unknown step number: $_s (valid: 1-6)" ;;
+                    esac
+                done
+                ;;
+            --run)
+                # --run N,M  → skip all steps NOT in the list
+                # First set all to skip, then re-enable only the listed steps
+                SKIP_NODE=1; SKIP_DOCKER=1; SKIP_NOMAD=1
+                SKIP_OPENCLAW=1; SKIP_JISHUSHELL=1; SKIP_JISHUSHELL_SERVICE=1
+                shift
+                IFS=',' read -ra _steps <<< "${1:-}"
+                for _s in "${_steps[@]}"; do
+                    case "$_s" in
+                        1) SKIP_NODE=0 ;;
+                        2) SKIP_DOCKER=0 ;;
+                        3) SKIP_NOMAD=0 ;;
+                        4) SKIP_OPENCLAW=0 ;;
+                        5) SKIP_JISHUSHELL=0 ;;
+                        6) SKIP_JISHUSHELL_SERVICE=0 ;;
+                        *) ui_warn "Unknown step number: $_s (valid: 1-6)" ;;
+                    esac
+                done
+                ;;
+            --registry)
+                shift
+                NPM_REGISTRY="${1:?--registry requires a URL argument}"
+                if [[ ! "$NPM_REGISTRY" =~ ^https?:// ]]; then
+                    ui_error "--registry must be a valid URL starting with http:// or https://"
+                    exit 1
+                fi
+                ;;
+            --network)
+                shift
+                case "${1:-}" in
+                    china)  NETWORK_CHINA=1 ;;
+                    global) NETWORK_CHINA=0 ;;
+                    *) ui_error "--network requires 'china' or 'global'"; exit 1 ;;
+                esac
+                NETWORK_OVERRIDE=1
+                ;;
+            --yes|-y)                  AUTO_YES=1 ;;
+            --help|-h)        usage; exit 0 ;;
+            *)                ui_warn "Unknown argument: $1" ;;
+        esac
+        shift
+    done
+}
+
+usage() {
+    cat <<EOF
+Usage: bash jishu-install.sh [options]
+
+Default (no options): runs steps 1,2,3,4,5,6
+
+Options:
+  --verbose         Show verbose output
+  --dry-run         Show install plan only, do not execute
+  --run <steps>     Run only the specified steps (comma-separated, e.g. --run 1,2,3)
+  --skip <steps>    Skip steps by number (comma-separated, e.g. --skip 4)
+  --skip-node                Skip step 1: Node.js installation
+  --skip-docker              Skip step 2: Docker installation
+  --skip-nomad               Skip step 3: Nomad installation
+  --skip-openclaw            Skip step 4: OpenClaw installation
+  --skip-jishushell          Skip step 5: JishuShell installation
+  --skip-jishushell-service  Skip step 6: JishuShell service registration
+  --registry <url>           Use a custom npm registry for all installs
+                             (e.g. --registry http://10.188.0.22:4873/)
+  --network <china|global>   Force network mode (skips auto-detection via ping)
+                             china:  use Alibaba mirrors for Docker and npm
+                             global: use default upstream sources
+  --yes, -y                  Skip all confirmation prompts
+  --help, -h                 Show this help message
+
+Steps:
+  1  Node.js   (via nvm)
+  2  Docker
+  3  Nomad
+  4  OpenClaw  (npm install + docker build)
+  5  JishuShell
+  6  JishuShell service registration (autostart)
+
+Environment variables:
+  JISHU_NODE_VERSION    Specify Node.js major version (default: ${NODE_VERSION})
+  JISHU_NVM_VERSION     Specify nvm version         (default: ${NVM_VERSION})
+  JISHU_NOMAD_VERSION   Specify Nomad version       (default: ${NOMAD_VERSION})
+  OPENCLAW_NPM_VERSION  Specify openclaw npm package version (default: latest)
+  OPENCLAW_DOCKER_TAG   Override built Docker image tag      (default: jishushell-base:v1)
+  NPM_REGISTRY          Custom npm registry URL (same as --registry flag)
+
+OpenClaw version flag (equivalent to OPENCLAW_NPM_VERSION env var):
+  --openclaw-version <ver>   Install a specific openclaw version, e.g. --openclaw-version 3.24
+  NO_PROMPT             Set to 1 to skip interactive prompts
+  VERBOSE               Set to 1 for verbose output
+
+Examples:
+  curl -fsSL https://www.aijishu.com/jishu-install.sh | bash
+  NO_PROMPT=1 bash jishu-install.sh --dry-run
+EOF
+}
+
+print_banner() {
+    echo -e "${ACCENT}${BOLD}"
+    echo "  ╔══════════════════════════════════════╗"
+    echo "  ║        JishuShell Installer          ║"
+    echo "  ╚══════════════════════════════════════╝"
+    echo -e "${NC}${INFO}  ${TAGLINE}${NC}"
+    echo ""
+}
+
+# ─── Install mode selection ───────────────────────────────────────────────────
+_prompt_install_confirm() {
+    if [[ "${AUTO_YES:-0}" == "1" || "${NO_PROMPT:-0}" == "1" ]]; then
+        return 0
+    fi
+    # Check /dev/tty directly — stdout/stdin may be redirected to the log FIFO
+    # so the standard -t 0/-t 1 tests are unreliable here.
+    if [[ ! -w /dev/tty || ! -r /dev/tty ]]; then
+        AUTO_YES=1
+        ui_info "Non-interactive shell detected — proceeding automatically"
+        return 0
+    fi
+
+    # Write everything directly to /dev/tty so output bypasses the log FIFO
+    # and is guaranteed to appear on screen before `read` blocks for input.
+    {
+        echo -e "${ACCENT}${BOLD}┌─────────────────────────────────────────────────────────┐${NC}"
+        echo -e "${ACCENT}${BOLD}│           THIRD-PARTY SOFTWARE NOTICE                   │${NC}"
+        echo -e "${ACCENT}${BOLD}└─────────────────────────────────────────────────────────┘${NC}"
+        echo ""
+        echo -e "  JishuShell assists in downloading and configuring the following"
+        echo -e "  third-party software packages for personal and internal use only."
+        echo -e "  Each package is governed solely by its own license. JishuShell"
+        echo -e "  does not modify, relicense, or assert ownership over any of them."
+        echo ""
+        echo -e "  You are the end user of these packages. You are solely"
+        echo -e "  responsible for ensuring that your use of each package complies"
+        echo -e "  with its respective license terms, including any restrictions on"
+        echo -e "  commercial use, competitive offerings, or redistribution."
+        echo ""
+
+        if [[ $SKIP_DOCKER -eq 0 ]]; then
+            echo -e "  ${BOLD}Docker Engine${NC}"
+            echo -e "  ${MUTED}  URL     : https://github.com/moby/moby${NC}"
+            echo -e "  ${MUTED}  License : Apache License, Version 2.0${NC}"
+            echo -e "  ${MUTED}            https://www.apache.org/licenses/LICENSE-2.0${NC}"
+            echo -e "  ${MUTED}  Author  : Docker, Inc.${NC}"
+            echo ""
+        fi
+        if [[ $SKIP_NOMAD -eq 0 ]]; then
+            echo -e "  ${BOLD}Nomad v${NOMAD_VERSION}+ (>= 1.7.0)${NC}"
+            echo -e "  ${MUTED}  URL     : https://github.com/hashicorp/nomad${NC}"
+            echo -e "  ${MUTED}  License : Business Source License 1.1 (BSL 1.1)${NC}"
+            echo -e "  ${MUTED}            https://github.com/hashicorp/nomad/blob/main/LICENSE${NC}"
+            echo -e "  ${MUTED}  Licensor: International Business Machines Corporation (IBM)${NC}"
+            echo -e "  ${MUTED}  Work    : Nomad Version 1.7.0 or later. (c) 2024 IBM Corp.${NC}"
+            echo ""
+        fi
+        echo -e "  ${MUTED}─────────────────────────────────────────────────────────${NC}"
+        echo -e "  ${MUTED}By continuing you acknowledge that you have read the above${NC}"
+        echo -e "  ${MUTED}notices and agree to each package's license terms.${NC}"
+        echo -e "  ${MUTED}sudo privileges are required to write to system directories.${NC}"
+        echo ""
+    } >/dev/tty
+
+    local answer
+    read -r -p "$(echo -e "  ${WARN}I have read and accept the above notices. Continue? [Y/n]: ${NC}")" answer </dev/tty || answer="y"
+    case "$(echo "$answer" | tr '[:upper:]' '[:lower:]')" in
+        n|no)
+            echo "Installation cancelled." >/dev/tty
+            exit 0
+            ;;
+    esac
+    echo "" >/dev/tty
+}
+
+# Finalize the install log: restore fds, wait for tee, strip ANSI codes.
+# Called from the EXIT trap so it runs on normal exit, Ctrl+C, and errors.
+_jishu_finalize_log() {
+    set +e
+    [[ -z "${_JISHU_RAW_LOG:-}" ]] && return 0  # not started or already finalized
+    local _raw="${_JISHU_RAW_LOG}"
+    local _log="${JISHU_LOG_FILE}"
+    local _fifo="${_JISHU_LOG_FIFO:-}"
+    local _tee_pid="${_JISHU_TEE_PID:-}"
+    # Mark as done to prevent re-entry
+    local _detail="${_JISHU_DETAIL_LOG:-}"
+    _JISHU_RAW_LOG=""; _JISHU_TEE_PID=""; _JISHU_LOG_FIFO=""; _JISHU_DETAIL_LOG=""
+
+    # ── Step 1: kill the sudo keepalive background process ────────────────────
+    # The keepalive is spawned before the FIFO redirect (so it does NOT hold
+    # the FIFO write-end).  We still kill it here for clean process accounting.
+    if [[ -n "${_SUDO_KEEPALIVE_PID:-}" ]]; then
+        kill "${_SUDO_KEEPALIVE_PID}" 2>/dev/null || true
+        _SUDO_KEEPALIVE_PID=""
+    fi
+
+    # ── Step 2: restore original fds ─────────────────────────────────────────
+    # Closing our fd1 (the FIFO write-end) now sends EOF to tee because the
+    # keepalive (the only other writer) is already dead.
+    exec 1>&3 2>/dev/null
+    exec 2>&4 2>/dev/null
+    exec 3>&- 2>/dev/null
+    exec 4>&- 2>/dev/null
+
+    # ── Step 3: wait for tee with a 5-second safety timeout ──────────────────
+    if [[ -n "$_tee_pid" ]]; then
+        local _n=0
+        while kill -0 "$_tee_pid" 2>/dev/null && [[ $_n -lt 50 ]]; do
+            sleep 0.1
+            _n=$((_n + 1))
+        done
+        # Safety kill if tee is somehow still alive (e.g. another process held
+        # the FIFO open), so this function never hangs the terminal.
+        if kill -0 "$_tee_pid" 2>/dev/null; then
+            kill    "$_tee_pid" 2>/dev/null || true
+            sleep 0.2
+            kill -9 "$_tee_pid" 2>/dev/null || true
+        fi
+    fi
+
+    # ── Step 4: remove the FIFO ───────────────────────────────────────────────
+    [[ -n "$_fifo" ]] && rm -f "$_fifo" 2>/dev/null || true
+
+    # ── Step 5: produce the clean log ────────────────────────────────────────
+    # Strip ANSI escape codes AND decorative box-drawing characters
+    # (╔══╗, ╚══╝, ════, ────, ── text ──) so the log is plain readable text.
+    if [[ -f "${_raw}" ]]; then
+        sed \
+            -e 's/\x1B\[[0-9;]*[A-Za-z]//g' \
+            -e 's/\r//g' \
+            -e 's/[╔╗╚╝╠╣╦╩╬║│]//g' \
+            -e 's/[═─]\{2,\}//g' \
+            -e '/^[[:space:]]*$/d' \
+            "${_raw}" > "${_log}" 2>/dev/null
+        rm -f "${_raw}"
+    fi
+    # ── Step 6: append detailed command output ────────────────────────────────
+    if [[ -f "${_detail}" && -s "${_detail}" ]]; then
+        {
+            printf '\n\n--- DETAILED COMMAND OUTPUT ---\n'
+            cat "${_detail}"
+        } >> "${_log}" 2>/dev/null
+        rm -f "${_detail}"
+    fi
+    echo "Log saved to: ${_log}"
+}
+
+_jishu_install_main() {
+    parse_args "$@"
+
+    # ── Set up log file ───────────────────────────────────────────────────────
+    # Strategy:
+    #   1. Create a named FIFO so we get an unambiguous tee PID via $!.
+    #   2. Start tee with SIGINT/SIGTERM ignored — Ctrl+C won't kill it mid-write.
+    #      tee inherits the current (real terminal) stdout, so screen output is
+    #      preserved.  Its stdin comes from the FIFO.
+    #   3. Redirect all script output into the FIFO.
+    #   4. EXIT trap calls _jishu_finalize_log which closes the FIFO write-end,
+    #      waits for tee with 'wait $PID', then strips ANSI codes to produce the
+    #      clean log.  Works for normal exit, Ctrl+C, and set -e errors.
+    local _log_ts
+    _log_ts="$(date +%Y-%m-%d-%H-%M-%S)"
+    JISHU_LOG_FILE="${JISHU_SCRIPT_DIR}/jishu-install-${_log_ts}.log"
+    # Fall back to $PWD when the script directory is not writable (e.g. curl|bash).
+    if [[ ! -w "${JISHU_SCRIPT_DIR}" ]]; then
+        JISHU_LOG_FILE="${PWD}/jishu-install-${_log_ts}.log"
+    fi
+    _JISHU_RAW_LOG="${JISHU_LOG_FILE}.tmp"
+    _JISHU_DETAIL_LOG="${JISHU_LOG_FILE}.detail"
+
+    # Create FIFO — $$ makes it unique per invocation, no mktemp race needed.
+    _JISHU_LOG_FIFO="${TMPDIR:-/tmp}/jishu_log_$$.fifo"
+    mkfifo "${_JISHU_LOG_FIFO}"
+
+    # Launch tee BEFORE redirecting so it inherits the real terminal as stdout.
+    # trap '' INT TERM makes it immune to Ctrl+C and termination signals.
+    ( trap '' INT TERM; exec tee "${_JISHU_RAW_LOG}" ) < "${_JISHU_LOG_FIFO}" &
+    _JISHU_TEE_PID=$!
+
+    # Override EXIT trap: finalize log first, then run normal temp-file cleanup.
+    trap '_jishu_finalize_log; cleanup_tmpfiles' EXIT
+
+    # ── Pre-FIFO keepalive: must be spawned BEFORE the exec redirect below so
+    # that it inherits the real terminal as fd 1 rather than the FIFO write-end.
+    # A keepalive holding the FIFO open would prevent tee from ever seeing EOF
+    # and cause _jishu_finalize_log to hang.  Credentials are acquired later,
+    # inside check_sudo() (which runs after the user confirms the install plan),
+    # so the keepalive's early sudo -n true calls are intentional no-ops.
+    if [[ $EUID -ne 0 ]] && command -v sudo &>/dev/null; then
+        if [[ -z "${_SUDO_KEEPALIVE_PID:-}" ]]; then
+            ( while true; do sudo -n true 2>/dev/null; sleep 60; done ) &
+            _SUDO_KEEPALIVE_PID=$!
+            disown "$_SUDO_KEEPALIVE_PID" 2>/dev/null || true
+        fi
+    fi
+
+    # Save original terminal fds, then redirect everything into the FIFO.
+    exec 3>&1 4>&2
+    exec > "${_JISHU_LOG_FIFO}" 2>&1
+
+    print_banner
+    ui_info "Logging to: ${JISHU_LOG_FILE}"
+    detect_os
+    detect_arch
+    show_install_plan --with-jishushell
+    if [[ "$OS" == "macos" ]]; then
+        ui_warn "macOS is not supported yet — coming soon!"
+        exit 0
+    fi
+    _prompt_install_confirm
+    check_sudo
+    ensure_prerequisites
+    run_install_components --with-jishushell
+    local rc=$?
+    show_summary --with-jishushell
+    exit $rc
+}
+
+# Only run main() when executed directly or piped via curl|bash (not when sourced).
+# When piped, BASH_SOURCE[0] is unset; when sourced it differs from $0.
+if [[ "${BASH_SOURCE[0]:-}" == "${0}" ]] || [[ -z "${BASH_SOURCE[0]:-}" ]]; then
+    _jishu_install_main "$@"
+fi