jishushell 0.4.2 → 0.4.17

package/install/jishu-install.sh

@@ -118,7 +118,11 @@ is_promptable() {
     if [[ "${NO_PROMPT:-0}" == "1" ]]; then
         return 1
     fi
-    if [[ -r /dev/tty && -w /dev/tty ]]; then
+    # Web-triggered upgrades never have an interactive TTY
+    if [[ "${JISHUSHELL_WEB_UPDATE:-0}" == "1" ]]; then
+        return 1
+    fi
+    if ( : <> /dev/tty ) 2>/dev/null; then
         return 0
     fi
     return 1
@@ -161,7 +165,7 @@ JISHU_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd 2>/dev/null |
 # ──── BEGIN VERSIONS ────
 NODE_VERSION="${JISHU_NODE_VERSION:-22}"
 NVM_VERSION="${JISHU_NVM_VERSION:-0.40.4}"
-NOMAD_VERSION="${JISHU_NOMAD_VERSION:-1.11.3}"
+NOMAD_VERSION="${JISHU_NOMAD_VERSION:-1.6.5}"
 JISHUSHELL_PORT="${JISHUSHELL_PORT:-8090}"
 
 # ──── NPM Registry Configuration ────
@@ -223,8 +227,13 @@ 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
+JISHUSHELL_NPM_VERSION="${JISHUSHELL_NPM_VERSION:-latest}"  # jishushell npm package version
+JISHUSHELL_VERSION_OVERRIDE=0
+if [[ "${JISHUSHELL_NPM_VERSION}" != "latest" ]]; then
+    JISHUSHELL_VERSION_OVERRIDE=1
+fi
 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_DOCKER_TAG="${OPENCLAW_DOCKER_TAG:-ghcr.io/x-aijishu/openclaw-runtime:latest}"  # pre-built image from registry
 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
@@ -405,18 +414,33 @@ detect_os() {
     ui_success "OS: ${OS_NAME} (package manager: ${PKG_MANAGER})"
 }
 
-# Detect CPU architecture.  Sets: ARCH (amd64 | arm64)
+# Detect CPU architecture.  Sets: ARCH (arm64)
+# Only Arm-family (aarch64, arm64, armv7l) and Apple Silicon (Darwin/arm64)
+# are supported.  x86_64, i686, riscv, mips, s390x, ppc, etc. are rejected.
 detect_arch() {
-    ARCH="$(uname -m)"
-    case "$ARCH" in
-        x86_64|amd64)    ARCH="amd64" ;;
-        aarch64|arm64)   ARCH="arm64" ;;
+    local raw_arch
+    raw_arch="$(uname -m)"
+    case "$raw_arch" in
+        aarch64|arm64)
+            ARCH="arm64"
+            ;;
+        armv7l|armv8l|armhf)
+            # 32-bit Arm — may work but not officially tested
+            ARCH="arm64"
+            ui_warn "32-bit Arm detected (${raw_arch}). 64-bit OS on a 64-bit board is strongly recommended."
+            ;;
         *)
-            ui_error "Unsupported CPU architecture: $ARCH"
+            ui_error "Unsupported CPU architecture: ${raw_arch}"
+            ui_error ""
+            ui_error "JishuShell runs exclusively on Arm-based devices (aarch64 / arm64)."
+            ui_error "Supported examples: Raspberry Pi 4/5, Orange Pi 5, Jetson Orin,"
+            ui_error "  Rockchip RK3588, Apple Silicon Mac (arm64 macOS)."
+            ui_error ""
+            ui_error "x86_64 / i686 / RISC-V / MIPS / s390x / PowerPC are not supported."
             exit 1
             ;;
     esac
-    ui_success "Architecture: ${ARCH}"
+    ui_success "Architecture: ${ARCH} (${raw_arch})"
 }
 
 # Verify sudo access.  Sets: SUDO ("" if root, "sudo" otherwise)
@@ -433,6 +457,10 @@ check_sudo() {
 
     if ! sudo -n true 2>/dev/null; then
         ui_info "Some steps require sudo — you may be prompted for your password."
+        if ! is_promptable; then
+            ui_error "Failed to obtain sudo privileges (no interactive TTY available)"
+            exit 1
+        fi
         if ! sudo -v </dev/tty; then
             ui_error "Failed to obtain sudo privileges"
             exit 1
@@ -446,7 +474,7 @@ check_sudo() {
     # 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 ) &
+        ( while true; do sudo -n true 2>/dev/null; sleep 60; done ) &>/dev/null &
         _SUDO_KEEPALIVE_PID=$!
         disown "$_SUDO_KEEPALIVE_PID" 2>/dev/null || true
     fi
@@ -925,6 +953,41 @@ _ensure_nvm_shell_config() {
 install_docker() {
     ui_stage "Docker"
 
+    # ── macOS: use private Colima instance ─────────────────────────────────────
+    if [[ "$OS" == "macos" ]]; then
+        local need_brew=0
+        local need_profile=0
+
+        if ! command -v docker &>/dev/null || ! command -v colima &>/dev/null; then
+            need_brew=1
+            need_profile=1
+        elif ! _colima list 2>/dev/null | grep -q "${_COLIMA_PROFILE}"; then
+            need_profile=1
+        fi
+
+        if [[ $need_brew -eq 1 ]]; then
+            if ! _do_install_docker; then
+                ui_error "Colima installation failed"
+                return 1
+            fi
+        elif [[ $need_profile -eq 1 ]]; then
+            ui_info "Starting Colima VM (profile: ${_COLIMA_PROFILE})..."
+            mkdir -p "${_COLIMA_HOME}"
+            _colima start "${_COLIMA_PROFILE}" \
+                --vm-type vz --mount-type virtiofs --network-address \
+                --activate=false --cpu 2 --memory 4 --disk 60 >/dev/null \
+                || { ui_warn "colima start failed — run 'COLIMA_HOME=${_COLIMA_HOME} colima start ${_COLIMA_PROFILE}' manually"; return 1; }
+            export DOCKER_HOST="unix://${_COLIMA_SOCKET}"
+            ui_success "Colima is running"
+        else
+            ui_success "Docker and Colima already configured"
+        fi
+
+        _ensure_docker_running
+        return 0
+    fi
+
+    # ── Linux: standard Docker Engine ──────────────────────────────────────────
     local need_install_docker=0
     local need_install_compose=0
 
@@ -948,8 +1011,6 @@ install_docker() {
         :
     elif command -v docker-compose &>/dev/null; then
         :
-    elif [[ "$OS" == "macos" ]]; then
-        :
     else
         need_install_compose=1
     fi
@@ -962,8 +1023,6 @@ install_docker() {
 
     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
@@ -971,7 +1030,6 @@ install_docker() {
                 return 1
             fi
         fi
-        # Compose is bundled; skip the separate install step
         need_install_compose=0
     fi
 
@@ -995,13 +1053,23 @@ _do_install_docker() {
     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"
+        ui_info "Installing docker and colima via Homebrew..."
+        if ! command -v brew &>/dev/null; then
+            ui_warn "Homebrew not found. Install it from https://brew.sh then re-run this script."
+            return 1
         fi
-        ui_info "After installation, open Docker Desktop and wait for the daemon to start, then re-run this script"
-        return 1
+        brew install -q docker colima || { ui_warn "brew install failed"; return 1; }
+        ui_success "docker and colima installed"
+
+        mkdir -p "${_COLIMA_HOME}"
+        ui_info "Starting Colima VM (profile: ${_COLIMA_PROFILE})..."
+        _colima start "${_COLIMA_PROFILE}" \
+            --vm-type vz --mount-type virtiofs --network-address \
+            --activate=false --cpu 2 --memory 4 --disk 60 >/dev/null \
+            || { ui_warn "colima start failed — run 'COLIMA_HOME=${_COLIMA_HOME} colima start ${_COLIMA_PROFILE}' manually"; return 1; }
+        ui_success "Colima is running"
+        export DOCKER_HOST="unix://${_COLIMA_SOCKET}"
+        return 0
     fi
 
     # Step 1: download
@@ -1096,7 +1164,7 @@ _do_install_docker_apt_fallback() {
     fi
 
     if [[ "$OS" == "macos" ]]; then
-        ui_warn "No apt/dnf fallback available on macOS — please install Docker Desktop manually"
+        ui_warn "No apt/dnf fallback available on macOS — install via Homebrew: brew install docker colima"
         return 1
     fi
 
@@ -1157,17 +1225,30 @@ _ensure_docker_running() {
     fi
 
     if [[ "$OS" == "macos" ]]; then
+        export DOCKER_HOST="unix://${_COLIMA_SOCKET}"
+        if ! docker info &>/dev/null 2>&1; then
+            ui_info "Starting Colima VM..."
+            mkdir -p "${_COLIMA_HOME}"
+            if ! _colima start "${_COLIMA_PROFILE}" \
+                --vm-type vz --mount-type virtiofs --network-address \
+                --activate=false --cpu 2 --memory 4 --disk 60 >/dev/null; then
+                ui_warn "colima start failed"
+                ui_info "Run manually: COLIMA_HOME=${_COLIMA_HOME} colima start ${_COLIMA_PROFILE}"
+                return 1
+            fi
+        fi
         local waited=0
+        local timeout=120
         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"
+            if [[ $waited -ge $timeout ]]; then
+                ui_warn "Docker daemon did not become ready within ${timeout} seconds"
+                ui_info "Run: COLIMA_HOME=${_COLIMA_HOME} colima status ${_COLIMA_PROFILE}"
                 return 1
             fi
-            sleep 1
-            (( waited++ )) || true
+            sleep 2
+            (( waited += 2 )) || true
         done
-        [[ $waited -lt 15 ]] && ui_success "Docker daemon is ready"
+        ui_success "Docker daemon is ready"
         return 0
     fi
 
@@ -1303,6 +1384,21 @@ docker_exec() {
     fi
 }
 
+# Private Colima wrapper — runs colima with COLIMA_HOME scoped to JishuShell's
+# data directory so the VM, socket, and all state are fully isolated from any
+# user-level Docker Desktop or default Colima installation.
+#
+# Usage:  _colima start jishushell --vm-type vz ...
+#         _colima stop jishushell
+#         _colima status jishushell
+_COLIMA_HOME="${JISHUSHELL_HOME}/colima"
+_COLIMA_PROFILE="jishushell"
+_COLIMA_SOCKET="${_COLIMA_HOME}/${_COLIMA_PROFILE}/docker.sock"
+
+_colima() {
+    COLIMA_HOME="${_COLIMA_HOME}" command colima "$@"
+}
+
 # ─── 3. Nomad ────────────────────────────────────────────────────────────────
 
 install_nomad() {
@@ -1330,12 +1426,24 @@ install_nomad() {
             if [[ -z "$current_version" ]]; then
                 ui_warn "Nomad at ${local_bin} is not functional (wrong arch or corrupt) — reinstalling..."
                 rm -f "$local_bin"
+            elif [[ "$current_version" == "$NOMAD_VERSION" ]]; then
+                ui_success "Nomad already at target version: v${current_version} → ${local_bin}"
+                _ensure_jishushell_bin_in_path
+                return 0
             elif version_gte "$current_version" "$NOMAD_VERSION"; then
-                ui_success "Nomad already installed: v${current_version} → ${local_bin}"
+                # current > target (the == case was handled above). JishuShell
+                # pins Nomad to a specific version on purpose (license downgrade
+                # from BSL 1.1 to MPL 2.0). Raft state is not backward compatible
+                # across the jump, so we auto-migrate: download + verify the new
+                # binary first (safe-first), then stop services, back up the old
+                # data_dir, wipe it, clean orphaned containers, and swap the
+                # binary. JishuShell re-bootstraps ACL and resubmits jobs from
+                # on-disk instance configs on the next start.
+                _migrate_nomad_to_target "$current_version" || return 1
                 _ensure_jishushell_bin_in_path
                 return 0
             else
-                ui_warn "Nomad version too old: v${current_version} (need >= v${NOMAD_VERSION}) — upgrading..."
+                ui_warn "Nomad version too old: v${current_version} (need v${NOMAD_VERSION}) — upgrading..."
                 rm -f "$local_bin"
             fi
         fi
@@ -1421,6 +1529,180 @@ REPO
     return 1
 }
 
+# Auto-migrate from a higher Nomad version (e.g. 1.11.3 BSL) back to the
+# jishushell target (1.6.5 MPL). Called when install_nomad detects a local
+# binary whose semver is > NOMAD_VERSION. The migration is destructive to
+# Nomad's raft state (schema is not backward compatible) but preserves
+# instance configs under ~/.jishushell/instances/*, which is what jishushell
+# uses to resubmit jobs after reboot. A single tar.gz snapshot of the old
+# data_dir is kept under ~/.jishushell/nomad/backups/ for forensic inspection
+# — it is not a user-recovery mechanism (the schema can't be replayed).
+_migrate_nomad_to_target() {
+    local current_version="$1"
+    local local_bin="${JISHUSHELL_BIN_DIR}/nomad"
+
+    if [[ "$DRY_RUN" == "1" ]]; then
+        ui_info "[dry-run] Would migrate Nomad v${current_version} → v${NOMAD_VERSION}:"
+        ui_info "[dry-run]   1. Stage + verify new binary in /tmp"
+        ui_info "[dry-run]   2. Stop jishushell + nomad services"
+        ui_info "[dry-run]   3. Tar backup ${JISHUSHELL_HOME}/nomad/data → nomad/backups/data-<ts>.tar.gz"
+        ui_info "[dry-run]   4. Wipe raft state + nomad.env files (schema incompatible)"
+        ui_info "[dry-run]   5. Remove orphaned gateway-<alloc> containers"
+        ui_info "[dry-run]   6. Swap binary into ${local_bin}"
+        return 0
+    fi
+
+    ui_warn "Nomad v${current_version} > target v${NOMAD_VERSION} — auto-migrating (BSL → MPL)..."
+    ui_info "  Raft state is not backward-compatible; allocation history will be reset."
+    ui_info "  Instance configs under ${JISHUSHELL_HOME}/instances/ are preserved."
+
+    # ── Stage 1: download + verify new binary before touching anything ────
+    local stage_dir
+    stage_dir="$(mktemp -d)" || { ui_error "mktemp failed"; return 1; }
+    # shellcheck disable=SC2064
+    trap "rm -rf '$stage_dir'" RETURN
+
+    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 sums_url="https://releases.hashicorp.com/nomad/${NOMAD_VERSION}/nomad_${NOMAD_VERSION}_SHA256SUMS"
+
+    ui_info "Staging Nomad v${NOMAD_VERSION} (${platform}/${ARCH})..."
+    if ! retry_net "Download Nomad binary" 3 curl -fsSL "$download_url" -o "${stage_dir}/nomad.zip"; then
+        ui_error "Failed to download Nomad v${NOMAD_VERSION} — keeping existing v${current_version}"
+        return 1
+    fi
+    if ! retry_net "Download Nomad checksums" 3 curl -fsSL "$sums_url" -o "${stage_dir}/SHA256SUMS"; then
+        ui_error "Failed to download Nomad checksum file — aborting migration for security"
+        return 1
+    fi
+
+    local expected_hash actual_hash
+    expected_hash="$(grep "nomad_${NOMAD_VERSION}_${platform}_${ARCH}.zip" "${stage_dir}/SHA256SUMS" | awk '{print $1}')"
+    if [[ -z "$expected_hash" ]]; then
+        ui_error "No checksum entry for nomad_${NOMAD_VERSION}_${platform}_${ARCH}.zip — aborting"
+        return 1
+    fi
+    if command -v sha256sum &>/dev/null; then
+        actual_hash="$(sha256sum "${stage_dir}/nomad.zip" | awk '{print $1}')"
+    else
+        actual_hash="$(shasum -a 256 "${stage_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"
+        return 1
+    fi
+    ui_info "Checksum verified ✓"
+
+    if ! command -v unzip &>/dev/null; then
+        ui_info "Installing unzip..."
+        pkg_install unzip >/dev/null 2>&1
+    fi
+    if ! unzip -o "${stage_dir}/nomad.zip" nomad -d "${stage_dir}" >/dev/null 2>&1; then
+        if ! unzip -o "${stage_dir}/nomad.zip" -d "${stage_dir}" >/dev/null 2>&1; then
+            ui_error "Failed to extract staged Nomad archive"
+            return 1
+        fi
+    fi
+    chmod 755 "${stage_dir}/nomad" 2>/dev/null
+
+    local staged_version
+    staged_version="$("${stage_dir}/nomad" version 2>/dev/null | head -n1 | extract_semver || echo "")"
+    if [[ "$staged_version" != "$NOMAD_VERSION" ]]; then
+        ui_error "Staged binary reports v${staged_version:-unknown}, expected v${NOMAD_VERSION} — aborting"
+        return 1
+    fi
+    ui_success "Staged new Nomad binary v${staged_version}"
+
+    # ── Stage 2: destructive state changes begin ──────────────────────────
+    ui_info "Stopping services..."
+    ${SUDO} systemctl stop jishushell 2>/dev/null || true
+    ${SUDO} systemctl stop nomad 2>/dev/null || true
+    # pkill -f 'nomad agent' matches its own cmdline ("pkill -f nomad agent"
+    # literally contains the pattern) and self-terminates before reaching the
+    # real nomad process. Use pgrep -x nomad instead (exact proc-name match,
+    # pgrep's own comm is "pgrep" not "nomad").
+    local nomad_pids
+    nomad_pids="$(pgrep -x nomad 2>/dev/null | tr '\n' ' ')"
+    if [[ -n "$nomad_pids" ]]; then
+        # shellcheck disable=SC2086
+        ${SUDO} kill -TERM $nomad_pids 2>/dev/null || kill -TERM $nomad_pids 2>/dev/null || true
+        sleep 2
+        nomad_pids="$(pgrep -x nomad 2>/dev/null | tr '\n' ' ')"
+        if [[ -n "$nomad_pids" ]]; then
+            # shellcheck disable=SC2086
+            ${SUDO} kill -KILL $nomad_pids 2>/dev/null || kill -KILL $nomad_pids 2>/dev/null || true
+        fi
+    fi
+
+    # ── Stage 3: tar backup (single snapshot, overwrite any previous) ─────
+    local backup_file=""
+    local backup_dir="${JISHUSHELL_HOME}/nomad/backups"
+    if [[ -d "${JISHUSHELL_HOME}/nomad/data" ]]; then
+        mkdir -p "$backup_dir"
+        local ts
+        ts="$(date +%Y%m%d-%H%M%S)"
+        backup_file="${backup_dir}/data-${ts}.tar.gz"
+        ui_info "Backing up raft state → ${backup_file}"
+        if ! tar czf "$backup_file" -C "${JISHUSHELL_HOME}/nomad" data 2>/dev/null; then
+            ui_warn "Backup tar failed — continuing (raft state will still be wiped)"
+            backup_file=""
+        else
+            # Keep only the most recent snapshot to avoid unbounded disk growth
+            ls -t "${backup_dir}"/data-*.tar.gz 2>/dev/null | tail -n +2 | xargs -r rm -f
+        fi
+    fi
+
+    # ── Stage 4: wipe raft state + env files ─────────────────────────────
+    ${SUDO} rm -rf "${JISHUSHELL_HOME}/nomad/data"
+    rm -f "${JISHUSHELL_HOME}/nomad.env"
+    ${SUDO} rm -f /etc/jishushell/nomad.env
+
+    # ── Stage 5: orphaned gateway containers (alloc ids gone with raft) ──
+    # sudo npm install -g runs postinstall as the invoking user (typically pi),
+    # whose login shell may not have docker group access — the legacy install
+    # only granted docker to the nomad.service via SupplementaryGroups, not to
+    # the login shell. Try unprivileged first, fall back to sudo docker so this
+    # step works regardless of group membership.
+    if command -v docker &>/dev/null; then
+        local _docker="docker"
+        if ! docker ps >/dev/null 2>&1; then
+            _docker="${SUDO} docker"
+        fi
+        local gw_containers
+        gw_containers="$($_docker ps -a --format '{{.Names}}' 2>/dev/null | grep '^gateway-' || true)"
+        if [[ -n "$gw_containers" ]]; then
+            local gw_count
+            gw_count="$(echo "$gw_containers" | wc -l)"
+            echo "$gw_containers" | xargs -r $_docker rm -f >/dev/null 2>&1 || true
+            ui_info "Removed ${gw_count} orphaned gateway container(s)"
+        fi
+    fi
+
+    # ── Stage 6: swap binary into place (atomic via temp name + rename) ──
+    mkdir -p "${JISHUSHELL_BIN_DIR}"
+    local dest_tmp="${local_bin}.tmp.$$"
+    if ! cp "${stage_dir}/nomad" "$dest_tmp"; then
+        ui_error "Failed to copy new Nomad binary into place"
+        [[ -n "$backup_file" ]] && ui_error "  Backup preserved at: ${backup_file}"
+        return 1
+    fi
+    chmod 755 "$dest_tmp"
+    if ! mv -f "$dest_tmp" "$local_bin"; then
+        ui_error "Failed to swap Nomad binary"
+        [[ -n "$backup_file" ]] && ui_error "  Backup preserved at: ${backup_file}"
+        rm -f "$dest_tmp"
+        return 1
+    fi
+
+    ui_success "Nomad migrated to v${NOMAD_VERSION}"
+    [[ -n "$backup_file" ]] && ui_info "  Backup (forensic, not self-recovery): ${backup_file}"
+    ui_info "  JishuShell will re-bootstrap ACL and resubmit jobs from instance configs on next start."
+    return 0
+}
+
 _install_nomad_binary() {
     local dest="${JISHUSHELL_BIN_DIR}/nomad"
 
@@ -1531,17 +1813,29 @@ _install_nomad_binary() {
     ui_success "Nomad installed: v${installed_version} → ${dest}"
 }
 
-# Add ~/.jishushell/bin to PATH in shell startup files and current session
+# Add ~/.jishushell/bin and npm global 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"
+
+    # Also ensure npm global bin is in PATH (for `npm install -g` with custom prefix)
+    local npm_bin=""
+    if command -v npm &>/dev/null; then
+        npm_bin="$(npm config get prefix 2>/dev/null)/bin"
+    fi
+
+    # Build PATH line: include npm global bin if it differs from jishushell bin
     local init_line="export PATH=\"${bin_dir}:\$PATH\""
+    if [[ -n "$npm_bin" && "$npm_bin" != "$bin_dir" && -d "$npm_bin" ]]; then
+        init_line="export PATH=\"${bin_dir}:${npm_bin}:\$PATH\""
+        export PATH="${npm_bin}:${PATH}"
+    fi
 
     # 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"
+        ui_info "[dry-run] Would add PATH entries in shell startup files"
         return 0
     fi
 
@@ -1550,7 +1844,7 @@ _ensure_jishushell_bin_in_path() {
     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}"
+            ui_info "Added PATH entries in ${rc}"
             added=1
         fi
     done
@@ -1587,6 +1881,14 @@ _ensure_nomad_hcl() {
     # Dirs are created by the current user — no sudo needed
     chown -R "${REAL_USER}:${REAL_GID:-${REAL_USER}}" "${JISHUSHELL_HOME}" 2>/dev/null || true
 
+    # Loopback interface name: lo0 on macOS, lo on Linux.
+    # Forces Nomad to fingerprint 127.0.0.1 as the node IP so Docker port
+    # publishing binds to loopback instead of the LAN IP.  On macOS+Colima the
+    # LAN IP doesn't exist inside the Lima VM, causing "cannot assign requested
+    # address" when Docker tries to bind to it.
+    local loopback_iface="lo"
+    [[ "$OS" == "macos" ]] && loopback_iface="lo0"
+
     cat > "$config_file" << NOMAD_HCL
 data_dir = "${nomad_data_dir}"
 
@@ -1608,6 +1910,7 @@ server {
 client {
   enabled = true
   servers = ["127.0.0.1:4647"]
+  network_interface = "${loopback_iface}"
   alloc_dir = "${nomad_alloc_dir}"
 
   drain_on_shutdown {
@@ -1745,14 +2048,17 @@ install_nomad_systemd() {
 
     _ensure_nomad_hcl
 
+    # Nomad 1.6.5's docker driver fingerprint requires euid==0 (PR #18197 lifted
+    # the root requirement only in 1.7+, which is BSL). The panel stays as the
+    # installing user via a separate unit; it talks to this agent over HTTP so
+    # ~/.jishushell/nomad/data/ can be root-owned without breaking anything.
     local service_content="[Unit]
 Description=Nomad Agent
 After=network-online.target docker.service
 Wants=network-online.target
 
 [Service]
-User=${REAL_USER}
-SupplementaryGroups=docker
+User=root
 Type=simple
 EnvironmentFile=-/etc/jishushell/nomad.env
 ExecStart=${nomad_bin} agent -config=${config_file}
@@ -1775,8 +2081,12 @@ WantedBy=multi-user.target"
         need_reload=1
     fi
 
-    # Ensure Nomad data dirs are owned by the real user before the service starts
+    # Keep the real user owning ~/.jishushell except for Nomad's own state,
+    # which must be root-owned because the agent runs as root for driver fingerprinting.
     chown -R "${REAL_USER}:${REAL_GID:-${REAL_USER}}" "${JISHUSHELL_HOME}" 2>/dev/null || true
+    if [[ -d "${nomad_config_dir}/data" ]]; then
+        ${SUDO} chown -R root:root "${nomad_config_dir}/data" 2>/dev/null || true
+    fi
 
     if [[ $need_reload -eq 1 ]]; then
         ${SUDO} systemctl daemon-reload
@@ -1805,10 +2115,10 @@ _install_nomad_launchd() {
 
     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
+    # Always use JishuShell's private Colima socket — hardcoded, not runtime-detected.
+    # Colima may not be running yet when the plist is written; runtime fallback would
+    # pick the wrong socket (Docker Desktop or /var/run/docker.sock).
+    local docker_sock="${_COLIMA_SOCKET}"
 
     cat > "$plist_path" << PLIST
 <?xml version="1.0" encoding="UTF-8"?>
@@ -1870,6 +2180,54 @@ 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
+}
+
+_pin_openclaw_image_if_needed() {
+    local image="$1"
+    if [[ -z "${image}" ]]; then
+        return 1
+    fi
+    if [[ ! "${image}" =~ :(latest|slim)$ ]]; then
+        printf '%s' "${image}"
+        return 0
+    fi
+
+    local version=""
+    version="$(docker_exec run --rm --entrypoint node "${image}" -p "require('/app/node_modules/openclaw/package.json').version" 2>/dev/null | tr -d '\r\n')"
+    if [[ ! "${version}" =~ ^[0-9]+\.[0-9]+\.[0-9]+ ]]; then
+        printf '%s' "${image}"
+        return 0
+    fi
+
+    local repo="${image%:*}"
+    local pinned="${repo}:${version}"
+    if docker_exec image inspect "${pinned}" &>/dev/null 2>&1; then
+        printf '%s' "${pinned}"
+        return 0
+    fi
+
+    if docker_exec tag "${image}" "${pinned}" &>/dev/null 2>&1; then
+        docker_exec rmi "${image}" &>/dev/null 2>&1 || true
+        printf '%s' "${pinned}"
+        return 0
+    fi
+
+    printf '%s' "${image}"
+    return 0
+}
+
 # Install OpenClaw npm package on the host (for process manager / raw_exec modes).
 # Skipped when using official Docker image.
 _install_openclaw_npm() {
@@ -1921,25 +2279,15 @@ install_openclaw() {
         return 1
     fi
 
+    local docker_tag="${OPENCLAW_DOCKER_TAG}"
+    local configured_tag=""
+
     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)"
+        ui_info "[dry-run] Would: docker pull ${docker_tag} (fallback: local build)"
         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
-
-    # ── Step 2: Ensure Docker daemon is accessible ────────────────────────────
+    # ── Step 1: 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"
@@ -1950,7 +2298,7 @@ install_openclaw() {
         else
             ui_warn "Docker daemon is not reachable"
             if [[ "$OS" == "macos" ]]; then
-                ui_warn "Make sure Docker Desktop is running"
+                ui_warn "Run: COLIMA_HOME=${_COLIMA_HOME} colima start ${_COLIMA_PROFILE}"
             else
                 ui_warn "Ensure Docker is running: sudo systemctl start docker"
             fi
@@ -1958,49 +2306,90 @@ install_openclaw() {
         fi
     fi
 
-    # ── Step 3: Skip if image already exists ──────────────────────────────────
+    # ── Step 2: Reuse the currently configured pinned image if it already
+    # exists locally. This avoids re-pulling :latest on machines where the
+    # running JishuShell service has already migrated panel.json from a mutable
+    # tag (e.g. :latest) to an immutable version tag (e.g. :2026.4.9).
+    configured_tag="$(_read_openclaw_image_from_panel)"
+    if [[ -n "${configured_tag}" ]] && docker_exec image inspect "${configured_tag}" &>/dev/null 2>&1; then
+        OPENCLAW_IMAGE="$(_pin_openclaw_image_if_needed "${configured_tag}")"
+        _save_openclaw_image_to_panel "${OPENCLAW_IMAGE}"
+        ui_success "Docker image ${OPENCLAW_IMAGE} already exists — reusing configured image"
+        return 0
+    fi
+
+    # ── Step 3: Skip if the requested install 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"
+        OPENCLAW_IMAGE="$(_pin_openclaw_image_if_needed "${docker_tag}")"
+        _save_openclaw_image_to_panel "${OPENCLAW_IMAGE}"
+        ui_success "Docker image ${OPENCLAW_IMAGE} already exists — skipping"
         return 0
     fi
 
-    # ── Step 4: Build Docker image (npm package + Python) ─────────────────────
-    local pkg_dir="${JISHUSHELL_HOME}/packages/openclaw"
+    # ── Step 4: Pull from registry, fallback to local build ──────────────────
+    ui_info "Pulling OpenClaw Docker image: ${docker_tag} ..."
+    log_detail ""
+    log_detail "[$(date '+%H:%M:%S')] docker pull ${docker_tag}"
+    if log_cmd docker_exec pull "${docker_tag}"; then
+        OPENCLAW_IMAGE="$(_pin_openclaw_image_if_needed "${docker_tag}")"
+        _save_openclaw_image_to_panel "${OPENCLAW_IMAGE}"
+        ui_success "OpenClaw Docker image pulled: ${OPENCLAW_IMAGE}"
+        return 0
+    fi
+
+    # ── Step 3b: Fallback — build locally using bundled Dockerfile ────
+    ui_warn "Pull failed, falling back to local build..."
+
+    # Locate the bundled Dockerfile.openclaw-slim + openclaw-entry.sh.
+    # Both ship at the npm package root, alongside the install/ directory,
+    # so from this script's perspective they are one level up.
+    local script_dir
+    if [[ -n "${BASH_SOURCE[0]:-}" ]]; then
+        script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    else
+        script_dir="${PWD}"
+    fi
+    local dockerfile_src="${script_dir}/../Dockerfile.openclaw-slim"
+    local entrypoint_src="${script_dir}/../openclaw-entry.sh"
+
+    if [[ ! -f "${dockerfile_src}" || ! -f "${entrypoint_src}" ]]; then
+        ui_error "Bundled build files not found near ${script_dir}/.."
+        ui_error "Expected: Dockerfile.openclaw-slim and openclaw-entry.sh"
+        return 1
+    fi
+
+    local build_ctx
+    build_ctx="$(mktemp -d)"
+    trap "rm -rf '${build_ctx}'" EXIT
 
-    # Write Dockerfile into the npm package directory (build context)
-    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
-
-    ui_info "Building Docker image: ${docker_tag} (npm package + Python)..."
+    cp "${dockerfile_src}" "${build_ctx}/Dockerfile.openclaw-slim"
+    cp "${entrypoint_src}" "${build_ctx}/openclaw-entry.sh"
+
+    # Query current OpenClaw version from npm so the --build-arg busts the
+    # Docker layer cache for the `RUN npm install openclaw@${ver}` step.
+    # Fall back to "latest" if npm is unreachable.
+    local openclaw_ver
+    openclaw_ver="$(npm view openclaw version 2>/dev/null)"
+    if [[ -z "${openclaw_ver}" ]]; then
+        openclaw_ver="latest"
+    fi
+    log_detail "Resolved OpenClaw version for build: ${openclaw_ver}"
+
+    ui_info "Building OpenClaw Docker image locally: ${docker_tag} (openclaw@${openclaw_ver}) ..."
     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
+    log_detail "[$(date '+%H:%M:%S')] docker build --network=host --build-arg OPENCLAW_VERSION=${openclaw_ver} -f Dockerfile.openclaw-slim -t ${docker_tag} ${build_ctx}"
+    if log_cmd docker_exec build --network=host \
+        --build-arg "OPENCLAW_VERSION=${openclaw_ver}" \
+        -f "${build_ctx}/Dockerfile.openclaw-slim" \
+        -t "${docker_tag}" "${build_ctx}"; 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)"
+        rm -rf "${build_ctx}"
+        trap - EXIT
+        ui_success "OpenClaw Docker image built: ${docker_tag}"
     else
-        rm -f "${pkg_dir}/Dockerfile"
+        rm -rf "${build_ctx}"
+        trap - EXIT
         ui_error "Failed to build OpenClaw Docker image"
         return 1
     fi
@@ -2028,6 +2417,14 @@ _prompt_openclaw_skip() {
     esac
 }
 
+jishushell_package_spec() {
+    if [[ "${JISHUSHELL_VERSION_OVERRIDE}" == "1" || "${JISHUSHELL_NPM_VERSION}" != "latest" ]]; then
+        printf 'jishushell@%s' "${JISHUSHELL_NPM_VERSION}"
+        return 0
+    fi
+    printf 'jishushell'
+}
+
 # show_install_plan [--with-jishushell]
 show_install_plan() {
     local with_jishushell=0
@@ -2043,17 +2440,19 @@ show_install_plan() {
     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)"
+    ui_kv "OpenClaw"    "$(if [[ "${SKIP_OPENCLAW}" == "1" ]]; then echo 'skip'; else echo "docker pull ${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}"
+            if [[ "${JISHUSHELL_VERSION_OVERRIDE}" != "1" && "${JISHUSHELL_NPM_VERSION}" == "latest" ]]; then
+                for _c in "${JISHU_SCRIPT_DIR}"/jishushell-*.tgz; do
+                    [[ -f "$_c" ]] && { _plan_tgz="$(basename "$_c")"; break; }
+                done
+            fi
+            _plan_jishu="${_plan_tgz:+npm install -g ${_plan_tgz} (local)}${_plan_tgz:-npm install -g $(jishushell_package_spec)}"
         fi
         ui_kv "JishuShell"         "$_plan_jishu"
         ui_kv "JishuShell service" "$(if [[ $SKIP_JISHUSHELL_SERVICE -eq 1 ]]; then echo 'skip'; else echo 'register autostart'; fi)"
@@ -2114,7 +2513,15 @@ show_summary() {
     fi
 
     if [[ "${SKIP_OPENCLAW}" != "1" ]]; then
-        if [[ -n "${OPENCLAW_IMAGE}" ]] && docker_exec image inspect "${OPENCLAW_IMAGE}" &>/dev/null 2>&1; then
+        local _summary_openclaw_image=""
+        _summary_openclaw_image="$(_read_openclaw_image_from_panel)"
+        if [[ -z "${_summary_openclaw_image}" && -n "${OPENCLAW_IMAGE}" ]]; then
+            _summary_openclaw_image="${OPENCLAW_IMAGE}"
+        fi
+
+        if [[ -n "${_summary_openclaw_image}" ]] && docker_exec image inspect "${_summary_openclaw_image}" &>/dev/null 2>&1; then
+            ui_kv "OpenClaw" "✓ ${_summary_openclaw_image}"
+        elif [[ -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"
@@ -2210,16 +2617,20 @@ install_jishushell() {
     fi
 
     if [[ "$DRY_RUN" == "1" ]]; then
+        local jishushell_pkg_spec
+        jishushell_pkg_spec="$(jishushell_package_spec)"
         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 [[ "${JISHUSHELL_VERSION_OVERRIDE}" != "1" && "${JISHUSHELL_NPM_VERSION}" == "latest" ]]; then
+            for _c in "${JISHU_SCRIPT_DIR}"/jishushell-*.tgz; do
+                [[ -f "$_c" ]] && { _dry_tgz="$_c"; break; }
+            done
+        fi
         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}"
+            ui_info "[dry-run] Would: npm install -g ${jishushell_pkg_spec}${_dry_reg}"
         fi
         ui_info "[dry-run] Would write wrapper: ${JISHUSHELL_BIN_DIR}/jishushell-panel-start"
         return 0
@@ -2250,6 +2661,8 @@ install_jishushell() {
         return 1
     fi
 
+    local jishushell_pkg_spec
+    jishushell_pkg_spec="$(jishushell_package_spec)"
     local npm_registry_args=()
     if [[ -n "${NPM_REGISTRY:-}" ]]; then
         if [[ ! "$NPM_REGISTRY" =~ ^https?:// ]]; then
@@ -2257,9 +2670,9 @@ install_jishushell() {
             return 1
         fi
         npm_registry_args=("--registry" "${NPM_REGISTRY}")
-        ui_info "Installing jishushell from ${NPM_REGISTRY}..."
+        ui_info "Installing ${jishushell_pkg_spec} from ${NPM_REGISTRY}..."
     else
-        ui_info "Installing jishushell from public npm registry..."
+        ui_info "Installing ${jishushell_pkg_spec} from public npm registry..."
     fi
 
     # When jishushell is already installed (e.g. running as npm postinstall hook),
@@ -2268,12 +2681,14 @@ install_jishushell() {
         # 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
+        if [[ "${JISHUSHELL_VERSION_OVERRIDE}" != "1" && "${JISHUSHELL_NPM_VERSION}" == "latest" ]]; then
+            for _tgz_candidate in "${JISHU_SCRIPT_DIR}"/jishushell-*.tgz; do
+                if [[ -f "$_tgz_candidate" ]]; then
+                    tgz_path="$_tgz_candidate"
+                    break
+                fi
+            done
+        fi
 
         # Export a sentinel so post-install.sh (triggered by npm's postinstall
         # lifecycle hook) knows it was launched from inside jishu-install.sh and
@@ -2289,10 +2704,10 @@ install_jishushell() {
                 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
+            log_detail "[$(date '+%H:%M:%S')] ${npm_bin} install -g ${jishushell_pkg_spec} ${npm_registry_args[*]:-}"
+            if ! log_cmd "$npm_bin" install -g "${jishushell_pkg_spec}" "${npm_registry_args[@]}"; then
                 unset JISHU_RUNNING_IN_INSTALLER
-                ui_error "npm install -g jishushell failed"
+                ui_error "npm install -g ${jishushell_pkg_spec} failed"
                 return 1
             fi
         fi
@@ -2462,7 +2877,9 @@ WantedBy=multi-user.target"
         ${SUDO} systemctl restart jishushell 2>/dev/null || true
         ui_success "JishuShell systemd service updated and restarted"
     else
-        ui_success "JishuShell systemd service already installed"
+        # Package may have been upgraded — always restart to pick up new code
+        ${SUDO} systemctl restart jishushell 2>/dev/null || true
+        ui_success "JishuShell systemd service restarted"
     fi
 }
 
@@ -2594,8 +3011,17 @@ parse_args() {
                 shift
                 OPENCLAW_NPM_VERSION="${1:?--openclaw-version requires a version argument (e.g. 3.24)}"
                 ;;
+            --openclaw-docker-tag)
+                shift
+                OPENCLAW_DOCKER_TAG="${1:?--openclaw-docker-tag requires a tag argument (e.g. ghcr.io/x-aijishu/openclaw-runtime:2026.4.9)}"
+                ;;
             --skip-jishushell)         SKIP_JISHUSHELL=1 ;;
             --skip-jishushell-service) SKIP_JISHUSHELL_SERVICE=1 ;;
+            --jishushell-version)
+                shift
+                JISHUSHELL_NPM_VERSION="${1:?--jishushell-version requires a version argument (e.g. 0.4.9)}"
+                JISHUSHELL_VERSION_OVERRIDE=1
+                ;;
             --skip)
                 shift
                 IFS=',' read -ra _steps <<< "${1:-}"
@@ -2661,10 +3087,16 @@ Options:
   --skip-docker              Skip step 2: Docker installation
   --skip-nomad               Skip step 3: Nomad installation
   --skip-openclaw            Skip step 4: OpenClaw installation
+    --openclaw-docker-tag <tag>
+                                                         Pull a specific OpenClaw image tag
+                                                         (e.g. --openclaw-docker-tag ghcr.io/x-aijishu/openclaw-runtime:2026.4.9)
   --skip-jishushell          Skip step 5: JishuShell installation
   --skip-jishushell-service  Skip step 6: JishuShell service registration
+    --jishushell-version <ver>
+                                                         Install a specific jishushell version
+                                                         (e.g. --jishushell-version 0.4.9)
   --registry <url>           Use a custom npm registry for all installs
-                             (e.g. --registry http://10.188.0.22:4873/)
+                             (e.g. --registry http://127.0.0.1:4873/)
   --yes, -y                  Skip all confirmation prompts
   --help, -h                 Show this help message
 
@@ -2672,7 +3104,7 @@ Steps:
   1  Node.js   (via nvm)
   2  Docker
   3  Nomad
-  4  OpenClaw  (npm install + docker build)
+  4  OpenClaw  (docker pull / local build)
   5  JishuShell
   6  JishuShell service registration (autostart)
 
@@ -2680,12 +3112,16 @@ 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})
+    JISHUSHELL_NPM_VERSION
+                                                 Specify jishushell npm package version (default: latest)
   OPENCLAW_NPM_VERSION  Specify openclaw npm package version (default: latest)
-  OPENCLAW_DOCKER_TAG   Override built Docker image tag      (default: jishushell-base:v1)
+    OPENCLAW_DOCKER_TAG   Override OpenClaw Docker image tag   (default: ${OPENCLAW_DOCKER_TAG})
   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
+Version flags:
+    --jishushell-version <ver>  Install a specific jishushell version, e.g. --jishushell-version 0.4.9
+    --openclaw-version <ver>    Install a specific openclaw version, e.g. --openclaw-version 3.24
+    --openclaw-docker-tag <tag> Pull a specific OpenClaw image tag, e.g. --openclaw-docker-tag ghcr.io/x-aijishu/openclaw-runtime:2026.4.9
   NO_PROMPT             Set to 1 to skip interactive prompts
   VERBOSE               Set to 1 for verbose output
 
@@ -2735,27 +3171,36 @@ _prompt_install_confirm() {
         echo -e "  commercial use, competitive offerings, or redistribution."
         echo ""
 
-        if [[ $SKIP_DOCKER -eq 0 ]]; then
+        if [[ $SKIP_DOCKER -eq 0 && "$OS" == "linux" ]]; 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 -e "  ${MUTED}  Docker Engine (container runtime — Linux)${NC}"
+            echo -e "  ${MUTED}    URL     : https://github.com/moby/moby${NC}"
+            echo -e "  ${MUTED}    License : Apache License, Version 2.0${NC}"
+            echo -e "  ${MUTED}    Author  : Docker, Inc.${NC}"
+            echo -e "  ${MUTED}  https://github.com/moby/moby/blob/master/LICENSE${NC}"
+            echo ""
+        fi
+        if [[ $SKIP_DOCKER -eq 0 && "$OS" == "macos" ]]; then
+            echo -e "  ${BOLD}Colima${NC}"
+            echo -e "  ${MUTED}  Colima (container runtime — macOS)${NC}"
+            echo -e "  ${MUTED}    URL     : https://github.com/abiosoft/colima${NC}"
+            echo -e "  ${MUTED}    License : MIT License${NC}"
+            echo -e "  ${MUTED}              https://github.com/abiosoft/colima/blob/main/LICENSE${NC}"
+            echo -e "  ${MUTED}    Author  : Abiola Ibrahim${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 -e "  ${BOLD}Nomad${NC}"
+            echo -e "  ${MUTED}  Nomad v${NOMAD_VERSION} (last MPL 2.0 release in the 1.6.x line)${NC}"
+            echo -e "  ${MUTED}    URL     : https://github.com/hashicorp/nomad/tree/v${NOMAD_VERSION}${NC}"
+            echo -e "  ${MUTED}    License : Mozilla Public License 2.0${NC}"
+            echo -e "  ${MUTED}              https://github.com/hashicorp/nomad/blob/v${NOMAD_VERSION}/LICENSE${NC}"
+            echo -e "  ${MUTED}    Author  : HashiCorp, Inc.${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 -e "  ${ACCENT}─────────────────────────────────────────────────────────${NC}"
+        echo -e "  By continuing you acknowledge that you have read the above"
+        echo -e "  notices and agree to each package's license terms."
         echo ""
     } >/dev/tty
 
@@ -2767,6 +3212,9 @@ _prompt_install_confirm() {
             exit 0
             ;;
     esac
+
+    echo "" >/dev/tty
+    echo -e "  ${INFO}sudo privileges are required to write to system directories.${NC}" >/dev/tty
     echo "" >/dev/tty
 }
 
@@ -2885,7 +3333,7 @@ _jishu_install_main() {
     # 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 ) &
+            ( while true; do sudo -n true 2>/dev/null; sleep 60; done ) &>/dev/null &
             _SUDO_KEEPALIVE_PID=$!
             disown "$_SUDO_KEEPALIVE_PID" 2>/dev/null || true
         fi
@@ -2900,10 +3348,6 @@ _jishu_install_main() {
     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