jishushell 0.5.22 → 0.6.18

package/dist/services/nomad-manager.js

@@ -1,3953 +0,0 @@
-/**
- * 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, spawn } from "child_process";
-import { existsSync, readFileSync } from "fs";
-import { createServer as netCreateServer } from "net";
-import { homedir, userInfo } from "os";
-import { basename, join } from "path";
-import { StringDecoder } from "string_decoder";
-import { promisify } from "util";
-import { parse } from "yaml";
-import * as config from "../config.js";
-import { extractGatewayPort, 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;
-/**
- * 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 jobPrefixFor(instanceId) {
-    try {
-        const agentType = getInstanceAgentType(instanceId);
-        const adapter = getAdapter(agentType);
-        return adapter.nomadJobPrefix ?? "jishushell-";
-    }
-    catch {
-        return "jishushell-";
-    }
-}
-/**
- * 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 adapterVariableSubpath(instanceId) {
-    try {
-        const agentType = getInstanceAgentType(instanceId);
-        const adapter = getAdapter(agentType);
-        return adapter.nomadVariablePath;
-    }
-    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";
-    }
-}
-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 } : {};
-}
-// §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) {
-    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
-// route layer, but this guard makes the template-building code self-contained.
-export const NOMAD_TEMPLATE_UNSAFE_RE = /[{}"\\]/;
-function assertSafeTemplateId(id) {
-    if (NOMAD_TEMPLATE_UNSAFE_RE.test(id)) {
-        throw new Error(`Job ID "${id}" contains characters unsafe for Nomad Template interpolation`);
-    }
-}
-async function nomadGet(path) {
-    const resp = await fetch(`${getNomadAddr()}${path}`, {
-        headers: nomadAuthHeaders(),
-        signal: AbortSignal.timeout(10000),
-    });
-    if (!resp.ok && resp.status !== 404)
-        throw new Error(`Nomad ${path}: ${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(10000),
-    });
-}
-async function nomadDelete(path) {
-    return fetch(`${getNomadAddr()}${path}`, {
-        method: "DELETE",
-        headers: nomadAuthHeaders(),
-        signal: AbortSignal.timeout(10000),
-    });
-}
-async function nomadPut(path, body) {
-    return fetch(`${getNomadAddr()}${path}`, {
-        method: "PUT",
-        headers: { "Content-Type": "application/json", ...nomadAuthHeaders() },
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(10000),
-    });
-}
-// ── Nomad Variables (secrets) ──
-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
-    // to variables under its own nomad/jobs/<job-id>/ prefix, providing per-job
-    // secret isolation within the shared "default" namespace. Per-instance Nomad
-    // namespaces remain a planned future improvement.
-    const ns = "default";
-    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);
-    const proxyToken = env.JSPROXY_API_KEY || "";
-    // Nothing to store when proxy token is unconfigured.
-    if (!proxyToken)
-        return;
-    const items = { JSPROXY_API_KEY: proxyToken };
-    // retry with exponential back-off on CAS conflicts (409) so concurrent
-    // startInstance calls do not silently discard the latest token. Throw after
-    // MAX_ATTEMPTS so the caller can surface the error instead of continuing with
-    // a missing proxy token.
-    const MAX_ATTEMPTS = 3;
-    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
-        // Re-read ModifyIndex on every attempt to always CAS against the latest version.
-        let cas = 0;
-        try {
-            const existing = await nomadGet(`/v1/var/${encodedPath}?namespace=${ns}`);
-            if (existing.ok) {
-                const data = await existing.json();
-                cas = data.ModifyIndex || 0;
-            }
-        }
-        catch { /* variable may not exist yet — cas=0 creates a new one */ }
-        const resp = await nomadPut(`/v1/var/${encodedPath}?cas=${cas}&namespace=${ns}`, {
-            Namespace: ns,
-            Path: varPath,
-            Items: items,
-        });
-        if (resp.ok)
-            return;
-        const text = await resp.text();
-        // 409 Conflict = CAS mismatch; another writer won the race — retry.
-        if (resp.status === 409 && attempt < MAX_ATTEMPTS - 1) {
-            await new Promise(r => setTimeout(r, 100 * Math.pow(2, attempt)));
-            continue;
-        }
-        throw new Error(`Failed to write Nomad Variables for ${instanceId}` +
-            ` (attempt ${attempt + 1}/${MAX_ATTEMPTS}): HTTP ${resp.status} ${text}`);
-    }
-}
-export async function purgeInstanceVariables(instanceId) {
-    const jid = jobId(instanceId);
-    const subpath = adapterVariableSubpath(instanceId);
-    if (!subpath)
-        return;
-    const varPath = `nomad/jobs/${jid}/${subpath}`;
-    const encodedPath = encodeURIComponent(varPath);
-    try {
-        // 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}`);
-        }
-    }
-    catch (e) {
-        console.warn(`[nomad] Failed to purge variables for ${instanceId}: ${e.message}`);
-    }
-}
-/**
- * Resolve the numeric uid:gid for a given username by reading /etc/passwd.
- * 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 {
-        const passwd = readFileSync("/etc/passwd", "utf-8");
-        const line = passwd.split("\n").find(l => l.startsWith(username + ":"));
-        if (line) {
-            const parts = line.split(":");
-            const uid = parseInt(parts[2], 10);
-            const gid = parseInt(parts[3], 10);
-            if (!isNaN(uid) && !isNaN(gid))
-                return `${uid}:${gid}`;
-        }
-    }
-    catch { /* ignore */ }
-    return `${process.getuid()}:${process.getgid()}`;
-}
-// §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);
-    }
-    catch {
-        return "openclaw";
-    }
-}
-function wrapNomadJob(jid, groupName, task) {
-    // Adapters declare port reservations on `task.Resources.Networks` (legacy
-    // schema). The docker driver's `Config.ports = [<label>]` lookup, however,
-    // resolves labels against the TaskGroup-level `Networks` block. Move (not
-    // copy) the network block so the docker driver can find the port and so
-    // HostNetwork ("external") is honored — without this, ports publish to
-    // 127.0.0.1 by default. Keeping it on both levels would make Nomad reject
-    // the job with "port label already in use".
-    const taskNetworks = Array.isArray(task?.Resources?.Networks)
-        ? task.Resources.Networks
-        : [];
-    const groupNetworks = taskNetworks.length > 0 ? taskNetworks.map((n) => ({ ...n })) : undefined;
-    if (groupNetworks && task?.Resources && typeof task.Resources === "object") {
-        delete task.Resources.Networks;
-    }
-    return {
-        Job: {
-            ID: jid,
-            Name: jid,
-            Namespace: "default",
-            Type: "service",
-            Datacenters: ["*"],
-            TaskGroups: [{
-                    Name: groupName,
-                    Count: 1,
-                    ...(groupNetworks ? { Networks: groupNetworks } : {}),
-                    RestartPolicy: {
-                        // 10 attempts × 15s delay = ~2.5min recovery window. Multi-task
-                        // groups (e.g. weknora-app racing paradedb cold-init) commonly
-                        // need 3-5 restarts before the dependency's external port-publish
-                        // settles. Previous 3-attempt cap caused alloc-fail cascades on
-                        // first-boot of stacks with DB sidecars.
-                        Attempts: 10,
-                        Interval: 600000000000,
-                        Delay: 15000000000,
-                        Mode: "fail",
-                    },
-                    Reschedule: {
-                        // Allow Nomad to reschedule the whole alloc up to 3 times if all
-                        // restarts fail (e.g. transient image pull or host reboot).
-                        // Unlimited stays false to keep alloc churn bounded.
-                        Attempts: 3,
-                        Interval: 3600000000000,
-                        Unlimited: false,
-                    },
-                    Update: {
-                        MaxParallel: 1,
-                        HealthCheck: "task_states",
-                        MinHealthyTime: 5000000000,
-                        HealthyDeadline: 60000000000,
-                        AutoRevert: false,
-                    },
-                    Tasks: [task],
-                }],
-        },
-    };
-}
-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);
-        await injectConnectionsRuntimeEnv(instanceId, task);
-        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);
-    await injectConnectionsRuntimeEnv(instanceId, task);
-    // 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);
-}
-/**
- * Re-resolve `instance.connections` against the live capability registry
- * and merge the resulting env into the freshly-built Nomad task. Idempotent
- * — empty meta.connections short-circuits to a no-op.
- *
- * Resolving at start time (rather than reading the frozen
- * `instance.json["connections-env"]` written by PUT /connections) means
- * provider port / address changes in the registry propagate on next
- * restart without requiring the user to re-bind. Failures here are
- * logged but never block start: a missing required binding still surfaces
- * via the Connections UI status badge.
- */
-async function injectConnectionsRuntimeEnv(instanceId, task) {
-    try {
-        const meta = getInstance(instanceId);
-        const connections = meta?.connections;
-        if (!meta || !connections || Object.keys(connections).length === 0)
-            return;
-        const { loadCapabilitySpecForLegacyInstance } = await import("./runtime/migrations.js");
-        const spec = loadCapabilitySpecForLegacyInstance(meta);
-        if (!spec)
-            return;
-        const { resolveConnections } = await import("./connection-resolver.js");
-        const { resolved } = resolveConnections(spec, { connections }, "preCreate");
-        if (resolved.length === 0)
-            return;
-        const { RUNTIME_HOOKS } = await import("./connection-apply.js");
-        const merged = {};
-        for (const binding of resolved) {
-            const hook = RUNTIME_HOOKS[binding.category];
-            if (!hook)
-                continue;
-            Object.assign(merged, await hook(meta, binding));
-        }
-        if (Object.keys(merged).length === 0)
-            return;
-        task.Env = { ...(task.Env ?? {}), ...merged };
-    }
-    catch (e) {
-        console.warn(`[nomad] connections runtime env merge failed for ${instanceId}: ${e?.message ?? e}`);
-    }
-}
-async function getRunningAlloc(instanceId) {
-    const allocs = await getAllocs(instanceId);
-    if (!allocs)
-        return null;
-    for (const status of ["running", "pending"]) {
-        for (const alloc of allocs) {
-            if (alloc.ClientStatus === status)
-                return alloc;
-        }
-    }
-    return null;
-}
-async function getAllocs(instanceId) {
-    const jid = jobId(instanceId);
-    try {
-        const resp = await nomadGet(`/v1/job/${jid}/allocations`);
-        if (resp.status === 404)
-            return [];
-        const allocs = await resp.json();
-        return Array.isArray(allocs) ? allocs : [];
-    }
-    catch {
-        return null;
-    }
-}
-function latestAlloc(allocs) {
-    if (!allocs.length)
-        return null;
-    return [...allocs].sort((a, b) => ((b.ModifyIndex ?? b.CreateIndex ?? 0) - (a.ModifyIndex ?? a.CreateIndex ?? 0)))[0] ?? null;
-}
-// Returns true if the Nomad job exists and was NOT explicitly stopped by the user (Stop=false).
-// Used on jishushell startup to auto-restart instances that were running before a reboot.
-export async function shouldAutoStart(instanceId) {
-    const jid = jobId(instanceId);
-    try {
-        const resp = await nomadGet(`/v1/job/${jid}`);
-        // 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.
-        // Also skip dead jobs — all allocs failed, resubmitting would fail again.
-        return job.Stop === false && job.Status !== "dead";
-    }
-    catch {
-        return false;
-    }
-}
-export async function getStatus(instanceId) {
-    const jid = jobId(instanceId);
-    const stopped = { status: "stopped", pid: null, uptime: null, memory_mb: null, cpu_percent: null };
-    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(instanceId);
-    if (allocs == null || allocs.length === 0)
-        return { ...stopped, status: "pending" };
-    const alloc = allocs.find((entry) => entry.ClientStatus === "running")
-        ?? allocs.find((entry) => entry.ClientStatus === "pending")
-        ?? latestAlloc(allocs);
-    if (!alloc)
-        return { ...stopped, status: "pending" };
-    const allocId = alloc.ID;
-    const result = {
-        status: alloc.ClientStatus || "unknown",
-        alloc_id: allocId,
-        pid: null,
-        uptime: null,
-        memory_mb: null,
-        cpu_percent: null,
-        restarts: 0,
-    };
-    const gwState = alloc.TaskStates?.[resolveTaskName(instanceId)] || {};
-    result.restarts = gwState.Restarts || 0;
-    const startedAt = gwState.StartedAt;
-    if (startedAt) {
-        try {
-            const start = new Date(startedAt);
-            result.uptime = Math.floor((Date.now() - start.getTime()) / 1000);
-        }
-        catch { /* ignore */ }
-    }
-    try {
-        const statsResp = await nomadGet(`/v1/client/allocation/${allocId}/stats`);
-        if (statsResp.ok) {
-            const stats = await statsResp.json();
-            // 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;
-            result.memory_mb = Math.round(memBytes / (1024 * 1024) * 10) / 10;
-            result.cpu_percent = Math.round((cpuStats.Percent || 0) * 10) / 10;
-        }
-    }
-    catch { /* ignore */ }
-    // Fallback: Nomad cgroup stats are often zero on cgroup v2 (e.g. Raspberry
-    // Pi / CIX). Read from the shared, cached, single-flight `docker stats`
-    // snapshot instead of forking one `docker stats` per instance — see
-    // getDockerMemSnapshot for why per-instance forking was the cold-path cost.
-    if (!result.memory_mb && allocId && /^[a-f0-9-]+$/i.test(allocId)) {
-        const containerName = `${resolveTaskName(instanceId)}-${allocId}`;
-        const stat = (await getDockerMemSnapshot()).get(containerName);
-        if (stat) {
-            if (stat.memory_mb)
-                result.memory_mb = stat.memory_mb;
-            if (!result.cpu_percent && stat.cpu_percent)
-                result.cpu_percent = stat.cpu_percent;
-        }
-    }
-    return result;
-}
-/** 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", code: "INSTANCE_ALREADY_RUNNING" };
-    }
-    return { ok: true };
-}
-async function phaseResetTerminalJobBeforeStart(instanceId) {
-    const status = await getStatus(instanceId);
-    if (!["failed", "dead", "complete"].includes(String(status.status)))
-        return;
-    try {
-        const resp = await nomadDelete(`/v1/job/${jobId(instanceId)}?purge=false`);
-        if (!resp.ok && resp.status !== 404) {
-            console.warn(`[nomad] ${instanceId}: failed to stop terminal job before start (HTTP ${resp.status}): ${await resp.text()}`);
-        }
-    }
-    catch (e) {
-        console.warn(`[nomad] ${instanceId}: failed to stop terminal job before start: ${e?.message ?? e}`);
-    }
-}
-/**
- * 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 sharedHomeIds) {
-        const otherStatus = await getStatus(otherId);
-        if (otherStatus.status === "running")
-            homeConflicts.push(otherId);
-    }
-    if (homeConflicts.length) {
-        return {
-            ok: false,
-            error: `This instance shares its agent-home directory with running instance(s): ` +
-                `${homeConflicts.join(", ")}. Move it to its own instance directory before starting it.`,
-        };
-    }
-    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" } };
-    }
-    catch (e) {
-        return {
-            ok: false,
-            error: `Gateway port ${desiredPort} is held by another process and reallocation failed: ${e?.message ?? e}`,
-        };
-    }
-}
-/**
- * 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) };
-    }
-}
-/**
- * §17 / PR 9 — re-render adapter-managed connection config from the
- * current capability registry before each instance start.
- *
- * Without this hook, env values (like `SEARCH_API_BASE_URL` =
- * `http://<host>:<port>/search`) are frozen into the adapter's config
- * files at PUT /connections time. When the host IP changes (DHCP
- * renewal, pi reboot picking up a new lease, network move) or a
- * provider gets re-deployed at a different host:port, the consumer
- * keeps trying the stale address and search/llm/etc. silently fail.
- *
- * What this does on every start:
- *   1. Read connections from instance.json
- *   2. Re-resolve them in `runtime` mode (tolerant: ambiguous/missing
- *      becomes empty resolved instead of throwing — start should still
- *      proceed even if one binding can't be re-rendered)
- *   3. Collect env via the same persist hooks PUT /connections uses
- *   4. Call adapter.applyConnectionEnv with the fresh env so the
- *      adapter rewrites its config files (mcp_servers / openclaw.json /
- *      etc.) with the current address
- *
- * Failures here are logged but never block start: a stale config is
- * better than no start. If something is genuinely wrong with the
- * registry, the user will see a connection error in the UI on next
- * use — at which point they can re-bind manually.
- */
-async function phaseRefreshConnections(adapter, instanceId) {
-    if (!adapter.applyConnectionEnv)
-        return;
-    try {
-        const meta = getInstance(instanceId);
-        const connections = meta?.connections;
-        if (!meta || !connections || Object.keys(connections).length === 0)
-            return;
-        const { loadCapabilitySpecForLegacyInstance } = await import("./runtime/migrations.js");
-        const spec = loadCapabilitySpecForLegacyInstance(meta);
-        if (!spec)
-            return;
-        const { resolveConnections } = await import("./connection-resolver.js");
-        const { resolved } = resolveConnections(spec, { connections }, "preCreate");
-        if (resolved.length === 0)
-            return;
-        const { PERSIST_HOOKS } = await import("./connection-apply.js");
-        const merged = {};
-        const seenEnvKeys = new Set();
-        // Accumulate env across all resolved bindings via a stub
-        // writeConnectionEnv that just collects into `merged`. We don't
-        // run the real persist hooks here because those would re-write
-        // generic-app `connections-env` (already handled by
-        // injectConnectionsRuntimeEnv); we only want the env so we can
-        // pass it to adapter.applyConnectionEnv below.
-        const stubCtx = {
-            registry: await import("./capability-registry.js"),
-            adapter: { applyConnectionEnv: undefined },
-            async writeConnectionEnv(_inst, env) {
-                for (const [k, v] of Object.entries(env)) {
-                    merged[k] = v;
-                    seenEnvKeys.add(k);
-                }
-            },
-        };
-        for (const binding of resolved) {
-            const hook = PERSIST_HOOKS[binding.category];
-            if (!hook)
-                continue;
-            await hook(meta, binding, stubCtx);
-        }
-        if (seenEnvKeys.size === 0)
-            return;
-        await adapter.applyConnectionEnv(instanceId, merged);
-    }
-    catch (e) {
-        console.warn(`[nomad] connections refresh failed for ${instanceId}: ${e?.message ?? 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 {
-            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 (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 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" };
-    }
-    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 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) {
-        const extra = { error: running.error };
-        if (running.code)
-            extra.code = running.code;
-        return failed("running_check", extra);
-    }
-    await phaseResetTerminalJobBeforeStart(instanceId);
-    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);
-        }
-    }
-    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 });
-        // PR 9 — refresh adapter-managed connection config from current
-        // capability registry before adapter pre-start. Best-effort: never
-        // blocks start (any failure is logged and we proceed with the
-        // existing on-disk config). See phaseRefreshConnections doc.
-        await phaseRefreshConnections(adapter, instanceId);
-        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 });
-    // Auto-register capability providers for legacy instances so they appear
-    // in the Connections UI alongside app-installed apps. App-dir installed
-    // apps short-circuit at the top of this function and don't reach here.
-    await registerLegacyCapabilitiesTopLevel(instanceId);
-    return {
-        ok: true,
-        eval_id: submit.evalId,
-        ...(submit.portAllocation ? { port_allocation: submit.portAllocation } : {}),
-    };
-}
-/**
- * Best-effort capability registration for legacy (non-app-installed)
- * hermes/openclaw instances. Loaded synthetic spec via the migrations
- * helper; failures are logged but never block start/stop.
- */
-async function registerLegacyCapabilitiesTopLevel(instanceId) {
-    try {
-        const meta = getInstance(instanceId);
-        if (!meta)
-            return;
-        const { loadCapabilitySpecForLegacyInstance } = await import("./runtime/migrations.js");
-        const synthSpec = loadCapabilitySpecForLegacyInstance(meta);
-        if (!synthSpec?.provides?.length)
-            return;
-        // The synthetic spec's `name` is the yaml template's display name
-        // ("Hermes Agent" / "OpenClaw Container"). For Connections-tab UX we
-        // want the candidate to surface the user's instance name (e.g. "h",
-        // "claw11"), so override before handing it to registerCapabilities.
-        const instanceName = typeof meta.name === "string" && meta.name
-            ? meta.name
-            : instanceId;
-        const namedSpec = { ...synthSpec, name: instanceName };
-        // The synthetic spec has `tasks: []`, so `resolveProvideEndpoint`
-        // can't compute the actual gateway port and falls back to the yaml's
-        // declared port (e.g. openclaw default 18789). Legacy instances may
-        // have been allocated a different port at creation time (port
-        // collision avoidance). Pass the live `getGatewayPort` so the
-        // capability registry advertises the port consumers can actually
-        // reach.
-        const portOverride = getGatewayPort(instanceId);
-        const { registerCapabilities } = await import("./app/app-manager.js");
-        registerCapabilities(instanceId, namedSpec, portOverride > 0 ? portOverride : undefined);
-    }
-    catch (e) {
-        console.warn(`[legacy-capabilities] register failed for ${instanceId}: ${e?.message ?? e}`);
-    }
-}
-async function unregisterLegacyCapabilitiesTopLevel(instanceId, purge) {
-    try {
-        const { markCapabilitiesStopped, unregisterCapabilities } = await import("./app/app-manager.js");
-        if (purge)
-            unregisterCapabilities(instanceId);
-        else
-            markCapabilitiesStopped(instanceId);
-    }
-    catch (e) {
-        console.warn(`[legacy-capabilities] unregister failed for ${instanceId}: ${e?.message ?? e}`);
-    }
-}
-export async function stopInstance(instanceId, purge = false) {
-    const jid = jobId(instanceId);
-    try {
-        const resp = await nomadDelete(`/v1/job/${jid}?purge=${purge}`);
-        if (resp.ok) {
-            if (purge) {
-                try {
-                    await purgeInstanceVariables(instanceId);
-                }
-                catch { /* ignore */ }
-            }
-            await unregisterLegacyCapabilitiesTopLevel(instanceId, purge);
-            return { ok: true };
-        }
-        if (resp.status === 404) {
-            // Already stopped — still mark capabilities stopped so the UI reflects state.
-            await unregisterLegacyCapabilitiesTopLevel(instanceId, purge);
-            return { ok: false, error: "Instance is not running" };
-        }
-        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 };
-    }
-}
-export async function restartInstance(instanceId) {
-    // Prefer the native Nomad allocation restart API over stop+start:
-    //   PUT /v1/client/allocation/{allocID}/restart
-    // This preserves alloc history, EvalID, and avoids rescheduling.
-    // 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);
-                // PR 9 — refresh connection-derived config (mcp_servers /
-                // openclaw.json plugins) from current capability registry so
-                // host IP changes propagate on restart without manual re-bind.
-                // Symmetric with the same call in startInstance.
-                await phaseRefreshConnections(adapter, instanceId);
-                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: resolveTaskName(instanceId),
-                AllTasks: false,
-            });
-            if (resp.ok) {
-                // Re-register capabilities — yaml provides may have changed since
-                // the last start (e.g. a panel upgrade adding `llm-agent`).
-                await registerLegacyCapabilitiesTopLevel(instanceId);
-                return { ok: true, alloc_id: alloc.ID };
-            }
-            // Non-2xx from the restart endpoint falls through to stop+start
-            const errText = await resp.text();
-            console.warn(`[nomad] Native restart failed for ${instanceId} (HTTP ${resp.status}): ${errText} — falling back to stop+start`);
-        }
-        catch (e) {
-            console.warn(`[nomad] Native restart error for ${instanceId}: ${e.message} — falling back to stop+start`);
-        }
-    }
-    // Fallback: stop the job and re-submit it
-    await stopInstance(instanceId);
-    await new Promise((r) => setTimeout(r, 2000));
-    return startInstance(instanceId);
-}
-export async function getLogs(instanceId, lines = 200, logType = "stderr") {
-    // Defense-in-depth: only allow known log types to prevent path/query injection
-    if (!VALID_LOG_TYPES.has(logType))
-        logType = "stderr";
-    let alloc = await getRunningAlloc(instanceId);
-    if (!alloc) {
-        const jid = jobId(instanceId);
-        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 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: resolvedTask,
-            type: logType,
-            plain: "true",
-            origin: "end",
-            offset: String(Math.max(lines * 512, 100000)),
-            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 */ }
-    // 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);
-const DOCKER_STATS_TTL_MS = 30_000;
-/** Field separator for the batched `docker stats --format` line. Exported so
- *  tests can construct mock output without hardcoding the literal. */
-export const DOCKER_STATS_FIELD_SEP = "__JS__";
-let _dockerStatsEntry = null;
-let _dockerStatsInFlight = null;
-/** Test-only: reset the shared docker-stats snapshot so each test starts from
- *  a cold cache (the 30s TTL + single-flight would otherwise leak one test's
- *  mocked snapshot into the next). Not used by production code paths. */
-export function __resetDockerStatsCacheForTests() {
-    _dockerStatsEntry = null;
-    _dockerStatsInFlight = null;
-}
-function parseDockerMemUsageMb(memUsage) {
-    // Format: "499.6MiB / 3GiB" — the used side is everything before "/".
-    const used = (memUsage.split("/")[0] ?? "").trim();
-    const match = used.match(/^([\d.]+)\s*(MiB|GiB|MB|GB|KiB|KB|B)?/i);
-    if (!match)
-        return 0;
-    let mb = parseFloat(match[1]);
-    if (!Number.isFinite(mb))
-        return 0;
-    const unit = (match[2] ?? "MiB").toLowerCase();
-    if (unit === "gib" || unit === "gb")
-        mb *= 1024;
-    else if (unit === "kib" || unit === "kb")
-        mb /= 1024;
-    else if (unit === "b")
-        mb /= 1024 * 1024;
-    return Math.round(mb * 10) / 10;
-}
-async function loadDockerStatsSnapshot() {
-    const snapshot = new Map();
-    try {
-        const fmt = `{{.Name}}${DOCKER_STATS_FIELD_SEP}{{.MemUsage}}${DOCKER_STATS_FIELD_SEP}{{.CPUPerc}}`;
-        const { stdout } = await execFileAsync("docker", ["stats", "--no-stream", "--format", fmt], { timeout: 8_000 });
-        for (const line of stdout.split("\n")) {
-            const trimmed = line.trim();
-            if (!trimmed)
-                continue;
-            const [name, memUsage, cpuPerc] = trimmed.split(DOCKER_STATS_FIELD_SEP);
-            if (!name)
-                continue;
-            snapshot.set(name, {
-                memory_mb: parseDockerMemUsageMb(memUsage ?? ""),
-                cpu_percent: Math.round((parseFloat(cpuPerc ?? "") || 0) * 10) / 10,
-            });
-        }
-    }
-    catch {
-        /* docker missing / timeout / daemon down → empty map, caller degrades */
-    }
-    return snapshot;
-}
-/**
- * Returns a per-container stats map, refreshing at most once per
- * DOCKER_STATS_TTL_MS. Concurrent callers (the `Promise.all` over every
- * instance in `GET /api/instances`) share a single in-flight docker call.
- */
-async function getDockerMemSnapshot() {
-    const now = Date.now();
-    if (_dockerStatsEntry && now - _dockerStatsEntry.ts < DOCKER_STATS_TTL_MS) {
-        return _dockerStatsEntry.data;
-    }
-    if (_dockerStatsInFlight)
-        return _dockerStatsInFlight;
-    _dockerStatsInFlight = loadDockerStatsSnapshot()
-        .then((data) => {
-        _dockerStatsEntry = { data, ts: Date.now() };
-        return data;
-    })
-        .finally(() => {
-        _dockerStatsInFlight = null;
-    });
-    return _dockerStatsInFlight;
-}
-export async function exec(instanceId, command, timeoutMs = 120_000) {
-    const alloc = await getRunningAlloc(instanceId);
-    if (!alloc || alloc.ClientStatus !== "running") {
-        throw new Error("Instance is not running");
-    }
-    const allocId = alloc.ID;
-    if (!/^[a-f0-9-]+$/i.test(allocId))
-        throw new Error("invalid allocId");
-    const containerName = `gateway-${allocId}`;
-    // Use the same user as the container's main process (runtime.user uid:gid)
-    const runtime = getInstanceRuntime(instanceId);
-    const userFlag = resolveUidGid(runtime.user);
-    try {
-        const { stdout, stderr } = await execFileAsync("docker", ["exec", "--user", userFlag, containerName, ...command], { timeout: timeoutMs });
-        return { stdout, stderr, exitCode: 0 };
-    }
-    catch (e) {
-        return {
-            stdout: e.stdout || "",
-            stderr: e.stderr || e.message,
-            exitCode: e.code ?? 1,
-        };
-    }
-}
-// ── 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, 10) * 1_000_000;
-        if (s.endsWith("s"))
-            return parseInt(s, 10) * 1_000_000_000;
-        if (s.endsWith("m"))
-            return parseInt(s, 10) * 60_000_000_000;
-        return parseInt(s, 10) * 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;
-        // Honor explicit host_network from spec (e.g. weknora's ports declare
-        // `host_network: docker_bridge` so peer tasks reach the published port
-        // via host.docker.internal). Verify the named network is actually
-        // declared in nomad.hcl — otherwise Nomad rejects job submission with
-        // "unknown host network". Falls back to "external" when unset.
-        const requested = (port.host_network ?? "").trim();
-        if (requested && nomadConfigDeclaresHostNetwork(requested))
-            return requested;
-        return nomadConfigDeclaresHostNetwork("external") ? "external" : undefined;
-    }
-    function specRequiresExternalHostNetwork(spec) {
-        return spec.tasks.some((task) => task.runtime !== "container"
-            && (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 } : {}),
-            // Attach the named host_network for any externally-visible port —
-            // including container tasks. Without it, Nomad falls back to
-            // HostNetwork="default" (loopback) and the docker driver publishes
-            // to 127.0.0.1, breaking cross-container consumers (e.g. OpenWebUI
-            // calling hermes / openclaw via the connections page). The earlier
-            // restriction to non-container tasks was overcautious — our task
-            // groups use host networking (Mode: "") rather than Nomad bridge
-            // mode, so attaching host_network is safe and is exactly what
-            // searxng-container has been doing in practice all along.
-            ...(hostNetworkForPort(port)
-                ? { HostNetwork: hostNetworkForPort(port) }
-                : {}),
-        }));
-    }
-    function isExternalAppTaskPort(port) {
-        return (port.visibility ?? "external") !== "internal";
-    }
-    function readDeclaredHostPort(port) {
-        const candidate = port.host_port ?? port.port;
-        return Number.isInteger(candidate) && candidate > 0 ? candidate : null;
-    }
-    function applyPersistedAppSpecPortOverrides(appId, spec) {
-        const meta = getInstance(appId);
-        if (!meta)
-            return spec;
-        const runtime = getInstanceRuntime(appId);
-        const runtimePorts = Array.isArray(runtime.ports) ? runtime.ports : [];
-        const persistedGatewayPort = extractGatewayPort(runtime, resolveAgentType(meta));
-        const totalExternalPorts = spec.tasks.reduce((count, task) => count + (task.ports ?? []).filter((port) => isExternalAppTaskPort(port)).length, 0);
-        let changed = false;
-        const tasks = spec.tasks.map((task) => {
-            if (!Array.isArray(task.ports) || task.ports.length === 0)
-                return task;
-            let taskChanged = false;
-            const ports = task.ports.map((port) => {
-                if (!isExternalAppTaskPort(port))
-                    return port;
-                const currentHostPort = readDeclaredHostPort(port);
-                if (!currentHostPort)
-                    return port;
-                let nextHostPort = null;
-                const namedRuntimePort = typeof port.name === "string" && port.name
-                    ? runtimePorts.find((candidate) => candidate?.name === port.name
-                        && Number.isInteger(candidate?.hostPort)
-                        && candidate.hostPort > 0)
-                    : null;
-                if (namedRuntimePort) {
-                    nextHostPort = namedRuntimePort.hostPort;
-                }
-                else if (runtimePorts.length === 1
-                    && totalExternalPorts === 1
-                    && Number.isInteger(runtimePorts[0]?.hostPort)
-                    && runtimePorts[0].hostPort > 0) {
-                    nextHostPort = runtimePorts[0].hostPort;
-                }
-                else if (totalExternalPorts === 1
-                    && persistedGatewayPort != null
-                    && persistedGatewayPort > 0) {
-                    nextHostPort = persistedGatewayPort;
-                }
-                if (!nextHostPort || nextHostPort === currentHostPort)
-                    return port;
-                changed = true;
-                taskChanged = true;
-                return { ...port, host_port: nextHostPort };
-            });
-            return taskChanged ? { ...task, ports } : task;
-        });
-        return changed ? { ...spec, tasks } : spec;
-    }
-    async function maybeReallocateAppSpecHostPort(appId, spec, reason) {
-        if (!getInstance(appId))
-            return { spec, changed: false };
-        const effectiveSpec = applyPersistedAppSpecPortOverrides(appId, spec);
-        const currentGatewayPort = getGatewayPort(appId);
-        if (!Number.isInteger(currentGatewayPort) || currentGatewayPort <= 0) {
-            return { spec: effectiveSpec, changed: false };
-        }
-        const declaredPorts = effectiveSpec.tasks.flatMap((task) => (task.ports ?? [])
-            .filter((port) => isExternalAppTaskPort(port))
-            .map((port) => readDeclaredHostPort(port))
-            .filter((port) => port != null));
-        if (!declaredPorts.includes(currentGatewayPort)) {
-            return { spec: effectiveSpec, changed: false };
-        }
-        if (!(await isPortInUse(currentGatewayPort))) {
-            return { spec: effectiveSpec, changed: false };
-        }
-        try {
-            const reallocation = await reallocateGatewayPort(appId);
-            console.log(`[nomad] ${appId}: reallocated AppSpec host port ${reallocation.from} -> ${reallocation.to} (${reason})`);
-            return {
-                spec: applyPersistedAppSpecPortOverrides(appId, spec),
-                changed: true,
-            };
-        }
-        catch (e) {
-            return {
-                spec: effectiveSpec,
-                changed: false,
-                error: `AppSpec host port ${currentGatewayPort} is held by another process and reallocation failed: ${e?.message ?? e}`,
-            };
-        }
-    }
-    // ── 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 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"}`;
-        });
-        // Resolve container task user. On Linux we default to the panel
-        // process's host uid:gid so bind-mounted data dirs (owned by the panel
-        // user, typically `pi`) are writable without forcing the container to
-        // run as root and without needing chown / DAC_OVERRIDE gymnastics.
-        // yaml override `user: "<uid>:<gid>"` wins; explicit `user: "root"` or
-        // `user: "0:0"` keeps the image's root default.
-        //
-        // On macOS we skip the host-uid default. Docker on Mac runs inside a
-        // Linux VM (Colima/Docker Desktop) with its own uid namespace — host
-        // uids like 501 (the standard macOS first-user) are virtualised away
-        // by virtiofs and almost never exist in the image's /etc/passwd. Some
-        // images crash hard when started as an unknown uid: e.g. browserless
-        // calls Node.js `os.userInfo()` very early, which throws
-        // `uv_os_get_passwd returned ENOENT` and the container exits before
-        // the port ever binds. Letting the image's default USER directive
-        // take effect is correct on Mac; users who do need bind-mount
-        // ownership control can still set yaml `user:` explicitly.
-        const containerUser = (() => {
-            if (task.runtime !== "container")
-                return undefined;
-            const declared = typeof task.user === "string" ? task.user.trim() : "";
-            if (declared === "host" || declared === "") {
-                if (process.platform === "darwin")
-                    return undefined;
-                const uid = process.getuid?.() ?? 1000;
-                const gid = process.getgid?.() ?? 1000;
-                return `${uid}:${gid}`;
-            }
-            return declared;
-        })();
-        // Validate cap_add against a tight allowlist. The full Linux cap surface
-        // is large; we only honor capabilities image entrypoints actually need
-        // for the canonical "start as root + gosu to user" pattern. Anything
-        // outside this list is silently dropped — failing closed protects
-        // against typo'd / hostile specs widening the container's capability
-        // bounds beyond what the panel author signed off on.
-        const ALLOWED_CAPS = new Set([
-            "CHOWN", "DAC_OVERRIDE", "FOWNER",
-            "SETUID", "SETGID", "SETPCAP", "NET_BIND_SERVICE",
-        ]);
-        const capAdd = Array.isArray(task.cap_add)
-            ? task.cap_add
-                .map((c) => typeof c === "string" ? c.trim().toUpperCase().replace(/^CAP_/, "") : "")
-                .filter((c) => ALLOWED_CAPS.has(c))
-            : [];
-        const taskDef = {
-            Name: task.name,
-            Driver: "docker",
-            ...(containerUser ? { User: containerUser } : {}),
-            Config: {
-                image,
-                force_pull: false,
-                // Nomad's docker driver default `image_pull_timeout` is 5 minutes;
-                // on Raspberry Pi or other constrained networks a 1+ GiB image
-                // (Open WebUI, OpenClaw, Hermes) can exceed that and the alloc
-                // restart-loops with "Failed to pull: context deadline exceeded"
-                // before it ever starts. Raise to 15 minutes — long enough for
-                // realistic Pi-class pulls, short enough that a genuinely
-                // unreachable registry still surfaces as a failure within a
-                // bounded window.
-                image_pull_timeout: "15m",
-                ...(task.command ? { command: String(task.command) } : {}),
-                args,
-                ...(publishedPorts.length > 0 ? { ports: publishedPorts } : {}),
-                extra_hosts: ["host.docker.internal:host-gateway"],
-                cap_drop: ["ALL"],
-                ...(capAdd.length > 0 ? { cap_add: capAdd } : {}),
-                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: {
-                            // 10 attempts × 15s delay = ~2.5min recovery window. Multi-task
-                            // app groups commonly need 3-5 restarts before sidecar
-                            // dependencies' external port-publish settles.
-                            Attempts: 10,
-                            Interval: 600_000_000_000,
-                            Delay: 15_000_000_000,
-                            Mode: "fail",
-                        },
-                        Reschedule: {
-                            Attempts: 3,
-                            Interval: 3_600_000_000_000,
-                            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];
-    }
-    UnifiedNomadJobs.aggregateHealthStatus = aggregateHealthStatus;
-    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: cgroup v2 (Pi / CIX) → Nomad alloc-stats are zero. Use the
-        // shared cached `docker stats` snapshot rather than forking per-instance.
-        if (!result.memory_mb && allocId && ptName && /^[a-f0-9-]+$/i.test(allocId)) {
-            const containerName = `${ptName}-${allocId}`;
-            const stat = (await getDockerMemSnapshot()).get(containerName);
-            if (stat) {
-                if (stat.memory_mb)
-                    result.memory_mb = stat.memory_mb;
-                if (!result.cpu_percent && stat.cpu_percent)
-                    result.cpu_percent = stat.cpu_percent;
-            }
-        }
-        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("; ") };
-        }
-        let effectiveSpec = applyPersistedAppSpecPortOverrides(appId, 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 };
-        }
-        if (driver === "docker") {
-            const preflight = await maybeReallocateAppSpecHostPort(appId, effectiveSpec, "host_port_busy");
-            if (preflight.error)
-                return { ok: false, error: preflight.error };
-            effectiveSpec = preflight.spec;
-        }
-        for (let attempt = 0; attempt < 2; attempt++) {
-            let jobDef;
-            try {
-                jobDef = buildAppJob(effectiveSpec, appId, driver, extraEnv);
-            }
-            catch (e) {
-                return { ok: false, error: `Job build failed: ${e.message}` };
-            }
-            let submitError = null;
-            let netErr = false;
-            try {
-                const resp = await nomadPost("/v1/jobs", jobDef);
-                if (resp.ok) {
-                    const data = await resp.json();
-                    // When the app was previously failed, verify it actually transitions
-                    // away from the failed state rather than reporting false success.
-                    if (status.status === "failed") {
-                        const recovered = await waitForRecovery(appId, 15_000, 2_000);
-                        if (!recovered) {
-                            return { ok: false, error: "App start submitted but instance remains in failed state. Check app logs for details.", eval_id: data.EvalID };
-                        }
-                    }
-                    return { ok: true, eval_id: data.EvalID };
-                }
-                submitError = await resp.text();
-            }
-            catch (e) {
-                netErr = e?.message === "fetch failed" || e?.cause?.code === "ECONNREFUSED";
-                submitError = netErr ? `Nomad 服务不可达 (${getNomadAddr()})，请先启动 Nomad` : e.message;
-            }
-            if (attempt === 0 && driver === "docker" && !netErr) {
-                const retry = await maybeReallocateAppSpecHostPort(appId, effectiveSpec, "docker_race");
-                if (retry.error)
-                    return { ok: false, error: retry.error };
-                if (retry.changed) {
-                    effectiveSpec = retry.spec;
-                    continue;
-                }
-            }
-            return { ok: false, error: submitError ?? "unknown error" };
-        }
-        return { ok: false, error: "start retry exhausted" };
-    }
-    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;
-    /**
-     * Poll until the app job leaves the "failed" state or times out.
-     * Used after start submission to verify actual recovery before reporting success.
-     * Returns true if the app transitions away from "failed" (to pending/running/etc).
-     */
-    async function waitForRecovery(appId, timeoutMs = 15_000, pollIntervalMs = 2_000) {
-        const deadline = Date.now() + timeoutMs;
-        while (Date.now() < deadline) {
-            await new Promise((r) => setTimeout(r, pollIntervalMs));
-            const status = await getAppStatus(appId);
-            if (status.status !== "failed")
-                return true;
-        }
-        return false;
-    }
-    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) {
-                const lingeringAlloc = await getRunningAlloc(appId);
-                if (!lingeringAlloc) {
-                    return { ok: true };
-                }
-                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;
-    /**
-     * Capability registration shim for **legacy** (non-app-installed)
-     * hermes/openclaw instances. Loads the synthetic spec via
-     * loadCapabilitySpecForLegacyInstance and routes provides through the
-     * app-manager registry helpers, so legacy instances surface in
-     * Connections candidate lists like app-installed ones.
-     *
-     * Errors are swallowed and logged — capability registration is best-
-     * effort; a failure here must not block start/stop.
-     */
-    async function registerLegacyCapabilities(instanceId) {
-        try {
-            const meta = getInstance(instanceId);
-            if (!meta)
-                return;
-            const { loadCapabilitySpecForLegacyInstance } = await import("./runtime/migrations.js");
-            const synthSpec = loadCapabilitySpecForLegacyInstance(meta);
-            if (!synthSpec?.provides?.length)
-                return;
-            // Same instance-name override + portOverride passthrough as
-            // registerLegacyCapabilitiesTopLevel — Connections candidates should
-            // show the user's instance name and advertise the actually-allocated
-            // gateway port (not the yaml default).
-            const instanceName = typeof meta.name === "string" && meta.name
-                ? meta.name
-                : instanceId;
-            const namedSpec = { ...synthSpec, name: instanceName };
-            const portOverride = getGatewayPort(instanceId);
-            const { registerCapabilities } = await import("./app/app-manager.js");
-            registerCapabilities(instanceId, namedSpec, portOverride > 0 ? portOverride : undefined);
-        }
-        catch (e) {
-            console.warn(`[legacy-capabilities] register failed for ${instanceId}: ${e?.message ?? e}`);
-        }
-    }
-    async function unregisterLegacyCapabilities(instanceId, purge) {
-        try {
-            const { markCapabilitiesStopped, unregisterCapabilities } = await import("./app/app-manager.js");
-            if (purge) {
-                unregisterCapabilities(instanceId);
-            }
-            else {
-                markCapabilitiesStopped(instanceId);
-            }
-        }
-        catch (e) {
-            console.warn(`[legacy-capabilities] unregister failed for ${instanceId}: ${e?.message ?? e}`);
-        }
-    }
-    async function startInstance(nomadJobId) {
-        const instanceBackedApp = await getInstanceBackedInstalledApp(nomadJobId);
-        if (instanceBackedApp) {
-            // PR 3 sub-step 3d: switch to resolveConnections in runtime mode so
-            // missing required producers / ambiguous prefix candidates throw with
-            // structured codes (412 / 409 / 400). Read the live instance.json so
-            // UI bindings persisted via PUT /connections (PR 4) drive the
-            // resolution; fall back to a stub `{ connections: {} }` when the
-            // instance file isn't readable yet.
-            let extraEnv = {};
-            try {
-                const { resolveConnections, resolvedToLegacyEnv } = await import("./connection-resolver.js");
-                const legacyInstanceManager = await import("./instance-manager.js");
-                const meta = legacyInstanceManager.getInstance(nomadJobId);
-                const instance = { connections: meta?.connections ?? {} };
-                // Validate in runtime mode so missing required / ambiguous still throws
-                // with structured error codes (412 / 409 / 400) before we touch Nomad.
-                const { resolved } = resolveConnections(instanceBackedApp.spec, instance, "runtime");
-                // Render the full RUNTIME_HOOKS env (covers llm/search/browser/mcp)
-                // rather than just the default-category subset, so apply: openai-env
-                // consumers (e.g. OpenWebUI) self-heal across provider port changes.
-                const { renderRuntimeConnectionsEnv } = await import("./connection-apply.js");
-                const runtimeEnv = await renderRuntimeConnectionsEnv(instanceBackedApp.spec, { id: nomadJobId, connections: instance.connections });
-                extraEnv = { ...resolvedToLegacyEnv(resolved), ...runtimeEnv };
-            }
-            catch (e) {
-                return {
-                    ok: false,
-                    error: e.message,
-                    ...(e.code ? { code: e.code } : {}),
-                    ...(typeof e.statusCode === "number" ? { statusCode: e.statusCode } : {}),
-                };
-            }
-            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))) {
-            const result = await instanceScheduler.startInstance(nomadJobId);
-            if (result.ok)
-                await registerLegacyCapabilities(nomadJobId);
-            return result;
-        }
-        if (nomadJobId.startsWith(OPENCLAW_PREFIX)) {
-            const inner = nomadJobId.slice(OPENCLAW_PREFIX.length);
-            const result = await instanceScheduler.startInstance(inner);
-            if (result.ok)
-                await registerLegacyCapabilities(inner);
-            return result;
-        }
-        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))) {
-            const result = await instanceScheduler.stopInstance(nomadJobId, purge);
-            if (result.ok || result.error?.includes("not running") || result.error?.includes("not found")) {
-                await unregisterLegacyCapabilities(nomadJobId, purge);
-            }
-            return result;
-        }
-        if (nomadJobId.startsWith(OPENCLAW_PREFIX)) {
-            const inner = nomadJobId.slice(OPENCLAW_PREFIX.length);
-            const result = await instanceScheduler.stopInstance(inner, purge);
-            if (result.ok || result.error?.includes("not running") || result.error?.includes("not found")) {
-                await unregisterLegacyCapabilities(inner, purge);
-            }
-            return result;
-        }
-        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))) {
-            const result = await instanceScheduler.restartInstance(nomadJobId);
-            if (result.ok)
-                await registerLegacyCapabilities(nomadJobId);
-            return result;
-        }
-        if (nomadJobId.startsWith(OPENCLAW_PREFIX)) {
-            const inner = nomadJobId.slice(OPENCLAW_PREFIX.length);
-            const result = await instanceScheduler.restartInstance(inner);
-            if (result.ok)
-                await registerLegacyCapabilities(inner);
-            return result;
-        }
-        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;
-// @internal — exposed for Phase 10.4 unit testing only.
-export const __aggregateHealthStatusForTests = UnifiedNomadJobs.aggregateHealthStatus;
-//# sourceMappingURL=nomad-manager.js.map