jishushell 0.4.10 → 0.4.24-beta.2

package/dist/services/setup-manager.js

@@ -1,30 +1,30 @@
 import { execFileSync, execSync, spawn as nodeSpawn } from "child_process";
-import { chmodSync, existsSync, readFileSync, symlinkSync, unlinkSync } from "fs";
-import { userInfo } from "node:os";
+import { chmodSync, copyFileSync, existsSync, mkdtempSync, readFileSync, renameSync, rmSync, symlinkSync, unlinkSync } from "fs";
+import { userInfo, platform as osPlatform } from "node:os";
 import { randomBytes } from "node:crypto";
 import { tmpdir } from "node:os";
 import { dirname, join } from "path";
 import { StringDecoder } from "string_decoder";
 import { fileURLToPath } from "url";
-import { JISHUSHELL_HOME, getPanelConfig, savePanelConfig, setOpenclawDockerImage, getOpenclawDockerImage, DEFAULT_OPENCLAW_DOCKER_IMAGE } from "../config.js";
+import { JISHUSHELL_HOME, getPanelConfig, savePanelConfig, setOpenclawDockerImage, getOpenclawDockerImage, DEFAULT_OPENCLAW_DOCKER_IMAGE, getRuntimeCatalogEntry, OPENCLAW_MODULES, OPENCLAW_BIN_DIR, } from "../config.js";
 import { ensureDirContainer, ensureDirHost, writeConfigFile, writeSecretFile, writeExecutableFile, writeSystemTmpFile } from "../utils/fs.js";
+import { buildDockerClientEnv, managedColimaSocketPath, resolveDockerHost } from "../utils/docker-host.js";
+import { getAdapter, listRegisteredAdapters } from "./runtime/index.js";
+// Internal usage of task primitives — re-exports further down preserve the
+// public import surface used by runtime/adapters/*, routes, and CLI.
+import { createTask, emitTask, getRunningTasks } from "./task-registry.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // ── Paths ──────────────────────────────────────────────────────────
 const BIN_DIR = join(JISHUSHELL_HOME, "bin");
-const PACKAGES_DIR = join(JISHUSHELL_HOME, "packages");
-const OPENCLAW_PKG_DIR = join(PACKAGES_DIR, "openclaw");
-/** npm global-prefix layout: lib/node_modules/<pkg>, bin/<cmd> */
-const OPENCLAW_MODULES = join(OPENCLAW_PKG_DIR, "lib", "node_modules");
-const OPENCLAW_BIN_DIR = join(OPENCLAW_PKG_DIR, "bin");
 const NOMAD_BIN = join(BIN_DIR, "nomad");
 const NOMAD_CONFIG_DIR = join(JISHUSHELL_HOME, "nomad");
 const NOMAD_DATA_DIR = join(JISHUSHELL_HOME, "nomad", "data");
 const NOMAD_ALLOC_DIR = join(JISHUSHELL_HOME, "nomad", "data", "alloc");
 const COLIMA_DIR = join(JISHUSHELL_HOME, "colima");
 const COLIMA_PROFILE = "jishushell";
-const COLIMA_SOCKET = join(COLIMA_DIR, COLIMA_PROFILE, "docker.sock");
-const NOMAD_VERSION = "1.11.3";
+const COLIMA_SOCKET = managedColimaSocketPath(JISHUSHELL_HOME, COLIMA_PROFILE);
+const NOMAD_VERSION = "1.6.5";
 let _serverPort = 8090;
 export function setServerPort(port) { _serverPort = port; }
 // ── Resolve non-root service user (board-agnostic) ─────────────────
@@ -76,72 +76,13 @@ function resolveServiceUser() {
     catch { /* /etc/passwd unreadable */ }
     throw new Error("Cannot determine service user. Run with a non-root user or set SUDO_UID.");
 }
-const tasks = new Map();
-const TASK_MAX_AGE = 600000; // 10 minutes
-// Periodically clean up completed tasks to prevent memory accumulation
-setInterval(() => {
-    const now = Date.now();
-    for (const [id, task] of tasks) {
-        if (task.status !== "running" && now - parseInt(id.split("-").pop() || "0") > TASK_MAX_AGE) {
-            tasks.delete(id);
-        }
-    }
-}, 60000).unref();
-function createTask(name) {
-    const id = `${name}-${Date.now()}`;
-    const task = { id, name, status: "running", events: [], listeners: new Set() };
-    tasks.set(id, task);
-    return task;
-}
-const MAX_TASK_EVENTS = 500;
-function emitTask(task, event) {
-    task.events.push(event);
-    // Cap events to prevent unbounded memory growth on long-running tasks
-    // (e.g., Docker pull/build can produce thousands of progress lines)
-    if (task.events.length > MAX_TASK_EVENTS) {
-        task.events.splice(0, task.events.length - MAX_TASK_EVENTS);
-    }
-    for (const listener of task.listeners) {
-        listener(event);
-    }
-}
-export function getTask(id) {
-    return tasks.get(id);
-}
-export function getTaskSnapshot(id) {
-    const task = tasks.get(id);
-    if (!task)
-        return undefined;
-    return {
-        id: task.id,
-        name: task.name,
-        status: task.status,
-        events: [...task.events],
-    };
-}
-/** Find running tasks, optionally filtered by name prefix */
-export function getRunningTasks(namePrefix) {
-    const result = [];
-    for (const [id, task] of tasks) {
-        if (task.status !== "running")
-            continue;
-        if (namePrefix && !task.name.startsWith(namePrefix))
-            continue;
-        result.push({ id, name: task.name });
-    }
-    return result;
-}
-export function subscribeTask(id, listener) {
-    const task = tasks.get(id);
-    if (!task)
-        return null;
-    task.listeners.add(listener);
-    // Send existing events
-    for (const event of task.events) {
-        listener(event);
-    }
-    return () => task.listeners.delete(listener);
-}
+// ── Task tracker (for SSE progress) ────────────────────────────────
+// Storage, event dispatch, and subscribe plumbing now live in
+// task-registry.ts so non-setup callers (runtime-apps/*) can publish
+// tasks without pulling in the rest of setup-manager's bootstrap
+// surface. These re-exports preserve the original import surface used
+// by runtime/adapters/*, routes, and CLI.
+export { createTask, emitTask, getTask, getTaskSnapshot, getRunningTasks, subscribeTask, } from "./task-registry.js";
 const ANSI_ESCAPE_RE = /\u001B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g;
 function sanitizeTaskLine(line) {
     return line
@@ -150,7 +91,7 @@ function sanitizeTaskLine(line) {
         .trimEnd();
 }
 /** Run a shell command as a spawned process, streaming output to a task */
-function spawnWithTask(task, cmd, args, options = {}) {
+export function spawnWithTask(task, cmd, args, options = {}) {
     return new Promise((resolve) => {
         const env = { ...process.env, ...options.env };
         const child = nodeSpawn(cmd, args, {
@@ -214,7 +155,7 @@ function spawnWithTask(task, cmd, args, options = {}) {
     });
 }
 // ── Progress parsers ───────────────────────────────────────────────
-function npmProgressParser(line) {
+export function npmProgressParser(line) {
     // npm shows "added X packages" at the end
     if (line.includes("added") && line.includes("packages"))
         return 100;
@@ -223,7 +164,7 @@ function npmProgressParser(line) {
         return null; // just a log line
     return null;
 }
-function dockerBuildProgressParser(line) {
+export function dockerBuildProgressParser(line) {
     // Docker build steps: "Step 1/6", "Step 2/6", etc.
     const legacyMatch = line.match(/Step\s+(\d+)\/(\d+)/);
     if (legacyMatch) {
@@ -248,7 +189,7 @@ function curlProgressParser(line) {
     return null;
 }
 // ── Dir size tracker for npm installs ──────────────────────────────
-function getDirSizeMB(dir) {
+export function getDirSizeMB(dir) {
     try {
         const result = execFileSync("du", ["-sm", dir], { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
         return parseInt(result.split("\t")[0]) || 0;
@@ -284,21 +225,34 @@ function isPortListening(port) {
     if (!Number.isInteger(port) || port < 1 || port > 65535)
         return false;
     const p = String(port);
+    const matchesPort = (output) => new RegExp(`:${p}\\s`).test(output);
     try {
         if (process.platform === "darwin") {
-            const result = execFileSync("lsof", ["-iTCP:" + p, "-sTCP:LISTEN", "-t"], { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
-            return result.trim().length > 0;
-        }
-        else {
-            // Linux: prefer ss, fall back to netstat
+            try {
+                const result = execFileSync("lsof", ["-iTCP:" + p, "-sTCP:LISTEN", "-t"], { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
+                if (result.trim().length > 0)
+                    return true;
+            }
+            catch {
+            }
             try {
                 const result = execFileSync("ss", ["-tlnp"], { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
-                return new RegExp(`:${p}\\s`).test(result);
+                if (matchesPort(result))
+                    return true;
             }
             catch {
-                const result = execFileSync("netstat", ["-tlnp"], { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
-                return new RegExp(`:${p}\\s`).test(result);
             }
+            const result = execFileSync("netstat", ["-tlnp"], { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
+            return matchesPort(result);
+        }
+        // Linux: prefer ss, fall back to netstat
+        try {
+            const result = execFileSync("ss", ["-tlnp"], { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
+            return matchesPort(result);
+        }
+        catch {
+            const result = execFileSync("netstat", ["-tlnp"], { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
+            return matchesPort(result);
         }
     }
     catch {
@@ -360,9 +314,10 @@ export function ensureCgroupMemory() {
     return false;
 }
 function canAccessDockerDaemon(timeout = 10000) {
-    const env = process.platform === "darwin" && existsSync(COLIMA_SOCKET)
-        ? { ...process.env, DOCKER_HOST: `unix://${COLIMA_SOCKET}` }
-        : undefined;
+    const env = buildDockerClientEnv({
+        jishuHome: JISHUSHELL_HOME,
+        colimaProfile: COLIMA_PROFILE,
+    });
     try {
         execFileSync("docker", ["info"], { timeout, stdio: "ignore", env });
         return true;
@@ -386,7 +341,7 @@ function getDockerVersionLine(timeout = 10000) {
     catch { }
     return "installed";
 }
-export function getSetupStatus() {
+export async function getSetupStatus() {
     // Fast path: if setup is already complete, do lightweight checks before returning cached result
     const config = getPanelConfig();
     if (config.service_manager) {
@@ -433,6 +388,7 @@ export function getSetupStatus() {
                 ready,
                 providerConfigured: !!config.default_provider,
                 hasSudo: true,
+                runtimes: await buildRuntimesStatus(),
             };
         }
     }
@@ -512,7 +468,42 @@ export function getSetupStatus() {
         needsReboot = true;
     }
     const runningTasks = getRunningTasks();
-    return { node: nodeStatus, docker: dockerStatus, nomad: nomadStatus, openclaw: openclawStatus, ready, providerConfigured, dockerImageReady, hasSudo: checkSudo(), needsReboot, runningTasks: runningTasks.length ? runningTasks : undefined };
+    return { node: nodeStatus, docker: dockerStatus, nomad: nomadStatus, openclaw: openclawStatus, ready, providerConfigured, dockerImageReady, hasSudo: checkSudo(), needsReboot, runningTasks: runningTasks.length ? runningTasks : undefined, runtimes: await buildRuntimesStatus() };
+}
+/**
+ * Build the per-runtime install status block by iterating over every
+ * registered adapter. A new adapter that implements `getInstallStatus()`
+ * automatically appears here — no change required in this function.
+ *
+ * Each probe is bounded by a short timeout so a hung adapter (slow docker
+ * socket, DNS stall) cannot block the `/api/setup/status` endpoint. This
+ * mirrors the pattern used by `routes/runtime.ts:probeInstallStatus` so
+ * Setup wizard and `/api/runtime/catalog` see a consistent view.
+ */
+const BUILD_RUNTIMES_PROBE_TIMEOUT_MS = 2500;
+async function buildRuntimesStatus() {
+    const adapters = listRegisteredAdapters().filter((a) => typeof a.getInstallStatus === "function");
+    const probes = adapters.map(async (adapter) => {
+        try {
+            const status = await Promise.race([
+                Promise.resolve(adapter.getInstallStatus()),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("install-status probe timed out")), BUILD_RUNTIMES_PROBE_TIMEOUT_MS)),
+            ]);
+            if (!status)
+                return null;
+            const sync = status;
+            return [adapter.agentType, { ...sync, required: !!adapter.required }];
+        }
+        catch {
+            return null;
+        }
+    });
+    const out = {};
+    for (const result of await Promise.all(probes)) {
+        if (result)
+            out[result[0]] = result[1];
+    }
+    return Object.keys(out).length ? out : undefined;
 }
 // ── Upgrade Node.js ────────────────────────────────────────────────
 export async function upgradeNode(targetMajor = 22) {
@@ -769,6 +760,227 @@ function getNomadDownloadUrl() {
     const os = process.platform === "linux" ? "linux" : "darwin";
     return `https://releases.hashicorp.com/nomad/${NOMAD_VERSION}/nomad_${NOMAD_VERSION}_${os}_${arch}.zip`;
 }
+/**
+ * Signal nomad agents by exact process name (pgrep -x nomad) to avoid the
+ * classic pkill -f self-match bug: a command line like "pkill -f 'nomad agent'"
+ * literally contains the pattern and pkill kills itself before reaching the
+ * real nomad process. pgrep's own comm is "pgrep" (not "nomad") so -x nomad
+ * cannot self-match. Unprivileged kill is tried first; sudo -n as a fallback
+ * if the running nomad is owned by root (1.6.5 User=root unit).
+ */
+function killNomadByProcName() {
+    const collect = () => {
+        try {
+            const out = execSync("pgrep -x nomad 2>/dev/null || true", { encoding: "utf-8" }).trim();
+            return out.split("\n").filter(Boolean);
+        }
+        catch {
+            return [];
+        }
+    };
+    const sendSignal = (sig, pids) => {
+        if (pids.length === 0)
+            return;
+        try {
+            execFileSync("sudo", ["-n", "kill", `-${sig}`, ...pids], { timeout: 5000, stdio: "pipe" });
+            return;
+        }
+        catch { }
+        try {
+            execSync(`kill -${sig} ${pids.join(" ")} 2>/dev/null || true`, { timeout: 5000 });
+        }
+        catch { }
+    };
+    let pids = collect();
+    sendSignal("TERM", pids);
+    if (pids.length > 0) {
+        // Short grace period, then SIGKILL any survivors.
+        execSync("sleep 2");
+        pids = collect();
+        sendSignal("KILL", pids);
+    }
+}
+/** Compare two "a.b.c" semver strings; returns a > b. */
+function isNomadVersionGreater(a, b) {
+    const parse = (v) => v.replace(/^v/, "").split(".").map(n => parseInt(n, 10) || 0);
+    const [aMaj, aMin, aPat] = parse(a);
+    const [bMaj, bMin, bPat] = parse(b);
+    if (aMaj !== bMaj)
+        return aMaj > bMaj;
+    if (aMin !== bMin)
+        return aMin > bMin;
+    return aPat > bPat;
+}
+/**
+ * Auto-migrate from a higher Nomad version (e.g. 1.11.3 BSL) back to the
+ * jishushell target (1.6.5 MPL). Called when installNomad detects a local
+ * binary whose semver is > NOMAD_VERSION. Destructive to Nomad's raft state
+ * (schema is not backward compatible) but preserves instance configs under
+ * ~/.jishushell/instances/*. A single tar.gz snapshot of the old data_dir
+ * is kept under ~/.jishushell/nomad/backups/ for forensic inspection.
+ *
+ * Safe-first: the new binary is downloaded and verified BEFORE any existing
+ * state is touched. If any stage 1 step fails, state is untouched.
+ *
+ * Throws on failure so the caller's outer catch reports the error.
+ */
+async function migrateNomadToTarget(currentVersion) {
+    console.log(`[nomad] Auto-migrating v${currentVersion} → v${NOMAD_VERSION} (BSL → MPL)`);
+    console.log("[nomad]   Raft state is not backward-compatible; allocation history will be reset.");
+    console.log("[nomad]   Instance configs under ~/.jishushell/instances/ are preserved.");
+    // ── Stage 1: download + verify new binary into a staging dir ─────────
+    const stageDir = mkdtempSync(join(tmpdir(), "nomad-migrate-"));
+    let backupFile = "";
+    try {
+        const stagedBin = join(stageDir, "nomad");
+        const zipPath = join(stageDir, "nomad.zip");
+        const url = getNomadDownloadUrl();
+        const arch = process.arch === "arm64" ? "arm64" : "amd64";
+        const os = process.platform === "linux" ? "linux" : "darwin";
+        const sumsUrl = `https://releases.hashicorp.com/nomad/${NOMAD_VERSION}/nomad_${NOMAD_VERSION}_SHA256SUMS`;
+        const sumsPath = join(stageDir, "SHA256SUMS");
+        console.log(`[nomad] Staging v${NOMAD_VERSION} (${os}/${arch})...`);
+        execFileSync("curl", ["-fsSL", url, "-o", zipPath], { timeout: 300000, stdio: "pipe" });
+        execFileSync("curl", ["-fsSL", sumsUrl, "-o", sumsPath], { timeout: 30000, stdio: "pipe" });
+        const sums = readFileSync(sumsPath, "utf-8");
+        const sumLine = sums.split("\n").find(l => l.includes(`nomad_${NOMAD_VERSION}_${os}_${arch}.zip`));
+        if (!sumLine)
+            throw new Error(`No checksum entry for nomad_${NOMAD_VERSION}_${os}_${arch}.zip`);
+        const expected = sumLine.split(/\s+/)[0];
+        // Match the bash installer: prefer sha256sum (GNU coreutils, Linux),
+        // fall back to shasum -a 256 (BSD, macOS default — sha256sum is not
+        // preinstalled there). Without this, triggering auto-migration from
+        // the WebUI / Node path on macOS would fail even though the shell
+        // installer works fine.
+        let actual;
+        try {
+            actual = execSync(`sha256sum "${zipPath}" | awk '{print $1}'`, { encoding: "utf-8" }).trim();
+        }
+        catch {
+            actual = execSync(`shasum -a 256 "${zipPath}" | awk '{print $1}'`, { encoding: "utf-8" }).trim();
+        }
+        if (expected !== actual) {
+            throw new Error(`Nomad checksum mismatch: expected ${expected}, got ${actual}`);
+        }
+        console.log("[nomad] Checksum verified");
+        execFileSync("unzip", ["-o", zipPath, "-d", stageDir], { timeout: 30000 });
+        chmodSync(stagedBin, 0o755);
+        const stagedVersionLine = execFileSync(stagedBin, ["version"], { encoding: "utf-8", timeout: 5000 }).trim().split("\n")[0];
+        if (!stagedVersionLine.includes(`v${NOMAD_VERSION}`)) {
+            throw new Error(`Staged binary reports "${stagedVersionLine}", expected v${NOMAD_VERSION}`);
+        }
+        console.log(`[nomad] Staged ${stagedVersionLine}`);
+        // ── Stage 2: destructive state changes begin ───────────────────────
+        console.log("[nomad] Stopping services...");
+        try {
+            execFileSync("sudo", ["-n", "systemctl", "stop", "jishushell"], { timeout: 15000, stdio: "pipe" });
+        }
+        catch { }
+        try {
+            execFileSync("sudo", ["-n", "systemctl", "stop", "nomad"], { timeout: 15000, stdio: "pipe" });
+        }
+        catch { }
+        // pkill -f 'nomad agent' matches pkill's own cmdline and self-terminates
+        // before reaching the real nomad process. Use pgrep -x nomad (exact proc
+        // name match; pgrep's comm is "pgrep") to avoid the self-match bug.
+        killNomadByProcName();
+        await new Promise(r => setTimeout(r, 2000));
+        // ── Stage 3: tar backup (single snapshot, overwrite any previous) ──
+        const backupDir = join(NOMAD_CONFIG_DIR, "backups");
+        if (existsSync(NOMAD_DATA_DIR)) {
+            try {
+                ensureDirHost(backupDir);
+            }
+            catch { }
+            const ts = new Date().toISOString().replace(/[-:]/g, "").replace(/\..+/, "").replace("T", "-");
+            const candidate = join(backupDir, `data-${ts}.tar.gz`);
+            console.log(`[nomad] Backing up raft state → ${candidate}`);
+            try {
+                execSync(`tar czf "${candidate}" -C "${NOMAD_CONFIG_DIR}" data 2>/dev/null`, { timeout: 120000 });
+                backupFile = candidate;
+                // Keep only the most recent snapshot
+                try {
+                    const list = execSync(`ls -t "${backupDir}"/data-*.tar.gz 2>/dev/null | tail -n +2 || true`, { encoding: "utf-8" }).trim();
+                    for (const old of list.split("\n").filter(Boolean)) {
+                        try {
+                            unlinkSync(old);
+                        }
+                        catch { }
+                    }
+                }
+                catch { }
+            }
+            catch {
+                console.warn("[nomad] Backup tar failed — continuing (raft state will still be wiped)");
+            }
+        }
+        // ── Stage 4: wipe raft state + env files (schema incompatible) ─────
+        try {
+            execFileSync("sudo", ["-n", "rm", "-rf", NOMAD_DATA_DIR], { timeout: 15000, stdio: "pipe" });
+        }
+        catch {
+            try {
+                rmSync(NOMAD_DATA_DIR, { recursive: true, force: true });
+            }
+            catch { }
+        }
+        try {
+            unlinkSync(join(JISHUSHELL_HOME, "nomad.env"));
+        }
+        catch { }
+        try {
+            execFileSync("sudo", ["-n", "rm", "-f", "/etc/jishushell/nomad.env"], { timeout: 5000, stdio: "pipe" });
+        }
+        catch { }
+        // ── Stage 5: orphaned gateway containers ───────────────────────────
+        // Panel normally has docker group via jishushell.service SupplementaryGroups,
+        // but postinstall may run this helper from a shell where the invoking
+        // user is not in docker group. Probe first, fall back to sudo docker.
+        try {
+            let dockerCmd = "docker";
+            try {
+                execSync("docker ps >/dev/null 2>&1", { timeout: 5000 });
+            }
+            catch {
+                dockerCmd = "sudo -n docker";
+            }
+            const names = execSync(`${dockerCmd} ps -a --format '{{.Names}}' 2>/dev/null | grep '^gateway-' || true`, { encoding: "utf-8" }).trim();
+            if (names) {
+                const rows = names.split("\n").filter(Boolean);
+                for (const name of rows) {
+                    try {
+                        execSync(`${dockerCmd} rm -f "${name}" 2>/dev/null`, { timeout: 10000 });
+                    }
+                    catch { }
+                }
+                console.log(`[nomad] Removed ${rows.length} orphaned gateway container(s)`);
+            }
+        }
+        catch { }
+        // ── Stage 6: swap binary into place (atomic via temp name + rename)
+        ensureDirHost(BIN_DIR);
+        const destTmp = `${NOMAD_BIN}.tmp.${process.pid}`;
+        copyFileSync(stagedBin, destTmp);
+        chmodSync(destTmp, 0o755);
+        renameSync(destTmp, NOMAD_BIN);
+        console.log(`[nomad] Migrated to v${NOMAD_VERSION}`);
+        if (backupFile)
+            console.log(`[nomad]   Backup (forensic, not self-recovery): ${backupFile}`);
+        console.log("[nomad]   JishuShell will re-bootstrap ACL and resubmit jobs on next start.");
+    }
+    catch (err) {
+        if (backupFile) {
+            console.error(`[nomad] Migration failed — backup preserved at ${backupFile}`);
+        }
+        throw err;
+    }
+    finally {
+        try {
+            rmSync(stageDir, { recursive: true, force: true });
+        }
+        catch { }
+    }
+}
 export async function installNomad() {
     try {
         if (existsSync(NOMAD_BIN)) {
@@ -790,8 +1002,42 @@ export async function installNomad() {
                 }
                 catch { }
                 // Boundary check 3: does it actually run?
+                let versionLine = "";
                 try {
-                    const version = execSync(`"${NOMAD_BIN}" version`, { encoding: "utf-8", timeout: 5000 }).trim();
+                    versionLine = execSync(`"${NOMAD_BIN}" version`, { encoding: "utf-8", timeout: 5000 }).trim().split("\n")[0];
+                }
+                catch {
+                    // Binary is corrupt or wrong arch — remove and reinstall
+                    try {
+                        unlinkSync(NOMAD_BIN);
+                    }
+                    catch { }
+                }
+                if (versionLine) {
+                    const match = versionLine.match(/v(\d+\.\d+\.\d+)/);
+                    const currentVersion = match ? match[1] : "";
+                    let migrated = false;
+                    if (currentVersion && isNomadVersionGreater(currentVersion, NOMAD_VERSION)) {
+                        // Current > target — auto-migrate (nomad 1.11.3 BSL → 1.6.5 MPL).
+                        // Migration failure is a hard stop: the old state has been
+                        // partially mutated (or about to be), returning falls through
+                        // to the reinstall path which would make a bad situation worse.
+                        try {
+                            await migrateNomadToTarget(currentVersion);
+                        }
+                        catch (migErr) {
+                            return {
+                                ok: false,
+                                message: "Nomad auto-migration failed",
+                                error: migErr?.message || String(migErr),
+                            };
+                        }
+                        migrated = true;
+                        versionLine = execSync(`"${NOMAD_BIN}" version`, { encoding: "utf-8", timeout: 5000 }).trim().split("\n")[0];
+                    }
+                    // Always (re)write config so the installed nomad.hcl stays up-to-date
+                    // with the current defaults (e.g. raw_exec plugin, acl, limits).
+                    writeNomadConfig();
                     // Ensure Nomad is started even if already installed
                     if (!isPortListening(4646)) {
                         try {
@@ -802,14 +1048,9 @@ export async function installNomad() {
                             await startNomad();
                         }
                     }
-                    return { ok: true, message: `Nomad already installed: ${version.split("\n")[0]}` };
-                }
-                catch {
-                    // Binary is corrupt or wrong arch — remove and reinstall
-                    try {
-                        unlinkSync(NOMAD_BIN);
-                    }
-                    catch { }
+                    return migrated
+                        ? { ok: true, message: `Nomad migrated to ${versionLine}` }
+                        : { ok: true, message: `Nomad already installed: ${versionLine}` };
                 }
             }
         }
@@ -823,6 +1064,7 @@ export async function installNomad() {
                     symlinkSync(systemNomad, NOMAD_BIN);
                     const version = execSync(`${NOMAD_BIN} version`, { encoding: "utf-8", timeout: 5000 }).trim();
                     console.log(`[nomad] Linked system nomad ${systemNomad} → ${NOMAD_BIN}`);
+                    writeNomadConfig();
                     return { ok: true, message: `Nomad linked from system: ${version.split("\n")[0]}` };
                 }
             }
@@ -900,7 +1142,16 @@ function writeNomadConfig() {
     ensureDirHost(NOMAD_CONFIG_DIR);
     ensureDirContainer(NOMAD_DATA_DIR);
     ensureDirContainer(NOMAD_ALLOC_DIR);
-    const loopbackIface = process.platform === "darwin" ? "lo0" : "lo";
+    const platform = osPlatform();
+    const loopbackIface = platform === "darwin" ? "lo0" : "lo";
+    const externalIface = detectNomadExternalInterface(loopbackIface);
+    const externalHostNetworkBlock = externalIface
+        ? `
+  host_network "external" {
+    interface = "${externalIface}"
+  }
+`
+        : "";
     const config = `
 data_dir = "${NOMAD_DATA_DIR}"
 
@@ -924,6 +1175,7 @@ client {
   servers = ["127.0.0.1:4647"]
   network_interface = "${loopbackIface}"
   alloc_dir = "${NOMAD_ALLOC_DIR}"
+${externalHostNetworkBlock}
 
   # drain_on_shutdown intentionally omitted: on single-node Pi there is
   # nowhere to drain workloads to, and draining on every systemctl restart
@@ -934,19 +1186,51 @@ client {
 
 plugin "docker" {
   config {
-    disable_log_collection = true
     volumes {
       enabled = true
     }
   }
 }
 
+plugin "raw_exec" {
+  config {
+    enabled = true
+  }
+}
+
 acl {
   enabled = true
 }
+
+limits {
+  http_max_conns_per_client = 0
+}
 `;
     writeConfigFile(join(NOMAD_CONFIG_DIR, "nomad.hcl"), config);
 }
+function detectNomadExternalInterface(loopbackIface) {
+    try {
+        if (osPlatform() === "darwin") {
+            const route = execFileSync("route", ["-n", "get", "default"], {
+                encoding: "utf8",
+                timeout: 3000,
+            });
+            const match = route.match(/interface:\s*(\S+)/);
+            const iface = match?.[1]?.trim() ?? "";
+            return iface && iface !== loopbackIface ? iface : "";
+        }
+        const route = execFileSync("ip", ["route", "show", "default"], {
+            encoding: "utf8",
+            timeout: 3000,
+        });
+        const match = route.match(/\bdev\s+(\S+)/);
+        const iface = match?.[1]?.trim() ?? "";
+        return iface && iface !== loopbackIface ? iface : "";
+    }
+    catch {
+        return "";
+    }
+}
 export function loadNomadToken() {
     if (process.env.NOMAD_TOKEN)
         return;
@@ -1090,14 +1374,27 @@ async function bootstrapNomadACL() {
         }
         const resetIndex = resetMatch[1];
         console.log(`[nomad] Bootstrap already done (reset index: ${resetIndex}). Performing ACL bootstrap reset...`);
-        // Write the reset trigger file (Nomad reads this on startup to allow re-bootstrap)
+        // Write the reset trigger file (Nomad reads this on startup to allow re-bootstrap).
+        // NOMAD_DATA_DIR/server is owned by root because nomad.service runs as User=root
+        // (docker driver on 1.6.5 requires euid==0). The panel runs as a non-root user, so
+        // plain writeConfigFile would fail with EACCES — route through `sudo tee` instead.
         const resetFile = join(NOMAD_DATA_DIR, "server", "acl-bootstrap-reset");
         try {
             writeConfigFile(resetFile, resetIndex);
         }
         catch (writeErr) {
-            console.warn("[nomad] Could not write acl-bootstrap-reset file:", writeErr.message);
-            return;
+            try {
+                execFileSync("sudo", ["-n", "mkdir", "-p", dirname(resetFile)], { timeout: 5000, stdio: "pipe" });
+                execFileSync("sudo", ["-n", "tee", resetFile], {
+                    timeout: 5000,
+                    input: resetIndex,
+                    stdio: ["pipe", "ignore", "pipe"],
+                });
+            }
+            catch (sudoErr) {
+                console.warn("[nomad] Could not write acl-bootstrap-reset file:", sudoErr.message || writeErr.message);
+                return;
+            }
         }
         // Restart Nomad so it picks up the reset file
         try {
@@ -1106,9 +1403,14 @@ async function bootstrapNomadACL() {
         catch {
             // No passwordless sudo — try pkill/re-spawn path (best effort)
             try {
-                execFileSync("pkill", ["-TERM", "-f", "nomad agent"], { stdio: "pipe" });
+                execFileSync("sudo", ["-n", "pkill", "-TERM", "-f", "nomad agent"], { stdio: "pipe" });
+            }
+            catch {
+                try {
+                    execFileSync("pkill", ["-TERM", "-f", "nomad agent"], { stdio: "pipe" });
+                }
+                catch { }
             }
-            catch { }
         }
         // Wait for Nomad to come back
         for (let i = 0; i < 20; i++) {
@@ -1240,11 +1542,8 @@ export async function stopNomad() {
         // running allocs without killing them (drain_on_shutdown is deliberately
         // not configured, so the docker containers keep running and will be
         // re-attached when Nomad comes back).
-        // Nomad runs as the current user; no sudo needed to send SIGTERM.
-        try {
-            execSync("pkill -TERM -f 'nomad agent'", { timeout: 5000 });
-        }
-        catch { }
+        // Use killNomadByProcName (pgrep -x) to avoid pkill -f self-matching.
+        killNomadByProcName();
         // Wait up to 10s for the process to exit. No drain means shutdown is
         // near-instant — most of this budget is slack for slow disks on Pi.
         for (let i = 0; i < 10; i++) {
@@ -1275,7 +1574,14 @@ export function installNomadSystemd() {
         if (process.platform === "darwin") {
             const plistLabel = "com.jishushell.nomad";
             const logPath = join(NOMAD_CONFIG_DIR, "nomad.log");
-            const dockerSock = COLIMA_SOCKET;
+            const dockerHost = resolveDockerHost({
+                jishuHome: JISHUSHELL_HOME,
+                colimaProfile: COLIMA_PROFILE,
+            });
+            const dockerHostEntry = dockerHost
+                ? `
+    <key>DOCKER_HOST</key><string>${dockerHost}</string>`
+                : "";
             const plistContent = `<?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">
@@ -1288,8 +1594,7 @@ export function installNomadSystemd() {
     <string>-config=${configPath}</string>
   </array>
   <key>EnvironmentVariables</key>
-  <dict>
-    <key>DOCKER_HOST</key><string>unix://${dockerSock}</string>
+  <dict>${dockerHostEntry}
     <key>PATH</key><string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
   </dict>
   <key>RunAtLoad</key><true/>
@@ -1307,22 +1612,25 @@ export function installNomadSystemd() {
             execSync(`launchctl load -w "${plistPath}"`, { timeout: 15000 });
             return { ok: true, message: "Nomad launchd agent installed and started" };
         }
-        // Nomad runs as the current (non-root) user so all ~/.jishushell/ files remain accessible.
-        // Group=docker gives the process access to /var/run/docker.sock for the Docker driver.
-        const currentUser = process.env.USER || process.env.LOGNAME || process.env.SUDO_USER || "jishu";
+        // Nomad 1.6.5's docker driver fingerprint requires euid==0 — PR #18197 lifted
+        // that restriction only in 1.7+, and we intentionally stay on the 1.6 MPL line.
+        // The panel stays as the installing user via a separate jishushell.service unit;
+        // it talks to this agent over HTTP, so no files under ~/.jishushell/nomad/data/
+        // are read directly by the panel.
         const serviceContent = `[Unit]
 Description=Nomad Agent
 After=network-online.target docker.service
 Wants=network-online.target
 
 [Service]
-User=${currentUser}
-SupplementaryGroups=docker
+User=root
 Type=simple
 EnvironmentFile=-/etc/jishushell/nomad.env
 ExecStart=${nomadPath} agent -config=${configPath}
 Restart=on-failure
 RestartSec=3
+Delegate=yes
+TasksMax=infinity
 
 [Install]
 WantedBy=multi-user.target
@@ -1365,7 +1673,6 @@ export function installJishushellSystemd(port) {
 export JISHUSHELL_HOME="${JISHUSHELL_HOME}"
 export HOME="${realHome}"
 export NODE_ENV=production
-export DOCKER_HOST="unix://${COLIMA_SOCKET}"
 export PATH="/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/local/sbin:/usr/bin:/bin:/usr/sbin:/sbin:${dirname(nodeBin)}:\${PATH}"
 exec "${nodeBin}" "${cliBin}" serve --port ${resolvedPort}
 `;
@@ -1434,64 +1741,77 @@ WantedBy=multi-user.target
     }
 }
 // ── Install OpenClaw (async with progress) ─────────────────────────
-const OPENCLAW_EXPECTED_SIZE_MB = 700;
+/**
+ * Install OpenClaw runtime — thin dispatch wrapper.
+ *
+ * The heavy lifting lives in `OpenClawAdapter.installRuntime()` (§32.2.4).
+ * This wrapper is kept only for back-compat with the existing
+ * `routes/setup.ts` endpoint and the CLI installer.
+ */
 export async function installOpenclaw(version = "latest") {
+    const adapter = getAdapter("openclaw");
+    if (typeof adapter.installRuntime !== "function") {
+        return { ok: false, message: "OpenClawAdapter.installRuntime is not implemented" };
+    }
+    return adapter.installRuntime({ version });
+}
+// ── Hermes install (§32.1 / §32.3) ─────────────────────────────────
+//
+// Hermes constants (HERMES_DEFAULT_IMAGE, HERMES_RUNTIME_DIR,
+// HERMES_SHIM_FILENAME) and the shim template resolver have moved to
+// `src/config.ts` (§32 Phase 8). setup-manager no longer defines them.
+// The HermesAdapter imports them directly from config.ts.
+/**
+ * Capture the immutable digest of a locally-present image so HermesAdapter
+ * can pin via digest rather than the mutable tag. Returns undefined if the
+ * image has no RepoDigests (e.g. locally-built image) — caller may still
+ * proceed using the tag alone.
+ */
+export function captureImageDigest(imageRef) {
     try {
-        const openclawPkgDir = join(OPENCLAW_MODULES, "openclaw");
-        if (existsSync(openclawPkgDir)) {
-            const ver = getLocalOpenclawVersion() || "unknown";
-            return { ok: true, message: `OpenClaw already installed: ${ver}` };
-        }
-        const task = createTask("openclaw");
-        ensureDirHost(OPENCLAW_PKG_DIR);
-        emitTask(task, { type: "progress", message: "开始安装 OpenClaw...", progress: 0 });
-        // Monitor directory size for progress estimation
-        const sizeTracker = setInterval(() => {
-            const sizeMB = getDirSizeMB(OPENCLAW_PKG_DIR);
-            const pct = Math.min(95, Math.round((sizeMB / OPENCLAW_EXPECTED_SIZE_MB) * 95));
-            if (pct > 0) {
-                emitTask(task, { type: "progress", message: `下载安装中... ${sizeMB}MB / ~${OPENCLAW_EXPECTED_SIZE_MB}MB`, progress: pct });
-            }
-        }, 3000);
-        // Use npm install -g with --prefix so npm uses global-install semantics:
-        // packages go to <prefix>/lib/node_modules/, bins to <prefix>/bin/
-        // This makes postinstall scripts run naturally (no manual workarounds needed).
-        const result = await spawnWithTask(task, "npm", ["install", "-g", "--prefix", OPENCLAW_PKG_DIR, `openclaw@${version}`], { timeout: 600000, progressParser: npmProgressParser });
-        clearInterval(sizeTracker);
-        if (!result.ok) {
-            emitTask(task, { type: "error", message: "OpenClaw 安装失败" });
-            task.status = "error";
-            return { ok: false, message: "OpenClaw installation failed", error: result.output, taskId: task.id };
-        }
-        // Read version from package.json since openclaw --version needs Node 22+
-        let ver = "installed";
-        try {
-            const pkg = join(OPENCLAW_MODULES, "openclaw", "package.json");
-            if (existsSync(pkg)) {
-                const pkgJson = JSON.parse(readFileSync(pkg, "utf-8"));
-                ver = pkgJson.version || "installed";
-            }
-        }
-        catch { }
-        emitTask(task, { type: "done", message: `OpenClaw 安装完成: ${ver}`, progress: 100 });
-        task.status = "done";
-        return { ok: true, message: `OpenClaw installed: ${ver}`, taskId: task.id };
+        const raw = execFileSync("docker", [
+            "image",
+            "inspect",
+            "--format",
+            "{{range .RepoDigests}}{{.}}{{\"\\n\"}}{{end}}",
+            imageRef,
+        ], { encoding: "utf-8", timeout: 10000, stdio: ["pipe", "pipe", "pipe"] });
+        const first = raw.split("\n").map((l) => l.trim()).find(Boolean);
+        return first || undefined;
     }
-    catch (e) {
-        return { ok: false, message: "OpenClaw installation failed", error: e.message };
+    catch {
+        return undefined;
     }
 }
-// ── Helpers ──────────────────────────────────────────────────────
-function getLocalOpenclawVersion() {
-    try {
-        const pkg = join(OPENCLAW_MODULES, "openclaw", "package.json");
-        if (existsSync(pkg))
-            return JSON.parse(readFileSync(pkg, "utf-8")).version || "";
+/**
+ * Install Hermes runtime — thin dispatch wrapper.
+ *
+ * Heavy lifting lives in `HermesAdapter.installRuntime()` (§32.2.4).
+ */
+export async function installHermes() {
+    const adapter = getAdapter("hermes");
+    if (typeof adapter.installRuntime !== "function") {
+        return { ok: false, message: "HermesAdapter.installRuntime is not implemented" };
     }
-    catch { }
-    return "";
+    return adapter.installRuntime();
 }
-function resolveDockerInvocation() {
+/**
+ * Non-blocking variant — returns a task id immediately. Implementation
+ * dispatches via `HermesAdapter.startInstallRuntime()`.
+ */
+export function startInstallHermes() {
+    const adapter = getAdapter("hermes");
+    if (typeof adapter.startInstallRuntime !== "function") {
+        return { ok: false, message: "HermesAdapter.startInstallRuntime is not implemented" };
+    }
+    return adapter.startInstallRuntime();
+}
+/** Helper for setup status — true when runtime catalog has hermes entry. */
+export function isHermesInstalled() {
+    const entry = getRuntimeCatalogEntry("hermes");
+    return !!entry && !!entry.defaultImage;
+}
+export function resolveDockerInvocation() {
     try {
         execFileSync("docker", ["info"], { timeout: 5000, stdio: "ignore" });
         return { cmd: "docker", argsPrefix: [] };
@@ -1512,465 +1832,70 @@ function checkDockerImageExists() {
         return true;
     }
     catch {
-        // Backward compat: after upgrading from old image names (jishushell-openclaw:*)
-        // to the new slim tag, the new image may not exist yet. Check if any old image
-        // is still available so we don't kick the user back to the Setup wizard.
+        // Fallback scan: list all local images and try to find any known runtime image.
+        // This handles two scenarios:
+        //  1. panel.json was wiped (e.g. after `jishushell reset`) and the pinned version
+        //     tag is no longer stored, causing getOpenclawDockerImage() to return the default
+        //     `:latest` tag which may have been removed locally during the first-run migration.
+        //  2. The environment uses a locally built runtime image (e.g. jishushell-hermes:latest)
+        //     that differs from the registry default.
+        // When a candidate is found we restore panel.json (self-heal) so the fast path works next time.
         try {
             const invocation = resolveDockerInvocation();
             const out = execFileSync(invocation.cmd, [...invocation.argsPrefix, "images", "--format", "{{.Repository}}:{{.Tag}}"], { encoding: "utf8", timeout: 5000 });
-            if (out.split("\n").some((l) => /^jishushell-openclaw:/.test(l)))
+            const lines = out.split("\n").map((l) => l.trim()).filter(Boolean);
+            // 1. Same repository as DEFAULT_OPENCLAW_DOCKER_IMAGE (e.g. after pinned-tag migration).
+            const defaultImage = DEFAULT_OPENCLAW_DOCKER_IMAGE;
+            const repoColonIdx = defaultImage.lastIndexOf(":");
+            const repoSlashIdx = defaultImage.lastIndexOf("/");
+            if (repoColonIdx > repoSlashIdx) {
+                const repo = defaultImage.slice(0, repoColonIdx);
+                const repoPrefix = repo + ":";
+                const found = lines.find((l) => l.startsWith(repoPrefix) && !l.endsWith(":<none>") && !l.endsWith(":none"));
+                if (found) {
+                    setOpenclawDockerImage(found);
+                    return true;
+                }
+            }
+            // 2. Backward compat: older locally-built jishushell-openclaw:* image names.
+            //    These use the same slim base architecture as ghcr.io/x-aijishu/openclaw-runtime:*
+            //    and are fully compatible. Self-heal panel.json so the tag stored there becomes
+            //    the concrete existing tag, preventing repeated DEFAULT-migration side effects.
+            const legacyFound = lines.find((l) => /^jishushell-openclaw:[^\s]+/.test(l) && !l.endsWith(":<none>") && !l.endsWith(":none"));
+            if (legacyFound) {
+                setOpenclawDockerImage(legacyFound);
                 return true;
+            }
         }
         catch { }
         return false;
     }
 }
-// The stable tag for the JishuShell base image (slim — no OpenClaw binary baked in).
+// The stable tag for the JishuShell base image. Reads panel.json — framework-level.
 function resolveDockerImageTag() {
     return getOpenclawDockerImage();
 }
-// Base image and mirror list for the OpenClaw Docker build.
-// Mirrors are tried in order when docker.io is unreachable (e.g. behind GFW or rate-limited).
-const DOCKER_BASE_IMAGE = "node:22-slim";
-const DOCKER_BASE_MIRRORS = [
-    "node:22-slim",
-    "hub-mirror.c.163.com/library/node:22-slim",
-    "mirrors.tencent.com/library/node:22-slim",
-    "registry.cn-hangzhou.aliyuncs.com/library/node:22-slim",
-];
-// Pull DOCKER_BASE_IMAGE from mirrors if not already cached locally.
-// Returns the image content digest (sha256:…) so that the subsequent
-// docker build can use `FROM <digest>`, which BuildKit resolves from
-// the local daemon without any outbound registry metadata request.
-async function ensureDockerBaseImage(invocation, task) {
-    // Fast path: already in local daemon cache — return image name (not digest) for Dockerfile FROM
-    try {
-        execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "inspect", DOCKER_BASE_IMAGE], {
-            timeout: 5000,
-            stdio: "ignore",
-        });
-        emitTask(task, { type: "log", message: `基础镜像已缓存: ${DOCKER_BASE_IMAGE}` });
-        return DOCKER_BASE_IMAGE;
-    }
-    catch { /* not cached, fall through */ }
-    for (const mirror of DOCKER_BASE_MIRRORS) {
-        emitTask(task, { type: "log", message: `拉取基础镜像: ${mirror} ...` });
-        const result = await spawnWithTask(task, invocation.cmd, [...invocation.argsPrefix, "pull", mirror], { timeout: 300000 });
-        if (result.ok) {
-            if (mirror !== DOCKER_BASE_IMAGE) {
-                try {
-                    execFileSync(invocation.cmd, [...invocation.argsPrefix, "tag", mirror, DOCKER_BASE_IMAGE], { timeout: 10000 });
-                }
-                catch { /* tag failure is non-fatal */ }
-            }
-            emitTask(task, { type: "log", message: `基础镜像就绪: ${DOCKER_BASE_IMAGE}` });
-            return DOCKER_BASE_IMAGE;
-        }
-        emitTask(task, { type: "log", message: `  → ${mirror} 不可达，尝试下一个镜像源...` });
-    }
-    throw new Error(`无法获取基础镜像 ${DOCKER_BASE_IMAGE}。请检查网络或手动执行: docker pull ${DOCKER_BASE_MIRRORS[1]}`);
-}
-function resolveVersionedBuildTag() {
-    try {
-        const pkg = join(OPENCLAW_MODULES, "openclaw", "package.json");
-        if (existsSync(pkg)) {
-            const ver = JSON.parse(readFileSync(pkg, "utf-8")).version;
-            if (ver)
-                return `jishushell-openclaw:${ver}`;
-        }
-    }
-    catch { }
-    return resolveDockerImageTag();
-}
-async function buildOpenclawDockerImageWithTask(task, tag) {
-    const targetTag = tag || resolveVersionedBuildTag();
-    try {
-        const invocation = resolveDockerInvocation();
-        // Fast check: if image with this exact tag exists, skip build (tag encodes version)
-        try {
-            execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "inspect", targetTag], {
-                timeout: 10000,
-                stdio: "ignore",
-            });
-            setOpenclawDockerImage(targetTag);
-            emitTask(task, { type: "done", message: `Docker 镜像已存在: ${targetTag}`, progress: 100 });
-            task.status = "done";
-            return { ok: true, message: `Docker image ${targetTag} already exists`, taskId: task.id };
-        }
-        catch { /* image not found, proceed to build */ }
-        // Clean up old openclaw:* images that predate the new slim-base architecture.
-        // Skip if the stored tag matches targetTag or is a remote registry image.
-        const oldTag = getPanelConfig().openclaw_image;
-        if (oldTag && oldTag !== targetTag && !oldTag.includes("/") && /^openclaw:/i.test(oldTag)) {
-            try {
-                execFileSync(invocation.cmd, [...invocation.argsPrefix, "rmi", oldTag], { timeout: 15000, stdio: "ignore" });
-            }
-            catch { }
-        }
-        // Ensure node:22-slim base image is in the local daemon cache before building.
-        emitTask(task, { type: "progress", message: "准备基础镜像...", progress: 5 });
-        const baseImageId = await ensureDockerBaseImage(invocation, task);
-        // Slim Dockerfile: no COPY of openclaw node_modules — the binary is bind-mounted
-        // from the host at runtime, so this image needs no OpenClaw-specific layers.
-        // Build context is an empty temp directory (no files to COPY).
-        const dockerfile = `FROM ${baseImageId}
-RUN apt-get update && apt-get install -y --no-install-recommends \\
-    ca-certificates curl \\
-    python3 python3-pip python3-venv python3-dev && \\
-    ln -sf /usr/bin/python3 /usr/local/bin/python && \\
-    rm -rf /var/lib/apt/lists/*
-WORKDIR /data
-USER node
-ENTRYPOINT ["node", "/usr/lib/node_modules/openclaw/openclaw.mjs"]
-CMD ["gateway", "run", "--port", "18789", "--allow-unconfigured"]
-`;
-        // Use a temp dir as build context — no files to COPY means no large transfer.
-        const buildDir = join(tmpdir(), `jishushell-base-build-${Date.now()}`);
-        ensureDirHost(buildDir);
-        const dockerfilePath = join(buildDir, "Dockerfile");
-        writeConfigFile(dockerfilePath, dockerfile);
-        emitTask(task, { type: "progress", message: `构建基础镜像 ${targetTag}（无需拷贝二进制，速度极快）...`, progress: 10 });
-        let result;
-        try {
-            result = await spawnWithTask(task, invocation.cmd, [...invocation.argsPrefix, "build", "--network=host", "-t", targetTag, buildDir], {
-                timeout: 1800000,
-                progressParser: dockerBuildProgressParser,
-                env: {},
-            });
-        }
-        finally {
-            // Always clean up temp build dir
-            try {
-                execSync(`rm -rf "${buildDir}"`, { timeout: 5000 });
-            }
-            catch { }
-        }
-        if (!result.ok) {
-            // Clean up dangling images from failed build
-            try {
-                execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "prune", "-f"], { timeout: 15000, stdio: "ignore" });
-            }
-            catch { }
-            emitTask(task, { type: "error", message: "Docker 镜像构建失败" });
-            task.status = "error";
-            return { ok: false, message: "Docker image build failed", error: result.output, taskId: task.id };
-        }
-        const localTag = "jishushell-openclaw:local";
-        if (targetTag !== localTag) {
-            try {
-                execFileSync(invocation.cmd, [...invocation.argsPrefix, "tag", targetTag, localTag], { timeout: 10000, stdio: "ignore" });
-            }
-            catch { }
-        }
-        setOpenclawDockerImage(localTag);
-        emitTask(task, { type: "done", message: `Docker 镜像构建完成: ${targetTag}`, progress: 100 });
-        task.status = "done";
-        return { ok: true, message: `Docker image ${targetTag} built`, taskId: task.id };
-    }
-    catch (e) {
-        // Clean up build artifacts on unexpected errors
-        try {
-            execSync("docker image prune -f", { timeout: 15000, stdio: "ignore" });
-        }
-        catch { }
-        emitTask(task, { type: "error", message: `Docker 镜像构建失败: ${e.message}` });
-        task.status = "error";
-        return { ok: false, message: "Docker image build failed", error: e.message, taskId: task.id };
-    }
-}
-export async function buildOpenclawDockerImage(tag) {
-    const task = createTask("openclaw-docker");
-    return buildOpenclawDockerImageWithTask(task, tag);
-}
-export function startBuildOpenclawDockerImage(tag) {
-    const task = createTask("openclaw-docker");
-    void buildOpenclawDockerImageWithTask(task, tag).catch((err) => {
-        emitTask(task, { type: "error", message: `Docker 镜像构建失败: ${err?.message || err}` });
-        task.status = "error";
-    });
-    return { ok: true, message: "Docker image build started", taskId: task.id };
-}
-// ── Build OpenClaw Docker image from npm package + Python ─────────
-async function buildCustomOpenclawImageWithTask(task, tag) {
-    const targetTag = tag || DEFAULT_OPENCLAW_DOCKER_IMAGE;
-    try {
-        const invocation = resolveDockerInvocation();
-        // Fast check: if image already exists locally, skip
-        try {
-            execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "inspect", targetTag], {
-                timeout: 10000,
-                stdio: "ignore",
-            });
-            setOpenclawDockerImage(targetTag);
-            emitTask(task, { type: "done", message: `Docker 镜像已存在: ${targetTag}`, progress: 100 });
-            task.status = "done";
-            return { ok: true, message: `Docker image ${targetTag} already exists`, taskId: task.id };
-        }
-        catch { /* image not found, proceed */ }
-        // Clean up old legacy images
-        const oldTag = getPanelConfig().openclaw_image;
-        if (oldTag && oldTag !== targetTag && /^jishushell-base:/i.test(oldTag)) {
-            try {
-                execFileSync(invocation.cmd, [...invocation.argsPrefix, "rmi", oldTag], { timeout: 15000, stdio: "ignore" });
-            }
-            catch { }
-        }
-        // Step 1: Ensure OpenClaw npm package is installed (used as build context)
-        const openclawPkgDir = join(OPENCLAW_MODULES, "openclaw");
-        if (!existsSync(openclawPkgDir)) {
-            emitTask(task, { type: "progress", message: "安装 OpenClaw npm 包...", progress: 5 });
-            const installResult = await installOpenclaw();
-            if (!installResult.ok) {
-                emitTask(task, { type: "error", message: "OpenClaw 安装失败" });
-                task.status = "error";
-                return { ok: false, message: "OpenClaw npm install failed", error: installResult.error, taskId: task.id };
-            }
-        }
-        // Step 2: Ensure base image is available
-        emitTask(task, { type: "progress", message: "准备基础镜像...", progress: 10 });
-        const baseImageId = await ensureDockerBaseImage(invocation, task);
-        // Step 3: Build image — COPY node_modules + Python
-        emitTask(task, { type: "progress", message: `构建 OpenClaw 镜像（含 Python）: ${targetTag} ...`, progress: 30 });
-        const dockerfile = `FROM ${baseImageId}
-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"]
-`;
-        // Write Dockerfile into the npm package directory (build context)
-        const dockerfilePath = join(OPENCLAW_PKG_DIR, "Dockerfile");
-        writeConfigFile(dockerfilePath, dockerfile);
-        let buildResult;
-        try {
-            buildResult = await spawnWithTask(task, invocation.cmd, [...invocation.argsPrefix, "build", "--network=host", "-t", targetTag, OPENCLAW_PKG_DIR], { timeout: 1800000, progressParser: dockerBuildProgressParser });
-        }
-        finally {
-            try {
-                unlinkSync(dockerfilePath);
-            }
-            catch { }
-        }
-        if (!buildResult.ok) {
-            try {
-                execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "prune", "-f"], { timeout: 15000, stdio: "ignore" });
-            }
-            catch { }
-            emitTask(task, { type: "error", message: "Docker 镜像构建失败" });
-            task.status = "error";
-            return { ok: false, message: "Docker image build failed", error: buildResult.output, taskId: task.id };
-        }
-        setOpenclawDockerImage(targetTag);
-        emitTask(task, { type: "done", message: `OpenClaw 镜像就绪: ${targetTag}（含 Python）`, progress: 100 });
-        task.status = "done";
-        return { ok: true, message: `Docker image ${targetTag} built`, taskId: task.id };
-    }
-    catch (e) {
-        emitTask(task, { type: "error", message: `镜像构建失败: ${e.message}` });
-        task.status = "error";
-        return { ok: false, message: "Docker image build failed", error: e.message, taskId: task.id };
-    }
-}
-// ── Pull or build OpenClaw Docker image ───────────────────────────
-/** Matches a semver-ish tag suffix, e.g. "...:2026.4.9" or "...:v1.2.3-beta". */
-const PINNED_IMAGE_TAG_RE = /:[0-9]+\.[0-9]+\.[0-9]+(-[A-Za-z0-9.-]+)?$/;
-/**
- * Query the npm registry for the current OpenClaw version. Used to bust the
- * Docker layer cache for `RUN npm install openclaw@${ver}` during local build.
- * Returns "latest" when npm is unreachable so the build can still proceed.
- */
-function resolveOpenclawNpmVersion() {
-    try {
-        const out = execFileSync("npm", ["view", "openclaw", "version"], {
-            timeout: 15000,
-            encoding: "utf-8",
-            stdio: ["ignore", "pipe", "ignore"],
-        }).trim();
-        if (/^\d+\.\d+\.\d+/.test(out))
-            return out;
-    }
-    catch { /* npm not reachable */ }
-    return "latest";
-}
-/**
- * Read the OpenClaw version actually bundled at /app/ inside a Docker image,
- * bypassing `openclaw-entry.sh`'s `.npm-global/` override. This is the
- * authoritative source of truth — the image's OCI label can be wrong
- * (CI bugs, layer cache reuse), but `/app/node_modules/openclaw/package.json`
- * is the exact content that ran through `npm install`.
- *
- * Spawns a throw-away container with `--entrypoint node` so Node prints the
- * version directly. Returns "" when docker is unavailable or the path is
- * missing (e.g. a non-openclaw image).
- */
-function readBundledOpenclawVersion(invocation, image) {
-    try {
-        const out = execFileSync(invocation.cmd, [
-            ...invocation.argsPrefix,
-            "run", "--rm",
-            "--entrypoint", "node",
-            image,
-            "-p",
-            "require('/app/node_modules/openclaw/package.json').version",
-        ], { timeout: 20000, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
-        if (/^\d+\.\d+\.\d+/.test(out))
-            return out;
-    }
-    catch { /* docker unavailable, image missing, or path not present */ }
-    return "";
-}
-/**
- * After a successful pull or build, capture the image's real OpenClaw version
- * and return a pinned tag of the form `ghcr.io/.../openclaw-runtime:<version>`.
- * The pinned tag is added as a local alias via `docker tag` so subsequent
- * Nomad allocations see an immutable reference and never re-pull on restart.
- *
- * Version discovery order:
- *  1. `explicitVersion` when the caller already knows it (e.g. the local build
- *     path, which queries npm for the version and passes it as `--build-arg`).
- *  2. Bundled `/app/node_modules/openclaw/package.json` inside the image
- *     (authoritative — bypasses both the `.npm-global/` override layer and a
- *     potentially stale OCI label).
- *
- * Returns the original tag unchanged when:
- *  - the target is already a pinned version tag
- *  - no version can be discovered
- *  - docker tag fails for any reason
- */
-function capturePinnedImageTag(invocation, targetTag, explicitVersion) {
-    // Already pinned? Nothing to do.
-    if (PINNED_IMAGE_TAG_RE.test(targetTag))
-        return targetTag;
-    let version = explicitVersion && /^\d+\.\d+\.\d+/.test(explicitVersion) ? explicitVersion : "";
-    if (!version) {
-        version = readBundledOpenclawVersion(invocation, targetTag);
-    }
-    if (!version || !/^\d+\.\d+\.\d+/.test(version))
-        return targetTag;
-    // Build the pinned tag by replacing the mutable tag portion.
-    // "ghcr.io/foo/bar:latest"   → "ghcr.io/foo/bar:2026.4.9"
-    // "ghcr.io/foo/bar"          → "ghcr.io/foo/bar:2026.4.9"
-    const colonIdx = targetTag.lastIndexOf(":");
-    const slashIdx = targetTag.lastIndexOf("/");
-    const hasTag = colonIdx > slashIdx;
-    const repo = hasTag ? targetTag.slice(0, colonIdx) : targetTag;
-    const pinnedTag = `${repo}:${version}`;
-    if (pinnedTag === targetTag)
-        return targetTag;
-    try {
-        execFileSync(invocation.cmd, [...invocation.argsPrefix, "tag", targetTag, pinnedTag], { timeout: 10000, stdio: "ignore" });
-    }
-    catch {
-        // Could not create the local alias — fall back to original tag.
-        return targetTag;
-    }
-    // Drop the mutable original alias (`:latest` / `:slim`) now that the pinned
-    // tag is in place. Removing a tag is cheap and leaves the underlying image
-    // alive because the new pinned reference still points to it. Best-effort:
-    // silent when the tag is already gone or in use.
-    if (/:(latest|slim)$/.test(targetTag)) {
-        try {
-            execFileSync(invocation.cmd, [...invocation.argsPrefix, "rmi", targetTag], { timeout: 10000, stdio: "ignore" });
-        }
-        catch { /* best-effort cleanup */ }
-    }
-    return pinnedTag;
-}
-async function pullOrBuildOpenclawImageWithTask(task, tag) {
-    const targetTag = tag || DEFAULT_OPENCLAW_DOCKER_IMAGE;
-    try {
-        const invocation = resolveDockerInvocation();
-        // Fast check: if image already exists locally, skip
-        try {
-            execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "inspect", targetTag], {
-                timeout: 10000,
-                stdio: "ignore",
-            });
-            const pinned = capturePinnedImageTag(invocation, targetTag);
-            setOpenclawDockerImage(pinned);
-            emitTask(task, { type: "done", message: `Docker 镜像已存在: ${pinned}`, progress: 100 });
-            task.status = "done";
-            return { ok: true, message: `Docker image ${pinned} already exists`, taskId: task.id };
-        }
-        catch { /* image not found, proceed */ }
-        // ── Step 1: Try docker pull from registry ─────────────────────
-        emitTask(task, { type: "progress", message: `正在拉取镜像: ${targetTag} ...`, progress: 10 });
-        const pullResult = await spawnWithTask(task, invocation.cmd, [...invocation.argsPrefix, "pull", targetTag], { timeout: 600000 });
-        if (pullResult.ok) {
-            const pinned = capturePinnedImageTag(invocation, targetTag);
-            setOpenclawDockerImage(pinned);
-            emitTask(task, { type: "done", message: `镜像拉取成功: ${pinned}`, progress: 100 });
-            task.status = "done";
-            return { ok: true, message: `Docker image ${pinned} pulled`, taskId: task.id };
-        }
-        // ── Step 2: Fallback to local build ───────────────────────────
-        console.log(`[setup] docker pull failed for ${targetTag}, falling back to local build...`);
-        emitTask(task, { type: "progress", message: `拉取失败，正在本地构建镜像: ${targetTag} ...`, progress: 20 });
-        const projectRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
-        const dockerfilePath = join(projectRoot, "Dockerfile.openclaw-slim");
-        if (!existsSync(dockerfilePath)) {
-            emitTask(task, { type: "error", message: "Dockerfile.openclaw-slim not found, cannot fallback to local build" });
-            task.status = "error";
-            return { ok: false, message: "Docker pull failed and Dockerfile.openclaw-slim not found", taskId: task.id };
-        }
-        // Resolve the OpenClaw version from npm so the build-arg busts the Docker
-        // layer cache for `RUN npm install openclaw@${ver}`. The Dockerfile's
-        // ARG OPENCLAW_VERSION=latest default would otherwise cause the layer to
-        // be silently reused across releases.
-        const openclawVersion = resolveOpenclawNpmVersion();
-        console.log(`[setup] building openclaw image with OPENCLAW_VERSION=${openclawVersion}`);
-        const buildResult = await spawnWithTask(task, invocation.cmd, [
-            ...invocation.argsPrefix,
-            "build",
-            "--network=host",
-            "--build-arg", `OPENCLAW_VERSION=${openclawVersion}`,
-            "-f", dockerfilePath,
-            "-t", targetTag,
-            projectRoot,
-        ], { timeout: 1800000, progressParser: dockerBuildProgressParser });
-        if (!buildResult.ok) {
-            try {
-                execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "prune", "-f"], { timeout: 15000, stdio: "ignore" });
-            }
-            catch { }
-            emitTask(task, { type: "error", message: "Docker 镜像构建失败" });
-            task.status = "error";
-            return { ok: false, message: "Docker image build failed", error: buildResult.output, taskId: task.id };
-        }
-        // Local builds don't get labels from the GitHub Action's `labels:` field,
-        // so pass the npm version we already know to let capturePinnedImageTag
-        // mint the pinned tag without relying on docker inspect.
-        const pinned = capturePinnedImageTag(invocation, targetTag, openclawVersion);
-        setOpenclawDockerImage(pinned);
-        emitTask(task, { type: "done", message: `OpenClaw 镜像就绪 (本地构建): ${pinned}`, progress: 100 });
-        task.status = "done";
-        return { ok: true, message: `Docker image ${pinned} built locally`, taskId: task.id };
-    }
-    catch (e) {
-        emitTask(task, { type: "error", message: `镜像获取失败: ${e.message}` });
-        task.status = "error";
-        return { ok: false, message: "Docker image pull/build failed", error: e.message, taskId: task.id };
-    }
-}
+// ── Docker image build dispatch wrappers ───────────────────────────────
+//
+// All OpenClaw-specific image build logic now lives in
+// `OpenClawAdapter.buildRuntimeImage()` (§32.2.4 physical migration). These
+// exports remain as thin wrappers so `routes/setup.ts` and
+// `install.ts` callers don't need to learn adapter dispatch.
+/** Blocking: pull or build the OpenClaw docker image. */
 export async function buildSlimOpenclawImage(tag) {
-    const task = createTask("openclaw-docker-pull");
-    return pullOrBuildOpenclawImageWithTask(task, tag);
+    const adapter = getAdapter("openclaw");
+    if (typeof adapter.buildRuntimeImage !== "function") {
+        return { ok: false, message: "OpenClawAdapter.buildRuntimeImage is not implemented" };
+    }
+    return adapter.buildRuntimeImage({ tag });
 }
+/** Non-blocking: returns immediately with a task id for SSE polling. */
 export function startBuildSlimOpenclawImage(tag) {
-    const task = createTask("openclaw-docker-pull");
-    void pullOrBuildOpenclawImageWithTask(task, tag).catch((err) => {
-        emitTask(task, { type: "error", message: `镜像获取失败: ${err?.message || err}` });
-        task.status = "error";
-    });
-    return { ok: true, message: "Docker image pull started", taskId: task.id };
+    const adapter = getAdapter("openclaw");
+    if (typeof adapter.startBuildRuntimeImage !== "function") {
+        return { ok: false, message: "OpenClawAdapter.startBuildRuntimeImage is not implemented" };
+    }
+    return adapter.startBuildRuntimeImage({ tag });
 }
 /** @deprecated Use buildSlimOpenclawImage instead */
 export async function buildCustomOpenclawImage(tag) {
@@ -2021,7 +1946,10 @@ export async function runFullSetup(options = {}) {
             }
         }
     }
-    // Prepare Docker image: pull official image or build slim base (legacy).
+    // Prepare each registered agent's runtime artefacts (docker image, shim,
+    // etc.). This loops over every adapter so onboarding a new agent only
+    // requires implementing `buildRuntimeImage` or `installRuntime` in its
+    // adapter — runFullSetup picks it up automatically.
     if (defaults.buildDockerImage) {
         // Restart Nomad so it re-detects Docker driver after Docker was installed
         try {
@@ -2033,12 +1961,50 @@ export async function runFullSetup(options = {}) {
             }
         }
         catch { }
-        steps.push({ step: "docker-image", status: "running", message: "Building OpenClaw Docker image..." });
-        const imgResult = await buildSlimOpenclawImage();
-        steps[steps.length - 1].status = imgResult.ok ? "done" : "error";
-        steps[steps.length - 1].message = imgResult.message;
-        if (!imgResult.ok)
-            allOk = false;
+        for (const adapter of listRegisteredAdapters()) {
+            const stepName = `runtime-${adapter.agentType}`;
+            // Prefer buildRuntimeImage (pure docker image prep) over
+            // installRuntime (legacy host-mode npm install). Adapters that only
+            // implement one will use whichever is present; adapters with neither
+            // are skipped silently.
+            const runner = adapter.buildRuntimeImage
+                ? adapter.buildRuntimeImage.bind(adapter)
+                : adapter.installRuntime
+                    ? adapter.installRuntime.bind(adapter)
+                    : null;
+            if (!runner)
+                continue;
+            const isRequired = !!adapter.required;
+            steps.push({
+                step: stepName,
+                status: "running",
+                message: `Preparing ${adapter.agentType} runtime…`,
+            });
+            try {
+                const imgResult = (await runner());
+                const okStep = !!imgResult.ok;
+                steps[steps.length - 1].status = okStep ? "done" : "error";
+                steps[steps.length - 1].message = okStep
+                    ? imgResult.message
+                    : isRequired
+                        ? imgResult.message
+                        : `${imgResult.message} (optional — panel will continue)`;
+                // Required adapter failures abort the overall setup; optional ones
+                // are warnings so that upgrade paths don't break when a third-party
+                // agent's registry is unreachable.
+                if (!okStep && isRequired)
+                    allOk = false;
+            }
+            catch (e) {
+                const msg = e?.message || "runtime prepare failed";
+                steps[steps.length - 1].status = "error";
+                steps[steps.length - 1].message = isRequired
+                    ? msg
+                    : `${msg} (optional — panel will continue)`;
+                if (isRequired)
+                    allOk = false;
+            }
+        }
     }
     if (isPortListening(4646)) {
         await finalizeNomadStartup();