jishushell 0.5.22 → 0.6.18

package/dist/services/setup/setup-manager.js

@@ -0,0 +1,2768 @@
+import { execFileSync, execSync, spawn as nodeSpawn } from "child_process";
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdtempSync, readFileSync, renameSync, rmSync, symlinkSync, unlinkSync } from "fs";
+import { userInfo, platform as osPlatform, arch as osArch, cpus as osCpus } from "node:os";
+import { randomBytes } from "node:crypto";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "path";
+import { StringDecoder } from "string_decoder";
+import { fileURLToPath } from "url";
+import { JISHUSHELL_HOME, getCoreConfig, saveCoreConfig, setOpenclawDockerImage, getOpenclawDockerImage, DEFAULT_OPENCLAW_DOCKER_IMAGE, getIntegrationRuntimeEntry, OPENCLAW_MODULES, OPENCLAW_BIN_DIR, } from "../../config.js";
+import { ensureDirContainer, ensureDirHost, writeConfigFile, writeSecretFile, writeExecutableFile, writeSystemTmpFile } from "../../utils/fs.js";
+import { buildDockerClientEnv, managedColimaSocketPath, managedColimaDockerHost, resolveDockerHost } from "../../utils/docker-host.js";
+import { appleSiliconGuard, buildColimaWrapperScript, buildColimaPlist, buildNomadWaitWrapper, buildNomadPlist, buildCoreGateWrapper, buildCorePlist, buildPanelPlist, } from "../system/macos-launchd.js";
+import { getIntegration, listRegisteredIntegrations } from "../integrations/index.js";
+import { hasLlmProviderSetup } from "../llm-proxy/providers.js";
+// Internal usage of task primitives — re-exports further down preserve the
+// public import surface used by integration modules, routes, and CLI.
+import { createTask, emitTask, getRunningTasks } from "../tasks/registry.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// ── Paths ──────────────────────────────────────────────────────────
+const BIN_DIR = join(JISHUSHELL_HOME, "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 = managedColimaSocketPath(JISHUSHELL_HOME, COLIMA_PROFILE);
+const NOMAD_VERSION = "1.6.5";
+const DEFAULT_CORE_PORT = 8091;
+const DEFAULT_PANEL_PORT = 8090;
+const SYSTEMD_CORE_SERVICE_PATH = "/etc/systemd/system/jishushell.service";
+const SYSTEMD_PANEL_SERVICE_PATH = "/etc/systemd/system/jishushell-panel.service";
+const SYSTEMD_NOMAD_SERVICE_PATH = "/etc/systemd/system/nomad.service";
+let _serverPort = DEFAULT_CORE_PORT;
+export function setServerPort(port) { _serverPort = port; }
+function shellQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function sudoCopySystemFile(content, destination, mode) {
+    const stagingDir = mkdtempSync(join(tmpdir(), "jishushell-system-"));
+    const stagingPath = join(stagingDir, basename(destination));
+    try {
+        writeSystemTmpFile(stagingPath, content);
+        execFileSync("sudo", ["cp", stagingPath, destination], { timeout: 5000 });
+        execFileSync("sudo", ["chown", "root:root", destination], { timeout: 5000 });
+        execFileSync("sudo", ["chmod", mode, destination], { timeout: 5000 });
+    }
+    finally {
+        rmSync(stagingDir, { recursive: true, force: true });
+    }
+}
+function removeSymlinkIfPresent(path) {
+    try {
+        if (lstatSync(path).isSymbolicLink())
+            unlinkSync(path);
+    }
+    catch (e) {
+        if (e?.code !== "ENOENT")
+            throw e;
+    }
+}
+function chownToUser(path, user, recursive = false) {
+    if (!user)
+        return;
+    const args = recursive ? ["-R", `${user}:`, path] : [`${user}:`, path];
+    const timeout = recursive ? 60000 : 5000;
+    if (typeof process.getuid === "function" && process.getuid() === 0) {
+        execFileSync("chown", args, { timeout });
+    }
+    else {
+        execFileSync("sudo", ["chown", ...args], { timeout });
+    }
+}
+function writeManagedExecutableFile(path, content, ownerUser) {
+    try {
+        writeExecutableFile(path, content);
+    }
+    catch (e) {
+        if (e?.code !== "EACCES" || !ownerUser)
+            throw e;
+        sudoCopySystemFile(content, path, "755");
+    }
+    chownToUser(path, ownerUser);
+}
+function resolveCoreCliBin() {
+    const candidates = [
+        process.env.JISHUSHELL_CORE_BIN,
+        join(__dirname, "..", "cli.js"),
+    ]
+        .map((candidate) => candidate?.trim())
+        .filter((candidate) => Boolean(candidate));
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    throw new Error("Cannot locate jishushell entrypoint. Set JISHUSHELL_CORE_BIN to the bundled CLI path.");
+}
+function resolveBundledPanelServerBin() {
+    const packageRoot = join(__dirname, "..", "..", "..");
+    const candidates = [
+        process.env.JISHUSHELL_PANEL_BIN,
+        join(packageRoot, "node_modules", "jishushell-panel", "output", "dist", "server.js"),
+    ]
+        .map((candidate) => candidate?.trim())
+        .filter((candidate) => Boolean(candidate));
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    throw new Error("Cannot locate bundled jishushell-panel entrypoint. Install the GUI jishushell package or set JISHUSHELL_PANEL_BIN.");
+}
+function buildWrapperEnvPrelude() {
+    return `_WRAPPER_DIR="$(cd "$(dirname "$0")" && pwd)"
+_DEFAULT_JISHUSHELL_HOME="$(cd "$_WRAPPER_DIR/.." && pwd)"
+
+_resolve_sudo_home() {
+  if [ -n "\${SUDO_UID:-}" ] && command -v getent >/dev/null 2>&1; then
+    _entry="$(getent passwd "$SUDO_UID" 2>/dev/null || true)"
+    if [ -n "$_entry" ]; then
+      printf '%s\\n' "$_entry" | cut -d: -f6
+      return
+    fi
+  fi
+}
+
+_SUDO_HOME="$(_resolve_sudo_home || true)"
+if [ -z "\${JISHUSHELL_HOME:-}" ]; then
+  case "$_DEFAULT_JISHUSHELL_HOME" in
+    /usr|/usr/local|/opt/homebrew|/opt/local)
+      if [ -n "$_SUDO_HOME" ]; then
+        JISHUSHELL_HOME="$_SUDO_HOME/.jishushell"
+      else
+        JISHUSHELL_HOME="$_DEFAULT_JISHUSHELL_HOME"
+      fi
+      ;;
+    *) JISHUSHELL_HOME="$_DEFAULT_JISHUSHELL_HOME" ;;
+  esac
+fi
+
+_resolve_home() {
+  if [ -n "$_SUDO_HOME" ]; then
+    printf '%s\\n' "$_SUDO_HOME"
+    return
+  fi
+  case "$JISHUSHELL_HOME" in
+    */.jishushell) printf '%s\\n' "\${JISHUSHELL_HOME%/.jishushell}" ;;
+    *) printf '%s\\n' "\${HOME:-$PWD}" ;;
+  esac
+}
+HOME="$(_resolve_home)"
+export JISHUSHELL_HOME HOME`;
+}
+function buildCoreStartWrapperContent(opts) {
+    const pathPrefix = [
+        "/opt/homebrew/bin",
+        "/opt/homebrew/sbin",
+        "/usr/local/bin",
+        "/usr/local/sbin",
+        "/usr/bin",
+        "/bin",
+        "/usr/sbin",
+        "/sbin",
+        dirname(opts.nodeBin),
+        dirname(opts.cliBin),
+    ].join(":");
+    const cliExec = opts.cliBin.endsWith(".js")
+        ? `${shellQuote(opts.nodeBin)} ${shellQuote(opts.cliBin)}`
+        : shellQuote(opts.cliBin);
+    return `#!/bin/sh
+set -eu
+${buildWrapperEnvPrelude()}
+[ -f "\${JISHUSHELL_HOME}/nomad.env" ] && . "\${JISHUSHELL_HOME}/nomad.env"
+export JISHUSHELL_CORE_BIN=${shellQuote(opts.cliBin)}
+export JISHUSHELL_CORE_PORT=${opts.port}
+export NODE_ENV=production
+export PATH=${shellQuote(pathPrefix)}\${PATH:+:\$PATH}
+if command -v ss >/dev/null 2>&1 && ss -tln 2>/dev/null | grep -Eq '(^|[[:space:]])[^[:space:]]*:${opts.port}[[:space:]]'; then
+  echo "JishuShell core port ${opts.port} is already listening; not starting another core."
+  exit 0
+fi
+exec ${cliExec} serve --port ${opts.port}
+`;
+}
+function buildCoreCliWrapperContent(opts) {
+    const pathPrefix = [
+        "/opt/homebrew/bin",
+        "/opt/homebrew/sbin",
+        "/usr/local/bin",
+        "/usr/local/sbin",
+        "/usr/bin",
+        "/bin",
+        "/usr/sbin",
+        "/sbin",
+        dirname(opts.nodeBin),
+        dirname(opts.cliBin),
+    ].join(":");
+    const cliExec = opts.cliBin.endsWith(".js")
+        ? `${shellQuote(opts.nodeBin)} ${shellQuote(opts.cliBin)}`
+        : shellQuote(opts.cliBin);
+    return `#!/bin/sh
+set -eu
+${buildWrapperEnvPrelude()}
+[ -f "\${JISHUSHELL_HOME}/nomad.env" ] && . "\${JISHUSHELL_HOME}/nomad.env"
+export JISHUSHELL_CORE_BIN=${shellQuote(opts.cliBin)}
+export JISHUSHELL_CORE_PORT=${opts.port}
+export NODE_ENV=\${NODE_ENV:-production}
+export PATH=${shellQuote(pathPrefix)}\${PATH:+:\$PATH}
+exec ${cliExec} "$@"
+`;
+}
+function buildPanelStartWrapperContent(opts) {
+    const manageCoreDefault = opts.manageCoreDefault ? "1" : "0";
+    const pathPrefix = [
+        "/opt/homebrew/bin",
+        "/opt/homebrew/sbin",
+        "/usr/local/bin",
+        "/usr/local/sbin",
+        "/usr/bin",
+        "/bin",
+        "/usr/sbin",
+        "/sbin",
+        dirname(opts.nodeBin),
+        dirname(opts.panelBin),
+    ].join(":");
+    return `#!/bin/sh
+set -eu
+${buildWrapperEnvPrelude()}
+export NODE_ENV=\${NODE_ENV:-production}
+export JISHUSHELL_CORE_BASE_URL=\${JISHUSHELL_CORE_BASE_URL:-http://127.0.0.1:${opts.corePort}}
+export JISHUSHELL_PANEL_PORT=\${JISHUSHELL_PANEL_PORT:-${opts.panelPort}}
+export JISHUSHELL_PANEL_MANAGE_CORE=\${JISHUSHELL_PANEL_MANAGE_CORE:-${manageCoreDefault}}
+export PATH=${shellQuote(pathPrefix)}\${PATH:+:\$PATH}
+exec ${shellQuote(opts.nodeBin)} ${shellQuote(opts.panelBin)} "$@"
+`;
+}
+// ── Resolve non-root service user (board-agnostic) ─────────────────
+/**
+ * Determine which user the systemd service should run as.
+ *
+ * Strategy (in order):
+ *  1. If current process is NOT root, return the real username directly.
+ *  2. Under sudo, trust the kernel-set SUDO_UID (numeric, hard to spoof)
+ *     and reverse-lookup via `getent passwd <uid>`.
+ *  3. Fallback: scan /etc/passwd for the first user with UID >= 1000
+ *     (works on any board — pi, orangepi, rock, nvidia, etc.).
+ *  4. Throw instead of guessing — running as the wrong user is worse
+ *     than a visible installation error.
+ */
+function resolveServiceUser() {
+    const current = userInfo();
+    if (current.uid !== 0)
+        return current.username;
+    // Under sudo: SUDO_UID is set by the kernel and is numeric
+    const sudoUid = parseInt(process.env.SUDO_UID || "", 10);
+    if (Number.isFinite(sudoUid) && sudoUid >= 1000) {
+        try {
+            const entry = execFileSync("getent", ["passwd", String(sudoUid)], {
+                encoding: "utf8",
+                timeout: 3000,
+            }).trim();
+            const name = entry.split(":")[0];
+            if (name)
+                return name;
+        }
+        catch { /* getent failed, continue */ }
+    }
+    // Board-agnostic fallback: first real user (UID >= 1000, exclude nobody)
+    try {
+        const firstUser = execFileSync("getent", ["passwd"], {
+            encoding: "utf8",
+            timeout: 3000,
+        })
+            .split("\n")
+            .map((line) => line.split(":"))
+            .find((cols) => {
+            const uid = parseInt(cols[2], 10);
+            return uid >= 1000 && uid < 65534;
+        });
+        if (firstUser?.[0])
+            return firstUser[0];
+    }
+    catch { /* /etc/passwd unreadable */ }
+    throw new Error("Cannot determine service user. Run with a non-root user or set SUDO_UID.");
+}
+function resolveRealHome() {
+    return dirname(JISHUSHELL_HOME);
+}
+function resolveLaunchAgentsDir(realHome = resolveRealHome()) {
+    return join(process.env.HOME || realHome, "Library/LaunchAgents");
+}
+function resolveNomadExecutable() {
+    if (existsSync(NOMAD_BIN))
+        return NOMAD_BIN;
+    try {
+        return execFileSync("which", ["nomad"], { encoding: "utf-8", timeout: 5000 }).trim();
+    }
+    catch {
+        return "nomad";
+    }
+}
+function resolveColimaExecutable() {
+    try {
+        return execFileSync("which", ["colima"], { encoding: "utf-8", timeout: 5000 }).trim().split("\n")[0];
+    }
+    catch {
+        if (existsSync("/opt/homebrew/bin/colima"))
+            return "/opt/homebrew/bin/colima";
+        if (existsSync("/usr/local/bin/colima"))
+            return "/usr/local/bin/colima";
+        return "colima";
+    }
+}
+function buildJishushellCoreSystemdUnit(opts) {
+    return `[Unit]
+Description=JishuShell Core
+After=network-online.target nomad.service
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=${opts.currentUser}
+SupplementaryGroups=docker
+Environment=HOME=${opts.realHome}
+Environment=JISHUSHELL_HOME=${JISHUSHELL_HOME}
+EnvironmentFile=-/etc/jishushell/nomad.env
+ExecStart=${opts.coreStartWrapperPath}
+Restart=on-failure
+RestartSec=3
+Environment=NODE_ENV=production
+ProtectSystem=strict
+PrivateTmp=true
+ReadWritePaths=${JISHUSHELL_HOME} /etc/jishushell /usr/local
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+function buildJishushellPanelSystemdUnit(opts) {
+    return `[Unit]
+Description=JishuShell Panel
+After=network-online.target jishushell.service
+Wants=network-online.target jishushell.service
+
+[Service]
+Type=simple
+User=${opts.currentUser}
+Environment=HOME=${opts.realHome}
+Environment=JISHUSHELL_HOME=${JISHUSHELL_HOME}
+Environment=JISHUSHELL_CORE_BASE_URL=http://127.0.0.1:${opts.corePort}
+Environment=JISHUSHELL_PANEL_PORT=${opts.panelPort}
+Environment=JISHUSHELL_PANEL_MANAGE_CORE=0
+Environment=NODE_ENV=production
+ExecStart=${opts.panelStartWrapperPath}
+Restart=on-failure
+RestartSec=3
+ProtectSystem=strict
+PrivateTmp=true
+ReadWritePaths=${JISHUSHELL_HOME}
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+function buildNomadSystemdUnit(opts) {
+    return `[Unit]
+Description=Nomad Agent
+After=network-online.target docker.service
+Wants=network-online.target
+
+[Service]
+User=root
+Type=simple
+EnvironmentFile=-/etc/jishushell/nomad.env
+ExecStart=${opts.nomadPath} agent -config=${opts.configPath}
+Restart=on-failure
+RestartSec=3
+Delegate=yes
+TasksMax=infinity
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+export function hasBundledPanel() {
+    try {
+        resolveBundledPanelServerBin();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function getExpectedCoreSystemFiles(port = _serverPort) {
+    const nodeBin = process.execPath;
+    const cliBin = resolveCoreCliBin();
+    const realHome = resolveRealHome();
+    const coreStartWrapperPath = join(BIN_DIR, "jishushell-core-start");
+    const coreCliWrapperPath = join(BIN_DIR, "jishushell");
+    const files = [
+        {
+            component: "wrapper",
+            id: "core.start-wrapper",
+            path: coreStartWrapperPath,
+            content: buildCoreStartWrapperContent({ nodeBin, cliBin, realHome, port }),
+            installScope: "core",
+            requiresSudo: false,
+            reloadRequired: true,
+            fix: "system-reload",
+        },
+        {
+            component: "wrapper",
+            id: "core.cli-wrapper",
+            path: coreCliWrapperPath,
+            content: buildCoreCliWrapperContent({ nodeBin, cliBin, realHome, port }),
+            installScope: "core",
+            requiresSudo: false,
+            reloadRequired: true,
+            fix: "system-reload",
+        },
+    ];
+    if (process.platform === "darwin") {
+        const gateWrapperPath = join(BIN_DIR, "core-launchd-wrapper.sh");
+        files.push({
+            component: "wrapper",
+            id: "core.launchd-gate-wrapper",
+            path: gateWrapperPath,
+            content: buildCoreGateWrapper({
+                socket: managedColimaSocketPath(JISHUSHELL_HOME, COLIMA_PROFILE),
+                coreStartWrapper: coreStartWrapperPath,
+            }),
+            installScope: "core",
+            requiresSudo: false,
+            reloadRequired: true,
+            fix: "system-reload",
+        }, {
+            component: "launchd",
+            id: "core.launchd-agent",
+            path: join(resolveLaunchAgentsDir(realHome), "com.jishushell.core.plist"),
+            content: buildCorePlist({
+                gateWrapperPath,
+                logPath: join(JISHUSHELL_HOME, "jishushell-core.log"),
+            }),
+            installScope: "core",
+            requiresSudo: false,
+            reloadRequired: true,
+            fix: "system-reload",
+        });
+        return files;
+    }
+    files.push({
+        component: "systemd",
+        id: "core.systemd-unit",
+        path: SYSTEMD_CORE_SERVICE_PATH,
+        content: buildJishushellCoreSystemdUnit({
+            currentUser: resolveServiceUser(),
+            realHome,
+            coreStartWrapperPath,
+        }),
+        installScope: "core",
+        requiresSudo: true,
+        reloadRequired: true,
+        fix: "system-reload",
+    });
+    return files;
+}
+export function getExpectedPanelSystemFiles(corePort = _serverPort, panelPort = DEFAULT_PANEL_PORT) {
+    const nodeBin = process.execPath;
+    const panelBin = resolveBundledPanelServerBin();
+    const realHome = resolveRealHome();
+    const panelStartWrapperPath = join(BIN_DIR, "jishushell-panel-start");
+    const files = [
+        {
+            component: "wrapper",
+            id: "panel.start-wrapper",
+            path: panelStartWrapperPath,
+            content: buildPanelStartWrapperContent({
+                nodeBin,
+                panelBin,
+                realHome,
+                corePort,
+                panelPort,
+            }),
+            installScope: "panel",
+            requiresSudo: false,
+            reloadRequired: true,
+            fix: "system-reload",
+        },
+    ];
+    if (process.platform === "darwin") {
+        files.push({
+            component: "launchd",
+            id: "panel.launchd-agent",
+            path: join(resolveLaunchAgentsDir(realHome), "com.jishushell.panel.plist"),
+            content: buildPanelPlist({
+                panelWrapperPath: panelStartWrapperPath,
+                logPath: join(JISHUSHELL_HOME, "jishushell-panel.log"),
+                home: realHome,
+                jishuHome: JISHUSHELL_HOME,
+                corePort,
+                panelPort,
+            }),
+            installScope: "panel",
+            requiresSudo: false,
+            reloadRequired: true,
+            fix: "system-reload",
+        });
+        return files;
+    }
+    files.push({
+        component: "systemd",
+        id: "panel.systemd-unit",
+        path: SYSTEMD_PANEL_SERVICE_PATH,
+        content: buildJishushellPanelSystemdUnit({
+            currentUser: resolveServiceUser(),
+            realHome,
+            panelStartWrapperPath,
+            corePort,
+            panelPort,
+        }),
+        installScope: "panel",
+        requiresSudo: true,
+        reloadRequired: true,
+        fix: "system-reload",
+    });
+    return files;
+}
+export function getExpectedNomadSystemFiles() {
+    const configPath = join(NOMAD_CONFIG_DIR, "nomad.hcl");
+    const files = [
+        {
+            component: "nomad",
+            id: "nomad.config",
+            path: configPath,
+            content: buildExpectedNomadConfigContent(),
+            installScope: "nomad",
+            requiresSudo: false,
+            reloadRequired: true,
+            fix: "system-reload",
+        },
+    ];
+    const nomadPath = resolveNomadExecutable();
+    if (process.platform === "darwin") {
+        const laDir = resolveLaunchAgentsDir();
+        const colimaSocket = managedColimaSocketPath(JISHUSHELL_HOME, COLIMA_PROFILE);
+        const colimaDockerHost = managedColimaDockerHost(JISHUSHELL_HOME, COLIMA_PROFILE);
+        const colimaWrapperPath = join(BIN_DIR, "colima-launchd-wrapper.sh");
+        const nomadWrapperPath = join(BIN_DIR, "nomad-launchd-wrapper.sh");
+        files.push({
+            component: "wrapper",
+            id: "nomad.colima-wrapper",
+            path: colimaWrapperPath,
+            content: buildColimaWrapperScript({
+                colimaHome: _COLIMA_DIR,
+                profile: COLIMA_PROFILE,
+                socket: colimaSocket,
+                colimaBin: resolveColimaExecutable(),
+            }),
+            installScope: "nomad",
+            requiresSudo: false,
+            reloadRequired: true,
+            fix: "system-reload",
+        }, {
+            component: "launchd",
+            id: "nomad.colima-launchd-agent",
+            path: join(laDir, "com.jishushell.colima.plist"),
+            content: buildColimaPlist({
+                wrapperPath: colimaWrapperPath,
+                colimaHome: _COLIMA_DIR,
+                logPath: join(_COLIMA_DIR, "colima-launchd.log"),
+            }),
+            installScope: "nomad",
+            requiresSudo: false,
+            reloadRequired: true,
+            fix: "system-reload",
+        }, {
+            component: "wrapper",
+            id: "nomad.launchd-wrapper",
+            path: nomadWrapperPath,
+            content: buildNomadWaitWrapper({
+                dockerHost: colimaDockerHost,
+                nomadBin: nomadPath,
+                configPath,
+            }),
+            installScope: "nomad",
+            requiresSudo: false,
+            reloadRequired: true,
+            fix: "system-reload",
+        }, {
+            component: "launchd",
+            id: "nomad.launchd-agent",
+            path: join(laDir, "com.jishushell.nomad.plist"),
+            content: buildNomadPlist({
+                wrapperPath: nomadWrapperPath,
+                dockerHost: colimaDockerHost,
+                logPath: join(NOMAD_CONFIG_DIR, "nomad.log"),
+            }),
+            installScope: "nomad",
+            requiresSudo: false,
+            reloadRequired: true,
+            fix: "system-reload",
+        });
+        return files;
+    }
+    files.push({
+        component: "systemd",
+        id: "nomad.systemd-unit",
+        path: SYSTEMD_NOMAD_SERVICE_PATH,
+        content: buildNomadSystemdUnit({ nomadPath, configPath }),
+        installScope: "nomad",
+        requiresSudo: true,
+        reloadRequired: true,
+        fix: "system-reload",
+    });
+    return files;
+}
+export function getExpectedSystemFiles(options = {}) {
+    const config = getCoreConfig();
+    const envCorePort = Number(process.env.JISHUSHELL_CORE_PORT);
+    const corePort = options.corePort ??
+        (Number.isFinite(envCorePort) && envCorePort > 0 ? envCorePort : Number(config.core_port) || _serverPort);
+    const panelPort = options.panelPort ?? DEFAULT_PANEL_PORT;
+    const includePanel = options.includePanel ?? hasBundledPanel();
+    const includeNomad = options.includeNomad ?? config.service_manager === "nomad";
+    const files = getExpectedCoreSystemFiles(corePort);
+    if (includePanel)
+        files.push(...getExpectedPanelSystemFiles(corePort, panelPort));
+    if (includeNomad)
+        files.push(...getExpectedNomadSystemFiles());
+    return files;
+}
+function persistCoreServicePort(port) {
+    const config = getCoreConfig();
+    if (Number(config.core_port) === port)
+        return;
+    config.core_port = port;
+    saveCoreConfig(config);
+}
+// ── Task tracker (for SSE progress) ────────────────────────────────
+// Storage, event dispatch, and subscribe plumbing now live in
+// task-registry.ts so non-setup callers can publish tasks without pulling in
+// the rest of setup-manager's bootstrap surface. These re-exports preserve the
+// original import surface used by integration modules, routes, and CLI.
+export { createTask, emitTask, getTask, getTaskSnapshot, getRunningTasks, subscribeTask, } from "../tasks/registry.js";
+const ANSI_ESCAPE_RE = /\u001B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g;
+function sanitizeTaskLine(line) {
+    return line
+        .replace(ANSI_ESCAPE_RE, "")
+        .replace(/[\u0000-\u0008\u000B-\u001F\u007F]/g, "")
+        .trimEnd();
+}
+/** Run a shell command as a spawned process, streaming output to a task */
+export function spawnWithTask(task, cmd, args, options = {}) {
+    return new Promise((resolve) => {
+        const env = { ...process.env, ...options.env };
+        const child = nodeSpawn(cmd, args, {
+            env,
+            cwd: options.cwd,
+            timeout: options.timeout || 600000,
+        });
+        let output = "";
+        const stdoutDecoder = new StringDecoder("utf8");
+        const stderrDecoder = new StringDecoder("utf8");
+        let stdoutPending = "";
+        let stderrPending = "";
+        const emitLine = (rawLine) => {
+            const line = sanitizeTaskLine(rawLine);
+            if (!line.trim())
+                return;
+            // Try to parse progress
+            if (options.progressParser) {
+                const pct = options.progressParser(line);
+                if (pct !== null) {
+                    emitTask(task, { type: "progress", message: line, progress: pct });
+                    return;
+                }
+            }
+            emitTask(task, { type: "log", message: line });
+        };
+        const handleDecodedText = (text, stream) => {
+            if (!text)
+                return;
+            output += text;
+            const normalized = `${stream === "stdout" ? stdoutPending : stderrPending}${text}`
+                .replace(/\r\n/g, "\n")
+                .replace(/\r/g, "\n");
+            const lines = normalized.split("\n");
+            const pending = lines.pop() ?? "";
+            if (stream === "stdout")
+                stdoutPending = pending;
+            else
+                stderrPending = pending;
+            for (const line of lines) {
+                emitLine(line);
+            }
+        };
+        child.stdout?.on("data", (data) => {
+            handleDecodedText(stdoutDecoder.write(data), "stdout");
+        });
+        child.stderr?.on("data", (data) => {
+            handleDecodedText(stderrDecoder.write(data), "stderr");
+        });
+        child.on("close", (code) => {
+            handleDecodedText(stdoutDecoder.end(), "stdout");
+            handleDecodedText(stderrDecoder.end(), "stderr");
+            emitLine(stdoutPending);
+            emitLine(stderrPending);
+            resolve({ ok: code === 0, output });
+        });
+        child.on("error", (err) => {
+            emitTask(task, { type: "log", message: `Error: ${err.message}` });
+            resolve({ ok: false, output: err.message });
+        });
+    });
+}
+// ── Progress parsers ───────────────────────────────────────────────
+export function npmProgressParser(line) {
+    // npm shows "added X packages" at the end
+    if (line.includes("added") && line.includes("packages"))
+        return 100;
+    // npm progress: "reify:packagename: timing"
+    if (line.includes("reify:"))
+        return null; // just a log line
+    return null;
+}
+export function dockerBuildProgressParser(line) {
+    // Docker build steps: "Step 1/6", "Step 2/6", etc.
+    const legacyMatch = line.match(/Step\s+(\d+)\/(\d+)/);
+    if (legacyMatch) {
+        return Math.round((parseInt(legacyMatch[1], 10) / parseInt(legacyMatch[2], 10)) * 100);
+    }
+    // BuildKit plain output: "#5 [2/4] COPY node_modules ..."
+    const buildkitMatch = line.match(/\[(\d+)\/(\d+)\]/);
+    if (buildkitMatch) {
+        return Math.round((parseInt(buildkitMatch[1], 10) / parseInt(buildkitMatch[2], 10)) * 100);
+    }
+    if (/exporting to image/i.test(line))
+        return 95;
+    if (/naming to /i.test(line))
+        return 98;
+    return null;
+}
+function curlProgressParser(line) {
+    // curl with -# shows progress
+    const match = line.match(/(\d+\.?\d*)%/);
+    if (match)
+        return Math.round(parseFloat(match[1]));
+    return null;
+}
+// ── Dir size tracker for npm installs ──────────────────────────────
+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], 10) || 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function checkCommand(cmd, versionFlag = "--version") {
+    try {
+        const version = execFileSync(cmd, [versionFlag], { encoding: "utf-8", timeout: 10000, stdio: ["pipe", "pipe", "pipe"] }).trim();
+        let cmdPath = "";
+        try {
+            cmdPath = execFileSync("which", [cmd], { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] }).trim();
+        }
+        catch { }
+        return { ok: true, version, path: cmdPath };
+    }
+    catch {
+        return { ok: false, version: "", path: "" };
+    }
+}
+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") {
+            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"] });
+                if (matchesPort(result))
+                    return true;
+            }
+            catch {
+            }
+            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 {
+        return false;
+    }
+}
+function waitForListeningPort(port, timeoutSeconds) {
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    while (Date.now() < deadline) {
+        if (isPortListening(port))
+            return true;
+        try {
+            execFileSync("sleep", ["1"], { timeout: 2000 });
+        }
+        catch {
+            return isPortListening(port);
+        }
+    }
+    return isPortListening(port);
+}
+function checkSudo() {
+    try {
+        execSync("sudo -n true 2>/dev/null", { timeout: 3000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Check if kernel memory cgroup is enabled (required for Docker memory stats on RPi) */
+function isCgroupMemoryEnabled() {
+    try {
+        const cgroups = readFileSync("/proc/cgroups", "utf-8");
+        const memLine = cgroups.split("\n").find(l => l.startsWith("memory\t"));
+        if (!memLine)
+            return false;
+        // Format: name hierarchy num_cgroups enabled
+        return memLine.trim().endsWith("1");
+    }
+    catch {
+        return true; /* non-Linux or unreadable — assume ok */
+    }
+}
+/** Enable cgroup memory in boot cmdline if not already enabled. Returns true if a reboot is needed. */
+export function ensureCgroupMemory() {
+    if (isCgroupMemoryEnabled())
+        return false;
+    const candidates = ["/boot/firmware/cmdline.txt", "/boot/cmdline.txt"];
+    for (const f of candidates) {
+        if (!existsSync(f))
+            continue;
+        try {
+            const content = readFileSync(f, "utf-8").trim();
+            if (content.includes("cgroup_memory=1"))
+                return false; // already in cmdline, just needs reboot
+            const patched = `${content} cgroup_memory=1 cgroup_enable=memory`;
+            execFileSync("sudo", ["cp", f, f + ".bak"], { timeout: 5000 });
+            sudoCopySystemFile(patched + "\n", f, "644");
+            console.log(`[setup] enabled cgroup memory in ${f} (reboot required)`);
+            return true;
+        }
+        catch (e) {
+            console.warn(`[setup] failed to patch ${f}:`, e.message);
+        }
+    }
+    return false;
+}
+function canAccessDockerDaemon(timeout = 10000) {
+    const env = buildDockerClientEnv({
+        jishuHome: JISHUSHELL_HOME,
+        colimaProfile: COLIMA_PROFILE,
+    });
+    try {
+        execFileSync("docker", ["info"], { timeout, stdio: "ignore", env });
+        return true;
+    }
+    catch { }
+    try {
+        execFileSync("sudo", ["-n", "docker", "info"], { timeout, stdio: "ignore", env });
+        return true;
+    }
+    catch { }
+    return false;
+}
+function getDockerVersionLine(timeout = 10000) {
+    try {
+        return execFileSync("docker", ["--version"], { encoding: "utf-8", timeout }).trim();
+    }
+    catch { }
+    try {
+        return execFileSync("sudo", ["-n", "docker", "--version"], { encoding: "utf-8", timeout }).trim();
+    }
+    catch { }
+    return "installed";
+}
+export async function getSetupStatus() {
+    // Fast path: if setup is already complete, do lightweight checks before returning cached result
+    const config = getCoreConfig();
+    if (config.service_manager) {
+        const localBin = join(OPENCLAW_BIN_DIR, "openclaw");
+        const localBinOk = existsSync(localBin);
+        const fastDockerImageReady = checkDockerImageExists();
+        const openclawOk = localBinOk || fastDockerImageReady;
+        // Lightweight validation: verify critical services are actually available
+        const dockerOk = canAccessDockerDaemon(5000);
+        const nomadOk = isPortListening(4646);
+        const hasSudo = checkSudo();
+        // If any critical check fails, fall through to the slow full check path
+        if (!openclawOk || !dockerOk || !nomadOk || !hasSudo) {
+            // Fall through to full check below
+        }
+        else {
+            // Fetch real versions (cheap execs, no fallback to slow path)
+            let dockerVer = "installed";
+            try {
+                dockerVer = execFileSync("docker", ["--version"], { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] }).trim().split("\n")[0];
+            }
+            catch { }
+            let nomadVer = "installed";
+            try {
+                nomadVer = execFileSync(NOMAD_BIN, ["--version"], { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] }).trim().split("\n")[0];
+            }
+            catch { }
+            let openclawVer = "installed";
+            let openclawPath = localBin;
+            // Prefer npm package.json for accurate OpenClaw version.
+            try {
+                const pkg = join(OPENCLAW_MODULES, "openclaw", "package.json");
+                if (existsSync(pkg))
+                    openclawVer = JSON.parse(readFileSync(pkg, "utf-8")).version || openclawVer;
+            }
+            catch { }
+            const runtimes = await buildRuntimesStatus();
+            const ready = requiredRuntimesReady(runtimes);
+            return {
+                node: { name: "Node.js", installed: true, running: true, version: process.version, path: process.execPath },
+                docker: { name: "Docker", installed: true, running: true, version: dockerVer, path: "" },
+                nomad: { name: "Nomad", installed: true, running: true, version: nomadVer, path: NOMAD_BIN },
+                openclaw: { name: "OpenClaw", installed: openclawOk, running: false, version: openclawVer, path: openclawPath },
+                runtimeImageReady: fastDockerImageReady,
+                ready,
+                providerConfigured: hasLlmProviderSetup(),
+                hasSudo: true,
+                runtimes,
+            };
+        }
+    }
+    const NODE_MINIMUM_MAJOR = 22;
+    // Use the currently-running Node binary (process.execPath) as the ground
+    // truth — avoids false-negative when PATH doesn't include nvm's bin dir
+    // (e.g. when started via systemd with a minimal environment).
+    const nodeVersion = process.version;
+    const nodeMajor = parseInt(nodeVersion.replace("v", "").split(".")[0], 10);
+    const nodeStatus = {
+        name: "Node.js",
+        installed: true,
+        running: true,
+        version: nodeVersion,
+        path: process.execPath,
+        needsUpgrade: nodeMajor < NODE_MINIMUM_MAJOR,
+    };
+    const docker = checkCommand("docker");
+    // Use docker info to verify daemon accessibility (not just process existence)
+    // Also try sudo in case the user hasn't logged out since being added to the docker group
+    const dockerRunning = canAccessDockerDaemon(10000);
+    const dockerStatus = {
+        name: "Docker",
+        installed: docker.ok,
+        running: dockerRunning,
+        version: docker.version.split("\n")[0],
+        path: docker.path,
+    };
+    let nomad = checkCommand("nomad");
+    if (!nomad.ok && existsSync(NOMAD_BIN)) {
+        nomad = checkCommand(NOMAD_BIN);
+    }
+    const nomadRunning = isPortListening(4646);
+    const nomadStatus = {
+        name: "Nomad",
+        installed: nomad.ok,
+        running: nomadRunning,
+        version: nomad.version.split("\n")[0],
+        path: nomad.path || NOMAD_BIN,
+    };
+    let openclaw = checkCommand("openclaw");
+    if (!openclaw.ok) {
+        const localBin = join(OPENCLAW_BIN_DIR, "openclaw");
+        if (existsSync(localBin)) {
+            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 { }
+            openclaw = { ok: true, version: ver, path: localBin };
+        }
+    }
+    const runtimeImageReady = checkDockerImageExists();
+    // If the Docker image already exists, treat openclaw as installed even when
+    // the local npm package is absent — the image is all that's needed to run instances.
+    if (!openclaw.ok && runtimeImageReady) {
+        const imageTag = resolveDockerImageTag();
+        const tagVersion = imageTag.split(":").pop() || "local";
+        openclaw = { ok: true, version: tagVersion, path: imageTag };
+    }
+    const openclawStatus = {
+        name: "OpenClaw",
+        installed: openclaw.ok,
+        running: false,
+        version: openclaw.version.split("\n")[0],
+        path: openclaw.path,
+    };
+    const runtimes = await buildRuntimesStatus();
+    const ready = nodeStatus.installed
+        && !nodeStatus.needsUpgrade
+        && dockerStatus.installed
+        && dockerStatus.running
+        && nomadStatus.installed
+        && nomadStatus.running
+        && requiredRuntimesReady(runtimes);
+    const providerConfigured = hasLlmProviderSetup();
+    // Read-only check: report whether cgroup memory needs fixing (actual fix is in POST install routes)
+    let needsReboot;
+    if (dockerStatus.installed && !isCgroupMemoryEnabled()) {
+        needsReboot = true;
+    }
+    const runningTasks = getRunningTasks();
+    return { node: nodeStatus, docker: dockerStatus, nomad: nomadStatus, openclaw: openclawStatus, ready, providerConfigured, runtimeImageReady, hasSudo: checkSudo(), needsReboot, runningTasks: runningTasks.length ? runningTasks : undefined, runtimes };
+}
+/**
+ * Build the per-runtime install status block by iterating over every
+ * registered integration. A new integration that implements `getInstallStatus()`
+ * automatically appears here — no change required in this function.
+ *
+ * Each probe is bounded by a short timeout so a hung integration (slow docker
+ * socket, DNS stall) cannot block the `/api/setup/status` endpoint. This
+ * mirrors the pattern used by `services/integrations/catalog.ts` so the
+ * Setup wizard and `/api/integrations` see a consistent view.
+ */
+const BUILD_RUNTIMES_PROBE_TIMEOUT_MS = 2500;
+function requiredRuntimesReady(runtimes) {
+    const required = listRegisteredIntegrations().filter((integration) => integration.manifest?.requiredForSetupReady === true);
+    if (required.length === 0)
+        return false;
+    return required.every((integration) => {
+        const status = runtimes?.[integration.kind];
+        return status?.installed === true && status.imageReady === true;
+    });
+}
+async function buildRuntimesStatus() {
+    const integrations = listRegisteredIntegrations().filter((a) => typeof a.getInstallStatus === "function");
+    const probes = integrations.map(async (integration) => {
+        let timer;
+        try {
+            const status = await Promise.race([
+                Promise.resolve(integration.getInstallStatus()),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error("install-status probe timed out")), BUILD_RUNTIMES_PROBE_TIMEOUT_MS);
+                }),
+            ]);
+            if (!status)
+                return null;
+            const sync = status;
+            return [integration.kind, { ...sync, required: integration.manifest?.requiredForSetupReady === true }];
+        }
+        catch {
+            return null;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    });
+    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) {
+    try {
+        const current = process.version; // e.g. "v20.20.1"
+        const currentMajor = parseInt(current.replace("v", "").split(".")[0], 10);
+        if (currentMajor >= targetMajor) {
+            return { ok: true, message: `Node.js ${current} already meets requirement (>= ${targetMajor})` };
+        }
+        const task = createTask("node-upgrade");
+        emitTask(task, { type: "progress", message: `升级 Node.js: ${current} → v${targetMajor}`, progress: 0 });
+        if (process.platform === "darwin") {
+            try {
+                execSync("brew --version", { timeout: 5000 });
+            }
+            catch {
+                emitTask(task, { type: "error", message: "未找到 Homebrew" });
+                task.status = "error";
+                return { ok: false, message: "Homebrew not found", error: "Install Homebrew first: https://brew.sh", taskId: task.id };
+            }
+            emitTask(task, { type: "progress", message: `安装 Node.js ${targetMajor} (brew)...`, progress: 20 });
+            const installResult = await spawnWithTask(task, "brew", ["install", `node@${targetMajor}`], { timeout: 300000 });
+            if (!installResult.ok) {
+                emitTask(task, { type: "error", message: "Node.js 安装失败" });
+                task.status = "error";
+                return { ok: false, message: "Node.js install failed", error: installResult.output, taskId: task.id };
+            }
+            emitTask(task, { type: "progress", message: "链接 Node.js...", progress: 80 });
+            try {
+                execSync(`brew link --overwrite --force node@${targetMajor}`, { timeout: 30000 });
+            }
+            catch { }
+        }
+        else {
+            // Use NodeSource setup script
+            emitTask(task, { type: "log", message: "下载 NodeSource 安装脚本..." });
+            emitTask(task, { type: "progress", message: "配置软件源...", progress: 10 });
+            // Use a unique temp path to prevent TOCTOU race: a fixed name like
+            // /tmp/nodesource_setup_22.sh could be replaced by another process
+            // between download (curl) and execution (sudo bash).
+            const nsScriptPath = join(tmpdir(), `nodesource_setup_${targetMajor}_${randomBytes(8).toString("hex")}.sh`);
+            const dlResult = await spawnWithTask(task, "curl", ["-fsSL", `https://deb.nodesource.com/setup_${targetMajor}.x`, "-o", nsScriptPath], { timeout: 60000 });
+            if (!dlResult.ok) {
+                emitTask(task, { type: "error", message: "NodeSource 脚本下载失败" });
+                task.status = "error";
+                return { ok: false, message: "NodeSource script download failed", error: dlResult.output, taskId: task.id };
+            }
+            const setupResult = await spawnWithTask(task, "sudo", ["-E", "bash", nsScriptPath], { timeout: 120000 });
+            if (!setupResult.ok) {
+                emitTask(task, { type: "error", message: "NodeSource 配置失败" });
+                task.status = "error";
+                return { ok: false, message: "Node.js source setup failed", error: setupResult.output, taskId: task.id };
+            }
+            emitTask(task, { type: "progress", message: "安装 Node.js...", progress: 50 });
+            const installResult = await spawnWithTask(task, "sudo", ["apt-get", "install", "-y", "nodejs"], { timeout: 300000 });
+            if (!installResult.ok) {
+                emitTask(task, { type: "error", message: "Node.js 安装失败" });
+                task.status = "error";
+                return { ok: false, message: "Node.js install failed", error: installResult.output, taskId: task.id };
+            }
+        }
+        const newVersion = execSync("node --version", { encoding: "utf-8", timeout: 5000 }).trim();
+        emitTask(task, { type: "done", message: `Node.js 升级完成: ${newVersion}`, progress: 100 });
+        task.status = "done";
+        return { ok: true, message: `Node.js upgraded to ${newVersion}. 请重启 JishuShell 以使用新版本。`, taskId: task.id };
+    }
+    catch (e) {
+        return { ok: false, message: "Node.js upgrade failed", error: e.message };
+    }
+}
+// ── Install Docker (async with progress) ───────────────────────────
+async function installDockerWithTask(task) {
+    try {
+        emitTask(task, { type: "progress", message: "开始安装 Docker...", progress: 0 });
+        // macOS short-circuit: the rest of this function targets apt/get.docker.com,
+        // both of which silently no-op or hard-fail on Darwin. Docker on macOS is
+        // provided by Colima (auto-installed by the bash installer at
+        // install/jishu-install.sh) — not by this code path. Refuse early with a
+        // clear pointer so the user doesn't see a confusing apt error.
+        if (process.platform === "darwin") {
+            const msg = "macOS Docker 需要 Colima。请运行 shell 安装器 (curl -fsSL https://raw.githubusercontent.com/nicepkg/jishushell/main/install/jishu-install.sh | bash),或参阅 docs/macos-colima.md 手动安装 Colima。";
+            emitTask(task, { type: "error", message: msg });
+            task.status = "error";
+            return { ok: false, message: msg, error: "darwin-not-supported-via-this-path" };
+        }
+        const user = execSync("whoami", { encoding: "utf-8", timeout: 5000 }).trim();
+        // ── Try the get.docker.com convenience script ─────────────────
+        emitTask(task, { type: "log", message: "下载 Docker 安装脚本..." });
+        emitTask(task, { type: "progress", message: "下载中...", progress: 5 });
+        // Unique temp path prevents TOCTOU: another user can't swap a fixed /tmp/get-docker.sh
+        // between our download and the sudo sh invocation.
+        const dockerScriptPath = join(tmpdir(), `get-docker_${randomBytes(8).toString("hex")}.sh`);
+        const dlResult = await spawnWithTask(task, "curl", ["-fsSL", "https://get.docker.com", "-o", dockerScriptPath], {
+            timeout: 60000,
+        });
+        let scriptOk = false;
+        if (dlResult.ok) {
+            emitTask(task, { type: "log", message: "运行 Docker 安装脚本..." });
+            const scriptResult = await spawnWithTask(task, "sudo", ["sh", dockerScriptPath], {
+                timeout: 600000,
+                progressParser: (line) => {
+                    if (line.includes("Executing docker install script"))
+                        return 10;
+                    if (line.includes("apt-get update"))
+                        return 20;
+                    if (line.includes("Installing packages"))
+                        return 40;
+                    if (line.includes("docker-ce"))
+                        return 60;
+                    if (line.includes("containerd"))
+                        return 70;
+                    if (line.includes("Created symlink"))
+                        return 85;
+                    return null;
+                },
+            });
+            scriptOk = scriptResult.ok;
+            if (!scriptOk) {
+                emitTask(task, { type: "log", message: "便捷脚本安装失败，尝试 apt 仓库方式..." });
+            }
+        }
+        else {
+            emitTask(task, { type: "log", message: "下载便捷脚本失败，尝试 apt 仓库方式..." });
+        }
+        // ── Fallback: apt-repo manual install (handles Debian trixie pre-releases) ─
+        if (!scriptOk) {
+            emitTask(task, { type: "progress", message: "通过 apt 仓库安装 Docker...", progress: 15 });
+            // Detect system ID + codename; downgrade trixie/sid to bookworm.
+            let codename = "bookworm";
+            let repoOs = "debian";
+            try {
+                const osRelease = readFileSync("/etc/os-release", "utf-8");
+                const codenameMatch = osRelease.match(/^VERSION_CODENAME=(.+)$/m);
+                const distroId = (osRelease.match(/^ID=(.+)$/m)?.[1] || "debian").trim();
+                const raw = (codenameMatch?.[1] || "").trim();
+                repoOs = (distroId === "ubuntu") ? "ubuntu" : "debian";
+                // Debian testing/unstable (trixie, sid) → use the previous stable repo.
+                const unstableCodenames = new Set(["trixie", "forky", "sid", "unstable", "testing"]);
+                const ubuntuFallback = "noble";
+                if (distroId === "ubuntu" && unstableCodenames.has(raw)) {
+                    codename = ubuntuFallback;
+                }
+                else if (unstableCodenames.has(raw)) {
+                    codename = "bookworm";
+                }
+                else {
+                    codename = raw || "bookworm";
+                }
+            }
+            catch { }
+            emitTask(task, { type: "log", message: `使用仓库 codename: ${codename} (OS: ${repoOs})` });
+            const aptSteps = [
+                ["sudo", ["apt-get", "update", "-qq"]],
+                ["sudo", ["apt-get", "install", "-y", "-qq", "ca-certificates", "curl", "gnupg"]],
+                ["sudo", ["install", "-m", "0755", "-d", "/etc/apt/keyrings"]],
+                ["sudo", ["bash", "-c",
+                        `curl -fsSL https://download.docker.com/linux/${repoOs}/gpg | gpg --dearmor --yes -o /etc/apt/keyrings/docker.gpg && chmod a+r /etc/apt/keyrings/docker.gpg`
+                    ]],
+                ["sudo", ["bash", "-c",
+                        `echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/${repoOs} ${codename} stable" > /etc/apt/sources.list.d/docker.list`
+                    ]],
+                ["sudo", ["apt-get", "update", "-qq"]],
+                ["sudo", ["apt-get", "install", "-y", "-qq",
+                        "docker-ce", "docker-ce-cli", "containerd.io", "docker-buildx-plugin", "docker-compose-plugin"
+                    ]],
+            ];
+            const progressSteps = [5, 15, 20, 30, 35, 45, 80];
+            for (let i = 0; i < aptSteps.length; i++) {
+                const [cmd, args] = aptSteps[i];
+                emitTask(task, { type: "progress", message: `${cmd} ${args[0]}...`, progress: progressSteps[i] });
+                const r = await spawnWithTask(task, cmd, args, { timeout: 300000 });
+                if (!r.ok) {
+                    emitTask(task, { type: "error", message: `apt 安装失败 (步骤 ${i + 1}): ${args.join(" ")}` });
+                    task.status = "error";
+                    return { ok: false, message: "Docker apt installation failed", error: r.output, taskId: task.id };
+                }
+            }
+        }
+        // ── Wrap up ────────────────────────────────────────────────────
+        emitTask(task, { type: "progress", message: "配置用户权限...", progress: 90 });
+        try {
+            execFileSync("sudo", ["groupadd", "docker"], { timeout: 10000 });
+        }
+        catch { }
+        try {
+            execFileSync("sudo", ["usermod", "-aG", "docker", user], { timeout: 10000 });
+        }
+        catch { }
+        emitTask(task, { type: "log", message: "注意: Docker 用户组变更可能需要重新登录才能生效" });
+        emitTask(task, { type: "progress", message: "启动 Docker 服务...", progress: 93 });
+        try {
+            execSync("sudo systemctl enable --now docker", { timeout: 30000 });
+        }
+        catch { }
+        // Enable cgroup memory for Docker stats (RPi default has it disabled)
+        const needsReboot = ensureCgroupMemory();
+        if (needsReboot) {
+            emitTask(task, { type: "log", message: "已启用内存 cgroup（需要重启生效，Docker 内存统计才会正常）" });
+        }
+        const version = getDockerVersionLine(10000);
+        // Verify the daemon via `sudo docker` (needed when the current user is not in the docker group yet).
+        const daemonOk = canAccessDockerDaemon(10000);
+        if (daemonOk) {
+            const doneMsg = needsReboot
+                ? `Docker 安装完成: ${version}（需要重启以启用内存统计）`
+                : `Docker 安装完成: ${version}`;
+            emitTask(task, { type: "done", message: doneMsg, progress: 100 });
+            task.status = "done";
+            return { ok: true, message: `Docker installed: ${version}`, needsReboot, taskId: task.id };
+        }
+        else {
+            emitTask(task, { type: "error", message: `Docker 已安装但 daemon 未运行: ${version}` });
+            task.status = "error";
+            return { ok: false, message: `Docker installed but daemon not accessible`, error: "Try: sudo systemctl start docker", taskId: task.id };
+        }
+    }
+    catch (e) {
+        return { ok: false, message: "Docker installation failed", error: e.message };
+    }
+}
+/** Ensure current user is in docker group and service is enabled (idempotent) */
+function ensureDockerPostInstall() {
+    try {
+        const user = execSync("whoami", { encoding: "utf-8", timeout: 5000 }).trim();
+        try {
+            execFileSync("sudo", ["groupadd", "docker"], { timeout: 5000, stdio: "pipe" });
+        }
+        catch { }
+        try {
+            execFileSync("sudo", ["usermod", "-aG", "docker", user], { timeout: 5000 });
+        }
+        catch { }
+        try {
+            execFileSync("sudo", ["systemctl", "enable", "--now", "docker"], { timeout: 10000 });
+        }
+        catch { }
+    }
+    catch { }
+}
+export async function installDocker() {
+    if (canAccessDockerDaemon(5000)) {
+        ensureDockerPostInstall();
+        const needsReboot = ensureCgroupMemory();
+        return { ok: true, message: "Docker already installed", needsReboot };
+    }
+    const task = createTask("docker");
+    return installDockerWithTask(task);
+}
+export function startInstallDocker() {
+    if (canAccessDockerDaemon(5000)) {
+        ensureDockerPostInstall();
+        ensureCgroupMemory();
+        return { ok: true, message: "Docker already installed" };
+    }
+    const task = createTask("docker");
+    void installDockerWithTask(task).catch((err) => {
+        emitTask(task, { type: "error", message: `Docker 安装失败: ${err?.message || err}` });
+        task.status = "error";
+    });
+    return { ok: true, message: "Docker install started", taskId: task.id };
+}
+// ── Install Nomad (async with progress) ────────────────────────────
+function getNomadDownloadUrl() {
+    const arch = process.arch === "arm64" ? "arm64" : "amd64";
+    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)) {
+            // Boundary check 1: is it a regular file?
+            try {
+                const stat = (await import("fs")).statSync(NOMAD_BIN);
+                if (!stat.isFile()) {
+                    try {
+                        unlinkSync(NOMAD_BIN);
+                    }
+                    catch { }
+                }
+            }
+            catch { }
+            if (existsSync(NOMAD_BIN)) {
+                // Boundary check 2: is it executable?
+                try {
+                    chmodSync(NOMAD_BIN, 0o755);
+                }
+                catch { }
+                // Boundary check 3: does it actually run?
+                let versionLine = "";
+                try {
+                    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 {
+                            installNomadSystemd();
+                        }
+                        catch { }
+                        if (!isPortListening(4646)) {
+                            await startNomad();
+                        }
+                    }
+                    return migrated
+                        ? { ok: true, message: `Nomad migrated to ${versionLine}` }
+                        : { ok: true, message: `Nomad already installed: ${versionLine}` };
+                }
+            }
+        }
+        // Fallback: if NOMAD_BIN still doesn't exist, check for a system-installed Nomad
+        // (e.g. installed via apt/dnf) and create a symlink so the systemd service path resolves.
+        if (!existsSync(NOMAD_BIN)) {
+            try {
+                const systemNomad = execSync("which nomad 2>/dev/null", { encoding: "utf-8" }).trim();
+                if (systemNomad && existsSync(systemNomad)) {
+                    ensureDirHost(BIN_DIR);
+                    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]}` };
+                }
+            }
+            catch { /* system nomad not found — proceed to download */ }
+        }
+        const task = createTask("nomad");
+        ensureDirHost(BIN_DIR);
+        const url = getNomadDownloadUrl();
+        const zipPath = join(BIN_DIR, "nomad.zip");
+        emitTask(task, { type: "progress", message: "下载 Nomad...", progress: 0 });
+        const result = await spawnWithTask(task, "curl", ["-fL", "--progress-bar", url, "-o", zipPath], {
+            timeout: 300000,
+            progressParser: curlProgressParser,
+        });
+        if (!result.ok) {
+            emitTask(task, { type: "error", message: "Nomad 下载失败" });
+            task.status = "error";
+            return { ok: false, message: "Nomad download failed", error: result.output, taskId: task.id };
+        }
+        emitTask(task, { type: "progress", message: "解压 Nomad...", progress: 80 });
+        try {
+            execSync("which unzip", { stdio: "ignore" });
+        }
+        catch {
+            emitTask(task, { type: "log", message: "未找到 unzip，尝试安装..." });
+            try {
+                if (process.platform === "linux") {
+                    execSync("sudo apt-get update -qq && sudo apt-get install -y -qq unzip", { timeout: 60000 });
+                }
+                else if (process.platform === "darwin") {
+                    execSync("brew install unzip", { timeout: 60000 });
+                }
+            }
+            catch (e) {
+                emitTask(task, { type: "error", message: "安装 unzip 失败，请手动安装后重试" });
+                throw e;
+            }
+        }
+        execFileSync("unzip", ["-o", zipPath, "-d", BIN_DIR], { timeout: 30000 });
+        chmodSync(NOMAD_BIN, 0o755);
+        try {
+            unlinkSync(zipPath);
+        }
+        catch { }
+        const version = execFileSync(NOMAD_BIN, ["version"], { encoding: "utf-8", timeout: 5000 }).trim();
+        emitTask(task, { type: "done", message: `Nomad 安装完成: ${version}`, progress: 100 });
+        task.status = "done";
+        return { ok: true, message: `Nomad installed: ${version}`, taskId: task.id };
+    }
+    catch (e) {
+        return { ok: false, message: "Nomad installation failed", error: e.message };
+    }
+}
+// ── Configure & start Nomad ────────────────────────────────────────
+/** Fix ~/.jishushell dirs if they were accidentally created as root (e.g. from an old sudo install). */
+function fixNomadDirOwnership() {
+    try {
+        const { statSync } = require("fs");
+        const stat = statSync(NOMAD_CONFIG_DIR);
+        if (stat.uid === 0) {
+            // Directory is owned by root — try to repair with sudo -n (non-interactive)
+            const currentUser = process.env.USER || process.env.LOGNAME || "";
+            if (currentUser) {
+                try {
+                    execFileSync("sudo", ["-n", "chown", "-R", `${currentUser}:${currentUser}`, JISHUSHELL_HOME], { timeout: 10000, stdio: "pipe" });
+                }
+                catch { /* sudo not available or no NOPASSWD — ignore */ }
+            }
+        }
+    }
+    catch { /* stat failed — dir doesn't exist yet, no action needed */ }
+}
+export function buildExpectedNomadConfigContent() {
+    const platform = osPlatform();
+    const loopbackIface = platform === "darwin" ? "lo0" : "lo";
+    const externalIface = detectNomadExternalInterface(loopbackIface);
+    const externalHostNetworkBlock = externalIface
+        ? `
+  host_network "external" {
+    interface = "${externalIface}"
+  }
+`
+        : "";
+    // Detect docker0 bridge CIDR so multi-container apps (weknora etc.) can
+    // declare `host_network: docker_bridge` on their ports and have Nomad
+    // publish them on the docker0 IP — which is what `host.docker.internal`
+    // resolves to inside peer containers. Hardcoding 172.17.0.0/16 would
+    // break setups where docker daemon.json overrides `bip` /
+    // `default-address-pools`. Fall back to the Docker default if detection
+    // fails (e.g. docker not yet installed at panel install time; doctor
+    // will regenerate later).
+    const dockerBridgeCidr = detectDockerBridgeCidr() || "172.17.0.0/16";
+    const dockerBridgeHostNetworkBlock = `
+  host_network "docker_bridge" {
+    cidr = "${dockerBridgeCidr}"
+  }
+`;
+    // Apple Silicon CPU fingerprint workaround. Nomad 1.6.x on darwin/arm64
+    // reads `hw.tbfrequency` (timebase, e.g. 24 MHz on M-series) as the CPU
+    // clock, so a 14-core M4 Max reports as 48 MHz total compute and every
+    // job that asks for CPU>48 gets rejected with "Resources exhausted on
+    // dimension cpu". Override with a conservative estimate (cores × 2500
+    // MHz) — M-series base clock is at least 2.5 GHz, so this never
+    // overcommits relative to actual silicon. Intel Macs fingerprint
+    // correctly and don't need the override.
+    const cpuTotalComputeBlock = platform === "darwin" && osArch() === "arm64"
+        ? `  cpu_total_compute = ${osCpus().length * 2500}  # Apple Silicon workaround: Nomad mis-fingerprints CPU freq via tbfrequency\n`
+        : "";
+    // macOS docker driver endpoint. macOS users run Docker via Colima
+    // (managed by this panel under `~/.jishushell/colima/jishushell/`) or
+    // Docker Desktop (`~/.docker/run/docker.sock`); neither exposes
+    // `/var/run/docker.sock` out of the box. Resolve the correct host once
+    // and bake it into the HCL so Nomad doesn't fall back to the default
+    // `unix:///var/run/docker.sock` and fail. Linux keeps the default
+    // (empty endpoint = Docker's standard /var/run/docker.sock).
+    const dockerHost = platform === "darwin"
+        ? resolveDockerHost({ jishuHome: JISHUSHELL_HOME, colimaProfile: COLIMA_PROFILE })
+        : undefined;
+    const dockerEndpointLine = dockerHost ? `\n    endpoint = "${dockerHost}"` : "";
+    const config = `
+data_dir = "${NOMAD_DATA_DIR}"
+
+bind_addr = "127.0.0.1"
+
+leave_on_terminate = false
+
+advertise {
+  http = "127.0.0.1"
+  rpc  = "127.0.0.1"
+  serf = "127.0.0.1"
+}
+
+server {
+  enabled = true
+  bootstrap_expect = 1
+}
+
+client {
+${cpuTotalComputeBlock}  enabled = true
+  servers = ["127.0.0.1:4647"]
+  network_interface = "${loopbackIface}"
+  alloc_dir = "${NOMAD_ALLOC_DIR}"
+${externalHostNetworkBlock}${dockerBridgeHostNetworkBlock}
+
+  # drain_on_shutdown intentionally omitted: on single-node Pi there is
+  # nowhere to drain workloads to, and draining on every systemctl restart
+  # would kill every running OpenClaw instance. Without this block Nomad
+  # leaves allocations running across client restarts — the docker driver
+  # re-attaches to the existing containers on startup.
+}
+
+plugin "docker" {
+  config {${dockerEndpointLine}
+    gc {
+      image = false
+    }
+    volumes {
+      enabled = true
+    }
+  }
+}
+
+plugin "raw_exec" {
+  config {
+    enabled = true
+  }
+}
+
+acl {
+  enabled = true
+}
+
+limits {
+  http_max_conns_per_client = 0
+}
+`;
+    return config;
+}
+function writeNomadConfig() {
+    fixNomadDirOwnership();
+    ensureDirHost(NOMAD_CONFIG_DIR);
+    ensureDirContainer(NOMAD_DATA_DIR);
+    ensureDirContainer(NOMAD_ALLOC_DIR);
+    writeConfigFile(join(NOMAD_CONFIG_DIR, "nomad.hcl"), buildExpectedNomadConfigContent());
+}
+function detectDockerBridgeCidr() {
+    // `docker network inspect bridge` returns the CIDR for docker0. The exact
+    // value depends on /etc/docker/daemon.json `bip` / `default-address-pools`
+    // — Docker's default is 172.17.0.0/16 but isn't guaranteed. We need the
+    // real value because Nomad uses `host_network "docker_bridge" { cidr = …}`
+    // to pick which interface to publish a port on for specs that declare
+    // `host_network: docker_bridge`. Wrong CIDR → port silently published on
+    // wrong interface → cross-task host.docker.internal calls get refused.
+    try {
+        const raw = execFileSync("docker", ["network", "inspect", "bridge", "--format", "{{(index .IPAM.Config 0).Subnet}}"], { encoding: "utf8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"] }).trim();
+        return /^\d{1,3}(\.\d{1,3}){3}\/\d{1,2}$/.test(raw) ? raw : "";
+    }
+    catch {
+        return "";
+    }
+}
+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;
+    const candidates = [
+        join(JISHUSHELL_HOME, "nomad.env"),
+        "/etc/jishushell/nomad.env",
+    ];
+    for (const envFile of candidates) {
+        if (!existsSync(envFile))
+            continue;
+        try {
+            const match = readFileSync(envFile, "utf-8").match(/^NOMAD_TOKEN=(.+)$/m);
+            if (match) {
+                process.env.NOMAD_TOKEN = match[1].trim();
+                return;
+            }
+        }
+        catch {
+            // no read permission, try next candidate
+        }
+    }
+    const legacy = getCoreConfig().nomad_token;
+    if (legacy)
+        process.env.NOMAD_TOKEN = legacy;
+}
+/** Verify the current NOMAD_TOKEN is accepted by the Nomad API. Returns false if it is missing or rejected (HTTP 403/401). */
+async function isNomadTokenValid() {
+    const token = process.env.NOMAD_TOKEN || getCoreConfig().nomad_token;
+    if (!token)
+        return false;
+    try {
+        const resp = await fetch("http://127.0.0.1:4646/v1/acl/token/self", {
+            headers: { "X-Nomad-Token": token },
+            signal: AbortSignal.timeout(5000),
+        });
+        return resp.status === 200;
+    }
+    catch {
+        return false;
+    }
+}
+function nomadApiHeaders(extra = {}) {
+    const token = process.env.NOMAD_TOKEN || getCoreConfig().nomad_token;
+    return token ? { "X-Nomad-Token": token, ...extra } : extra;
+}
+export async function ensureNomadMemoryOversubscriptionEnabled() {
+    try {
+        const resp = await fetch("http://127.0.0.1:4646/v1/operator/scheduler/configuration", {
+            headers: nomadApiHeaders(),
+            signal: AbortSignal.timeout(5000),
+        });
+        if (resp.status !== 200)
+            return;
+        const payload = await resp.json();
+        const scheduler = payload?.SchedulerConfig;
+        if (!scheduler || typeof scheduler !== "object")
+            return;
+        if (scheduler.MemoryOversubscriptionEnabled === true)
+            return;
+        const putResp = await fetch("http://127.0.0.1:4646/v1/operator/scheduler/configuration", {
+            method: "PUT",
+            headers: nomadApiHeaders({ "Content-Type": "application/json" }),
+            body: JSON.stringify({ ...scheduler, MemoryOversubscriptionEnabled: true }),
+            signal: AbortSignal.timeout(5000),
+        });
+        if (putResp.status === 200) {
+            console.log("[nomad] Enabled memory oversubscription so MemoryMaxMB becomes an actual task limit.");
+        }
+        else {
+            console.warn(`[nomad] Failed to enable memory oversubscription: HTTP ${putResp.status}`);
+        }
+    }
+    catch (e) {
+        console.warn("[nomad] Failed to enable memory oversubscription:", e.message);
+    }
+}
+/** Shared post-start sequence: load token, bootstrap ACL, enable oversubscription, enable node. */
+async function finalizeNomadStartup() {
+    loadNomadToken();
+    await bootstrapNomadACL();
+    await ensureNomadMemoryOversubscriptionEnabled();
+    enableNomadNodeEligibility();
+}
+async function bootstrapNomadACL() {
+    // If a token is already loaded, verify it's still valid before trusting it.
+    if (process.env.NOMAD_TOKEN || getCoreConfig().nomad_token) {
+        if (await isNomadTokenValid())
+            return;
+        console.log("[nomad] Stored ACL token is invalid — re-bootstrapping...");
+        delete process.env.NOMAD_TOKEN;
+    }
+    const nomadPath = existsSync(NOMAD_BIN) ? NOMAD_BIN : "nomad";
+    const doBootstrap = async () => {
+        try {
+            const raw = execFileSync(nomadPath, ["acl", "bootstrap", "-json"], {
+                timeout: 10000,
+                encoding: "utf-8",
+                env: { ...process.env, NOMAD_ADDR: "http://127.0.0.1:4646" },
+            });
+            return JSON.parse(raw).SecretID ?? null;
+        }
+        catch (e) {
+            // Return the raw stderr/stdout so caller can inspect it
+            throw e;
+        }
+    };
+    const saveToken = (token) => {
+        const envFile = join(JISHUSHELL_HOME, "nomad.env");
+        const envContent = `NOMAD_TOKEN=${token}\n`;
+        writeSecretFile(envFile, envContent);
+        try {
+            execFileSync("sudo", ["-n", "mkdir", "-p", "/etc/jishushell"], { timeout: 5000, stdio: "pipe" });
+            sudoCopySystemFile(envContent, "/etc/jishushell/nomad.env", "600");
+        }
+        catch (copyErr) {
+            console.warn("[nomad] Could not sync token to /etc/jishushell/nomad.env:", copyErr.message);
+        }
+        process.env.NOMAD_TOKEN = token;
+        console.log("[nomad] ACL token saved to", envFile);
+    };
+    try {
+        const token = await doBootstrap();
+        if (token)
+            saveToken(token);
+        return;
+    }
+    catch (e) {
+        const msg = (e.stderr || e.stdout || e.message || "").toString();
+        // "ACL bootstrap already done" — extract reset index and perform a reset
+        const resetMatch = msg.match(/reset index[:\s]+(\d+)/i);
+        if (!resetMatch) {
+            if (!msg.includes("bootstrap"))
+                console.warn("[nomad] ACL bootstrap warning:", msg);
+            return;
+        }
+        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).
+        // 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) {
+            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 {
+            execFileSync("sudo", ["-n", "systemctl", "restart", "nomad"], { timeout: 15000, stdio: "pipe" });
+        }
+        catch {
+            // No passwordless sudo — try pkill/re-spawn path (best effort)
+            try {
+                execFileSync("sudo", ["-n", "pkill", "-TERM", "-f", "nomad agent"], { stdio: "pipe" });
+            }
+            catch {
+                try {
+                    execFileSync("pkill", ["-TERM", "-f", "nomad agent"], { stdio: "pipe" });
+                }
+                catch { }
+            }
+        }
+        // Wait for Nomad to come back
+        for (let i = 0; i < 20; i++) {
+            await new Promise(r => setTimeout(r, 1000));
+            if (isPortListening(4646))
+                break;
+        }
+        // Bootstrap again — reset file is consumed by Nomad on first start after restart
+        try {
+            const token = await doBootstrap();
+            if (token)
+                saveToken(token);
+        }
+        catch (e2) {
+            console.warn("[nomad] ACL bootstrap after reset failed:", (e2.stderr || e2.message || "").toString().split("\n")[0]);
+        }
+    }
+}
+function enableNomadNodeEligibility() {
+    const nomadPath = existsSync(NOMAD_BIN) ? NOMAD_BIN : "nomad";
+    try {
+        const raw = execSync(`${nomadPath} node status -self -json`, {
+            timeout: 5000,
+            encoding: "utf-8",
+            env: { ...process.env, NOMAD_ADDR: "http://127.0.0.1:4646" },
+        });
+        const nodeId = JSON.parse(raw).ID;
+        if (!nodeId)
+            return;
+        execSync(`${nomadPath} node eligibility -enable ${nodeId}`, {
+            timeout: 5000,
+            env: { ...process.env, NOMAD_ADDR: "http://127.0.0.1:4646" },
+        });
+    }
+    catch {
+    }
+}
+export async function startNomad() {
+    try {
+        const configPath = join(NOMAD_CONFIG_DIR, "nomad.hcl");
+        const readConfig = () => {
+            try {
+                return existsSync(configPath) ? readFileSync(configPath, "utf-8") : "";
+            }
+            catch {
+                return "";
+            }
+        };
+        const oldConfig = readConfig();
+        writeNomadConfig();
+        const newConfig = readConfig();
+        const drifted = oldConfig.length > 0 && newConfig.length > 0 && oldConfig !== newConfig;
+        if (isPortListening(4646)) {
+            // Nomad already running, but if the rewritten config differs (typically
+            // because detectNomadExternalInterface() now resolves to a different
+            // interface — e.g. older install missing the host_network block, or
+            // network interface renamed across reboots), reload nomad so allocations
+            // bind to the right host network on next placement.
+            if (drifted) {
+                try {
+                    execFileSync("sudo", ["-n", "systemctl", "restart", "nomad"], { stdio: "pipe", timeout: 15000 });
+                    for (let i = 0; i < 15; i++) {
+                        await new Promise(r => setTimeout(r, 1000));
+                        if (isPortListening(4646)) {
+                            await finalizeNomadStartup();
+                            return { ok: true, message: "Nomad restarted (config reconciled)" };
+                        }
+                    }
+                    return { ok: false, message: "Nomad restart timed out after config reconcile", error: "Port 4646 not listening after 15s" };
+                }
+                catch (e) {
+                    console.warn(`[nomad] config drift detected but restart failed (${e.message}); existing nomad continues with stale config`);
+                }
+            }
+            await finalizeNomadStartup();
+            return { ok: true, message: "Nomad already running" };
+        }
+        // If systemd manages nomad, delegate to systemctl to avoid spawning a competing process
+        const isSystemdManaged = (() => {
+            try {
+                const result = execFileSync("systemctl", ["is-enabled", "nomad"], { stdio: "pipe", timeout: 3000 });
+                return result.toString().trim() === "enabled";
+            }
+            catch {
+                return false;
+            }
+        })();
+        if (isSystemdManaged) {
+            try {
+                execFileSync("sudo", ["-n", "systemctl", "start", "nomad"], { stdio: "pipe", timeout: 10000 });
+            }
+            catch {
+                // sudo -n failed (no passwordless sudo); service may start on its own
+            }
+            for (let i = 0; i < 15; i++) {
+                await new Promise(r => setTimeout(r, 1000));
+                if (isPortListening(4646)) {
+                    await finalizeNomadStartup();
+                    return { ok: true, message: "Nomad started via systemd" };
+                }
+            }
+            return { ok: false, message: "Nomad start timed out", error: "Port 4646 not listening after 15s" };
+        }
+        if (process.platform === "darwin") {
+            const launchdPlist = join(process.env.HOME || dirname(JISHUSHELL_HOME), "Library/LaunchAgents/com.jishushell.nomad.plist");
+            if (existsSync(launchdPlist)) {
+                for (let i = 0; i < 30; i++) {
+                    await new Promise(r => setTimeout(r, 1000));
+                    if (isPortListening(4646)) {
+                        await finalizeNomadStartup();
+                        return { ok: true, message: "Nomad started" };
+                    }
+                }
+                return { ok: false, message: "Nomad start timed out", error: "Port 4646 not listening after 30s" };
+            }
+        }
+        const nomadPath = existsSync(NOMAD_BIN) ? NOMAD_BIN : "nomad";
+        try {
+            execFileSync(nomadPath, ["version"], { timeout: 5000, stdio: "pipe" });
+        }
+        catch {
+            return { ok: false, message: "Nomad not installed", error: "Install Nomad first" };
+        }
+        const logPath = join(NOMAD_CONFIG_DIR, "nomad.log");
+        // Use spawn with detached to avoid execSync shell injection and ensure proper daemonization
+        try {
+            const { openSync, closeSync } = await import("fs");
+            const logFd = openSync(logPath, "a");
+            // Run as current (non-root) user — Nomad only binds to 127.0.0.1:4646/4647/4648
+            // (non-privileged ports) and all data dirs live under ~/.jishushell/, so sudo is not needed.
+            const cmd = nomadPath;
+            const args = ["agent", `-config=${configPath}`];
+            const child = nodeSpawn(cmd, args, {
+                detached: true,
+                stdio: ["ignore", logFd, logFd],
+            });
+            child.unref();
+            closeSync(logFd);
+        }
+        catch (e) {
+            return { ok: false, message: "Failed to start Nomad", error: `launch failed: ${e.message}. Check sudo/permissions.` };
+        }
+        for (let i = 0; i < 15; i++) {
+            await new Promise(r => setTimeout(r, 1000));
+            if (isPortListening(4646)) {
+                await finalizeNomadStartup();
+                return { ok: true, message: "Nomad started" };
+            }
+        }
+        return { ok: false, message: "Nomad start timed out", error: "Port 4646 not listening after 15s" };
+    }
+    catch (e) {
+        return { ok: false, message: "Failed to start Nomad", error: e.message };
+    }
+}
+export async function stopNomad() {
+    try {
+        if (!isPortListening(4646))
+            return { ok: true, message: "Nomad not running" };
+        // SIGTERM: graceful shutdown — Nomad flushes state and detaches from
+        // 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).
+        // 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++) {
+            await new Promise(r => setTimeout(r, 1000));
+            if (!isPortListening(4646))
+                return { ok: true, message: "Nomad stopped" };
+        }
+        return { ok: true, message: "Nomad stop requested" };
+    }
+    catch (e) {
+        return { ok: false, message: "Failed to stop Nomad", error: e.message };
+    }
+}
+// ── Install Nomad as systemd service ───────────────────────────────
+export function installNomadSystemd() {
+    try {
+        const nomadPath = resolveNomadExecutable();
+        const configPath = join(NOMAD_CONFIG_DIR, "nomad.hcl");
+        writeNomadConfig();
+        if (process.platform === "darwin") {
+            // macOS is Apple Silicon only — fail fast (mirrors the bash uname guard).
+            const guard = appleSiliconGuard();
+            if (!guard.ok)
+                return { ok: false, message: guard.message };
+            const laDir = join(process.env.HOME || dirname(JISHUSHELL_HOME), "Library/LaunchAgents");
+            // 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). Mirrors the bash _COLIMA_SOCKET use.
+            const colimaSocket = managedColimaSocketPath(JISHUSHELL_HOME, COLIMA_PROFILE);
+            const colimaDockerHost = managedColimaDockerHost(JISHUSHELL_HOME, COLIMA_PROFILE);
+            // ── 1. Colima self-retrying launchd agent ───────────────────────
+            // colima binary: prefer PATH, fall back to both Homebrew prefixes
+            // (mirrors the bash COLIMA_BIN resolution).
+            const colimaBin = resolveColimaExecutable();
+            const colimaWrapperPath = join(BIN_DIR, "colima-launchd-wrapper.sh");
+            writeExecutableFile(colimaWrapperPath, buildColimaWrapperScript({
+                colimaHome: _COLIMA_DIR,
+                profile: COLIMA_PROFILE,
+                socket: colimaSocket,
+                colimaBin,
+            }));
+            const colimaPlistPath = join(laDir, "com.jishushell.colima.plist");
+            writeConfigFile(colimaPlistPath, buildColimaPlist({
+                wrapperPath: colimaWrapperPath,
+                colimaHome: _COLIMA_DIR,
+                logPath: join(_COLIMA_DIR, "colima-launchd.log"),
+            }));
+            try {
+                execSync(`launchctl unload "${colimaPlistPath}" 2>/dev/null`);
+            }
+            catch { }
+            try {
+                execSync(`launchctl load -w "${colimaPlistPath}"`, { timeout: 15000 });
+            }
+            catch { }
+            // ── 2. Nomad gated behind a docker-readiness wrapper ────────────
+            const logPath = join(NOMAD_CONFIG_DIR, "nomad.log");
+            const nomadWrapperPath = join(BIN_DIR, "nomad-launchd-wrapper.sh");
+            writeExecutableFile(nomadWrapperPath, buildNomadWaitWrapper({
+                dockerHost: colimaDockerHost,
+                nomadBin: nomadPath,
+                configPath,
+            }));
+            const plistContent = buildNomadPlist({
+                wrapperPath: nomadWrapperPath,
+                dockerHost: colimaDockerHost,
+                logPath,
+            });
+            const plistPath = join(laDir, "com.jishushell.nomad.plist");
+            writeConfigFile(plistPath, plistContent);
+            try {
+                execSync(`launchctl unload "${plistPath}" 2>/dev/null`);
+            }
+            catch { }
+            execSync(`launchctl load -w "${plistPath}"`, { timeout: 15000 });
+            return { ok: true, message: "Nomad launchd agent installed and started (Colima gated)" };
+        }
+        // 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 core server 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 core process.
+        const serviceContent = buildNomadSystemdUnit({ nomadPath, configPath });
+        const servicePath = SYSTEMD_NOMAD_SERVICE_PATH;
+        execFileSync("sudo", ["mkdir", "-p", "/etc/jishushell"], { timeout: 5000 });
+        sudoCopySystemFile(serviceContent, servicePath, "644");
+        execFileSync("sudo", ["systemctl", "daemon-reload"], { timeout: 5000 });
+        execFileSync("sudo", ["systemctl", "enable", "--now", "nomad"], { timeout: 15000 });
+        // Also restart if already running so it picks up the new User= directive
+        try {
+            execFileSync("sudo", ["systemctl", "restart", "nomad"], { timeout: 15000 });
+        }
+        catch { }
+        return { ok: true, message: "Nomad systemd service installed and started" };
+    }
+    catch (e) {
+        return { ok: false, message: "Failed to install Nomad systemd service", error: e.message };
+    }
+}
+// ── Install JishuShell as systemd service ─────────────────────────
+export function installJishushellSystemd(port, startNow = false) {
+    try {
+        const resolvedPort = port || _serverPort;
+        persistCoreServicePort(resolvedPort);
+        const serviceUser = process.platform === "darwin" ? undefined : resolveServiceUser();
+        // Use the node binary that is currently running this process — avoids
+        // "which node" failing when PATH doesn't include nvm's bin dir.
+        const nodeBin = process.execPath;
+        const cliBin = resolveCoreCliBin();
+        // The real owner home: prefer JISHUSHELL_HOME's parent so we don't rely on $HOME.
+        const realHome = resolveRealHome();
+        const coreStartWrapperPath = join(BIN_DIR, "jishushell-core-start");
+        const coreCliWrapperPath = join(BIN_DIR, "jishushell");
+        removeSymlinkIfPresent(coreCliWrapperPath);
+        writeManagedExecutableFile(coreStartWrapperPath, buildCoreStartWrapperContent({
+            nodeBin,
+            cliBin,
+            realHome,
+            port: resolvedPort,
+        }), serviceUser);
+        writeManagedExecutableFile(coreCliWrapperPath, buildCoreCliWrapperContent({
+            nodeBin,
+            cliBin,
+            realHome,
+            port: resolvedPort,
+        }), serviceUser);
+        chownToUser(JISHUSHELL_HOME, serviceUser, true);
+        if (process.platform === "darwin") {
+            // macOS is Apple Silicon only — fail fast (mirrors the bash uname guard).
+            const guard = appleSiliconGuard();
+            if (!guard.ok)
+                return { ok: false, message: guard.message };
+            const logPath = join(JISHUSHELL_HOME, "jishushell-core.log");
+            // 60s docker-readiness gate before core starts; on timeout it starts anyway.
+            const gateWrapperPath = join(BIN_DIR, "core-launchd-wrapper.sh");
+            writeExecutableFile(gateWrapperPath, buildCoreGateWrapper({
+                socket: managedColimaSocketPath(JISHUSHELL_HOME, COLIMA_PROFILE),
+                coreStartWrapper: coreStartWrapperPath,
+            }));
+            const plistContent = buildCorePlist({
+                gateWrapperPath,
+                logPath,
+            });
+            // Symmetric with installNomadSystemd()'s laDir (realHome === dirname(JISHUSHELL_HOME),
+            // so process.env.HOME || dirname(JISHUSHELL_HOME) is provably the same path).
+            const laDir = resolveLaunchAgentsDir(realHome);
+            const plistPath = join(laDir, "com.jishushell.core.plist");
+            writeConfigFile(plistPath, plistContent);
+            if (startNow || !isPortListening(resolvedPort)) {
+                try {
+                    execSync(`launchctl unload "${plistPath}" 2>/dev/null`);
+                }
+                catch { }
+                execSync(`launchctl load -w "${plistPath}"`, { timeout: 15000 });
+                if (!waitForListeningPort(resolvedPort, 30)) {
+                    return {
+                        ok: false,
+                        message: "JishuShell core launchd agent installed, but the core port is not ready yet",
+                    };
+                }
+                return { ok: true, message: "JishuShell core launchd agent installed and started (port " + resolvedPort + ")" };
+            }
+            return { ok: true, message: "JishuShell core launchd agent installed and enabled (port " + resolvedPort + ")" };
+        }
+        const currentUser = serviceUser ?? resolveServiceUser();
+        const serviceContent = buildJishushellCoreSystemdUnit({
+            currentUser,
+            realHome,
+            coreStartWrapperPath,
+        });
+        execFileSync("sudo", ["mkdir", "-p", "/etc/jishushell"], { timeout: 5000 });
+        sudoCopySystemFile(serviceContent, SYSTEMD_CORE_SERVICE_PATH, "644");
+        execFileSync("sudo", ["systemctl", "daemon-reload"], { timeout: 5000 });
+        execFileSync("sudo", ["systemctl", "enable", "jishushell"], { timeout: 15000, stdio: "pipe" });
+        if (!startNow) {
+            return { ok: true, message: "JishuShell core systemd service installed and enabled (port " + resolvedPort + ")" };
+        }
+        execFileSync("sudo", ["systemctl", "restart", "jishushell"], { timeout: 15000 });
+        if (!waitForListeningPort(resolvedPort, 30)) {
+            return {
+                ok: false,
+                message: "JishuShell core systemd service installed, but the core port is not ready yet",
+            };
+        }
+        return { ok: true, message: "JishuShell core systemd service installed and started (port " + resolvedPort + ")" };
+    }
+    catch (e) {
+        return { ok: false, message: "Failed to install JishuShell systemd service", error: e.message };
+    }
+}
+export function installJishushellPanelSystemd(corePort, panelPort = DEFAULT_PANEL_PORT, startNow = true) {
+    try {
+        const resolvedCorePort = corePort || _serverPort;
+        const serviceUser = process.platform === "darwin" ? undefined : resolveServiceUser();
+        const nodeBin = process.execPath;
+        const panelBin = resolveBundledPanelServerBin();
+        const realHome = resolveRealHome();
+        const panelStartWrapperPath = join(BIN_DIR, "jishushell-panel-start");
+        writeManagedExecutableFile(panelStartWrapperPath, buildPanelStartWrapperContent({
+            nodeBin,
+            panelBin,
+            realHome,
+            corePort: resolvedCorePort,
+            panelPort,
+        }), serviceUser);
+        if (process.platform === "darwin") {
+            const guard = appleSiliconGuard();
+            if (!guard.ok)
+                return { ok: false, message: guard.message };
+            const laDir = resolveLaunchAgentsDir(realHome);
+            const plistPath = join(laDir, "com.jishushell.panel.plist");
+            writeConfigFile(plistPath, buildPanelPlist({
+                panelWrapperPath: panelStartWrapperPath,
+                logPath: join(JISHUSHELL_HOME, "jishushell-panel.log"),
+                home: realHome,
+                jishuHome: JISHUSHELL_HOME,
+                corePort: resolvedCorePort,
+                panelPort,
+            }));
+            if (!waitForListeningPort(resolvedCorePort, 30)) {
+                return {
+                    ok: false,
+                    message: "JishuShell Panel launchd agent was written but not started because the core port is not ready",
+                };
+            }
+            try {
+                execSync(`launchctl unload "${plistPath}" 2>/dev/null`);
+            }
+            catch { }
+            execSync(`launchctl load -w "${plistPath}"`, { timeout: 15000 });
+            if (!waitForListeningPort(panelPort, 15)) {
+                return {
+                    ok: false,
+                    message: "JishuShell Panel launchd agent started, but the panel port is not ready yet",
+                };
+            }
+            return { ok: true, message: "JishuShell Panel launchd agent installed and started (port " + panelPort + ")" };
+        }
+        const currentUser = serviceUser ?? resolveServiceUser();
+        const serviceContent = buildJishushellPanelSystemdUnit({
+            currentUser,
+            realHome,
+            panelStartWrapperPath,
+            corePort: resolvedCorePort,
+            panelPort,
+        });
+        execFileSync("sudo", ["mkdir", "-p", "/etc/jishushell"], { timeout: 5000 });
+        sudoCopySystemFile(serviceContent, SYSTEMD_PANEL_SERVICE_PATH, "644");
+        execFileSync("sudo", ["systemctl", "daemon-reload"], { timeout: 5000 });
+        execFileSync("sudo", ["systemctl", "enable", "jishushell-panel"], { timeout: 15000, stdio: "pipe" });
+        if (!startNow) {
+            return { ok: true, message: "JishuShell Panel systemd service installed and enabled (port " + panelPort + ")" };
+        }
+        if (!waitForListeningPort(resolvedCorePort, 30)) {
+            return {
+                ok: false,
+                message: "JishuShell Panel systemd service was enabled but not started because the core port is not ready",
+            };
+        }
+        execFileSync("sudo", ["systemctl", "restart", "jishushell-panel"], { timeout: 15000 });
+        if (!waitForListeningPort(panelPort, 15)) {
+            return {
+                ok: false,
+                message: "JishuShell Panel systemd service started, but the panel port is not ready yet",
+            };
+        }
+        return { ok: true, message: "JishuShell Panel systemd service installed and started (port " + panelPort + ")" };
+    }
+    catch (e) {
+        return { ok: false, message: "Failed to install JishuShell Panel systemd service", error: e.message };
+    }
+}
+// ── Install OpenClaw (async with progress) ─────────────────────────
+/**
+ * Install OpenClaw runtime — thin dispatch wrapper.
+ *
+ * The heavy lifting lives in `OpenClawIntegration.installRuntime()`.
+ * 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 integration = getIntegration("openclaw");
+    if (typeof integration.installRuntime !== "function") {
+        return { ok: false, message: "OpenClawIntegration.installRuntime is not implemented" };
+    }
+    return integration.installRuntime({ version });
+}
+// ── Hermes install ─────────────────────────────────────────────────
+//
+// Hermes constants (HERMES_DEFAULT_IMAGE, HERMES_RUNTIME_DIR,
+// HERMES_SHIM_FILENAME) and the shim template resolver have moved to
+// `src/config.ts`. setup-manager no longer defines them.
+// The HermesIntegration imports them directly from config.ts.
+/**
+ * Capture the immutable digest of a locally-present image so HermesIntegration
+ * 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 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 {
+        return undefined;
+    }
+}
+/**
+ * Install Hermes runtime — thin dispatch wrapper.
+ *
+ * Heavy lifting lives in `HermesIntegration.installRuntime()`.
+ */
+export async function installHermes() {
+    const integration = getIntegration("hermes");
+    if (typeof integration.installRuntime !== "function") {
+        return { ok: false, message: "HermesIntegration.installRuntime is not implemented" };
+    }
+    return integration.installRuntime();
+}
+/**
+ * Non-blocking variant — returns a task id immediately. Implementation
+ * dispatches via `HermesIntegration.startInstallRuntime()`.
+ */
+export function startInstallHermes() {
+    const integration = getIntegration("hermes");
+    if (typeof integration.startInstallRuntime !== "function") {
+        return { ok: false, message: "HermesIntegration.startInstallRuntime is not implemented" };
+    }
+    return integration.startInstallRuntime();
+}
+/** Helper for setup status — true when Hermes has a persisted runtime install record. */
+export function isHermesInstalled() {
+    const entry = getIntegrationRuntimeEntry("hermes");
+    return !!entry && !!entry.defaultImage;
+}
+export function resolveDockerInvocation() {
+    try {
+        execFileSync("docker", ["info"], { timeout: 5000, stdio: "ignore" });
+        return { cmd: "docker", argsPrefix: [] };
+    }
+    catch { }
+    try {
+        execFileSync("sudo", ["-n", "docker", "info"], { timeout: 5000, stdio: "ignore" });
+        return { cmd: "sudo", argsPrefix: ["-n", "docker"] };
+    }
+    catch { }
+    return { cmd: "docker", argsPrefix: [] };
+}
+function checkDockerImageExists() {
+    const tag = resolveDockerImageTag();
+    try {
+        const invocation = resolveDockerInvocation();
+        execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "inspect", tag], { timeout: 5000, stdio: "ignore" });
+        return true;
+    }
+    catch {
+        // Fallback scan: list all local images and try to find any known runtime image.
+        // This handles two scenarios:
+        //  1. core.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 core.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 });
+            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 core.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. Reads core.json — framework-level.
+function resolveDockerImageTag() {
+    return getOpenclawDockerImage();
+}
+// ── Docker image build dispatch wrappers ───────────────────────────────
+//
+// All OpenClaw-specific image build logic now lives in
+// `OpenClawIntegration.buildRuntimeImage()`. These
+// exports remain as thin wrappers so `routes/setup.ts` and
+// `install.ts` callers don't need to learn integration dispatch.
+/** Blocking: pull or build the OpenClaw docker image. */
+export async function buildSlimOpenclawImage(tag) {
+    const integration = getIntegration("openclaw");
+    if (typeof integration.buildRuntimeImage !== "function") {
+        return { ok: false, message: "OpenClawIntegration.buildRuntimeImage is not implemented" };
+    }
+    return integration.buildRuntimeImage({ tag });
+}
+/** Non-blocking: returns immediately with a task id for SSE polling. */
+export function startBuildSlimOpenclawImage(tag) {
+    const integration = getIntegration("openclaw");
+    if (typeof integration.startBuildRuntimeImage !== "function") {
+        return { ok: false, message: "OpenClawIntegration.startBuildRuntimeImage is not implemented" };
+    }
+    return integration.startBuildRuntimeImage({ tag });
+}
+/** @deprecated Use buildSlimOpenclawImage instead */
+export async function buildCustomOpenclawImage(tag) {
+    return buildSlimOpenclawImage(tag);
+}
+/** @deprecated Use startBuildSlimOpenclawImage instead */
+export function startBuildCustomOpenclawImage(tag) {
+    return startBuildSlimOpenclawImage(tag);
+}
+export async function runFullSetup(options = {}) {
+    const steps = [];
+    let allOk = true;
+    const defaults = {
+        installNomad: true,
+        buildDockerImage: true,
+        ...options,
+    };
+    // Check Docker by daemon accessibility (docker info), not just binary existence
+    const dockerReady = canAccessDockerDaemon(10000);
+    if (!dockerReady) {
+        steps.push({ step: "docker", status: "running", message: "Installing Docker..." });
+        const result = await installDocker();
+        steps[steps.length - 1].status = result.ok ? "done" : "error";
+        steps[steps.length - 1].message = result.message;
+        if (!result.ok)
+            allOk = false;
+    }
+    if (defaults.installNomad) {
+        steps.push({ step: "nomad", status: "running", message: "Installing Nomad..." });
+        const result = await installNomad();
+        steps[steps.length - 1].status = result.ok ? "done" : "error";
+        steps[steps.length - 1].message = result.message;
+        if (!result.ok)
+            allOk = false;
+        if (result.ok) {
+            steps.push({ step: "nomad-systemd", status: "running", message: "Configuring Nomad auto-start..." });
+            const sysResult = installNomadSystemd();
+            steps[steps.length - 1].status = sysResult.ok ? "done" : "error";
+            steps[steps.length - 1].message = sysResult.message;
+            if (!sysResult.ok) {
+                // Fallback to manual start if systemd fails
+                steps.push({ step: "nomad-start", status: "running", message: "Starting Nomad..." });
+                const startResult = await startNomad();
+                steps[steps.length - 1].status = startResult.ok ? "done" : "error";
+                steps[steps.length - 1].message = startResult.message;
+                if (!startResult.ok)
+                    allOk = false;
+            }
+        }
+    }
+    // First-time setup prepares only required App workload images. Merely
+    // registering an optional Integration must not download its App image: the
+    // user installs optional Apps explicitly through Panel or CLI.
+    if (defaults.buildDockerImage) {
+        // Restart Nomad so it re-detects Docker driver after Docker was installed
+        try {
+            execSync("sudo systemctl restart nomad 2>/dev/null || true", { timeout: 15000 });
+            for (let i = 0; i < 10; i++) {
+                await new Promise(r => setTimeout(r, 2000));
+                if (isPortListening(4646))
+                    break;
+            }
+        }
+        catch { }
+        for (const integration of listRegisteredIntegrations().filter((item) => item.manifest?.requiredForSetupReady === true)) {
+            const stepName = `runtime-${integration.kind}`;
+            // Prefer buildRuntimeImage (pure docker image prep) over
+            // installRuntime (legacy host-mode npm install). Integrations that only
+            // implement one will use whichever is present; integrations with neither
+            // are skipped silently.
+            const runner = integration.buildRuntimeImage
+                ? integration.buildRuntimeImage.bind(integration)
+                : integration.installRuntime
+                    ? integration.installRuntime.bind(integration)
+                    : null;
+            if (!runner)
+                continue;
+            steps.push({
+                step: stepName,
+                status: "running",
+                message: `Preparing ${integration.kind} runtime…`,
+            });
+            try {
+                const imgResult = (await runner());
+                const okStep = !!imgResult.ok;
+                steps[steps.length - 1].status = okStep ? "done" : "error";
+                steps[steps.length - 1].message = imgResult.message;
+                if (!okStep)
+                    allOk = false;
+            }
+            catch (e) {
+                const msg = e?.message || "runtime prepare failed";
+                steps[steps.length - 1].status = "error";
+                steps[steps.length - 1].message = msg;
+                allOk = false;
+            }
+        }
+    }
+    if (isPortListening(4646)) {
+        await finalizeNomadStartup();
+    }
+    // Only mark setup as complete if all critical steps succeeded
+    if (!allOk) {
+        return { ok: false, steps };
+    }
+    const config = getCoreConfig();
+    config.service_manager = "nomad";
+    config.nomad_driver = "docker";
+    saveCoreConfig(config);
+    // Install jishushell systemd service (best-effort — does not block setup completion)
+    steps.push({ step: "jishushell-systemd", status: "running", message: "Configuring JishuShell auto-start..." });
+    const jsResult = installJishushellSystemd();
+    steps[steps.length - 1].status = jsResult.ok ? "done" : "error";
+    steps[steps.length - 1].message = jsResult.message;
+    return { ok: allOk, steps };
+}
+//# sourceMappingURL=setup-manager.js.map