jishushell 0.4.10 → 0.4.24

package/dist/services/nomad-manager.js

@@ -1,104 +1,264 @@
 /**
- * Nomad-based service manager for OpenClaw instances.
- * Communicates with Nomad via its HTTP API.
+ * Nomad-based service manager — kind-agnostic scheduler layer.
+ *
+ * §32.2 / §32.8: this file contains ZERO knowledge of specific agent kinds.
+ * Runtime-specific task assembly (`buildNomadTask`), pre-start patches
+ * (`hooks.onBeforeStart`), and capability profiles live inside
+ * `src/services/runtime/adapters/<agentType>.ts`. Framework dispatch is:
+ *
+ *     const agentType = resolveAgentType(getInstance(id));
+ *     const adapter = getAdapter(agentType);
+ *     await adapter.hooks?.onBeforeStart?.({ instanceId });
+ *     const task = await adapter.buildNomadTask(instanceId);
  */
-import { execFile as execFileCb, execFileSync } from "child_process";
-import { chmodSync, existsSync, readFileSync, readdirSync } from "fs";
+import { execFile as execFileCb, spawn } from "child_process";
+import { existsSync, readFileSync } from "fs";
+import { createServer as netCreateServer } from "net";
 import { homedir, userInfo } from "os";
-import { dirname } from "path";
-import { join } from "path";
+import { basename, join } from "path";
+import { StringDecoder } from "string_decoder";
 import { promisify } from "util";
-import { getNomadAddr, getNomadDriver, getNomadToken, getOpenclawDockerImage } from "../config.js";
-import { ensureDirContainer, writeConfigFile } from "../utils/fs.js";
-import { findInstancesSharingGatewayPort, findInstancesSharingOpenclawHome, getGatewayPort, getInstanceRuntime, getOpenclawConfigPath, getOpenclawHome, getRuntimeEnv } from "./instance-manager.js";
-import { getLegacyStatus, stopInstance as stopLegacyInstance } from "./process-manager.js";
+import { parse } from "yaml";
+import * as config from "../config.js";
+import { getGatewayPort, getInstance, getInstanceRuntime, instanceMetaPath, getRuntimeEnv, isPortInUse, reallocateGatewayPort, } from "./instance-manager.js";
+import { getAdapter, resolveAgentType } from "./runtime/index.js";
+function getConfigValue(name) {
+    return name in config ? config[name] : undefined;
+}
+function resolveConfigPath(value, fallback) {
+    return typeof value === "string" && value.trim() ? value : fallback;
+}
+const JISHUSHELL_HOME = resolveConfigPath(getConfigValue("JISHUSHELL_HOME"), join(process.env.HOME ?? homedir(), ".jishushell"));
+const APPS_DIR = resolveConfigPath(getConfigValue("APPS_DIR"), join(JISHUSHELL_HOME, "apps"));
+const INSTANCES_DIR = resolveConfigPath(getConfigValue("INSTANCES_DIR"), join(JISHUSHELL_HOME, "instances"));
+const getNomadAddrValue = getConfigValue("getNomadAddr");
+const getNomadDriverValue = getConfigValue("getNomadDriver");
+const getNomadTokenValue = getConfigValue("getNomadToken");
+const getPanelConfigValue = getConfigValue("getPanelConfig");
+const getNomadAddr = typeof getNomadAddrValue === "function"
+    ? getNomadAddrValue
+    : () => "http://127.0.0.1:4646";
+const getNomadDriver = typeof getNomadDriverValue === "function"
+    ? getNomadDriverValue
+    : () => "docker";
+const getNomadToken = typeof getNomadTokenValue === "function"
+    ? getNomadTokenValue
+    : () => "";
+const getPanelConfig = typeof getPanelConfigValue === "function"
+    ? getPanelConfigValue
+    : () => ({});
 // Docker image names must match this pattern to prevent command injection.
 export const DOCKER_IMAGE_RE = /^[a-zA-Z0-9][a-zA-Z0-9\-_.:/@]*$/;
+/**
+ * Linux username validation regex. Shared by adapter Nomad task builders
+ * (OpenClaw / Hermes) and re-exported here as a neutral framework constant
+ * so security-regression tests can assert on it without depending on a
+ * specific adapter file.
+ *
+ * Strict form: lowercase letters/digits/dot/dash/underscore only, 1..32 chars.
+ * Rejects uppercase, shell metacharacters, paths, and empty strings.
+ */
+export const VALID_USER_RE = /^[a-z0-9._-]{1,32}$/;
 // Maximum allowed length for a Docker image reference.
 export const MAX_DOCKER_IMAGE_NAME_LEN = 256;
-const JOB_PREFIX = "openclaw-";
-// Tracks the panel's listening port so bridge-mode containers can reach it via host.docker.internal.
-let _panelPort = 8090;
-export function setPanelPort(port) { _panelPort = port; }
 /**
- * When running in docker bridge mode, 127.0.0.1 inside the container resolves to
- * the container's own loopback, not the host. Rewrite the jsproxy provider baseUrl
- * in openclaw.json to use host.docker.internal instead so the container can reach
- * the JishuShell LLM proxy.
+ * Nomad job name prefix. Dispatched via `adapter.nomadJobPrefix` so
+ * every runtime owns its own namespace (`hermes-<id>`, `openclaw-<id>`,
+ * …). New agent runtimes should declare their own prefix on the
+ * adapter rather than re-using another kind's. Falls back to the
+ * framework-generic `jishushell-` only when the adapter lookup fails —
+ * that branch shouldn't fire for a registered agent type.
  */
-function patchJsproxyBaseUrl(configPath) {
+function jobPrefixFor(instanceId) {
     try {
-        const raw = readFileSync(configPath, "utf-8");
-        const patched = raw.replace(/http:\/\/127\.0\.0\.1:(\d+)\/proxy/g, `http://host.docker.internal:$1/proxy`);
-        if (patched !== raw) {
-            writeConfigFile(configPath, patched);
-            console.log(`[nomad] Patched jsproxy baseUrl in ${configPath} (127.0.0.1 → host.docker.internal)`);
-        }
+        const agentType = getInstanceAgentType(instanceId);
+        const adapter = getAdapter(agentType);
+        return adapter.nomadJobPrefix ?? "jishushell-";
     }
-    catch (e) {
-        console.warn(`[nomad] Failed to patch jsproxy baseUrl in ${configPath}: ${e.message}`);
+    catch {
+        return "jishushell-";
     }
 }
 /**
- * Docker bridge port publishing cannot reach a process that only binds the
- * container loopback. Normalize default/loopback gateway binds to `lan` so
- * Nomad's published host port can reach the gateway.
- *
- * OpenClaw will seed localhost Control UI origins automatically for non-loopback
- * binds on startup when they are missing, so persisting the bind mode here keeps
- * startup and runtime behavior aligned.
+ * Per-instance Nomad Variable subpath. Returned without the leading
+ * `nomad/jobs/<jid>/` prefix. `undefined` means this adapter does not
+ * use Nomad Variables — writeInstanceVariables/purgeInstanceVariables
+ * become no-ops.
  */
-function patchDockerBridgeGatewayBind(configPath) {
+function adapterVariableSubpath(instanceId) {
     try {
-        const raw = readFileSync(configPath, "utf-8");
-        const parsed = JSON.parse(raw);
-        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
-            return;
-        const gatewayRaw = parsed.gateway;
-        const gateway = gatewayRaw && typeof gatewayRaw === "object" && !Array.isArray(gatewayRaw)
-            ? gatewayRaw
-            : (parsed.gateway = {});
-        const bind = typeof gateway.bind === "string" ? gateway.bind.trim() : "";
-        if (bind && bind !== "loopback")
-            return;
-        gateway.bind = "lan";
-        const next = JSON.stringify(parsed, null, 2);
-        const output = raw.endsWith("\n") ? `${next}\n` : next;
-        if (output === raw)
-            return;
-        writeConfigFile(configPath, output);
-        console.log(`[nomad] Normalized gateway.bind to "lan" in ${configPath} for Docker bridge networking`);
+        const agentType = getInstanceAgentType(instanceId);
+        const adapter = getAdapter(agentType);
+        return adapter.nomadVariablePath;
     }
-    catch (e) {
-        console.warn(`[nomad] Failed to patch gateway.bind in ${configPath}: ${e.message}`);
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve the Nomad task name for the given instance. Reads
+ * `adapter.nomadTaskName` so framework code never hardcodes "gateway".
+ * Falls back to "gateway" for backwards compat when the adapter leaves it
+ * unset or the lookup fails.
+ */
+function resolveTaskName(instanceId) {
+    try {
+        const agentType = getInstanceAgentType(instanceId);
+        return getAdapter(agentType).nomadTaskName ?? "gateway";
+    }
+    catch {
+        return "gateway";
     }
 }
-const DEFAULT_COMMAND = "/usr/bin/openclaw";
-const DEFAULT_PIDS_LIMIT = 512;
+function getLegacyManagedAppType(instanceId) {
+    const meta = getInstance(instanceId);
+    const appType = typeof meta?.app_type === "string" ? meta.app_type.trim() : "";
+    return appType === "custom" || appType === "ollama" ? appType : null;
+}
+async function getLegacyAppManager(instanceId) {
+    const appType = getLegacyManagedAppType(instanceId);
+    if (!appType)
+        return null;
+    const { getAppManager } = await import("./app/registry.js");
+    return getAppManager(appType);
+}
+async function getInstanceBackedInstalledApp(instanceId) {
+    const { getApp } = await import("./app/app-manager.js");
+    const appData = getApp(instanceId);
+    if (!appData || appData.manifest.install_mode !== "instance-dir")
+        return null;
+    return appData;
+}
+async function getAppDirInstalledApp(instanceId) {
+    const { getApp } = await import("./app/app-manager.js");
+    const appData = getApp(instanceId);
+    if (!appData || appData.manifest.install_mode !== "app-dir")
+        return null;
+    return appData;
+}
+// Tracks the panel's listening port so bridge-mode containers can reach it via host.docker.internal.
+let _panelPort = 8090;
+export function setPanelPort(port) { _panelPort = port; }
+// §32.2 / §32.8: patchJsproxyBaseUrl / patchDockerBridgeGatewayBind /
+// ensureOpenclawUpdateSeed previously lived here (~140 lines). They are now
+// owned by `src/services/runtime/adapters/openclaw.ts` and invoked via
+// `adapter.hooks.onBeforeStart({ instanceId })` in startInstance below.
 export const VALID_LOG_TYPES = new Set(["stdout", "stderr"]);
+async function inspectDockerLogPath(command, args) {
+    try {
+        const { stdout } = await execFileAsync(command, args, { timeout: 5_000 });
+        const logPath = stdout.trim();
+        return logPath || null;
+    }
+    catch {
+        return null;
+    }
+}
+async function resolveDockerLogPath(containerName) {
+    const direct = await inspectDockerLogPath("docker", [
+        "inspect",
+        "--format",
+        "{{.LogPath}}",
+        containerName,
+    ]);
+    if (direct)
+        return direct;
+    return inspectDockerLogPath("sudo", [
+        "-n",
+        "docker",
+        "inspect",
+        "--format",
+        "{{.LogPath}}",
+        containerName,
+    ]);
+}
+async function readDockerLogText(logPath, lines) {
+    try {
+        return readFileSync(logPath, "utf-8");
+    }
+    catch {
+        try {
+            const tailLines = String(Math.max(lines * 50, 2_000));
+            const { stdout } = await execFileAsync("sudo", ["-n", "tail", "-n", tailLines, logPath], {
+                timeout: 5_000,
+            });
+            return stdout;
+        }
+        catch {
+            return "";
+        }
+    }
+}
+async function readDockerCliLogs(containerName, lines) {
+    const commands = [
+        { command: "docker", args: ["logs", "--tail", String(lines), containerName] },
+        { command: "sudo", args: ["-n", "docker", "logs", "--tail", String(lines), containerName] },
+    ];
+    for (const candidate of commands) {
+        try {
+            const { stdout, stderr } = await execFileAsync(candidate.command, candidate.args, { timeout: 10_000 });
+            const combined = `${stdout}${stderr}`.trim();
+            if (combined)
+                return combined.split("\n").slice(-lines);
+        }
+        catch {
+            continue;
+        }
+    }
+    return [];
+}
+async function readDockerStreamLogs(containerName, lines = 200, logType = "stderr") {
+    if (!VALID_LOG_TYPES.has(logType))
+        logType = "stderr";
+    const logPath = await resolveDockerLogPath(containerName);
+    if (!logPath)
+        return readDockerCliLogs(containerName, lines);
+    const rawText = await readDockerLogText(logPath, lines);
+    if (!rawText)
+        return readDockerCliLogs(containerName, lines);
+    const collected = [];
+    const entries = rawText.split("\n");
+    for (let index = entries.length - 1; index >= 0 && collected.length < lines; index--) {
+        const line = entries[index]?.trim();
+        if (!line)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed.stream !== logType)
+                continue;
+            const message = typeof parsed.log === "string"
+                ? parsed.log.replace(/\n$/, "")
+                : "";
+            if (message)
+                collected.push(message);
+        }
+        catch {
+            continue;
+        }
+    }
+    const streamLines = collected.reverse();
+    if (streamLines.length > 0)
+        return streamLines;
+    return readDockerCliLogs(containerName, lines);
+}
 function nomadAuthHeaders() {
     const token = getNomadToken();
     return token ? { "X-Nomad-Token": token } : {};
 }
-const DEFAULT_ARGS = ["gateway", "run", "--port", "18789", "--allow-unconfigured"];
-const DEFAULT_USER = userInfo().username;
-const DEFAULT_CWD = homedir();
-const DEFAULT_ENV = {
-    HOME: homedir(),
-    TMPDIR: "/tmp",
-    PATH: `${homedir()}/.local/bin:${homedir()}/.npm-global/bin:${homedir()}/bin:${homedir()}/.volta/bin:`
-        + `${homedir()}/.asdf/shims:${homedir()}/.bun/bin:${homedir()}/.nvm/current/bin:${homedir()}/.fnm/current/bin:`
-        + `${homedir()}/.local/share/pnpm:/usr/local/bin:/usr/bin:/bin`,
-};
-const DEFAULT_RESOURCES = { CPU: 500, MemoryMB: 512 };
-// Hard upper bounds applied before submitting any Nomad job. Prevents a
-// misconfigured or malicious instance config from exhausting scheduler
-// resources on the host (no Nomad Enterprise Resource Quotas in OSS).
-const MAX_CPU_MHZ = 4000; // 4 GHz — sane ceiling for a single task
-const MAX_MEMORY_MB = 4096; // 4 GB reservation
-const MAX_MEMORY_MAX_MB = 4096; // 4 GB hard limit (memory_max)
+// §32.2 / §32.8: scheduler-level defaults and resource ceilings. Runtime
+// command / args / env / resources now live inside each adapter's
+// `buildNomadTask` — nomad-manager never looks at them directly.
 function jobId(instanceId) {
-    return `${JOB_PREFIX}${instanceId}`;
+    const prefix = jobPrefixFor(instanceId);
+    if (!prefix)
+        return instanceId;
+    if (instanceId.startsWith(prefix))
+        return instanceId;
+    return `${prefix}${instanceId}`;
+}
+/** Exported only for unit tests — not part of the public API. */
+export function __jobIdForTests(instanceId) {
+    return jobId(instanceId);
 }
 // Nomad Template metacharacters that must not appear in values interpolated
 // into EmbeddedTmpl. Defense-in-depth: instanceId is already validated by the
@@ -142,7 +302,7 @@ async function nomadPut(path, body) {
     });
 }
 // ── Nomad Variables (secrets) ──
-async function writeInstanceVariables(instanceId) {
+export async function writeInstanceVariables(instanceId) {
     const jid = jobId(instanceId);
     // (short-term mitigation): variable path follows Nomad's workload-identity
     // convention. Each job's workload identity has implicit read/write access only
@@ -150,7 +310,10 @@ async function writeInstanceVariables(instanceId) {
     // secret isolation within the shared "default" namespace. Per-instance Nomad
     // namespaces remain a planned future improvement.
     const ns = "default";
-    const varPath = `nomad/jobs/${jid}/openclaw/gateway`;
+    const subpath = adapterVariableSubpath(instanceId);
+    if (!subpath)
+        return;
+    const varPath = `nomad/jobs/${jid}/${subpath}`;
     const encodedPath = encodeURIComponent(varPath);
     // Read proxy token from env file
     const env = getRuntimeEnv(instanceId);
@@ -194,10 +357,18 @@ async function writeInstanceVariables(instanceId) {
 }
 export async function purgeInstanceVariables(instanceId) {
     const jid = jobId(instanceId);
-    const varPath = `nomad/jobs/${jid}/openclaw/gateway`;
+    const subpath = adapterVariableSubpath(instanceId);
+    if (!subpath)
+        return;
+    const varPath = `nomad/jobs/${jid}/${subpath}`;
     const encodedPath = encodeURIComponent(varPath);
     try {
-        const resp = await nomadDelete(`/v1/var/${encodedPath}`);
+        // Match writeInstanceVariables symmetry: always pin the namespace on
+        // every Variables API call so the delete cannot drift into a different
+        // namespace if Nomad's default-namespace behaviour changes between
+        // minor versions. Without this, a schema tweak in a future 1.6.x point
+        // release could leave a stale secret behind after purge=true.
+        const resp = await nomadDelete(`/v1/var/${encodedPath}?namespace=default`);
         if (!resp.ok && resp.status !== 404) {
             console.warn(`[nomad] Failed to purge variables for ${instanceId}: HTTP ${resp.status}`);
         }
@@ -206,11 +377,11 @@ export async function purgeInstanceVariables(instanceId) {
         console.warn(`[nomad] Failed to purge variables for ${instanceId}: ${e.message}`);
     }
 }
-export const VALID_USER_RE = /^[a-z0-9._-]{1,32}$/;
 /**
  * Resolve the numeric uid:gid for a given username by reading /etc/passwd.
- * Falls back to process.getuid!():process.getgid!() when the lookup fails
- * (e.g. the user doesn't exist on this host or /etc/passwd is unreadable).
+ * Falls back to process.getuid!():process.getgid!() when the lookup fails.
+ * Still used here by the kind-agnostic `exec()` helper below (for docker
+ * exec user resolution); adapters carry their own copies for task build.
  */
 function resolveUidGid(username) {
     try {
@@ -227,158 +398,23 @@ function resolveUidGid(username) {
     catch { /* ignore */ }
     return `${process.getuid()}:${process.getgid()}`;
 }
-function buildRuntime(instanceId) {
-    const runtime = getInstanceRuntime(instanceId);
-    const openclawHome = getOpenclawHome(instanceId);
-    // Validate user to prevent injection via Nomad job spec
-    if (runtime.user && !VALID_USER_RE.test(runtime.user)) {
-        throw new Error(`Invalid runtime user: ${runtime.user}`);
-    }
-    const command = runtime.command || DEFAULT_COMMAND;
-    let args = runtime.args;
-    if (!Array.isArray(args))
-        args = [...DEFAULT_ARGS];
-    else
-        args = args.map(String);
-    const env = { ...DEFAULT_ENV };
-    Object.assign(env, getRuntimeEnv(instanceId));
-    delete env.JSPROXY_API_KEY; // Injected by Nomad template from Variables
-    env.OPENCLAW_HOME = openclawHome;
-    env.OPENCLAW_INSTANCE_ID = instanceId;
-    const resources = { ...DEFAULT_RESOURCES };
-    for (const [key, value] of Object.entries(runtime.resources || {})) {
-        if (value != null)
-            resources[key] = Number(value);
-    }
-    // Clamp to sane upper bounds — guards against arbitrarily large values that
-    // would exhaust Nomad scheduler capacity or system memory.
-    resources.CPU = Math.max(1, Math.min(resources.CPU, MAX_CPU_MHZ));
-    resources.MemoryMB = Math.max(1, Math.min(resources.MemoryMB, MAX_MEMORY_MB));
-    return {
-        command: String(command),
-        args,
-        user: runtime.user || DEFAULT_USER,
-        cwd: runtime.cwd || DEFAULT_CWD,
-        env,
-        resources,
-    };
-}
-function normalizeDockerResources(instanceId, runtime) {
-    const requestedMemoryMB = Number(runtime.resources.MemoryMB ?? DEFAULT_RESOURCES.MemoryMB);
-    let effectiveMemoryMB = requestedMemoryMB;
-    let effectiveMemoryMaxMB = Math.min(Number(runtime.resources.MemoryMaxMB ?? requestedMemoryMB), MAX_MEMORY_MAX_MB);
-    if (effectiveMemoryMaxMB < effectiveMemoryMB) {
-        console.warn(`[nomad] ${instanceId}: MemoryMaxMB (${effectiveMemoryMaxMB}) is below MemoryMB (${effectiveMemoryMB}); clamping max to reservation.`);
-        effectiveMemoryMaxMB = effectiveMemoryMB;
+// §32.2 / §32.8:
+//   The previous ~380 lines of OpenClaw / Hermes task assembly
+//   (`buildRuntime`, `buildTaskDocker`, `buildHermesTaskDocker`, resource
+//   normalizer, kind detector) have been physically migrated into
+//   `src/services/runtime/adapters/{openclaw,hermes}.ts:buildNomadTask()`.
+//   Framework code here is now a pure dispatcher: it asks the adapter for
+//   a Nomad task definition and embeds it in the job spec below.
+function getInstanceAgentType(instanceId) {
+    try {
+        const meta = getInstance(instanceId);
+        return resolveAgentType(meta);
     }
-    return {
-        ...runtime.resources,
-        MemoryMB: effectiveMemoryMB,
-        MemoryMaxMB: effectiveMemoryMaxMB,
-    };
-}
-function buildTaskDocker(instanceId, runtime) {
-    // Guard against Nomad Template injection: validate the job ID contains no
-    // template metacharacters before interpolating it into EmbeddedTmpl.
-    const safeJobId = jobId(instanceId);
-    assertSafeTemplateId(safeJobId);
-    const openclawHome = getOpenclawHome(instanceId);
-    const image = getOpenclawDockerImage();
-    const volumes = [
-        `${openclawHome}:${openclawHome}:rw`,
-    ];
-    const containerEnv = { ...runtime.env };
-    // Set HOME to the bind-mounted openclaw-home directory so that user-level
-    // installs (pip install --user, npm cache, etc.) persist across restarts.
-    containerEnv.HOME = openclawHome;
-    // Plugins (e.g. openclaw-weixin) use OPENCLAW_STATE_DIR to find credentials.
-    if (!containerEnv.OPENCLAW_STATE_DIR) {
-        containerEnv.OPENCLAW_STATE_DIR = `${openclawHome}/.openclaw`;
-    }
-    // State cohesion: redirect all user-level installs to HOME
-    containerEnv.npm_config_prefix = `${openclawHome}/.npm-global`;
-    containerEnv.PIP_USER = "1";
-    containerEnv.PYTHONUSERBASE = `${openclawHome}/.local`;
-    containerEnv.NODE_ENV = "production";
-    // Let plugins in the bind-mounted extensions dir resolve openclaw/plugin-sdk.
-    // Prefer user-upgraded openclaw (in HOME/.npm-global), fall back to container built-in.
-    containerEnv.NODE_PATH = [
-        `${openclawHome}/.npm-global/lib/node_modules`,
-        "/app/node_modules",
-    ].join(":");
-    // PATH: HOME bin dirs first (upgraded OpenClaw, pip, go, cargo), then system
-    containerEnv.PATH = [
-        `${openclawHome}/.npm-global/bin`,
-        `${openclawHome}/.local/bin`,
-        `${openclawHome}/go/bin`,
-        `${openclawHome}/.cargo/bin`,
-        "/usr/local/sbin",
-        "/usr/local/bin",
-        "/usr/sbin",
-        "/usr/bin",
-        "/sbin",
-        "/bin",
-    ].join(":");
-    const runtimeArgs = [...(runtime.args || [])];
-    // Only the gateway port is published to the host; all other container ports stay
-    // hidden. Bridge networking gives each container an isolated network namespace;
-    // extra_hosts injects the host gateway IP so the container can still reach the
-    // JishuShell LLM proxy on the host without needing host-mode networking.
-    const gatewayPort = getGatewayPort(instanceId);
-    const normalizedResources = normalizeDockerResources(instanceId, runtime);
-    return {
-        Name: "gateway",
-        Driver: "docker",
-        // Task-level User field — Nomad passes this as --user to docker run.
-        User: resolveUidGid(runtime.user),
-        Config: {
-            image,
-            force_pull: false,
-            args: runtimeArgs,
-            work_dir: openclawHome,
-            volumes,
-            extra_hosts: ["host.docker.internal:host-gateway"],
-            cap_drop: ["ALL"],
-            security_opt: ["no-new-privileges"],
-            pids_limit: DEFAULT_PIDS_LIMIT,
-            readonly_rootfs: true,
-            // Provide a writable /tmp via mount config (Nomad docker driver
-            // doesn't support top-level "tmpfs" field in older versions).
-            mounts: [
-                { type: "tmpfs", target: "/tmp", tmpfs_options: { size: 536870912 } },
-                { type: "tmpfs", target: "/var/tmp", tmpfs_options: { size: 67108864 } },
-                { type: "tmpfs", target: "/run", tmpfs_options: { size: 52428800 } },
-            ],
-        },
-        Env: containerEnv,
-        Resources: {
-            ...normalizedResources,
-            // Statically reserve the gateway port on the host so Nomad can track it and
-            // detect conflicts across instances before the container even starts.
-            // In bridge mode Nomad maps this host port to the same container port.
-            Networks: [{ ReservedPorts: [{ Label: "gateway", Value: gatewayPort }] }],
-        },
-        LogConfig: { MaxFiles: 3, MaxFileSizeMB: 10 },
-        Templates: [{
-                DestPath: "secrets/instance.env",
-                Envvars: true,
-                EmbeddedTmpl: [
-                    `{{ if nomadVarExists "nomad/jobs/${safeJobId}/openclaw/gateway" }}`,
-                    `JSPROXY_API_KEY={{ with nomadVar "nomad/jobs/${safeJobId}/openclaw/gateway" }}{{ .JSPROXY_API_KEY }}{{ end }}`,
-                    `{{ end }}`,
-                ].join("\n"),
-                ChangeMode: "restart",
-            }],
-    };
-}
-async function buildJob(instanceId) {
-    const jid = jobId(instanceId);
-    const runtime = buildRuntime(instanceId);
-    const driver = getNomadDriver();
-    if (driver !== "docker") {
-        throw new Error(`Unsupported Nomad driver: ${driver}. Only "docker" is supported.`);
+    catch {
+        return "openclaw";
     }
-    const task = buildTaskDocker(instanceId, runtime);
+}
+function wrapNomadJob(jid, groupName, task) {
     return {
         Job: {
             ID: jid,
@@ -387,34 +423,23 @@ async function buildJob(instanceId) {
             Type: "service",
             Datacenters: ["*"],
             TaskGroups: [{
-                    Name: "openclaw",
+                    Name: groupName,
                     Count: 1,
                     RestartPolicy: {
                         Attempts: 3,
-                        Interval: 300000000000, // 5 min (nanoseconds)
-                        Delay: 15000000000, // 15 s  (nanoseconds)
-                        // "fail" mode: once attempts are exhausted the alloc is marked failed
-                        // and triggers reschedule evaluation, making failures visible.
-                        // "delay" (old default) silently retries forever without ever
-                        // setting the alloc to failed or triggering reschedule.
+                        Interval: 300000000000,
+                        Delay: 15000000000,
                         Mode: "fail",
                     },
-                    // Single-node (Raspberry Pi) environment: reschedule is meaningless
-                    // because there is only one node. Explicitly disable it so Nomad
-                    // doesn't spin trying to place the job on a non-existent second node.
                     Reschedule: {
                         Attempts: 0,
                         Unlimited: false,
                     },
-                    // Update policy: use task_states health check because no service
-                    // checks are registered. Without this, Nomad defaults to
-                    // health_check="checks" and waits forever for a signal that never comes,
-                    // hanging every job re-submission indefinitely.
                     Update: {
                         MaxParallel: 1,
                         HealthCheck: "task_states",
-                        MinHealthyTime: 5000000000, // 5 s
-                        HealthyDeadline: 60000000000, // 60 s
+                        MinHealthyTime: 5000000000,
+                        HealthyDeadline: 60000000000,
                         AutoRevert: false,
                     },
                     Tasks: [task],
@@ -422,6 +447,30 @@ async function buildJob(instanceId) {
         },
     };
 }
+async function buildJob(instanceId) {
+    const jid = jobId(instanceId);
+    const driver = getNomadDriver();
+    if (driver !== "docker") {
+        throw new Error(`Unsupported Nomad driver: ${driver}. Only "docker" is supported.`);
+    }
+    const legacyManager = await getLegacyAppManager(instanceId);
+    if (legacyManager) {
+        const runtime = legacyManager.buildRuntime(instanceId);
+        const task = legacyManager.buildNomadTask(instanceId, runtime, jid);
+        return wrapNomadJob(jid, legacyManager.nomadTaskGroupName(), task);
+    }
+    // Pure adapter dispatch — no more `isHermesInstance()` / kind literals.
+    const agentType = getInstanceAgentType(instanceId);
+    const adapter = getAdapter(agentType);
+    if (!adapter.buildNomadTask) {
+        throw new Error(`Runtime adapter "${agentType}" does not implement buildNomadTask(); cannot schedule Nomad job`);
+    }
+    const task = await adapter.buildNomadTask(instanceId);
+    // Task group name mirrors the agentType. Log/status helpers resolve the
+    // Nomad task name via resolveTaskName(instanceId) → adapter.nomadTaskName.
+    const groupName = agentType;
+    return wrapNomadJob(jid, groupName, task);
+}
 async function getRunningAlloc(instanceId) {
     const jid = jobId(instanceId);
     try {
@@ -447,7 +496,22 @@ export async function shouldAutoStart(instanceId) {
     const jid = jobId(instanceId);
     try {
         const resp = await nomadGet(`/v1/job/${jid}`);
-        if (!resp.ok || resp.status === 404)
+        // 404 = nomad has no record of this job. Two cases:
+        //   (a) Raft was wiped — e.g. Nomad 1.11.3 → 1.6.5 auto-migration
+        //       (install/jishu-install.sh:_migrate_nomad_to_target). The
+        //       on-disk instance config is still present and MUST be
+        //       resubmitted on the next jishushell startup, otherwise every
+        //       OpenClaw instance silently disappears after the upgrade.
+        //   (b) Brand-new instance created without a default_provider, never
+        //       started via /api/instances/.../service/start. Resubmitting it
+        //       here is a safe superset — the Nomad job is idempotent and the
+        //       container starts whether or not a provider is configured; the
+        //       user still needs to configure one to answer chat.
+        // Returning true on 404 covers (a); (b) is an accepted side effect and
+        // does not regress any user-facing behaviour.
+        if (resp.status === 404)
+            return true;
+        if (!resp.ok)
             return false;
         const job = await resp.json();
         // Stop=true means user explicitly stopped it; Stop=false means it was running.
@@ -485,7 +549,7 @@ export async function getStatus(instanceId) {
         cpu_percent: null,
         restarts: 0,
     };
-    const gwState = alloc.TaskStates?.gateway || {};
+    const gwState = alloc.TaskStates?.[resolveTaskName(instanceId)] || {};
     result.restarts = gwState.Restarts || 0;
     const startedAt = gwState.StartedAt;
     if (startedAt) {
@@ -499,8 +563,9 @@ export async function getStatus(instanceId) {
         const statsResp = await nomadGet(`/v1/client/allocation/${allocId}/stats`);
         if (statsResp.ok) {
             const stats = await statsResp.json();
-            // raw_exec: stats nested under Tasks.gateway; docker: top-level ResourceUsage
-            const taskStats = stats.Tasks?.gateway?.ResourceUsage || stats.ResourceUsage || {};
+            // raw_exec: stats nested under Tasks.<taskName>; docker: top-level ResourceUsage
+            const tn = resolveTaskName(instanceId);
+            const taskStats = stats.Tasks?.[tn]?.ResourceUsage || stats.ResourceUsage || {};
             const memStats = taskStats.MemoryStats || {};
             const cpuStats = taskStats.CpuStats || {};
             const memBytes = memStats.RSS || memStats.Usage || 0;
@@ -516,7 +581,7 @@ export async function getStatus(instanceId) {
             // Validate allocId to prevent shell injection (Nomad UUIDs are hex + hyphens)
             if (!/^[a-f0-9-]+$/i.test(allocId))
                 throw new Error("invalid allocId");
-            const containerName = `gateway-${allocId}`;
+            const containerName = `${resolveTaskName(instanceId)}-${allocId}`;
             const { execFile } = await import("child_process");
             const { promisify } = await import("util");
             const execFileAsync = promisify(execFile);
@@ -538,13 +603,24 @@ export async function getStatus(instanceId) {
     }
     return result;
 }
-export async function startInstance(instanceId) {
+/** Phase 1: reject if the instance's Nomad job is already running. */
+async function phaseRunningCheck(instanceId) {
     const status = await getStatus(instanceId);
     if (status.status === "running") {
         return { ok: false, error: "Instance is already running" };
     }
+    return { ok: true };
+}
+/**
+ * Phase 2: home-conflict check — dispatched through the adapter so
+ * framework code carries no agentType-specific knowledge. Adapters that
+ * do not share an agent-home directory across instances (e.g. Hermes,
+ * each instance owns its own bind-mount) leave the hook unset and this
+ * phase is a no-op.
+ */
+async function phaseHomeConflict(instanceId, sharedHomeIds) {
     const homeConflicts = [];
-    for (const otherId of findInstancesSharingOpenclawHome(instanceId)) {
+    for (const otherId of sharedHomeIds) {
         const otherStatus = await getStatus(otherId);
         if (otherStatus.status === "running")
             homeConflicts.push(otherId);
@@ -552,107 +628,160 @@ export async function startInstance(instanceId) {
     if (homeConflicts.length) {
         return {
             ok: false,
-            error: `This instance shares OPENCLAW_HOME with running instance(s): ${homeConflicts.join(", ")}. Move it to its own instance directory before starting it.`,
+            error: `This instance shares its agent-home directory with running instance(s): ` +
+                `${homeConflicts.join(", ")}. Move it to its own instance directory before starting it.`,
         };
     }
-    const portConflicts = [];
-    for (const otherId of findInstancesSharingGatewayPort(instanceId)) {
-        const otherStatus = await getStatus(otherId);
-        if (otherStatus.status === "running")
-            portConflicts.push(otherId);
+    return { ok: true };
+}
+/**
+ * Phase 3: host port probe + self-heal. Returns the allocation record so
+ * the caller can surface it in the API response, or null if the desired
+ * port was already free.
+ */
+async function phasePortAlloc(instanceId) {
+    const desiredPort = getGatewayPort(instanceId);
+    if (!(await isPortInUse(desiredPort)))
+        return { ok: true, portAllocation: null };
+    try {
+        const re = await reallocateGatewayPort(instanceId);
+        return { ok: true, portAllocation: { from: re.from, to: re.to, reason: "host_port_busy" } };
     }
-    if (portConflicts.length) {
-        const port = getGatewayPort(instanceId);
+    catch (e) {
         return {
             ok: false,
-            error: `Gateway port ${port} is already in use by running instance(s): ${portConflicts.join(", ")}. Assign a different port before starting this instance.`,
+            error: `Gateway port ${desiredPort} is held by another process and reallocation failed: ${e?.message ?? e}`,
         };
     }
-    const legacyStatus = await getLegacyStatus(instanceId);
-    if (legacyStatus.status === "running") {
-        console.log(`[nomad] Stopping legacy process for ${instanceId} (pid=${legacyStatus.pid}) before Nomad start...`);
-        await stopLegacyInstance(instanceId);
-        // Give it a moment to exit
-        await new Promise((r) => setTimeout(r, 2000));
-    }
-    const configPath = getOpenclawConfigPath(instanceId);
-    if (!existsSync(configPath)) {
-        return { ok: false, error: "Config file not found" };
-    }
-    if (getNomadDriver() === "docker") {
-        const stateDir = dirname(configPath);
-        ensureDirContainer(stateDir);
-        try {
-            for (const entry of readdirSync(stateDir, { withFileTypes: true })) {
-                if (entry.isDirectory()) {
-                    const sub = join(stateDir, entry.name);
-                    ensureDirContainer(sub);
-                    try {
-                        for (const child of readdirSync(sub, { withFileTypes: true })) {
-                            if (child.isDirectory())
-                                ensureDirContainer(join(sub, child.name));
-                        }
-                    }
-                    catch (_) { }
-                }
-            }
-        }
-        catch (_) { }
-        if (existsSync(configPath))
-            chmodSync(configPath, 0o644);
-        patchDockerBridgeGatewayBind(configPath);
-        // Bridge mode: rewrite 127.0.0.1 → host.docker.internal in jsproxy baseUrl
-        // so the container can reach the JishuShell LLM proxy on the host.
-        patchJsproxyBaseUrl(configPath);
-        const image = getOpenclawDockerImage();
-        // validate image name format and length.
-        if (!DOCKER_IMAGE_RE.test(image) || image.length > MAX_DOCKER_IMAGE_NAME_LEN) {
-            return { ok: false, error: `Invalid Docker image name: "${image}"` };
+}
+/**
+ * Phase 4: adapter pre-start hook — kind-specific setup (config patches,
+ * image validation, secret seeding, legacy process cleanup). A thrown
+ * error with `.building` / `.taskId` signals an async background build;
+ * we surface it to the caller so the UI can poll the task.
+ */
+async function phasePreStartHook(adapter, instanceId) {
+    if (!adapter.hooks?.onBeforeStart)
+        return { ok: true };
+    try {
+        await adapter.hooks.onBeforeStart({ instanceId });
+        return { ok: true };
+    }
+    catch (e) {
+        if (e && typeof e === "object" && e.building && e.taskId) {
+            return { ok: false, error: e.message, building: true, taskId: e.taskId };
         }
+        return { ok: false, error: e?.message || String(e) };
+    }
+}
+/**
+ * Phase 5: submit to Nomad with a single retry on port race. Between our
+ * earlier host probe and Docker's actual bind another process could have
+ * grabbed the port; on submit failure we re-probe, reallocate once if
+ * busy, and retry. Otherwise we surface the original submit error.
+ */
+async function phaseSubmit(instanceId, initialAllocation) {
+    let portAllocation = initialAllocation;
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const jobDef = await buildJob(instanceId);
+        let submitError = null;
+        let netErr = false;
         try {
-            execFileSync("docker", ["image", "inspect", image], { timeout: 10000, stdio: "ignore" });
+            const resp = await nomadPost("/v1/jobs", jobDef);
+            if (resp.ok) {
+                const data = await resp.json();
+                return { ok: true, evalId: data.EvalID, portAllocation };
+            }
+            submitError = await resp.text();
         }
-        catch {
-            // Image not found locally — kick off a background pull (with local build
-            // fallback) and return immediately so the API doesn't block.
-            console.log(`[nomad] Docker image ${image} not found, starting background pull...`);
+        catch (e) {
+            netErr = e?.message === "fetch failed" || e?.cause?.code === "ECONNREFUSED";
+            submitError = netErr ? `Nomad 服务不可达 (${getNomadAddr()})，请先启动 Nomad` : e.message;
+        }
+        if (attempt === 0 && !netErr && (await isPortInUse(getGatewayPort(instanceId)))) {
             try {
-                const setupManager = await import("./setup-manager.js");
-                const result = setupManager.startBuildSlimOpenclawImage(image);
-                return {
-                    ok: false,
-                    error: `Docker image ${image} not found. Pull started in background.`,
-                    building: true,
-                    taskId: result.taskId,
-                };
-            }
-            catch (e) {
-                return { ok: false, error: `Docker image ${image} not available: ${e.message}` };
+                const re = await reallocateGatewayPort(instanceId);
+                portAllocation = { from: re.from, to: re.to, reason: "docker_race" };
+                console.log(`[nomad] ${instanceId}: retrying after docker port race (${re.from} -> ${re.to})`);
+                continue;
             }
+            catch { /* fall through to error return */ }
         }
+        return { ok: false, error: submitError ?? "unknown error" };
     }
-    // Write instance secrets to Nomad Variables before starting the job.
-    // propagate failure — a missing proxy token causes 401 on every LLM
-    // request, so it is better to surface the error here than start a broken instance.
-    try {
-        await writeInstanceVariables(instanceId);
-    }
-    catch (e) {
-        return { ok: false, error: `Failed to store instance secrets in Nomad Variables: ${e.message}` };
+    return { ok: false, error: "start retry exhausted" };
+}
+/**
+ * §32.2 / §32.8: pure adapter dispatch. Framework owns five generic
+ * responsibilities delegated to `phase*` helpers above; every kind-
+ * specific concern lives in `adapter.hooks.onBeforeStart()`.
+ *
+ * Phase ordering:
+ *   running_check → home_conflict → pre_start_hook → port_alloc → submit
+ *
+ * `pre_start_hook` intentionally runs BEFORE `port_alloc` so deterministic
+ * errors (missing config, missing image, variables-write failure) surface
+ * ahead of port-reallocation noise. A port reallocation failure after a
+ * successful hook means the environment is genuinely contended; a hook
+ * failure after a reallocation would waste the allocation and bury the
+ * real cause under an incidental port change.
+ *
+ * Error returns carry a `phase` tag so callers and logs can distinguish
+ * *where* the failure happened. The shape stays backward-compatible: old
+ * callers that only read `ok`/`error` continue to work.
+ */
+export async function startInstance(instanceId) {
+    const appDirInstalledApp = await getAppDirInstalledApp(instanceId);
+    if (appDirInstalledApp) {
+        const { startApp } = await import("./app/app-manager.js");
+        return startApp(instanceId);
     }
-    const jobDef = await buildJob(instanceId);
-    try {
-        const resp = await nomadPost("/v1/jobs", jobDef);
-        if (resp.ok) {
-            const data = await resp.json();
-            return { ok: true, eval_id: data.EvalID };
+    const failed = (phase, rest) => {
+        console.log(`[nomad] ${instanceId}: startInstance failed at phase=${phase}: ${rest.error ?? ""}`);
+        return { ok: false, phase, ...rest };
+    };
+    const running = await phaseRunningCheck(instanceId);
+    if (!running.ok)
+        return failed("running_check", { error: running.error });
+    const legacyManager = await getLegacyAppManager(instanceId);
+    if (legacyManager) {
+        const prep = await legacyManager.prepareStart(instanceId);
+        if (!prep.ok) {
+            const extra = { error: prep.error ?? "prepareStart failed" };
+            if (prep.building)
+                extra.building = true;
+            if (prep.taskId)
+                extra.taskId = prep.taskId;
+            return failed("pre_start_hook", extra);
         }
-        return { ok: false, error: await resp.text() };
     }
-    catch (e) {
-        const isNetErr = e?.message === "fetch failed" || e?.cause?.code === "ECONNREFUSED";
-        return { ok: false, error: isNetErr ? `Nomad 服务不可达 (${getNomadAddr()})，请先启动 Nomad` : e.message };
+    else {
+        const agentType = getInstanceAgentType(instanceId);
+        const adapter = getAdapter(agentType);
+        const home = await phaseHomeConflict(instanceId, adapter.findInstancesSharingHome?.(instanceId) ?? []);
+        if (!home.ok)
+            return failed("home_conflict", { error: home.error });
+        const hook = await phasePreStartHook(adapter, instanceId);
+        if (!hook.ok) {
+            const extra = { error: hook.error };
+            if (hook.building)
+                extra.building = true;
+            if (hook.taskId)
+                extra.taskId = hook.taskId;
+            return failed("pre_start_hook", extra);
+        }
     }
+    const port = await phasePortAlloc(instanceId);
+    if (!port.ok)
+        return failed("port_alloc", { error: port.error });
+    const submit = await phaseSubmit(instanceId, port.portAllocation);
+    if (!submit.ok)
+        return failed("submit", { error: submit.error });
+    return {
+        ok: true,
+        eval_id: submit.evalId,
+        ...(submit.portAllocation ? { port_allocation: submit.portAllocation } : {}),
+    };
 }
 export async function stopInstance(instanceId, purge = false) {
     const jid = jobId(instanceId);
@@ -683,9 +812,33 @@ export async function restartInstance(instanceId) {
     // Only falls back to stop+start when no running/pending alloc exists.
     const alloc = await getRunningAlloc(instanceId);
     if (alloc) {
+        // Run the adapter's onBeforeStart even on native restart so pre-start
+        // migrations (e.g. Hermes's OPENAI_* env sync) still apply. The hook
+        // contract says it must be idempotent, so this is safe on every
+        // restart — including cases where the spec didn't change.
+        try {
+            const legacyManager = await getLegacyAppManager(instanceId);
+            if (legacyManager) {
+                const prep = await legacyManager.prepareStart(instanceId);
+                if (!prep.ok) {
+                    console.warn(`[nomad] prepareStart on restart failed for ${instanceId}: ${prep.error}`);
+                }
+            }
+            else {
+                const meta = getInstance(instanceId);
+                const agentType = resolveAgentType(meta);
+                const adapter = getAdapter(agentType);
+                if (adapter.hooks?.onBeforeStart) {
+                    await adapter.hooks.onBeforeStart({ instanceId });
+                }
+            }
+        }
+        catch (e) {
+            console.warn(`[nomad] onBeforeStart on restart failed for ${instanceId}: ${e.message}`);
+        }
         try {
             const resp = await nomadPut(`/v1/client/allocation/${alloc.ID}/restart`, {
-                TaskName: "gateway",
+                TaskName: resolveTaskName(instanceId),
                 AllTasks: false,
             });
             if (resp.ok)
@@ -723,9 +876,16 @@ export async function getLogs(instanceId, lines = 200, logType = "stderr") {
     }
     if (!alloc)
         return [];
+    const preferredTask = resolveTaskName(instanceId);
+    const resolvedTask = alloc.TaskStates?.[preferredTask]
+        ? preferredTask
+        : alloc.TaskStates?.gateway
+            ? "gateway"
+            : (Object.keys(alloc.TaskStates ?? {})[0] ?? preferredTask);
+    // Primary: Nomad log API
     try {
         const params = new URLSearchParams({
-            task: "gateway",
+            task: resolvedTask,
             type: logType,
             plain: "true",
             origin: "end",
@@ -735,10 +895,17 @@ export async function getLogs(instanceId, lines = 200, logType = "stderr") {
         const resp = await nomadGet(`/v1/client/fs/logs/${alloc.ID}?${params}`);
         if (resp.ok) {
             const text = await resp.text();
-            return text.split("\n").slice(-lines);
+            const trimmed = text.trim();
+            if (trimmed)
+                return trimmed.split("\n").slice(-lines);
         }
     }
     catch { /* ignore */ }
+    // Fallback: read Docker's json-file log directly so stdout/stderr can still
+    // be separated when Nomad log collection is disabled.
+    const dockerLogLines = await readDockerStreamLogs(`${resolvedTask}-${alloc.ID}`, lines, logType);
+    if (dockerLogLines.length > 0)
+        return dockerLogLines;
     return [];
 }
 const execFileAsync = promisify(execFileCb);
@@ -766,4 +933,2417 @@ export async function exec(instanceId, command, timeoutMs = 120_000) {
         };
     }
 }
+// ── Compatibility constants for app-type managers (src/services/app/) ───────
+// The cli branch kept these in-file; HEAD shrunk nomad-manager.ts to a
+// framework-generic layer, so the app-type managers would otherwise lose
+// their imports. Keep them here as the single source of truth and re-export
+// via the block below.
+export const DEFAULT_PIDS_LIMIT = 512;
+export const DEFAULT_ARGS = ["gateway", "run", "--port", "18789", "--allow-unconfigured"];
+export const DEFAULT_USER = userInfo().username;
+export const DEFAULT_CWD = homedir();
+export const DEFAULT_ENV = {
+    HOME: homedir(),
+    TMPDIR: "/tmp",
+    PATH: `${homedir()}/.local/bin:${homedir()}/.npm-global/bin:${homedir()}/bin:${homedir()}/.volta/bin:`
+        + `${homedir()}/.asdf/shims:${homedir()}/.bun/bin:${homedir()}/.nvm/current/bin:${homedir()}/.fnm/current/bin:`
+        + `${homedir()}/.local/share/pnpm:/usr/local/bin:/usr/bin:/bin`,
+};
+export const DEFAULT_RESOURCES = { CPU: 500, MemoryMB: 512 };
+export const MAX_CPU_MHZ = 4000; // 4 GHz per task
+export const MAX_MEMORY_MB = 4096; // 4 GB reservation
+export const MAX_MEMORY_MAX_MB = 4096; // 4 GB hard limit (memory_max)
+/**
+ * Clamp container memory reservation/limit to the framework ceilings and
+ * ensure `MemoryMaxMB >= MemoryMB`. Shared by every container-runtime app
+ * manager (openclaw / custom / ollama / hermes) so they apply the same
+ * guard-rails before handing a task spec to Nomad.
+ */
+export function normalizeDockerResources(instanceId, runtime) {
+    const requestedMemoryMB = Number(runtime.resources?.MemoryMB ?? DEFAULT_RESOURCES.MemoryMB);
+    let effectiveMemoryMB = Math.min(requestedMemoryMB, MAX_MEMORY_MB);
+    let effectiveMemoryMaxMB = Math.min(Number(runtime.resources?.MemoryMaxMB ?? requestedMemoryMB), MAX_MEMORY_MAX_MB);
+    if (effectiveMemoryMaxMB < effectiveMemoryMB) {
+        console.warn(`[nomad] ${instanceId}: MemoryMaxMB (${effectiveMemoryMaxMB}) is below MemoryMB (${effectiveMemoryMB}); clamping max to reservation.`);
+        effectiveMemoryMaxMB = effectiveMemoryMB;
+    }
+    return {
+        ...(runtime.resources ?? {}),
+        MemoryMB: effectiveMemoryMB,
+        MemoryMaxMB: effectiveMemoryMaxMB,
+    };
+}
+// ── Compatibility re-exports for app-type managers ─────────────────────────
+// `jobId`/`resolveUidGid`/`nomadGet`/`nomadPut`/`assertSafeTemplateId` are
+// internal helpers defined elsewhere in this file; re-exporting them keeps
+// cli-branch imports (`../nomad-manager.js`) working.
+export { jobId, resolveUidGid, nomadGet, nomadPut, assertSafeTemplateId, };
+const instanceScheduler = {
+    getStatus,
+    startInstance,
+    stopInstance,
+    restartInstance,
+    getLogs,
+    exec,
+};
+var UnifiedNomadJobs;
+(function (UnifiedNomadJobs) {
+    // ── Constants ─────────────────────────────────────────────────────────────
+    const OPENCLAW_PREFIX = "openclaw-";
+    // Docker image names must match this pattern to prevent command injection.
+    UnifiedNomadJobs.DOCKER_IMAGE_RE = /^[a-zA-Z0-9][a-zA-Z0-9\-_.:/@]*$/;
+    UnifiedNomadJobs.MAX_DOCKER_IMAGE_NAME_LEN = 256;
+    UnifiedNomadJobs.VALID_LOG_TYPES = new Set(["stdout", "stderr"]);
+    // Nomad Template metacharacters that must not appear in values interpolated
+    // into EmbeddedTmpl strings.
+    UnifiedNomadJobs.NOMAD_TEMPLATE_UNSAFE_RE = /[{}"\\]/;
+    const DEFAULT_CPU_MHZ = 500;
+    const DEFAULT_MEMORY_MB = 512;
+    // Hard upper bounds: prevents misconfigured specs from exhausting scheduler resources.
+    const MAX_CPU_MHZ = 4000; // 4 GHz
+    const MAX_MEMORY_MB = 4096; // 4 GB reservation
+    const MAX_MEMORY_MAX_MB = 4096; // 4 GB hard limit
+    const DEFAULT_PIDS_LIMIT = 512;
+    const NOMAD_CONFIG_PATH = join(JISHUSHELL_HOME, "nomad", "nomad.hcl");
+    const DEFAULT_CWD = homedir();
+    function appDirForId(appId) {
+        return join(APPS_DIR, appId);
+    }
+    function isAppJob(id) {
+        const dir = appDirForId(id);
+        if (existsSync(join(dir, "manifest.json")) || existsSync(join(dir, "app-spec.yaml"))) {
+            return true;
+        }
+        if (id.startsWith(OPENCLAW_PREFIX))
+            return false;
+        return false;
+    }
+    UnifiedNomadJobs.isAppJob = isAppJob;
+    function resolveAppDir(appId) {
+        const dir = appDirForId(appId);
+        if (existsSync(join(dir, "manifest.json")) || existsSync(join(dir, "app-spec.yaml"))) {
+            return dir;
+        }
+        return null;
+    }
+    // ── Job ID ────────────────────────────────────────────────────────────────
+    function jobId(appId) {
+        return appId;
+    }
+    function assertSafeTemplateId(id) {
+        if (UnifiedNomadJobs.NOMAD_TEMPLATE_UNSAFE_RE.test(id)) {
+            throw new Error(`Job ID "${id}" contains characters unsafe for Nomad Template interpolation`);
+        }
+    }
+    // ── Nomad HTTP helpers ────────────────────────────────────────────────────
+    function nomadAuthHeaders() {
+        const token = getNomadToken();
+        return token ? { "X-Nomad-Token": token } : {};
+    }
+    async function nomadGet(path) {
+        const resp = await fetch(`${getNomadAddr()}${path}`, {
+            headers: nomadAuthHeaders(),
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!resp.ok && resp.status !== 404) {
+            throw new Error(`Nomad GET ${path}: HTTP ${resp.status}`);
+        }
+        return resp;
+    }
+    async function nomadPost(path, body) {
+        return fetch(`${getNomadAddr()}${path}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", ...nomadAuthHeaders() },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    async function nomadPut(path, body) {
+        return fetch(`${getNomadAddr()}${path}`, {
+            method: "PUT",
+            headers: { "Content-Type": "application/json", ...nomadAuthHeaders() },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    async function nomadDelete(path) {
+        return fetch(`${getNomadAddr()}${path}`, {
+            method: "DELETE",
+            headers: nomadAuthHeaders(),
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    async function listNomadNodes() {
+        try {
+            const resp = await nomadGet("/v1/nodes");
+            if (!resp.ok)
+                return [];
+            const nodes = await resp.json();
+            return Array.isArray(nodes) ? nodes : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    function isSchedulableNode(node) {
+        return (node.Status ?? "ready") === "ready"
+            && (node.SchedulingEligibility ?? "eligible") === "eligible";
+    }
+    function rawExecDriverHealthy(node) {
+        const driver = node.Drivers?.raw_exec;
+        return driver?.Detected === true && driver?.Healthy === true;
+    }
+    function rawExecRestartHint() {
+        if (process.platform === "linux")
+            return "sudo systemctl restart nomad";
+        if (process.platform === "darwin")
+            return "重启 Nomad launchd agent";
+        return "重启 Nomad 服务";
+    }
+    function nomadConfigEnablesRawExec() {
+        try {
+            const config = readFileSync(NOMAD_CONFIG_PATH, "utf-8");
+            return /plugin\s+"raw_exec"\s*\{[\s\S]*?enabled\s*=\s*true\b/.test(config);
+        }
+        catch {
+            return false;
+        }
+    }
+    async function validateRawExecDriverAvailability() {
+        const nodes = (await listNomadNodes()).filter(isSchedulableNode);
+        if (nodes.length === 0)
+            return null;
+        if (nodes.some(rawExecDriverHealthy))
+            return null;
+        const detail = nodes
+            .map((node) => {
+            const driver = node.Drivers?.raw_exec;
+            const name = String(node.Name ?? node.ID ?? "unknown-node");
+            const description = String(driver?.HealthDescription
+                ?? (driver?.Detected === false ? "disabled" : "unavailable"));
+            return `${name}: ${description}`;
+        })
+            .join("; ");
+        if (nomadConfigEnablesRawExec()) {
+            return `Nomad client 当前未启用 raw_exec driver（${detail}）。磁盘配置已启用 raw_exec，但运行中的 Nomad 仍在使用旧配置；请先执行 ${rawExecRestartHint()} 后重试。`;
+        }
+        return `Nomad client 当前未启用 raw_exec driver（${detail}）。请先在 Nomad 配置中启用 plugin \"raw_exec\" { config { enabled = true } }，然后重启 Nomad。`;
+    }
+    function allocTimestamp(alloc) {
+        const raw = alloc.ModifyTime ?? alloc.CreateTime ?? alloc.CreateIndex ?? 0;
+        return typeof raw === "number" ? raw : Number(raw) || 0;
+    }
+    // ── Resource unit parsers ─────────────────────────────────────────────────
+    /**
+     * Parse a CPU resource string to Nomad MHz integer.
+     *  "500m"  → 500  (millicores treated as MHz for simplicity)
+     *  "1"     → 1000 (1 core → 1000 MHz)
+     *  "1000"  → 1000 (bare integer treated as MHz already)
+     *
+     * Nomad doesn't have a concept of "cores"; it schedules by MHz.
+     * We treat 1 core = 1000 MHz as a reasonable proxy for a Pi-class host.
+     */
+    function parseCpuMHz(cpu) {
+        if (cpu == null)
+            return DEFAULT_CPU_MHZ;
+        const s = String(cpu).trim();
+        if (s.endsWith("m")) {
+            // millicores (K8s-style): "500m" → 500 MHz
+            const val = parseFloat(s.slice(0, -1));
+            return isNaN(val) ? DEFAULT_CPU_MHZ : Math.max(1, Math.min(Math.round(val), MAX_CPU_MHZ));
+        }
+        const val = parseFloat(s);
+        if (isNaN(val))
+            return DEFAULT_CPU_MHZ;
+        // Bare integer ≤ 16 likely means "cores" (e.g. "1", "2"); convert to MHz.
+        // Bare integer > 16 likely already MHz.
+        const mhz = val <= 16 ? Math.round(val * 1000) : Math.round(val);
+        return Math.max(1, Math.min(mhz, MAX_CPU_MHZ));
+    }
+    UnifiedNomadJobs.parseCpuMHz = parseCpuMHz;
+    /**
+     * Parse a memory resource string to Nomad MB integer.
+     *  "512Mi" or "512MiB" → 512 MB
+     *  "1Gi"   or "1GiB"   → 1024 MB
+     *  "512M"  or "512MB"  → 512 MB
+     *  "1G"    or "1GB"    → 1024 MB
+     *  "1024"              → 1024 MB (bare integer = MB)
+     */
+    function parseMemoryMB(memory) {
+        if (memory == null)
+            return DEFAULT_MEMORY_MB;
+        const s = String(memory).trim();
+        const match = s.match(/^([\d.]+)\s*(gi|gib|g|gb|mi|mib|m|mb|ki|kib|k|kb)?$/i);
+        if (!match)
+            return DEFAULT_MEMORY_MB;
+        const val = parseFloat(match[1]);
+        if (isNaN(val))
+            return DEFAULT_MEMORY_MB;
+        const unit = (match[2] || "").toLowerCase();
+        let mb;
+        if (unit === "gi" || unit === "gib" || unit === "g" || unit === "gb") {
+            mb = Math.round(val * 1024);
+        }
+        else if (unit === "ki" || unit === "kib" || unit === "k" || unit === "kb") {
+            mb = Math.round(val / 1024);
+        }
+        else {
+            // "mi"/"mib"/"m"/"mb" or bare integer
+            mb = Math.round(val);
+        }
+        return Math.max(1, Math.min(mb, MAX_MEMORY_MB));
+    }
+    UnifiedNomadJobs.parseMemoryMB = parseMemoryMB;
+    // ── Interval parser ───────────────────────────────────────────────────────
+    function parseIntervalNs(s, defaultNs) {
+        if (!s)
+            return defaultNs;
+        if (s.endsWith("ms"))
+            return parseInt(s) * 1_000_000;
+        if (s.endsWith("s"))
+            return parseInt(s) * 1_000_000_000;
+        if (s.endsWith("m"))
+            return parseInt(s) * 60_000_000_000;
+        return parseInt(s) * 1_000_000_000;
+    }
+    function portLabel(taskName, portName) {
+        const sanitize = (value) => value.replace(/[^a-zA-Z0-9_-]/g, "-");
+        return `${sanitize(taskName)}-${sanitize(portName)}`;
+    }
+    function nomadConfigDeclaresHostNetwork(name) {
+        if (!existsSync(NOMAD_CONFIG_PATH))
+            return false;
+        try {
+            const config = readFileSync(NOMAD_CONFIG_PATH, "utf-8");
+            const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            return new RegExp(`host_network\\s+"${escaped}"\\s*\\{`).test(config);
+        }
+        catch {
+            return false;
+        }
+    }
+    function hostNetworkForPort(port) {
+        if ((port.visibility ?? "external") === "internal")
+            return undefined;
+        return nomadConfigDeclaresHostNetwork("external") ? "external" : undefined;
+    }
+    function specRequiresExternalHostNetwork(spec) {
+        return spec.tasks.some((task) => (task.ports ?? []).some((port) => (port.visibility ?? "external") !== "internal"));
+    }
+    async function validateRequiredHostNetworks(spec) {
+        if (!specRequiresExternalHostNetwork(spec))
+            return null;
+        if (!nomadConfigDeclaresHostNetwork("external"))
+            return null;
+        try {
+            const resp = await nomadGet("/v1/agent/self");
+            if (!resp.ok)
+                return null;
+            const self = await resp.json();
+            const hostNetworks = Array.isArray(self?.config?.Client?.HostNetworks)
+                ? self.config.Client.HostNetworks
+                : [];
+            const loadedNetworks = new Set(hostNetworks
+                .map((network) => String(network?.Name ?? "").trim())
+                .filter(Boolean));
+            if (!loadedNetworks.has("external")) {
+                return 'Nomad 运行中的 agent 尚未加载 host_network "external"。请先重启 Nomad，再启动该应用。';
+            }
+        }
+        catch {
+            // Let the later job submission path report Nomad unreachable when needed.
+        }
+        return null;
+    }
+    function reservedPortsForTask(task) {
+        // visibility=internal ports are intra-group only (e.g. SearXNG sidecar
+        // reachable from the gateway task via 127.0.0.1 inside the bridge
+        // network namespace). Reserving them on the host would occupy a host
+        // port slot AND, combined with docker publishing below, expose the
+        // endpoint externally. Skip them entirely — they stay inside the task
+        // group's network namespace.
+        return (task.ports ?? [])
+            .filter((port) => (port.visibility ?? "external") !== "internal")
+            .map((port) => ({
+            Label: portLabel(task.name, port.name),
+            Value: port.host_port ?? port.port,
+            ...(task.runtime === "container" ? { To: port.container_port ?? port.port } : {}),
+            ...(hostNetworkForPort(port) ? { HostNetwork: hostNetworkForPort(port) } : {}),
+        }));
+    }
+    // ── Health check → Nomad service check builder ────────────────────────────
+    function buildServiceCheck(task, appId) {
+        const health = task.health;
+        if (!health?.http)
+            return null;
+        const portEntry = task.ports?.find((p) => p.port === health.http.port
+            || p.host_port === health.http.port
+            || p.container_port === health.http.port);
+        if (!portEntry)
+            return null;
+        // Internal ports are not reserved on host (see reservedPortsForTask),
+        // so a host-mode Nomad service check would reference an unknown port
+        // label. Skip the task-level health check; intra-group readiness for
+        // sidecars falls through to the `after:` ordering once that lands.
+        if ((portEntry.visibility ?? "external") === "internal")
+            return null;
+        const checkPortLabel = portLabel(task.name, portEntry.name);
+        // Task-level checks cannot use address_mode="alloc". raw_exec tasks also do
+        // not create an allocation network namespace, so host mode is the valid
+        // Nomad-compatible choice here.
+        const checkAddressMode = "host";
+        const check = {
+            Name: `${task.name}-health`,
+            Type: "http",
+            Path: health.http.path,
+            PortLabel: checkPortLabel,
+            AddressMode: checkAddressMode,
+            Header: {
+                "X-Real-IP": ["127.0.0.1"],
+            },
+            Interval: parseIntervalNs(health.interval, 15_000_000_000),
+            Timeout: parseIntervalNs(health.timeout, 5_000_000_000),
+        };
+        if (health.retries != null || health.start_period) {
+            check.CheckRestart = {
+                Limit: health.retries ?? 3,
+                Grace: health.start_period ? parseIntervalNs(health.start_period, 0) : 0,
+                IgnoreWarnings: false,
+            };
+        }
+        return {
+            Name: `${appId}-${task.name}`,
+            Provider: "nomad",
+            PortLabel: checkPortLabel,
+            AddressMode: "host",
+            Checks: [check],
+        };
+    }
+    // ── Deep merge utility ────────────────────────────────────────────────────
+    function deepMerge(target, source) {
+        const result = { ...target };
+        for (const key of Object.keys(source)) {
+            if (source[key] && typeof source[key] === "object" && !Array.isArray(source[key]) &&
+                result[key] && typeof result[key] === "object" && !Array.isArray(result[key])) {
+                result[key] = deepMerge(result[key], source[key]);
+            }
+            else {
+                result[key] = source[key];
+            }
+        }
+        return result;
+    }
+    function interpolateEnvRequires(taskEnv, extraEnv) {
+        if (Object.keys(extraEnv).length === 0)
+            return taskEnv;
+        const result = {};
+        for (const [k, v] of Object.entries(taskEnv)) {
+            result[k] = v.replace(/\$\{requires\.([^}]+)\}/g, (_, key) => extraEnv[key] ?? "");
+        }
+        return result;
+    }
+    function materializeAppIdTokens(value, appId) {
+        if (typeof value === "string") {
+            return value
+                .replace(/\$\{app_id\}/g, appId)
+                .replace(/\$\{app\.id\}/g, appId);
+        }
+        if (Array.isArray(value)) {
+            return value.map((entry) => materializeAppIdTokens(entry, appId));
+        }
+        if (value && typeof value === "object") {
+            const result = {};
+            for (const [key, entry] of Object.entries(value)) {
+                result[key] = materializeAppIdTokens(entry, appId);
+            }
+            return result;
+        }
+        return value;
+    }
+    // ── Task lifecycle mapping ────────────────────────────────────────────────
+    /**
+     * Map AppTask role to a Nomad task lifecycle block.
+     * Returns null for the default "service" role (no lifecycle block needed).
+     *
+     * Nomad lifecycle hooks:
+     *   prestart  - runs before main tasks; sidecar=false means it must complete
+     *   poststart - runs after main tasks start; sidecar=true means it keeps running
+     *   poststop  - runs after all main tasks stop
+     *
+     * TODO: AppTask.after[] dependency ordering is not yet mapped.
+     */
+    function roleToLifecycle(role) {
+        switch (role) {
+            case "init":
+                return { Hook: "prestart", Sidecar: false };
+            case "sidecar":
+                return { Hook: "prestart", Sidecar: true };
+            case "cleanup":
+                return { Hook: "poststop", Sidecar: false };
+            case "service":
+            default:
+                return null;
+        }
+    }
+    // ── Process runtime helpers ──────────────────────────────────────────────
+    /**
+     * Check whether a binary process is already running on the host OS by
+     * matching its command path via pgrep -f.
+     *
+     * Used by startAppJob to skip Nomad submission when the binary is already
+     * running (e.g. started outside of Nomad or when raw_exec driver is unavailable).
+     */
+    async function isBinaryRunning(command) {
+        if (!command)
+            return false;
+        const expanded = command.replace(/^~(?=\/|$)/, homedir());
+        // Try full path first, then basename — covers symlinks & macOS App Translocation.
+        const patterns = [expanded];
+        const base = basename(expanded);
+        if (base !== expanded)
+            patterns.push(base);
+        for (const pattern of patterns) {
+            const found = await new Promise((resolve) => {
+                execFileCb("pgrep", ["-f", pattern], { timeout: 3_000 }, (_err, stdout) => {
+                    resolve(stdout.trim().length > 0);
+                });
+            });
+            if (found)
+                return true;
+        }
+        return false;
+    }
+    UnifiedNomadJobs.isBinaryRunning = isBinaryRunning;
+    function tryBindPort(port, host) {
+        return new Promise((resolve) => {
+            const server = netCreateServer();
+            server.once("error", (error) => {
+                if (error?.code === "EADDRINUSE") {
+                    resolve(true);
+                    return;
+                }
+                console.warn(`[port-probe] bind ${host}:${port} failed with ${error?.code ?? "unknown"}: ${error?.message}; treating as free`);
+                resolve(false);
+            });
+            server.once("listening", () => {
+                server.close(() => resolve(false));
+            });
+            server.listen(port, host);
+        });
+    }
+    async function isPortInUse(port) {
+        if (!Number.isInteger(port) || port < 1 || port > 65535)
+            return false;
+        // Probe sequentially so the wildcard probe does not race with the loopback
+        // probe and falsely trigger EADDRINUSE against our own temporary socket.
+        if (await tryBindPort(port, "0.0.0.0"))
+            return true;
+        return tryBindPort(port, "127.0.0.1");
+    }
+    function loadInstalledAppSpec(appId) {
+        const appDir = resolveAppDir(appId);
+        if (!appDir)
+            return null;
+        try {
+            return parse(readFileSync(join(appDir, "app-spec.yaml"), "utf-8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    function externalHealthProbeTimeoutMs(task) {
+        return Math.max(1_000, Math.floor(parseIntervalNs(task.health?.timeout, 5_000_000_000) / 1_000_000));
+    }
+    async function probeExternalTaskHealth(appId, task) {
+        const health = task.health?.http;
+        if (!health)
+            return null;
+        const url = `http://127.0.0.1:${health.port}${health.path}`;
+        try {
+            const resp = await fetch(url, { signal: AbortSignal.timeout(externalHealthProbeTimeoutMs(task)) });
+            return {
+                name: `${task.name}-health`,
+                status: resp.ok ? "success" : "failure",
+                service: `${appId}-${task.name}`,
+                output: `external probe: HTTP ${resp.status}`,
+            };
+        }
+        catch (e) {
+            return {
+                name: `${task.name}-health`,
+                status: "failure",
+                service: `${appId}-${task.name}`,
+                output: `external probe: ${e?.message ?? "request failed"}`,
+            };
+        }
+    }
+    const EXTERNAL_PROCESS_ADOPT_COMMAND = "/bin/sh";
+    const EXTERNAL_PROCESS_ADOPT_ARGS = [
+        "-c",
+        "echo 'jishushell adopting external service'; trap 'exit 0' TERM INT; while true; do sleep 3600; done",
+    ];
+    const EXTERNAL_STOP_POLL_INTERVAL_MS = 250;
+    const EXTERNAL_STOP_SETTLE_TIMEOUT_MS = 4_000;
+    function expandTaskCommand(command) {
+        if (!command)
+            return null;
+        return command.replace(/^~(?=\/|$)/, homedir());
+    }
+    function taskCommandLine(task) {
+        const command = expandTaskCommand(task.command);
+        if (!command)
+            return null;
+        return [command, ...(task.args ?? []).map(String)].join(" ").trim();
+    }
+    function commandLineMatchesTask(commandLine, task) {
+        const normalized = commandLine.trim();
+        const command = expandTaskCommand(task.command);
+        if (!command)
+            return false;
+        const [actualCommand, ...actualArgs] = normalized.split(/\s+/);
+        const expectedArgs = (task.args ?? []).map(String);
+        const commandMatches = actualCommand === command || actualCommand === basename(command);
+        if (!commandMatches)
+            return false;
+        const actualTail = actualArgs.join(" ").trim();
+        const expectedTail = expectedArgs.join(" ").trim();
+        if (!expectedTail)
+            return true;
+        return actualTail === expectedTail || actualTail.startsWith(`${expectedTail} `);
+    }
+    function parseExecFileError(error) {
+        const stderr = typeof error?.stderr === "string" ? error.stderr.trim() : "";
+        if (stderr)
+            return stderr.split("\n")[0];
+        const stdout = typeof error?.stdout === "string" ? error.stdout.trim() : "";
+        if (stdout)
+            return stdout.split("\n")[0];
+        return String(error?.message ?? "command failed").trim();
+    }
+    async function listExternalTaskProcesses(task) {
+        const command = expandTaskCommand(task.command);
+        if (!command)
+            return [];
+        const execFileAsync = promisify(execFileCb);
+        try {
+            const { stdout } = await execFileAsync("ps", ["-eo", "pid=,user=,args="], { timeout: 5_000 });
+            return stdout
+                .split("\n")
+                .map((line) => line.match(/^\s*(\d+)\s+(\S+)\s+(.*)$/))
+                .filter((match) => Boolean(match))
+                .map((match) => ({
+                pid: Number(match[1]),
+                user: match[2] || null,
+                commandLine: match[3]?.trim() ?? "",
+            }))
+                .filter((entry) => entry.pid > 1 && commandLineMatchesTask(entry.commandLine, task));
+        }
+        catch {
+            return [];
+        }
+    }
+    async function listExternalTaskBusyPorts(task) {
+        const declaredPorts = (task.ports ?? [])
+            .map((port) => port.port)
+            .filter((port) => Number.isInteger(port) && port > 0 && port <= 65535);
+        const occupiedFlags = await Promise.all(declaredPorts.map((port) => isPortInUse(port)));
+        return declaredPorts.filter((_port, index) => occupiedFlags[index]);
+    }
+    function parseSsPortLine(line) {
+        const columns = line.trim().split(/\s+/);
+        const local = columns[3] ?? "";
+        if (!local)
+            return null;
+        if (local.startsWith("[")) {
+            const end = local.indexOf("]:");
+            if (end < 0)
+                return null;
+            const address = local.slice(1, end);
+            const port = Number(local.slice(end + 2));
+            return Number.isInteger(port) ? { address, port } : null;
+        }
+        const idx = local.lastIndexOf(":");
+        if (idx < 0)
+            return null;
+        const address = local.slice(0, idx);
+        const port = Number(local.slice(idx + 1));
+        return Number.isInteger(port) ? { address, port } : null;
+    }
+    async function listListeningAddressesForPorts(ports) {
+        const wanted = new Set(ports.filter((port) => Number.isInteger(port) && port > 0 && port <= 65535));
+        if (wanted.size === 0)
+            return {};
+        const execFileAsync = promisify(execFileCb);
+        try {
+            const { stdout } = await execFileAsync("ss", ["-ltnH"], { timeout: 5_000 });
+            const result = {};
+            for (const line of stdout.split("\n")) {
+                const parsed = parseSsPortLine(line);
+                if (!parsed || !wanted.has(parsed.port))
+                    continue;
+                result[parsed.port] ??= [];
+                if (!result[parsed.port].includes(parsed.address)) {
+                    result[parsed.port].push(parsed.address);
+                }
+            }
+            return result;
+        }
+        catch {
+            return {};
+        }
+    }
+    function portRequiresExternalBinding(task, port) {
+        const portEntry = (task.ports ?? []).find((entry) => entry.port === port);
+        return (portEntry?.visibility ?? "external") !== "internal";
+    }
+    function isNonLoopbackAddress(address) {
+        const normalized = address.trim().replace(/^\[|\]$/g, "");
+        if (!normalized || normalized === "*" || normalized === "0.0.0.0" || normalized === "::" || normalized === ":::") {
+            return true;
+        }
+        if (normalized === "localhost" || normalized === "::1")
+            return false;
+        if (/^127\./.test(normalized))
+            return false;
+        return true;
+    }
+    function loopbackOnlyConflictDetail(task, occupiedPorts, listeningAddresses) {
+        const invalidPorts = occupiedPorts.filter((port) => {
+            if (!portRequiresExternalBinding(task, port))
+                return false;
+            const addresses = listeningAddresses[port] ?? [];
+            return addresses.length > 0 && !addresses.some(isNonLoopbackAddress);
+        });
+        if (invalidPorts.length === 0)
+            return null;
+        const details = invalidPorts.map((port) => {
+            const bindings = (listeningAddresses[port] ?? []).join(", ") || "127.0.0.1";
+            return `${port} (${bindings})`;
+        });
+        return `Task "${task.name}" 端口 ${details.join(", ")} 当前仅监听在本地回环地址，无法作为可外部访问的应用接管`;
+    }
+    async function snapshotExternalTaskRuntime(task) {
+        const [processes, occupiedPorts, healthCheck] = await Promise.all([
+            listExternalTaskProcesses(task),
+            listExternalTaskBusyPorts(task),
+            probeExternalTaskHealth("external-stop", task),
+        ]);
+        const healthy = healthCheck?.status === "success";
+        return {
+            running: processes.length > 0 || (occupiedPorts.length > 0 && (healthy || !task.health?.http)),
+            processes,
+            occupiedPorts,
+            healthy,
+        };
+    }
+    async function waitForExternalTaskExit(task, timeoutMs = EXTERNAL_STOP_SETTLE_TIMEOUT_MS) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const snapshot = await snapshotExternalTaskRuntime(task);
+            if (!snapshot.running)
+                return true;
+            await new Promise((resolve) => setTimeout(resolve, EXTERNAL_STOP_POLL_INTERVAL_MS));
+        }
+        const finalSnapshot = await snapshotExternalTaskRuntime(task);
+        return !finalSnapshot.running;
+    }
+    async function detectSystemdUnitForTask(task, processes) {
+        if (process.platform !== "linux" || processes.length === 0)
+            return null;
+        const command = expandTaskCommand(task.command);
+        if (!command)
+            return null;
+        const candidate = `${basename(command).replace(/\.[^.]+$/, "")}.service`;
+        const execFileAsync = promisify(execFileCb);
+        try {
+            const { stdout } = await execFileAsync("systemctl", ["show", candidate, "--property=LoadState,ActiveState,MainPID,ExecStart"], { timeout: 5_000 });
+            const props = Object.fromEntries(stdout
+                .split("\n")
+                .map((line) => line.trim())
+                .filter(Boolean)
+                .map((line) => {
+                const idx = line.indexOf("=");
+                return idx >= 0 ? [line.slice(0, idx), line.slice(idx + 1)] : [line, ""];
+            }));
+            if (props.LoadState === "not-found")
+                return null;
+            if (!["active", "activating", "reloading"].includes(props.ActiveState ?? ""))
+                return null;
+            const mainPid = Number(props.MainPID ?? 0);
+            if (processes.some((entry) => entry.pid === mainPid)) {
+                return candidate;
+            }
+            return props.ExecStart?.includes(command) ? candidate : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async function stopSystemdUnit(unit) {
+        const execFileAsync = promisify(execFileCb);
+        let lastError = null;
+        try {
+            await execFileAsync("systemctl", ["--no-ask-password", "stop", unit], { timeout: 15_000 });
+            return null;
+        }
+        catch (error) {
+            lastError = parseExecFileError(error);
+        }
+        try {
+            await execFileAsync("sudo", ["-n", "systemctl", "stop", unit], { timeout: 15_000 });
+            return null;
+        }
+        catch (error) {
+            return parseExecFileError(error) || lastError;
+        }
+    }
+    function isProcessAlive(pid) {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (error) {
+            return error?.code === "EPERM";
+        }
+    }
+    async function waitForPidExit(pid, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (!isProcessAlive(pid))
+                return true;
+            await new Promise((resolve) => setTimeout(resolve, EXTERNAL_STOP_POLL_INTERVAL_MS));
+        }
+        return !isProcessAlive(pid);
+    }
+    async function terminateExternalProcess(pid) {
+        try {
+            process.kill(pid, "SIGTERM");
+        }
+        catch (error) {
+            if (error?.code === "ESRCH")
+                return null;
+            return String(error?.message ?? error);
+        }
+        if (await waitForPidExit(pid, 2_500)) {
+            return null;
+        }
+        try {
+            process.kill(pid, "SIGKILL");
+        }
+        catch (error) {
+            if (error?.code === "ESRCH")
+                return null;
+            return String(error?.message ?? error);
+        }
+        return (await waitForPidExit(pid, 1_500)) ? null : `pid ${pid} 在 SIGKILL 后仍存活`;
+    }
+    async function stopExternalProcessTask(task) {
+        const initial = await snapshotExternalTaskRuntime(task);
+        if (!initial.running) {
+            return { detected: false, ok: true };
+        }
+        const errors = [];
+        const systemdUnit = await detectSystemdUnitForTask(task, initial.processes);
+        if (systemdUnit) {
+            const stopError = await stopSystemdUnit(systemdUnit);
+            if (stopError) {
+                errors.push(`systemd unit "${systemdUnit}" 停止失败: ${stopError}`);
+            }
+            if (await waitForExternalTaskExit(task)) {
+                return { detected: true, ok: true };
+            }
+        }
+        for (const proc of initial.processes) {
+            const stopError = await terminateExternalProcess(proc.pid);
+            if (stopError) {
+                const owner = proc.user ? ` (${proc.user})` : "";
+                errors.push(`无法停止进程 ${proc.pid}${owner}: ${stopError}`);
+            }
+        }
+        if (await waitForExternalTaskExit(task)) {
+            return { detected: true, ok: true };
+        }
+        const finalSnapshot = await snapshotExternalTaskRuntime(task);
+        const details = [];
+        if (finalSnapshot.processes.length > 0) {
+            details.push(`进程 ${finalSnapshot.processes.map((proc) => `${proc.pid}${proc.user ? `(${proc.user})` : ""}`).join(", ")} 仍在运行`);
+        }
+        if (finalSnapshot.occupiedPorts.length > 0) {
+            details.push(`端口 ${finalSnapshot.occupiedPorts.join(", ")} 仍被占用`);
+        }
+        if (systemdUnit) {
+            details.push(`可手动执行 sudo systemctl stop ${systemdUnit}`);
+        }
+        return {
+            detected: true,
+            ok: false,
+            error: `Task "${task.name}" 未能完全停止：${details.join("，")}${errors.length ? `；${errors.join("; ")}` : ""}`,
+        };
+    }
+    async function stopExternalProcessApp(appId) {
+        const spec = loadInstalledAppSpec(appId);
+        if (!spec) {
+            return { detected: false, ok: true };
+        }
+        const processTasks = spec.tasks.filter((task) => task.runtime === "process" && (task.role ?? "service") === "service");
+        if (processTasks.length === 0) {
+            return { detected: false, ok: true };
+        }
+        const errors = [];
+        let detected = false;
+        for (const task of processTasks) {
+            const result = await stopExternalProcessTask(task);
+            detected ||= result.detected;
+            if (!result.ok && result.error) {
+                errors.push(result.error);
+            }
+        }
+        return {
+            detected,
+            ok: errors.length === 0,
+            ...(errors.length ? { error: errors.join("; ") } : {}),
+        };
+    }
+    async function inspectExternalProcessTask(appId, task) {
+        const commandRunning = task.command ? await isBinaryRunning(task.command) : false;
+        const declaredPorts = (task.ports ?? [])
+            .map((port) => port.port)
+            .filter((port) => Number.isInteger(port) && port > 0 && port <= 65535);
+        const occupiedFlags = await Promise.all(declaredPorts.map((port) => isPortInUse(port)));
+        const busyPorts = declaredPorts.filter((_port, index) => occupiedFlags[index]);
+        const listeningAddresses = await listListeningAddressesForPorts(busyPorts);
+        const healthCheck = await probeExternalTaskHealth(appId, task);
+        const healthMatched = healthCheck?.status === "success";
+        const bindingConflict = loopbackOnlyConflictDetail(task, busyPorts, listeningAddresses);
+        const hasDeclaredPorts = declaredPorts.length > 0;
+        // External adoption must be conservative. A matching command name alone is
+        // not enough evidence for service readiness because unrelated host processes
+        // can share the same binary. When a health check exists, require it to pass.
+        // Without a health check, require the service to actually occupy its declared
+        // port(s); only port-less process tasks can fall back to command detection.
+        const detected = !bindingConflict && ((Boolean(task.health?.http) && healthMatched)
+            || (!task.health?.http && hasDeclaredPorts && busyPorts.length > 0)
+            || (!task.health?.http && !hasDeclaredPorts && commandRunning));
+        const conflict = Boolean(bindingConflict) || (busyPorts.length > 0 && !healthMatched && Boolean(task.health?.http));
+        const status = {
+            state: detected ? "running" : conflict ? "failed" : "stopped",
+            restarts: 0,
+        };
+        if (healthCheck) {
+            status.health_checks = [healthCheck];
+            status.health_status = aggregateHealthStatus(status.health_checks);
+        }
+        return {
+            detected,
+            conflict,
+            occupiedPorts: busyPorts,
+            ...(bindingConflict ? { conflictDetail: bindingConflict } : {}),
+            status,
+        };
+    }
+    async function inspectExternalProcessApp(appId, spec) {
+        if (!resolveAppDir(appId)) {
+            return { detected: false, conflicts: [], status: null };
+        }
+        const appSpec = spec ?? loadInstalledAppSpec(appId);
+        if (!appSpec)
+            return { detected: false, conflicts: [], status: null };
+        const serviceProcessTasks = appSpec.tasks.filter((task) => task.runtime === "process" && (task.role ?? "service") === "service");
+        if (serviceProcessTasks.length === 0) {
+            return { detected: false, conflicts: [], status: null };
+        }
+        const tasks = {};
+        const conflicts = [];
+        let detected = false;
+        for (const task of appSpec.tasks) {
+            if (task.runtime === "process" && (task.role ?? "service") === "service") {
+                const inspection = await inspectExternalProcessTask(appId, task);
+                tasks[task.name] = inspection.status;
+                detected ||= inspection.detected;
+                if (inspection.conflict) {
+                    if (inspection.conflictDetail) {
+                        conflicts.push(inspection.conflictDetail);
+                    }
+                    else {
+                        const ports = inspection.occupiedPorts.join(", ");
+                        const path = task.health?.http?.path ?? "/";
+                        conflicts.push(`Task "${task.name}" 端口 ${ports} 已被占用，但现有服务未通过健康检查 ${path}`);
+                    }
+                }
+                continue;
+            }
+            tasks[task.name] = {
+                state: (task.role ?? "service") === "init" ? "dead" : "unknown",
+                restarts: 0,
+            };
+        }
+        if (!detected) {
+            return { detected: false, conflicts, status: null };
+        }
+        const primaryTaskName = serviceProcessTasks[0]?.name ?? Object.keys(tasks)[0] ?? "";
+        return {
+            detected: true,
+            conflicts,
+            status: {
+                status: "running",
+                tasks,
+                pid: null,
+                uptime: null,
+                memory_mb: null,
+                cpu_percent: null,
+                restarts: tasks[primaryTaskName]?.restarts ?? 0,
+            },
+        };
+    }
+    async function buildExternalAdoptedSpec(appId, spec) {
+        if (!resolveAppDir(appId)) {
+            return { adopted: false, conflicts: [], spec };
+        }
+        const conflicts = [];
+        let adopted = false;
+        const tasks = await Promise.all(spec.tasks.map(async (task) => {
+            if (task.runtime !== "process" || (task.role ?? "service") !== "service") {
+                return task;
+            }
+            const inspection = await inspectExternalProcessTask(appId, task);
+            if (inspection.conflict) {
+                if (inspection.conflictDetail) {
+                    conflicts.push(inspection.conflictDetail);
+                }
+                else {
+                    const ports = inspection.occupiedPorts.join(", ");
+                    const path = task.health?.http?.path ?? "/";
+                    conflicts.push(`Task "${task.name}" 端口 ${ports} 已被占用，但现有服务未通过健康检查 ${path}`);
+                }
+                return task;
+            }
+            if (!inspection.detected) {
+                return task;
+            }
+            adopted = true;
+            return {
+                ...task,
+                command: EXTERNAL_PROCESS_ADOPT_COMMAND,
+                args: [...EXTERNAL_PROCESS_ADOPT_ARGS],
+                env: {
+                    ...(task.env ?? {}),
+                    JISHUSHELL_EXTERNAL_ADOPTED: "1",
+                },
+            };
+        }));
+        return {
+            adopted,
+            conflicts,
+            spec: adopted ? { ...spec, tasks } : spec,
+        };
+    }
+    // ── Nomad task builders ───────────────────────────────────────────────────
+    /**
+     * Build a Nomad raw_exec task from an AppTask with runtime="process".
+     *
+     * raw_exec runs the command directly on the host as the specified user.
+     * Ports declared in task.ports are registered with Nomad for discovery
+     * but do NOT require network mapping (process binds the host port directly).
+     */
+    function buildRawExecTask(task, appId, extraEnv) {
+        const command = (task.command ?? task.binary)
+            ?.replace(/^~(?=\/|$)/, homedir());
+        if (!command)
+            throw new Error(`raw_exec task "${task.name}" must specify command`);
+        const args = (task.args ?? []).map(String);
+        const cpu = parseCpuMHz(task.resources?.cpu);
+        const mem = parseMemoryMB(task.resources?.memory);
+        const env = {
+            ...extraEnv,
+            ...interpolateEnvRequires(task.env ?? {}, extraEnv),
+        };
+        const lifecycle = roleToLifecycle(task.role ?? "service");
+        const taskDef = {
+            Name: task.name,
+            Driver: "raw_exec",
+            Config: {
+                command,
+                args,
+            },
+            Env: env,
+            Resources: {
+                CPU: cpu,
+                MemoryMB: mem,
+            },
+            LogConfig: { MaxFiles: 3, MaxFileSizeMB: 10 },
+        };
+        if (lifecycle)
+            taskDef.Lifecycle = lifecycle;
+        const svcCheck = buildServiceCheck(task, appId);
+        if (svcCheck)
+            taskDef.Services = [svcCheck];
+        return taskDef;
+    }
+    /**
+     * Build a Nomad docker task from an AppTask with runtime="container".
+     *
+     * Uses bridge network mode. Each declared port in task.ports is published
+     * from the host to the container.
+     */
+    function buildDockerTask(task, appId, extraEnv) {
+        const image = task.image;
+        if (!image)
+            throw new Error(`docker task "${task.name}" must specify image`);
+        if (!UnifiedNomadJobs.DOCKER_IMAGE_RE.test(image) || image.length > UnifiedNomadJobs.MAX_DOCKER_IMAGE_NAME_LEN) {
+            throw new Error(`docker task "${task.name}": invalid image name "${image}"`);
+        }
+        const args = (task.args ?? []).map(String);
+        const cpu = parseCpuMHz(task.resources?.cpu);
+        const mem = parseMemoryMB(task.resources?.memory);
+        const memMax = Math.min(mem, MAX_MEMORY_MAX_MB);
+        const env = {
+            ...extraEnv,
+            ...interpolateEnvRequires(task.env ?? {}, extraEnv),
+        };
+        // Only externally-visible ports get published to the host. Internal
+        // ports (e.g. SearXNG sidecar at 8080) stay inside the container /
+        // task-group network and are reached from peer tasks via 127.0.0.1.
+        const publishedPorts = (task.ports ?? [])
+            .filter((p) => (p.visibility ?? "external") !== "internal")
+            .map((p) => portLabel(task.name, p.name));
+        const lifecycle = roleToLifecycle(task.role ?? "service");
+        const volumes = (task.volumes ?? []).map((v) => {
+            if (typeof v === "string")
+                return v.replace(/^~(?=\/|$)/, homedir());
+            const src = v.source.replace(/^~(?=\/|$)/, homedir());
+            return `${src}:${v.target}${v.readonly ? ":ro" : ":rw"}`;
+        });
+        const taskDef = {
+            Name: task.name,
+            Driver: "docker",
+            Config: {
+                image,
+                force_pull: false,
+                ...(task.command ? { command: String(task.command) } : {}),
+                args,
+                ...(publishedPorts.length > 0 ? { ports: publishedPorts } : {}),
+                extra_hosts: ["host.docker.internal:host-gateway"],
+                cap_drop: ["ALL"],
+                security_opt: ["no-new-privileges"],
+                pids_limit: DEFAULT_PIDS_LIMIT,
+                readonly_rootfs: false,
+                ...(volumes.length > 0 ? { volumes } : {}),
+                mounts: [
+                    { type: "tmpfs", target: "/tmp", tmpfs_options: { size: 536_870_912 } },
+                    { type: "tmpfs", target: "/var/tmp", tmpfs_options: { size: 67_108_864 } },
+                ],
+            },
+            Env: env,
+            Resources: {
+                CPU: cpu,
+                MemoryMB: mem,
+                MemoryMaxMB: memMax,
+            },
+            LogConfig: { MaxFiles: 3, MaxFileSizeMB: 10 },
+        };
+        if (lifecycle)
+            taskDef.Lifecycle = lifecycle;
+        const svcCheck = buildServiceCheck(task, appId);
+        if (svcCheck)
+            taskDef.Services = [svcCheck];
+        return taskDef;
+    }
+    // ── Job builder ───────────────────────────────────────────────────────────
+    /**
+     * Build a complete Nomad job payload from an AppSpec.
+     *
+     * @param spec      The validated AppSpec.
+     * @param appId     A unique instance/run ID (used as job suffix).
+     * @param driver    "docker" | "raw_exec"
+     * @param extraEnv  Additional env vars injected into every task (e.g. capability addresses).
+     */
+    function buildAppJob(spec, appId, driver, extraEnv) {
+        const materializedSpec = materializeAppIdTokens(spec, appId);
+        const jid = jobId(appId);
+        assertSafeTemplateId(jid);
+        const tasks = materializedSpec.tasks.map((task) => {
+            const actualDriver = task.runtime === "container" ? "docker" : "raw_exec";
+            // Validate driver availability
+            if (actualDriver !== driver) {
+                // Allow mixed task runtimes — build each task with its own driver.
+                // Nomad supports heterogeneous drivers within one group.
+            }
+            if (task.runtime === "container") {
+                return buildDockerTask(task, appId, extraEnv);
+            }
+            else if (task.runtime === "process") {
+                return buildRawExecTask(task, appId, extraEnv);
+            }
+            else {
+                throw new Error(`Unsupported task runtime "${task.runtime}" for task "${task.name}"`);
+            }
+        });
+        const groupReservedPorts = materializedSpec.tasks.flatMap((task) => reservedPortsForTask(task));
+        const jobDef = {
+            Job: {
+                ID: jid,
+                Name: jid,
+                Namespace: "default",
+                Type: "service",
+                Datacenters: ["*"],
+                TaskGroups: [{
+                        Name: materializedSpec.id,
+                        Count: 1,
+                        ...(groupReservedPorts.length > 0
+                            ? { Networks: [{ ReservedPorts: groupReservedPorts }] }
+                            : {}),
+                        RestartPolicy: {
+                            Attempts: 3,
+                            Interval: 300_000_000_000,
+                            Delay: 15_000_000_000,
+                            Mode: "fail",
+                        },
+                        Reschedule: {
+                            Attempts: 0,
+                            Unlimited: false,
+                        },
+                        Update: {
+                            MaxParallel: 1,
+                            HealthCheck: "task_states",
+                            MinHealthyTime: 5_000_000_000,
+                            HealthyDeadline: 120_000_000_000,
+                            AutoRevert: false,
+                        },
+                        Tasks: tasks,
+                    }],
+            },
+        };
+        if (materializedSpec._engine) {
+            jobDef.Job = deepMerge(jobDef.Job, materializedSpec._engine.Job ?? materializedSpec._engine);
+        }
+        return jobDef;
+    }
+    // ── Alloc helpers ─────────────────────────────────────────────────────────
+    async function getAllocs(appId) {
+        const jid = jobId(appId);
+        try {
+            const resp = await nomadGet(`/v1/job/${jid}/allocations`);
+            if (resp.status === 404)
+                return [];
+            const allocs = await resp.json();
+            return allocs;
+        }
+        catch {
+            return [];
+        }
+    }
+    function pickLiveAlloc(allocs) {
+        for (const clientStatus of ["running", "pending"]) {
+            for (const alloc of allocs) {
+                if (alloc.ClientStatus === clientStatus)
+                    return alloc;
+            }
+        }
+        return null;
+    }
+    function pickLatestTerminalAlloc(allocs) {
+        const terminalAllocs = allocs
+            .filter((alloc) => alloc.ClientStatus !== "running" && alloc.ClientStatus !== "pending")
+            .sort((left, right) => allocTimestamp(right) - allocTimestamp(left));
+        return terminalAllocs[0] ?? null;
+    }
+    async function getAllocClientStatus(allocId) {
+        if (!/^[a-f0-9-]+$/i.test(allocId))
+            return null;
+        try {
+            const resp = await nomadGet(`/v1/allocation/${allocId}`);
+            if (resp.status === 404 || !resp.ok)
+                return null;
+            const alloc = await resp.json();
+            return typeof alloc?.ClientStatus === "string" ? alloc.ClientStatus : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async function waitForAllocationsToStop(allocIds, timeoutMs = 30_000, pollIntervalMs = 1_000) {
+        const pending = new Set(allocIds.filter((allocId) => /^[a-f0-9-]+$/i.test(allocId)));
+        if (pending.size === 0)
+            return true;
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            for (const allocId of [...pending]) {
+                const status = await getAllocClientStatus(allocId);
+                if (status == null || (status !== "running" && status !== "pending")) {
+                    pending.delete(allocId);
+                }
+            }
+            if (pending.size === 0)
+                return true;
+            await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+        }
+        return pending.size === 0;
+    }
+    async function getAllocChecks(allocId) {
+        try {
+            const resp = await nomadGet(`/v1/allocation/${allocId}/checks`);
+            if (resp.status === 404 || !resp.ok)
+                return [];
+            const checks = await resp.json();
+            return Object.values(checks ?? {});
+        }
+        catch {
+            return [];
+        }
+    }
+    function taskNameForAllocCheck(check, taskNames, appId) {
+        const checkName = String(check.Check ?? "");
+        for (const taskName of taskNames) {
+            if (checkName === `${taskName}-health` || checkName.startsWith(`${taskName}-`)) {
+                return taskName;
+            }
+        }
+        const serviceName = String(check.Service ?? "");
+        if (taskNames.includes(serviceName))
+            return serviceName;
+        const appTaskPrefix = `${appId}-`;
+        if (serviceName.startsWith(appTaskPrefix)) {
+            const candidate = serviceName.slice(appTaskPrefix.length);
+            if (taskNames.includes(candidate))
+                return candidate;
+        }
+        return null;
+    }
+    function aggregateHealthStatus(checks) {
+        const statuses = checks.map((check) => String(check.status ?? "unknown").toLowerCase());
+        if (statuses.length === 0)
+            return "unknown";
+        const healthy = new Set(["success", "passing", "healthy"]);
+        const unhealthy = new Set(["failure", "critical", "warning", "unhealthy"]);
+        if (statuses.every((status) => healthy.has(status)))
+            return "healthy";
+        if (statuses.some((status) => unhealthy.has(status)))
+            return "unhealthy";
+        if (statuses.some((status) => status === "pending" || status === "unknown" || status === "")) {
+            return "unknown";
+        }
+        return statuses[0];
+    }
+    async function getRunningAlloc(appId) {
+        return pickLiveAlloc(await getAllocs(appId));
+    }
+    // ── Public API ────────────────────────────────────────────────────────────
+    /**
+     * Returns true if this app job exists in Nomad and was NOT explicitly stopped.
+     * Used at JishuShell startup to auto-restart apps that were running before reboot.
+     */
+    async function shouldAutoStart(appId) {
+        const jid = jobId(appId);
+        try {
+            const resp = await nomadGet(`/v1/job/${jid}`);
+            if (!resp.ok || resp.status === 404)
+                return false;
+            const job = await resp.json();
+            return job.Stop === false && job.Status !== "dead";
+        }
+        catch {
+            return false;
+        }
+    }
+    UnifiedNomadJobs.shouldAutoStart = shouldAutoStart;
+    /**
+     * Get the aggregated status of an app job.
+     *
+     * @param appId       App instance ID.
+     * @param primaryTask Task name to use for uptime/restarts summary.
+     *                    Defaults to the first service task in the spec.
+     *                    If omitted, the first task state found is used.
+     */
+    async function getAppStatus(appId, primaryTask) {
+        const jid = jobId(appId);
+        const stopped = {
+            status: "stopped",
+            tasks: {},
+            pid: null,
+            uptime: null,
+            memory_mb: null,
+            cpu_percent: null,
+            restarts: 0,
+        };
+        try {
+            const resp = await nomadGet(`/v1/job/${jid}`);
+            if (resp.status === 404)
+                return stopped;
+            const job = await resp.json();
+            if (job.Stop)
+                return stopped;
+        }
+        catch {
+            return { ...stopped, status: "unknown", error: "Nomad unreachable" };
+        }
+        const allocs = await getAllocs(appId);
+        const alloc = pickLiveAlloc(allocs) ?? pickLatestTerminalAlloc(allocs);
+        // When Nomad has no allocation (e.g. raw_exec driver disabled), fall back to
+        // external process detection for process-runtime apps.
+        if (!alloc || alloc.ClientStatus === "pending") {
+            const ext = await inspectExternalProcessApp(appId);
+            if (ext.detected && ext.status)
+                return ext.status;
+            if (!alloc)
+                return { ...stopped, status: "pending" };
+        }
+        const allocId = alloc.ID;
+        const taskStates = alloc.TaskStates ?? {};
+        // Build per-task summary
+        const tasks = {};
+        for (const [name, state] of Object.entries(taskStates)) {
+            const s = state;
+            tasks[name] = {
+                state: s.State ?? "unknown",
+                restarts: s.Restarts ?? 0,
+                started_at: s.StartedAt ?? undefined,
+            };
+        }
+        const allocChecks = await getAllocChecks(allocId);
+        const taskNames = Object.keys(tasks);
+        for (const check of allocChecks) {
+            const taskName = taskNameForAllocCheck(check, taskNames, appId);
+            if (!taskName || !tasks[taskName])
+                continue;
+            tasks[taskName].health_checks ??= [];
+            tasks[taskName].health_checks.push({
+                name: String(check.Check ?? "health"),
+                status: String(check.Status ?? "unknown"),
+                ...(typeof check.Service === "string" ? { service: check.Service } : {}),
+                ...(typeof check.Output === "string" && check.Output ? { output: check.Output } : {}),
+            });
+        }
+        for (const task of Object.values(tasks)) {
+            if (task.health_checks?.length) {
+                task.health_status = aggregateHealthStatus(task.health_checks);
+            }
+        }
+        // Determine primary task for aggregated stats
+        const ptName = primaryTask ?? Object.keys(tasks)[0] ?? "";
+        const pt = tasks[ptName] ?? {};
+        const result = {
+            status: alloc.ClientStatus ?? "unknown",
+            alloc_id: allocId,
+            tasks,
+            pid: null,
+            uptime: null,
+            memory_mb: null,
+            cpu_percent: null,
+            restarts: pt.restarts ?? 0,
+        };
+        // Uptime from primary task's StartedAt
+        if (pt.started_at) {
+            try {
+                result.uptime = Math.floor((Date.now() - new Date(pt.started_at).getTime()) / 1000);
+            }
+            catch { /* ignore */ }
+        }
+        // Resource stats from Nomad alloc stats API
+        try {
+            const statsResp = await nomadGet(`/v1/client/allocation/${allocId}/stats`);
+            if (statsResp.ok) {
+                const stats = await statsResp.json();
+                // raw_exec: stats nested under Tasks.<name>; docker: top-level ResourceUsage
+                const taskStats = (ptName ? stats.Tasks?.[ptName]?.ResourceUsage : null) ??
+                    stats.ResourceUsage ??
+                    {};
+                const memStats = taskStats.MemoryStats ?? {};
+                const cpuStats = taskStats.CpuStats ?? {};
+                const memBytes = memStats.RSS ?? memStats.Usage ?? 0;
+                result.memory_mb = Math.round((memBytes / (1024 * 1024)) * 10) / 10;
+                result.cpu_percent = Math.round((cpuStats.Percent ?? 0) * 10) / 10;
+            }
+        }
+        catch { /* ignore */ }
+        // Fallback: use `docker stats` when Nomad cgroup stats are zero (cgroup v2 / Pi).
+        // Only applicable for docker-driver tasks.
+        if (!result.memory_mb && allocId && ptName) {
+            try {
+                if (!/^[a-f0-9-]+$/i.test(allocId))
+                    throw new Error("invalid allocId");
+                const containerName = `${ptName}-${allocId}`;
+                const execFileAsync = promisify(execFileCb);
+                const { stdout } = await execFileAsync("docker", ["stats", "--no-stream", "--format", "{{.MemUsage}}", containerName], { timeout: 5_000 });
+                const raw = stdout.trim();
+                const match = raw.match(/^([\d.]+)\s*(MiB|GiB|MB|GB|KiB|KB)/i);
+                if (match) {
+                    let mb = parseFloat(match[1]);
+                    const unit = match[2].toLowerCase();
+                    if (unit === "gib" || unit === "gb")
+                        mb *= 1024;
+                    else if (unit === "kib" || unit === "kb")
+                        mb /= 1024;
+                    result.memory_mb = Math.round(mb * 10) / 10;
+                }
+            }
+            catch { /* ignore */ }
+        }
+        return result;
+    }
+    UnifiedNomadJobs.getAppStatus = getAppStatus;
+    // ── Driver health check + auto-restart ────────────────────────────────────
+    /**
+     * Check whether a Nomad task driver is healthy on the local node.
+     * Returns true if the driver is both detected and healthy.
+     */
+    async function isNomadDriverHealthy(driverName) {
+        try {
+            const nodesResp = await nomadGet("/v1/nodes");
+            if (!nodesResp.ok)
+                return true; // assume healthy if we can't check
+            const nodes = await nodesResp.json();
+            if (nodes.length === 0)
+                return true;
+            const nodeId = nodes[0]?.ID;
+            if (!nodeId)
+                return true;
+            const nodeResp = await nomadGet(`/v1/node/${nodeId}`);
+            if (!nodeResp.ok)
+                return true;
+            const node = await nodeResp.json();
+            const driver = node.Drivers?.[driverName];
+            if (!driver)
+                return false;
+            return driver.Detected === true && driver.Healthy === true;
+        }
+        catch {
+            return true; // don't block on transient errors
+        }
+    }
+    /**
+     * If the required Nomad driver is not healthy, restart Nomad so it picks up
+     * the current config (e.g. raw_exec enabled = true). Driver plugin changes
+     * require a full Nomad agent restart — SIGHUP / reload API are insufficient.
+     *
+     * Returns true if the driver is healthy (possibly after restart), false if it
+     * could not be made healthy.
+     */
+    async function ensureNomadDriverHealthy(driverName) {
+        if (await isNomadDriverHealthy(driverName))
+            return true;
+        console.warn(`[nomad] Driver "${driverName}" is not healthy — restarting Nomad to apply config…`);
+        try {
+            const { stopNomad, startNomad } = await import("./setup-manager.js");
+            const stopResult = await stopNomad();
+            if (!stopResult.ok) {
+                console.warn(`[nomad] Nomad stop failed: ${stopResult.error}`);
+            }
+            const startResult = await startNomad();
+            if (!startResult.ok) {
+                console.warn(`[nomad] Nomad start failed: ${startResult.error}`);
+                return false;
+            }
+            // Wait up to 15s for the driver to become healthy after restart
+            for (let i = 0; i < 15; i++) {
+                await new Promise((r) => setTimeout(r, 1_000));
+                if (await isNomadDriverHealthy(driverName))
+                    return true;
+            }
+            console.warn(`[nomad] Driver "${driverName}" still unhealthy after Nomad restart`);
+            return false;
+        }
+        catch (e) {
+            console.warn(`[nomad] Failed to restart Nomad: ${e.message}`);
+            return false;
+        }
+    }
+    /**
+     * Submit a Nomad job for an app.
+     *
+     * @param spec     Validated AppSpec.
+     * @param appId    Unique instance ID (job name suffix).
+     * @param extraEnv Env vars injected into every task (e.g. resolved capability addresses).
+     */
+    async function startAppJob(spec, appId, extraEnv = {}) {
+        const status = await getAppStatus(appId);
+        if (status.status === "running") {
+            // Already running is a success state — no need to resubmit.
+            return { ok: true };
+        }
+        const adoptedExternal = await buildExternalAdoptedSpec(appId, spec);
+        if (adoptedExternal.conflicts.length > 0) {
+            return { ok: false, error: adoptedExternal.conflicts.join("; ") };
+        }
+        const effectiveSpec = adoptedExternal.spec;
+        // Validate all images before submitting
+        for (const task of effectiveSpec.tasks) {
+            if (task.runtime === "container") {
+                if (!task.image || !UnifiedNomadJobs.DOCKER_IMAGE_RE.test(task.image) || task.image.length > UnifiedNomadJobs.MAX_DOCKER_IMAGE_NAME_LEN) {
+                    return { ok: false, error: `Task "${task.name}": invalid docker image "${task.image ?? ""}"` };
+                }
+            }
+        }
+        // Determine predominant driver (first service task wins)
+        const primaryTask = effectiveSpec.tasks.find((t) => (t.role ?? "service") === "service") ?? effectiveSpec.tasks[0];
+        const driver = primaryTask?.runtime === "container" ? "docker" : "raw_exec";
+        // Ensure the required Nomad driver is healthy; restart Nomad if needed.
+        const driverOk = await ensureNomadDriverHealthy(driver);
+        if (!driverOk) {
+            if (driver === "raw_exec") {
+                const rawExecError = await validateRawExecDriverAvailability();
+                if (rawExecError) {
+                    return { ok: false, error: rawExecError };
+                }
+            }
+            return { ok: false, error: `Nomad driver "${driver}" is not available. Check Nomad configuration and restart Nomad.` };
+        }
+        const hostNetworkError = await validateRequiredHostNetworks(effectiveSpec);
+        if (hostNetworkError) {
+            return { ok: false, error: hostNetworkError };
+        }
+        let jobDef;
+        try {
+            jobDef = buildAppJob(effectiveSpec, appId, driver, extraEnv);
+        }
+        catch (e) {
+            return { ok: false, error: `Job build failed: ${e.message}` };
+        }
+        try {
+            const resp = await nomadPost("/v1/jobs", jobDef);
+            if (resp.ok) {
+                const data = await resp.json();
+                return { ok: true, eval_id: data.EvalID };
+            }
+            const text = await resp.text();
+            return { ok: false, error: text };
+        }
+        catch (e) {
+            const isNetErr = e?.message === "fetch failed" || e?.cause?.code === "ECONNREFUSED";
+            return {
+                ok: false,
+                error: isNetErr
+                    ? `Nomad 服务不可达 (${getNomadAddr()})，请先启动 Nomad`
+                    : e.message,
+            };
+        }
+    }
+    UnifiedNomadJobs.startAppJob = startAppJob;
+    /**
+     * Poll until the app job reaches "running" status or times out.
+     * Returns true if the job is running, false if timed out.
+     */
+    async function waitForRunning(appId, timeoutMs = 120_000, pollIntervalMs = 3_000) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const status = await getAppStatus(appId);
+            if (status.status === "running")
+                return true;
+            if (status.status === "dead" || status.status === "failed")
+                return false;
+            await new Promise((r) => setTimeout(r, pollIntervalMs));
+        }
+        return false;
+    }
+    UnifiedNomadJobs.waitForRunning = waitForRunning;
+    async function checkDependencies(spec) {
+        if (!spec.depends_on || Object.keys(spec.depends_on).length === 0) {
+            return { ok: true, errors: [] };
+        }
+        const errors = [];
+        for (const [depId, dep] of Object.entries(spec.depends_on)) {
+            const status = await getAppStatus(depId);
+            const condition = dep.condition ?? "started";
+            const required = dep.required !== false;
+            let satisfied = false;
+            if (condition === "started") {
+                satisfied = status.status !== "stopped" && status.status !== "unknown";
+            }
+            else if (condition === "healthy") {
+                satisfied = status.status === "running";
+            }
+            else if (condition === "completed") {
+                satisfied = status.status === "dead";
+            }
+            if (!satisfied) {
+                const msg = `Dependency "${depId}" not satisfied (need: ${condition}, got: ${status.status})`;
+                if (required) {
+                    errors.push(msg);
+                }
+                else {
+                    console.warn(`  [depends_on] ${msg} (optional, continuing)`);
+                }
+            }
+        }
+        return { ok: errors.length === 0, errors };
+    }
+    UnifiedNomadJobs.checkDependencies = checkDependencies;
+    /**
+     * Stop (and optionally purge) a Nomad app job.
+     */
+    async function stopAppJob(appId, purge = false) {
+        const jid = jobId(appId);
+        const liveAllocIds = (await getAllocs(appId))
+            .filter((alloc) => alloc?.ID && (alloc.ClientStatus === "running" || alloc.ClientStatus === "pending"))
+            .map((alloc) => String(alloc.ID));
+        let nomadStopped = false;
+        let appMissing = false;
+        let nomadError;
+        try {
+            const resp = await nomadDelete(`/v1/job/${jid}?purge=${purge}`);
+            nomadStopped = resp.ok;
+            appMissing = resp.status === 404;
+            if (!resp.ok && !appMissing) {
+                nomadError = await resp.text();
+            }
+        }
+        catch (e) {
+            const isNetErr = e?.message === "fetch failed" || e?.cause?.code === "ECONNREFUSED";
+            nomadError = isNetErr
+                ? `Nomad 服务不可达 (${getNomadAddr()})，请先启动 Nomad`
+                : e.message;
+        }
+        const externalStop = await stopExternalProcessApp(appId);
+        if (!externalStop.ok) {
+            return {
+                ok: false,
+                error: nomadError ? `${nomadError}; ${externalStop.error}` : externalStop.error,
+            };
+        }
+        if (nomadStopped) {
+            const allocsStopped = await waitForAllocationsToStop(liveAllocIds);
+            if (!allocsStopped) {
+                return { ok: false, error: `App '${appId}' allocations did not stop in time` };
+            }
+            return { ok: true };
+        }
+        if (nomadError)
+            return { ok: false, error: nomadError };
+        if (appMissing) {
+            return externalStop.detected ? { ok: true } : { ok: false, error: "App is not running" };
+        }
+        return { ok: true };
+    }
+    UnifiedNomadJobs.stopAppJob = stopAppJob;
+    /**
+     * Restart a running app job.
+     * Prefers native Nomad allocation restart to preserve alloc history.
+     * Falls back to stop + re-submit when no AppSpec is available for re-submit.
+     *
+     * @param appId       App instance ID.
+     * @param primaryTask Task name to restart. Defaults to the first task.
+     */
+    async function restartAppJob(appId, primaryTask) {
+        const alloc = await getRunningAlloc(appId);
+        if (alloc) {
+            try {
+                // Native Nomad allocation restart — preserves alloc history.
+                const resp = await nomadPut(`/v1/client/allocation/${alloc.ID}/restart`, {
+                    TaskName: primaryTask ?? "",
+                    AllTasks: !primaryTask,
+                });
+                if (resp.ok)
+                    return { ok: true, alloc_id: alloc.ID };
+                const errText = await resp.text();
+                console.warn(`[nomad] Native restart failed for app ${appId} (HTTP ${resp.status}): ${errText}` +
+                    " — falling back to stop+start");
+            }
+            catch (e) {
+                console.warn(`[nomad] Native restart error for app ${appId}: ${e.message}` +
+                    " — falling back to stop+start");
+            }
+        }
+        // Fallback: stop then re-start. Caller must re-call startAppJob with spec.
+        // This path is intentionally not self-contained because we don't cache the
+        // AppSpec here — app-manager owns the spec and should call startAppJob.
+        const stopResult = await stopAppJob(appId);
+        if (!stopResult.ok && stopResult.error !== "App is not running") {
+            return stopResult;
+        }
+        return { ok: false, error: "restart_requires_resubmit" };
+    }
+    UnifiedNomadJobs.restartAppJob = restartAppJob;
+    /**
+     * Fetch recent log lines for a task in an app job.
+     *
+     * @param appId    App instance ID.
+     * @param taskName Nomad task name (task.name from AppSpec).
+     * @param lines    Number of lines to return (default 200).
+     * @param logType  "stdout" | "stderr" (default "stderr").
+     */
+    async function getAppLogs(appId, taskName = "", lines = 200, logType = "stderr") {
+        if (!UnifiedNomadJobs.VALID_LOG_TYPES.has(logType))
+            logType = "stderr";
+        let alloc = await getRunningAlloc(appId);
+        // If no running alloc, try the most recent alloc (for post-mortem logs).
+        if (!alloc) {
+            const jid = jobId(appId);
+            try {
+                const resp = await nomadGet(`/v1/job/${jid}/allocations`);
+                if (resp.ok) {
+                    const allocs = await resp.json();
+                    if (allocs.length) {
+                        alloc = allocs.sort((a, b) => (b.CreateIndex ?? 0) - (a.CreateIndex ?? 0))[0];
+                    }
+                }
+            }
+            catch { /* ignore */ }
+        }
+        if (!alloc)
+            return [];
+        const resolvedTask = taskName || (Object.keys(alloc.TaskStates ?? {})[0] ?? "");
+        if (!resolvedTask)
+            return [];
+        // Primary: Nomad log API (works for both docker and raw_exec).
+        try {
+            const params = new URLSearchParams({
+                task: resolvedTask,
+                type: logType,
+                plain: "true",
+                origin: "end",
+                offset: String(Math.max(lines * 512, 100_000)),
+                follow: "false",
+            });
+            const resp = await nomadGet(`/v1/client/fs/logs/${alloc.ID}?${params}`);
+            if (resp.ok) {
+                const text = await resp.text();
+                const trimmed = text.trim();
+                if (trimmed)
+                    return trimmed.split("\n").slice(-lines);
+            }
+        }
+        catch { /* ignore */ }
+        if (!/^[a-f0-9-]+$/i.test(alloc.ID))
+            return [];
+        const dockerLogLines = await readDockerStreamLogs(`${resolvedTask}-${alloc.ID}`, lines, logType);
+        if (dockerLogLines.length > 0)
+            return dockerLogLines;
+        return [];
+    }
+    UnifiedNomadJobs.getAppLogs = getAppLogs;
+    // ── Nomad WebSocket exec ─────────────────────────────────────────────────
+    /**
+     * Execute a command inside a running task via Nomad's WebSocket exec API.
+     * Works for both `docker` and `raw_exec` tasks — Nomad proxies the exec
+     * through the allocation without requiring direct Docker socket access.
+     *
+     * Protocol (https://developer.hashicorp.com/nomad/api-docs/client#stream-file):
+     *   - Upgrade:  GET /v1/client/allocation/{id}/exec  → 101 Switching Protocols
+     *   - Send stdin frames:  {"stdin":{"data":"<base64>"}}
+     *   - Close stdin:        {"stdin":{"close":true}}
+     *   - Recv stdout frames: {"stdout":{"data":"<base64>"}}
+     *   - Recv stderr frames: {"stderr":{"data":"<base64>"}}
+     *   - Recv exit frame:    {"exited":true,"result":{"exit_code":0}}
+     *
+     * Authentication: Nomad token is passed as a query parameter because the
+     * native WebSocket API (Node.js ≥21) does not support custom headers.
+     *
+     * @param allocId   Nomad allocation UUID.
+     * @param taskName  Task name within the allocation.
+     * @param command   Command + args array.
+     * @param stdin     Optional stdin data to pipe in.
+     * @param timeoutMs Execution timeout in ms (default 120 s).
+     */
+    async function nomadWsExec(allocId, taskName, command, stdin, timeoutMs = 120_000) {
+        return nomadWsExecStream(allocId, taskName, command, stdin, {}, timeoutMs);
+    }
+    function emitStreamChunk(handler, decoder, data) {
+        const chunk = typeof data === "string" ? data : decoder.write(data);
+        if (chunk)
+            handler?.(chunk);
+        return chunk;
+    }
+    function flushStreamChunk(handler, decoder) {
+        const chunk = decoder.end();
+        if (chunk)
+            handler?.(chunk);
+        return chunk;
+    }
+    async function streamSpawnedExec(file, args, handlers, timeoutMs, options) {
+        return new Promise((resolve) => {
+            const stdoutDecoder = new StringDecoder("utf8");
+            const stderrDecoder = new StringDecoder("utf8");
+            let stdoutBuf = "";
+            let stderrBuf = "";
+            let settled = false;
+            const settle = (exitCode) => {
+                if (settled)
+                    return;
+                settled = true;
+                stdoutBuf += flushStreamChunk(handlers.onStdout, stdoutDecoder);
+                stderrBuf += flushStreamChunk(handlers.onStderr, stderrDecoder);
+                resolve({ stdout: stdoutBuf, stderr: stderrBuf, exitCode });
+            };
+            const child = spawn(file, args, {
+                ...options,
+                stdio: ["ignore", "pipe", "pipe"],
+                timeout: timeoutMs,
+            });
+            child.stdout?.on("data", (data) => {
+                stdoutBuf += emitStreamChunk(handlers.onStdout, stdoutDecoder, data);
+            });
+            child.stderr?.on("data", (data) => {
+                stderrBuf += emitStreamChunk(handlers.onStderr, stderrDecoder, data);
+            });
+            child.on("error", (error) => {
+                const message = error.message || String(error);
+                stderrBuf += message;
+                handlers.onStderr?.(message);
+                settle(error.code === "ENOENT" ? 127 : 1);
+            });
+            child.on("close", (code) => {
+                settle(code ?? 1);
+            });
+        });
+    }
+    async function nomadWsExecStream(allocId, taskName, command, stdin, handlers, timeoutMs = 120_000) {
+        const nomadAddr = getNomadAddr();
+        // Convert http(s) → ws(s) for the WebSocket URL.
+        const wsBase = nomadAddr.replace(/^http/, "ws");
+        const params = new URLSearchParams({
+            task: taskName,
+            command: JSON.stringify(command),
+            tty: "false",
+        });
+        // Native WebSocket does not support custom request headers;
+        // Nomad also accepts the token as a query parameter.
+        const token = getNomadToken();
+        if (token)
+            params.set("token", token);
+        const url = `${wsBase}/v1/client/allocation/${allocId}/exec?${params}`;
+        return new Promise((resolve, reject) => {
+            // Node.js ≥21 ships a global WebSocket; engines field requires ≥22.
+            const ws = new WebSocket(url);
+            let stdoutBuf = "";
+            let stderrBuf = "";
+            let exitCode = 1;
+            let settled = false;
+            const settle = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                ws.close();
+                resolve(result);
+            };
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                ws.close();
+                reject(new Error(`nomad exec timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            ws.onopen = () => {
+                if (stdin) {
+                    ws.send(JSON.stringify({
+                        stdin: { data: Buffer.from(stdin, "utf-8").toString("base64") },
+                    }));
+                }
+                // Always close stdin so the remote process sees EOF.
+                ws.send(JSON.stringify({ stdin: { close: true } }));
+            };
+            ws.onmessage = (event) => {
+                try {
+                    const msg = JSON.parse(event.data);
+                    if (msg.stdout?.data) {
+                        const chunk = Buffer.from(msg.stdout.data, "base64").toString("utf-8");
+                        stdoutBuf += chunk;
+                        if (chunk)
+                            handlers.onStdout?.(chunk);
+                    }
+                    if (msg.stderr?.data) {
+                        const chunk = Buffer.from(msg.stderr.data, "base64").toString("utf-8");
+                        stderrBuf += chunk;
+                        if (chunk)
+                            handlers.onStderr?.(chunk);
+                    }
+                    if (msg.exited === true) {
+                        exitCode = msg.result?.exit_code ?? 1;
+                        settle({ stdout: stdoutBuf, stderr: stderrBuf, exitCode });
+                    }
+                }
+                catch { /* ignore malformed frames */ }
+            };
+            ws.onerror = (event) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                // ErrorEvent has a .message; plain Event does not.
+                const msg = event.message ?? "WebSocket error";
+                reject(new Error(`[nomad-ws-exec] ${msg}`));
+            };
+            ws.onclose = () => {
+                // Connection dropped before we received the exited frame.
+                // Resolve with whatever we collected so the caller sees partial output.
+                settle({ stdout: stdoutBuf, stderr: stderrBuf, exitCode });
+            };
+        });
+    }
+    /**
+     * Execute a command inside a running app task.
+     *
+     * Strategy:
+     *   1. Try `docker exec` (fast path for docker-driver tasks, no Nomad dependency).
+     *   2. If the container is not found, fall back to the Nomad WebSocket exec API
+     *      which works for both `docker` and `raw_exec` tasks.
+     *
+     * @param appId     App instance ID.
+     * @param taskName  Task name from AppSpec.
+     * @param command   Command + args array.
+     * @param timeoutMs Execution timeout in ms (default 120 s).
+     */
+    async function execInApp(appId, taskName = "", command, timeoutMs = 120_000) {
+        const alloc = await getRunningAlloc(appId);
+        if (!alloc || alloc.ClientStatus !== "running") {
+            throw new Error("App is not running");
+        }
+        const allocId = alloc.ID;
+        if (!/^[a-f0-9-]+$/i.test(allocId))
+            throw new Error("invalid allocId");
+        const resolvedTask = taskName || (Object.keys(alloc.TaskStates ?? {})[0] ?? "");
+        if (!resolvedTask)
+            throw new Error("No task found in alloc");
+        const taskState = alloc.TaskStates?.[resolvedTask];
+        if (!taskState)
+            throw new Error(`Task "${resolvedTask}" not found in alloc`);
+        // For process (raw_exec) apps, execute directly on the host — no container
+        // or Nomad WebSocket overhead needed since the binary runs natively.
+        const { getApp } = await import("./app/app-manager.js");
+        const appData = getApp(appId);
+        const matchedTask = appData?.spec.tasks.find((t) => t.name === resolvedTask);
+        if (matchedTask?.runtime === "process") {
+            const execFileAsync = promisify(execFileCb);
+            try {
+                const { stdout, stderr } = await execFileAsync(command[0], command.slice(1), {
+                    timeout: timeoutMs,
+                    env: { ...process.env, ...matchedTask.env },
+                });
+                return { stdout, stderr, exitCode: 0 };
+            }
+            catch (e) {
+                return {
+                    stdout: e.stdout ?? "",
+                    stderr: e.stderr ?? e.message,
+                    exitCode: e.code ?? 1,
+                };
+            }
+        }
+        // Fast path: docker exec (avoids WebSocket overhead for container tasks).
+        const execFileAsync = promisify(execFileCb);
+        const containerName = `${resolvedTask}-${allocId}`;
+        try {
+            const { stdout, stderr } = await execFileAsync("docker", ["exec", containerName, ...command], { timeout: timeoutMs });
+            return { stdout, stderr, exitCode: 0 };
+        }
+        catch (e) {
+            const notFound = e?.stderr?.includes("No such container") ||
+                e?.message?.includes("No such container") ||
+                e?.code === 125; // docker CLI: container not found exit code
+            if (!notFound) {
+                // docker exec was found but the command itself failed — real error.
+                return {
+                    stdout: e.stdout ?? "",
+                    stderr: e.stderr ?? e.message,
+                    exitCode: e.code ?? 1,
+                };
+            }
+            // Container not found → likely raw_exec; fall through to Nomad WS exec.
+            console.log(`[nomad] execInApp: container "${containerName}" not found, ` +
+                `falling back to Nomad WebSocket exec for task "${resolvedTask}"`);
+        }
+        // Nomad WebSocket exec — works for raw_exec and docker without docker socket.
+        return nomadWsExec(allocId, resolvedTask, command, undefined, timeoutMs);
+    }
+    UnifiedNomadJobs.execInApp = execInApp;
+    async function streamExecInApp(appId, taskName = "", command, handlers = {}, timeoutMs = 120_000) {
+        const alloc = await getRunningAlloc(appId);
+        if (!alloc || alloc.ClientStatus !== "running") {
+            throw new Error("App is not running");
+        }
+        const allocId = alloc.ID;
+        if (!/^[a-f0-9-]+$/i.test(allocId))
+            throw new Error("invalid allocId");
+        const resolvedTask = taskName || (Object.keys(alloc.TaskStates ?? {})[0] ?? "");
+        if (!resolvedTask)
+            throw new Error("No task found in alloc");
+        const taskState = alloc.TaskStates?.[resolvedTask];
+        if (!taskState)
+            throw new Error(`Task "${resolvedTask}" not found in alloc`);
+        const { getApp } = await import("./app/app-manager.js");
+        const appData = getApp(appId);
+        const matchedTask = appData?.spec.tasks.find((task) => task.name === resolvedTask);
+        if (matchedTask?.runtime === "process") {
+            return streamSpawnedExec(command[0], command.slice(1), handlers, timeoutMs, { env: { ...process.env, ...matchedTask.env } });
+        }
+        const containerName = `${resolvedTask}-${allocId}`;
+        const dockerResult = await streamSpawnedExec("docker", ["exec", containerName, ...command], handlers, timeoutMs);
+        const notFound = dockerResult.stderr.includes("No such container") ||
+            dockerResult.exitCode === 125;
+        if (!notFound) {
+            return dockerResult;
+        }
+        console.log(`[nomad] streamExecInApp: container "${containerName}" not found, ` +
+            `falling back to Nomad WebSocket exec for task "${resolvedTask}"`);
+        return nomadWsExecStream(allocId, resolvedTask, command, undefined, handlers, timeoutMs);
+    }
+    UnifiedNomadJobs.streamExecInApp = streamExecInApp;
+    async function listInstanceIds() {
+        try {
+            const resp = await nomadGet("/v1/jobs");
+            if (!resp.ok)
+                return [];
+            const jobs = await resp.json();
+            return [...new Set(jobs.map((job) => readInstanceMeta(job.ID)?.id || job.ID))];
+        }
+        catch {
+            return [];
+        }
+    }
+    UnifiedNomadJobs.listInstanceIds = listInstanceIds;
+    function readInstanceMeta(nomadJobId) {
+        const directMetaPath = instanceMetaPath(nomadJobId);
+        try {
+            if (existsSync(directMetaPath))
+                return JSON.parse(readFileSync(directMetaPath, "utf-8"));
+        }
+        catch { }
+        if (nomadJobId.startsWith(OPENCLAW_PREFIX)) {
+            const id = nomadJobId.slice(OPENCLAW_PREFIX.length);
+            const metaPath = instanceMetaPath(id);
+            try {
+                if (existsSync(metaPath))
+                    return JSON.parse(readFileSync(metaPath, "utf-8"));
+            }
+            catch { }
+            return null;
+        }
+        if (isAppJob(nomadJobId)) {
+            const appDir = resolveAppDir(nomadJobId);
+            if (!appDir)
+                return null;
+            const manifestPath = join(appDir, "manifest.json");
+            const yamlPath = join(appDir, "app-spec.yaml");
+            try {
+                const manifest = existsSync(manifestPath)
+                    ? JSON.parse(readFileSync(manifestPath, "utf-8"))
+                    : {};
+                if (existsSync(yamlPath)) {
+                    const m = readFileSync(yamlPath, "utf-8").match(/^name:\s*(.+)$/m);
+                    if (m)
+                        return { ...manifest, name: m[1].trim().replace(/^['"]|['"]$/g, "") };
+                }
+                return Object.keys(manifest).length > 0 ? manifest : null;
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+    UnifiedNomadJobs.readInstanceMeta = readInstanceMeta;
+    async function resolveInstanceId(id) {
+        const ids = await listInstanceIds();
+        if (ids.length === 0)
+            throw new Error("No instances found.");
+        if (id) {
+            if (existsSync(instanceMetaPath(id))) {
+                return id;
+            }
+            if (!ids.includes(id)) {
+                throw new Error(`Instance "${id}" not found. Available: ${ids.join(", ")}`);
+            }
+            return id;
+        }
+        if (ids.length === 1)
+            return ids[0];
+        throw new Error(`Multiple instances exist. Specify an ID. Available: ${ids.join(", ")}`);
+    }
+    UnifiedNomadJobs.resolveInstanceId = resolveInstanceId;
+    async function resolveInstanceForPairing(instanceId) {
+        const ids = await listInstanceIds();
+        if (ids.length === 0)
+            throw new Error("No instances found.");
+        if (instanceId) {
+            if (existsSync(instanceMetaPath(instanceId)))
+                return instanceId;
+            if (!ids.includes(instanceId))
+                throw new Error(`Instance "${instanceId}" not found.`);
+            return instanceId;
+        }
+        if (ids.length === 1)
+            return ids[0];
+        const runningIds = [];
+        for (const id of ids) {
+            try {
+                const st = await getInstanceStatus(id);
+                if (st.status === "running")
+                    runningIds.push(id);
+            }
+            catch { }
+        }
+        if (runningIds.length === 1)
+            return runningIds[0];
+        if (runningIds.length === 0)
+            throw new Error("No running instances found. Start an instance first.");
+        throw new Error(`Multiple running instances: ${runningIds.join(", ")}. Use --instance <id>.`);
+    }
+    UnifiedNomadJobs.resolveInstanceForPairing = resolveInstanceForPairing;
+    function ensureNomadToken() {
+        if (process.env.NOMAD_TOKEN)
+            return;
+        const candidates = [
+            join(homedir(), ".jishushell", "nomad.env"),
+            "/etc/jishushell/nomad.env",
+        ];
+        for (const f of candidates) {
+            if (!existsSync(f))
+                continue;
+            try {
+                const match = readFileSync(f, "utf-8").match(/^NOMAD_TOKEN=(.+)$/m);
+                if (match) {
+                    process.env.NOMAD_TOKEN = match[1].trim();
+                    return;
+                }
+            }
+            catch { }
+        }
+        const legacy = getPanelConfig().nomad_token;
+        if (legacy)
+            process.env.NOMAD_TOKEN = legacy;
+    }
+    UnifiedNomadJobs.ensureNomadToken = ensureNomadToken;
+    async function getGenericJobStatus(jobId) {
+        const stopped = { status: "stopped", pid: null, uptime: null, memory_mb: null, cpu_percent: null };
+        try {
+            const resp = await nomadGet(`/v1/job/${jobId}`);
+            if (!resp.ok)
+                return stopped;
+            const job = await resp.json();
+            if (job.Stop)
+                return stopped;
+            const allocResp = await nomadGet(`/v1/job/${jobId}/allocations`);
+            if (!allocResp.ok)
+                return { ...stopped, status: "unknown" };
+            const allocs = await allocResp.json();
+            if (!allocs.length)
+                return { ...stopped, status: "pending" };
+            const sorted = [...allocs].sort((a, b) => (b.CreateIndex ?? 0) - (a.CreateIndex ?? 0));
+            const running = sorted.find(a => a.ClientStatus === "running") ?? sorted[0];
+            return { ...stopped, status: running.ClientStatus ?? "unknown" };
+        }
+        catch {
+            return { ...stopped, status: "unknown" };
+        }
+    }
+    async function getInstanceStatus(nomadJobId) {
+        if (await getInstanceBackedInstalledApp(nomadJobId)) {
+            const st = await getAppStatus(nomadJobId);
+            return {
+                status: st.status,
+                pid: st.pid,
+                uptime: st.uptime,
+                memory_mb: st.memory_mb,
+                cpu_percent: st.cpu_percent,
+            };
+        }
+        if (isAppJob(nomadJobId)) {
+            const st = await getAppStatus(nomadJobId);
+            return {
+                status: st.status,
+                pid: st.pid,
+                uptime: st.uptime,
+                memory_mb: st.memory_mb,
+                cpu_percent: st.cpu_percent,
+            };
+        }
+        if (existsSync(instanceMetaPath(nomadJobId))) {
+            return instanceScheduler.getStatus(nomadJobId);
+        }
+        if (nomadJobId.startsWith(OPENCLAW_PREFIX)) {
+            return instanceScheduler.getStatus(nomadJobId.slice(OPENCLAW_PREFIX.length));
+        }
+        return getGenericJobStatus(nomadJobId);
+    }
+    UnifiedNomadJobs.getInstanceStatus = getInstanceStatus;
+    async function startInstance(nomadJobId) {
+        const instanceBackedApp = await getInstanceBackedInstalledApp(nomadJobId);
+        if (instanceBackedApp) {
+            let extraEnv = {};
+            try {
+                const { resolveRequires } = await import("./app/app-manager.js");
+                extraEnv = resolveRequires(instanceBackedApp.spec);
+            }
+            catch (e) {
+                return { ok: false, error: e.message };
+            }
+            const depCheck = await checkDependencies(instanceBackedApp.spec);
+            if (!depCheck.ok) {
+                return { ok: false, error: depCheck.errors.join("; ") };
+            }
+            const result = await startAppJob(instanceBackedApp.spec, nomadJobId, extraEnv);
+            if (!result.ok)
+                return result;
+            const { registerCapabilities, runPostStartSteps } = await import("./app/app-manager.js");
+            if (instanceBackedApp.spec.provides?.length) {
+                registerCapabilities(nomadJobId, instanceBackedApp.spec);
+            }
+            if (instanceBackedApp.spec.lifecycle?.post_start?.length) {
+                const running = await waitForRunning(nomadJobId);
+                if (running) {
+                    await runPostStartSteps(instanceBackedApp.spec);
+                }
+            }
+            return result;
+        }
+        if (isAppJob(nomadJobId)) {
+            return { ok: false, error: `App '${nomadJobId}' 必须通过 app-manager 启动` };
+        }
+        if (existsSync(instanceMetaPath(nomadJobId))) {
+            return instanceScheduler.startInstance(nomadJobId);
+        }
+        if (nomadJobId.startsWith(OPENCLAW_PREFIX)) {
+            return instanceScheduler.startInstance(nomadJobId.slice(OPENCLAW_PREFIX.length));
+        }
+        if (!isAppJob(nomadJobId)) {
+            return { ok: false, error: `Cannot start unmanaged job "${nomadJobId}"` };
+        }
+        return { ok: false, error: `Cannot start unmanaged job "${nomadJobId}"` };
+    }
+    UnifiedNomadJobs.startInstance = startInstance;
+    async function stopInstance(nomadJobId, purge = false) {
+        if (await getInstanceBackedInstalledApp(nomadJobId)) {
+            const result = await stopAppJob(nomadJobId, purge);
+            if (result.ok || result.error?.includes("not running") || result.error?.includes("not found")) {
+                const { unregisterCapabilities } = await import("./app/app-manager.js");
+                unregisterCapabilities(nomadJobId);
+            }
+            return result;
+        }
+        if (isAppJob(nomadJobId)) {
+            return { ok: false, error: `App '${nomadJobId}' 必须通过 app-manager 停止` };
+        }
+        if (existsSync(instanceMetaPath(nomadJobId))) {
+            return instanceScheduler.stopInstance(nomadJobId, purge);
+        }
+        if (nomadJobId.startsWith(OPENCLAW_PREFIX)) {
+            return instanceScheduler.stopInstance(nomadJobId.slice(OPENCLAW_PREFIX.length), purge);
+        }
+        try {
+            const resp = await nomadDelete(`/v1/job/${nomadJobId}?purge=${purge}`);
+            return resp.ok ? { ok: true } : { ok: false, error: `HTTP ${resp.status}` };
+        }
+        catch (e) {
+            return { ok: false, error: e.message };
+        }
+    }
+    UnifiedNomadJobs.stopInstance = stopInstance;
+    async function restartInstance(nomadJobId) {
+        if (await getInstanceBackedInstalledApp(nomadJobId)) {
+            const stopResult = await stopInstance(nomadJobId);
+            if (!stopResult.ok && !stopResult.error?.includes("not running") && !stopResult.error?.includes("not found")) {
+                return stopResult;
+            }
+            return startInstance(nomadJobId);
+        }
+        if (isAppJob(nomadJobId)) {
+            return { ok: false, error: `App '${nomadJobId}' 必须通过 app-manager 重启` };
+        }
+        if (existsSync(instanceMetaPath(nomadJobId))) {
+            return instanceScheduler.restartInstance(nomadJobId);
+        }
+        if (nomadJobId.startsWith(OPENCLAW_PREFIX)) {
+            return instanceScheduler.restartInstance(nomadJobId.slice(OPENCLAW_PREFIX.length));
+        }
+        if (!isAppJob(nomadJobId)) {
+            return { ok: false, error: `Cannot restart unmanaged job "${nomadJobId}"` };
+        }
+        return { ok: false, error: `Cannot restart unmanaged job "${nomadJobId}"` };
+    }
+    UnifiedNomadJobs.restartInstance = restartInstance;
+    async function getInstanceLogs(nomadJobId, lines = 200, logType = "stderr") {
+        if (await getInstanceBackedInstalledApp(nomadJobId)) {
+            return getAppLogs(nomadJobId, "", lines, logType);
+        }
+        if (isAppJob(nomadJobId))
+            return getAppLogs(nomadJobId, "", lines, logType);
+        if (existsSync(instanceMetaPath(nomadJobId))) {
+            return instanceScheduler.getLogs(nomadJobId, lines, logType);
+        }
+        if (nomadJobId.startsWith(OPENCLAW_PREFIX)) {
+            return instanceScheduler.getLogs(nomadJobId.slice(OPENCLAW_PREFIX.length), lines, logType);
+        }
+        if (!isAppJob(nomadJobId))
+            return [];
+        return [];
+    }
+    UnifiedNomadJobs.getInstanceLogs = getInstanceLogs;
+    async function execInInstance(nomadJobId, command, timeoutMs) {
+        if (await getInstanceBackedInstalledApp(nomadJobId)) {
+            return execInApp(nomadJobId, "", command, timeoutMs ?? 120_000);
+        }
+        if (isAppJob(nomadJobId)) {
+            return execInApp(nomadJobId, "", command, timeoutMs ?? 120_000);
+        }
+        if (existsSync(instanceMetaPath(nomadJobId))) {
+            return instanceScheduler.exec(nomadJobId, command, timeoutMs);
+        }
+        if (nomadJobId.startsWith(OPENCLAW_PREFIX)) {
+            return instanceScheduler.exec(nomadJobId.slice(OPENCLAW_PREFIX.length), command, timeoutMs);
+        }
+        if (!isAppJob(nomadJobId)) {
+            return { stdout: "", stderr: `Cannot exec into unmanaged job "${nomadJobId}"`, exitCode: 1 };
+        }
+        return { stdout: "", stderr: `Cannot exec into unmanaged job "${nomadJobId}"`, exitCode: 1 };
+    }
+    UnifiedNomadJobs.execInInstance = execInInstance;
+    async function streamExecInInstance(nomadJobId, command, handlers = {}, timeoutMs, taskName = "") {
+        if (await getInstanceBackedInstalledApp(nomadJobId)) {
+            return streamExecInApp(nomadJobId, taskName, command, handlers, timeoutMs ?? 120_000);
+        }
+        if (isAppJob(nomadJobId)) {
+            return streamExecInApp(nomadJobId, taskName, command, handlers, timeoutMs ?? 120_000);
+        }
+        if (existsSync(instanceMetaPath(nomadJobId))) {
+            const result = await instanceScheduler.exec(nomadJobId, command, timeoutMs);
+            if (result.stdout)
+                handlers.onStdout?.(result.stdout);
+            if (result.stderr)
+                handlers.onStderr?.(result.stderr);
+            return result;
+        }
+        if (nomadJobId.startsWith(OPENCLAW_PREFIX)) {
+            const result = await instanceScheduler.exec(nomadJobId.slice(OPENCLAW_PREFIX.length), command, timeoutMs);
+            if (result.stdout)
+                handlers.onStdout?.(result.stdout);
+            if (result.stderr)
+                handlers.onStderr?.(result.stderr);
+            return result;
+        }
+        if (!isAppJob(nomadJobId)) {
+            const stderr = `Cannot exec into unmanaged job "${nomadJobId}"`;
+            handlers.onStderr?.(stderr);
+            return { stdout: "", stderr, exitCode: 1 };
+        }
+        const stderr = `Cannot exec into unmanaged job "${nomadJobId}"`;
+        handlers.onStderr?.(stderr);
+        return { stdout: "", stderr, exitCode: 1 };
+    }
+    UnifiedNomadJobs.streamExecInInstance = streamExecInInstance;
+})(UnifiedNomadJobs || (UnifiedNomadJobs = {}));
+export const isAppJob = UnifiedNomadJobs.isAppJob;
+export const parseCpuMHz = UnifiedNomadJobs.parseCpuMHz;
+export const parseMemoryMB = UnifiedNomadJobs.parseMemoryMB;
+export const isBinaryRunning = UnifiedNomadJobs.isBinaryRunning;
+export const getAppStatus = UnifiedNomadJobs.getAppStatus;
+export const startAppJob = UnifiedNomadJobs.startAppJob;
+export const waitForRunning = UnifiedNomadJobs.waitForRunning;
+export const checkDependencies = UnifiedNomadJobs.checkDependencies;
+export const stopAppJob = UnifiedNomadJobs.stopAppJob;
+export const restartAppJob = UnifiedNomadJobs.restartAppJob;
+export const getAppLogs = UnifiedNomadJobs.getAppLogs;
+export const execInApp = UnifiedNomadJobs.execInApp;
+export const streamExecInApp = UnifiedNomadJobs.streamExecInApp;
+export const listInstanceIds = UnifiedNomadJobs.listInstanceIds;
+export const readInstanceMeta = UnifiedNomadJobs.readInstanceMeta;
+export const resolveInstanceId = UnifiedNomadJobs.resolveInstanceId;
+export const resolveInstanceForPairing = UnifiedNomadJobs.resolveInstanceForPairing;
+export const ensureNomadToken = UnifiedNomadJobs.ensureNomadToken;
+export const getInstanceStatus = UnifiedNomadJobs.getInstanceStatus;
+export const getInstanceLogs = UnifiedNomadJobs.getInstanceLogs;
+export const execInInstance = UnifiedNomadJobs.execInInstance;
+export const streamExecInInstance = UnifiedNomadJobs.streamExecInInstance;
+export const shouldAutoStartNomadJob = UnifiedNomadJobs.shouldAutoStart;
+export const startNomadJobInstance = UnifiedNomadJobs.startInstance;
+export const stopNomadJobInstance = UnifiedNomadJobs.stopInstance;
+export const restartNomadJobInstance = UnifiedNomadJobs.restartInstance;
 //# sourceMappingURL=nomad-manager.js.map