jishushell 0.5.22 → 0.6.18

package/dist/services/runtime/drivers/nomad.js

@@ -0,0 +1,3092 @@
+/**
+ * Nomad runtime driver — kind-agnostic scheduler layer.
+ *
+ * This file contains no direct knowledge of specific agent kinds. The runtime
+ * dispatch surface is now reduced to two compile-path primitives:
+ *
+ *     const kind = resolvePrimaryIntegrationKind(getInstance(id));
+ *     const integration = getIntegration(kind);
+ *     const persistedRuntime = await integration.getPersistedRuntimeSpec(id);
+ *     const contribution = await integration.buildRuntimeContribution?.(id);
+ *
+ * The persisted runtime spec + contribution are then handed to
+ * WorkloadCompiler, which is the single canonical task builder. The app
+ * lifecycle pipeline owns integration pre-start materialization before calling
+ * the prepared submit path; the legacy direct start wrapper still preserves the
+ * older runtime-local hook path until remaining callers are migrated.
+ */
+import { execFile as execFileCb, spawn } from "child_process";
+import { existsSync, readFileSync } from "fs";
+import { createServer as netCreateServer } from "net";
+import { homedir } from "os";
+import { basename, join } from "path";
+import { StringDecoder } from "string_decoder";
+import { promisify } from "util";
+import * as config from "../../../config.js";
+import { getPrimaryHostPort, getInstance, getInstanceRuntime, instanceMetaPath, getRuntimeEnv, isPortInUse, reallocatePrimaryHostPort, reallocateRuntimeHostPort, } from "../../instances/manager.js";
+import { getIntegration } from "../../integrations/index.js";
+import { resolveNomadJobId } from "../job-id.js";
+import { isExecutionOwnerRequiredError, resolveExecutionOwner, } from "../../app-common/execution-owner.js";
+import { readCanonicalSpecForInstance } from "../../app-common/instance-store.js";
+import { DEFINITION_FILENAME, MANIFEST_FILENAME, RESOLVED_SPEC_FILENAME, resolveAppDir, } from "../../app-common/paths.js";
+import { compileWorkload } from "../workload-compiler.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 getNomadAddrValue = getConfigValue("getNomadAddr");
+const getNomadDriverValue = getConfigValue("getNomadDriver");
+const getNomadTokenValue = getConfigValue("getNomadToken");
+const getCoreConfigValue = getConfigValue("getCoreConfig");
+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 getCoreConfig = typeof getCoreConfigValue === "function"
+    ? getCoreConfigValue
+    : () => ({});
+// 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 integration 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 integration 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 `integration.nomadJobPrefix` so
+ * every runtime owns its own namespace (`hermes-<id>`, `openclaw-<id>`,
+ * …). New integration runtimes should declare their own prefix on the
+ * integration rather than re-using another kind's.
+ */
+function jobPrefixFor(instanceId) {
+    const kind = getInstanceIntegrationKind(instanceId);
+    const integration = getIntegration(kind);
+    return integration.nomadJobPrefix ?? "jishushell-";
+}
+/**
+ * Per-instance Nomad Variable subpath. Returned without the leading
+ * `nomad/jobs/<jid>/` prefix. `undefined` means this integration does not
+ * use Nomad Variables — writeInstanceVariables/purgeInstanceVariables
+ * become no-ops.
+ */
+function integrationVariableSubpath(instanceId) {
+    const kind = getInstanceIntegrationKind(instanceId);
+    const integration = getIntegration(kind);
+    return integration.nomadVariablePath;
+}
+/**
+ * Resolve the Nomad task name for the given instance. Reads
+ * `integration.nomadTaskName` so framework code never hardcodes "gateway".
+ */
+function resolveTaskName(instanceId) {
+    const kind = getInstanceIntegrationKind(instanceId);
+    return getIntegration(kind).nomadTaskName ?? "gateway";
+}
+async function getInstanceInstallRecordForRuntime(instanceId) {
+    const { getInstanceInstallRecord } = await import("../../app-common/service.js");
+    return getInstanceInstallRecord(instanceId);
+}
+async function getIntegrationManagedInstanceRecord(instanceId) {
+    const installRecord = await getInstanceInstallRecordForRuntime(instanceId);
+    if (!installRecord)
+        return null;
+    const owner = tryResolveExecutionOwner(instanceId);
+    return owner?.type === "integration" ? installRecord : null;
+}
+function synthesizeCompileOnlyRuntimeAppSpec(input) {
+    const runtimeKind = typeof input.runtime.image === "string" && input.runtime.image.trim()
+        ? "container"
+        : "process";
+    return {
+        id: input.instanceId,
+        name: input.instanceId,
+        tasks: [{
+                name: input.taskName,
+                role: "service",
+                runtime: runtimeKind,
+            }],
+    };
+}
+async function compileIntegrationManagedJob(instanceId) {
+    const kind = getInstanceIntegrationKind(instanceId);
+    const integration = getIntegration(kind);
+    if (!integration.getPersistedRuntimeSpec) {
+        throw new Error(`Runtime integration "${kind}" must implement getPersistedRuntimeSpec() so WorkloadCompiler remains the only compile path`);
+    }
+    const persistedRuntime = await integration.getPersistedRuntimeSpec(instanceId);
+    const installRecord = await getIntegrationManagedInstanceRecord(instanceId);
+    const taskName = integration.nomadTaskName
+        ?? (installRecord ? primaryTaskNameForSpec(installRecord.spec) : "gateway");
+    const inferredRuntimeKind = typeof persistedRuntime.image === "string"
+        && String(persistedRuntime.image).trim()
+        ? "container"
+        : "process";
+    const spec = installRecord?.spec
+        ? {
+            ...installRecord.spec,
+            tasks: installRecord.spec.tasks.map((task, index) => (task.name === taskName || index === 0
+                ? {
+                    ...task,
+                    runtime: task.runtime ?? inferredRuntimeKind,
+                }
+                : task)),
+        }
+        : synthesizeCompileOnlyRuntimeAppSpec({
+            instanceId,
+            taskName,
+            runtime: persistedRuntime,
+        });
+    const compiled = compileWorkload({
+        instanceId,
+        jobId: jobId(instanceId),
+        groupName: kind,
+        spec,
+        runtimeByTaskName: {
+            [taskName]: persistedRuntime,
+        },
+        contribution: integration.buildRuntimeContribution
+            ? await integration.buildRuntimeContribution(instanceId)
+            : undefined,
+    });
+    const tasks = (compiled.nomadJob?.Job?.TaskGroups?.[0]?.Tasks ?? []);
+    const runtimeTask = tasks.find((task) => task?.Name === taskName) ?? tasks[0];
+    if (runtimeTask) {
+        await injectConnectionsRuntimeEnv(instanceId, runtimeTask);
+    }
+    return compiled.nomadJob;
+}
+function primaryTaskNameForSpec(spec, fallback = "gateway") {
+    return spec.tasks.find((task) => (task.role ?? "service") === "service")?.name
+        ?? spec.tasks[0]?.name
+        ?? fallback;
+}
+// Tracks the core server's listening port so bridge-mode containers can reach it via host.docker.internal.
+let _corePort = 8091;
+export function setCorePort(port) { _corePort = port; }
+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 } : {};
+}
+// Integration dispatch: scheduler-level defaults and resource ceilings. Runtime
+// command / args / env / resources now live inside each integration's
+// `buildNomadTask` — the Nomad driver never looks at them directly.
+function jobId(instanceId) {
+    return resolveNomadJobId(instanceId, jobPrefixFor(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 = integrationVariableSubpath(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
+    // runtime submit 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 = integrationVariableSubpath(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); integrations 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()}`;
+}
+// Integration dispatch:
+//   The previous ~380 lines of OpenClaw / Hermes task assembly
+//   (`buildRuntime`, `buildTaskDocker`, `buildHermesTaskDocker`, resource
+//   normalizer, kind detector) have been physically migrated into
+//   `src/services/integrations/{openclaw,hermes}/integration.ts:buildNomadTask()`.
+//   Framework code here is now a pure dispatcher: it asks the integration for
+//   a Nomad task definition and embeds it in the job spec below.
+function getInstanceIntegrationKind(instanceId) {
+    const owner = tryResolveExecutionOwner(instanceId);
+    if (owner?.type === "integration") {
+        return owner.integrationKind;
+    }
+    throw new Error(missingExecutionOwnerMessage(instanceId));
+}
+function tryResolveExecutionOwner(instanceId) {
+    try {
+        return resolveExecutionOwner(instanceId);
+    }
+    catch (error) {
+        if (isExecutionOwnerRequiredError(error))
+            return null;
+        throw error;
+    }
+}
+function missingExecutionOwnerMessage(instanceId) {
+    return `Instance '${instanceId}' is missing canonical execution owner; run migration or repair before using the runtime path.`;
+}
+async function buildJob(instanceId) {
+    const driver = getNomadDriver();
+    if (driver !== "docker") {
+        throw new Error(`Unsupported Nomad driver: ${driver}. Only "docker" is supported.`);
+    }
+    return compileIntegrationManagedJob(instanceId);
+}
+/**
+ * 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 { readCanonicalSpecForInstance } = await import("../../app-common/instance-store.js");
+        const spec = readCanonicalSpecForInstance(instanceId);
+        if (!spec)
+            return;
+        const { resolveConnections } = await import("../../connections/resolver.js");
+        const { resolved } = resolveConnections(spec, { connections }, "preCreate");
+        if (resolved.length === 0)
+            return;
+        const { RUNTIME_HOOKS } = await import("../../connections/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 LLM 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 integration so
+ * framework code carries no kind-specific knowledge. Integrations that
+ * do not share an integration-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 integration-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) {
+    let desiredPort;
+    try {
+        desiredPort = getPrimaryHostPort(instanceId);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: e?.message || `Instance '${instanceId}' has no canonical primary host port allocation`,
+            ...(typeof e?.code === "string" ? { code: e.code } : {}),
+            ...(typeof e?.statusCode === "number" ? { statusCode: e.statusCode } : {}),
+        };
+    }
+    if (!(await isPortInUse(desiredPort)))
+        return { ok: true, portAllocation: null };
+    try {
+        const re = await reallocatePrimaryHostPort(instanceId);
+        return { ok: true, portAllocation: { from: re.from, to: re.to, reason: "host_port_busy" } };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: `Primary host port ${desiredPort} is held by another process and reallocation failed: ${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++) {
+        let jobDef;
+        try {
+            jobDef = await buildJob(instanceId);
+        }
+        catch (e) {
+            return {
+                ok: false,
+                error: e?.message || `Failed to build Nomad job for ${instanceId}`,
+                ...(typeof e?.code === "string" ? { code: e.code } : {}),
+                ...(typeof e?.statusCode === "number" ? { statusCode: e.statusCode } : {}),
+            };
+        }
+        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;
+        }
+        let currentPrimaryHostPort = null;
+        try {
+            currentPrimaryHostPort = getPrimaryHostPort(instanceId);
+        }
+        catch (e) {
+            return {
+                ok: false,
+                error: e?.message || `Instance '${instanceId}' has no canonical primary host port allocation`,
+                ...(typeof e?.code === "string" ? { code: e.code } : {}),
+                ...(typeof e?.statusCode === "number" ? { statusCode: e.statusCode } : {}),
+            };
+        }
+        if (attempt === 0 && !netErr && currentPrimaryHostPort != null && (await isPortInUse(currentPrimaryHostPort))) {
+            try {
+                const re = await reallocatePrimaryHostPort(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" };
+}
+async function submitPreparedIntegrationJob(instanceId) {
+    return startPreparedInstance(instanceId);
+}
+async function startPreparedInstance(instanceId) {
+    const owner = tryResolveExecutionOwner(instanceId);
+    if (owner && owner.type !== "integration") {
+        return { ok: false, error: `App '${instanceId}' 必须通过 lifecycle-service 启动` };
+    }
+    if (owner?.type !== "integration") {
+        return { ok: false, error: missingExecutionOwnerMessage(instanceId) };
+    }
+    const failed = (phase, rest) => {
+        console.log(`[nomad] ${instanceId}: prepared start 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 kind = getInstanceIntegrationKind(instanceId);
+    const integration = getIntegration(kind);
+    const home = await phaseHomeConflict(instanceId, integration.findInstancesSharingHome?.(instanceId) ?? []);
+    if (!home.ok)
+        return failed("home_conflict", { error: home.error });
+    const port = await phasePortAlloc(instanceId);
+    if (!port.ok) {
+        const extra = { error: port.error };
+        if (port.code)
+            extra.code = port.code;
+        if (typeof port.statusCode === "number")
+            extra.statusCode = port.statusCode;
+        return failed("port_alloc", extra);
+    }
+    const submit = await phaseSubmit(instanceId, port.portAllocation);
+    if (!submit.ok) {
+        const extra = { error: submit.error };
+        if (submit.code)
+            extra.code = submit.code;
+        if (typeof submit.statusCode === "number")
+            extra.statusCode = submit.statusCode;
+        return failed("submit", extra);
+    }
+    return {
+        ok: true,
+        eval_id: submit.evalId,
+        ...(submit.portAllocation ? { port_allocation: submit.portAllocation } : {}),
+    };
+}
+async function stopPreparedIntegrationJob(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 */ }
+            }
+            // No capability-sync on stop — lifecycle/status observation owns registry projection.
+            // Stop callers (`waitForObservedStatus("stopped")`) drive observer
+            // ticks until the registry reflects `status: "stopped"` and the
+            // reverse proxy stops routing to the dead allocation.
+            return { ok: true };
+        }
+        if (resp.status === 404) {
+            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 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, options = {}) {
+    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 unless the caller
+    // explicitly requested a docker-exec user.
+    const runtime = getInstanceRuntime(instanceId);
+    const userFlag = options.user ?? 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,
+        };
+    }
+}
+/**
+ * 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 ceiling = config.getMaxAppMemoryMB();
+    const requestedMemoryMB = Number(runtime.resources?.MemoryMB ?? 512);
+    let effectiveMemoryMB = Math.min(requestedMemoryMB, ceiling);
+    let effectiveMemoryMaxMB = Math.min(Number(runtime.resources?.MemoryMaxMB ?? requestedMemoryMB), ceiling);
+    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 working while preserving a single driver implementation.
+export { jobId, resolveUidGid, nomadGet, nomadPut, assertSafeTemplateId, };
+const instanceScheduler = {
+    getStatus,
+    submitIntegrationRuntimeJob: submitPreparedIntegrationJob,
+    startPreparedInstance,
+    stopIntegrationRuntimeJob: stopPreparedIntegrationJob,
+    getLogs,
+    exec,
+};
+var UnifiedNomadJobs;
+(function (UnifiedNomadJobs) {
+    // ── Constants ─────────────────────────────────────────────────────────────
+    // 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
+    // Memory ceilings read from core.json at runtime via config.getMaxAppMemoryMB().
+    const DEFAULT_PIDS_LIMIT = 512;
+    const NOMAD_CONFIG_PATH = join(JISHUSHELL_HOME, "nomad", "nomad.hcl");
+    const _DEFAULT_CWD = homedir();
+    function isAppJob(id) {
+        const owner = tryResolveExecutionOwner(id);
+        return owner?.type === "app-job";
+    }
+    UnifiedNomadJobs.isAppJob = isAppJob;
+    function findInstalledRuntimeRoot(instanceId) {
+        const dir = resolveAppDir(instanceId);
+        const hasCanonicalSpec = existsSync(join(dir, RESOLVED_SPEC_FILENAME))
+            || existsSync(join(dir, DEFINITION_FILENAME));
+        if (existsSync(join(dir, MANIFEST_FILENAME)) && hasCanonicalSpec) {
+            return dir;
+        }
+        return null;
+    }
+    // ── Job ID ────────────────────────────────────────────────────────────────
+    function jobId(instanceId) {
+        return instanceId;
+    }
+    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, config.getMaxAppMemoryMB()));
+    }
+    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 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 requiredHostNetworkForPort(port) {
+        if ((port.visibility ?? "external") === "internal")
+            return null;
+        const requested = (port.host_network ?? "").trim();
+        return requested || "external";
+    }
+    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 validation rejects the start before
+        // job submission. Falls back to "external" only when no explicit
+        // host_network was requested.
+        const requested = (port.host_network ?? "").trim();
+        if (requested)
+            return nomadConfigDeclaresHostNetwork(requested) ? requested : undefined;
+        return nomadConfigDeclaresHostNetwork("external") ? "external" : undefined;
+    }
+    function requiredHostNetworksForPorts(ports) {
+        const required = new Set();
+        for (const port of ports) {
+            const network = requiredHostNetworkForPort(port);
+            if (network)
+                required.add(network);
+        }
+        return required;
+    }
+    async function validateNomadPortHostNetworks(ports) {
+        const requiredNetworks = requiredHostNetworksForPorts(ports);
+        if (requiredNetworks.size === 0)
+            return null;
+        for (const network of requiredNetworks) {
+            if (!nomadConfigDeclaresHostNetwork(network)) {
+                return `Nomad 配置缺少 host_network "${network}"。请重新运行/修复 JishuShell 设置并重启 Nomad，再启动该应用。`;
+            }
+        }
+        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));
+            for (const network of requiredNetworks) {
+                if (!loadedNetworks.has(network)) {
+                    return `Nomad 运行中的 agent 尚未加载 host_network "${network}"。请先重启 Nomad，再启动该应用。`;
+                }
+            }
+        }
+        catch {
+            // Let the later job submission path report Nomad unreachable when needed.
+        }
+        return null;
+    }
+    UnifiedNomadJobs.validateNomadPortHostNetworks = validateNomadPortHostNetworks;
+    async function validateRequiredHostNetworks(spec) {
+        return validateNomadPortHostNetworks(spec.tasks.flatMap((task) => task.ports ?? []));
+    }
+    function buildNomadReservedPort(input) {
+        const hostNetwork = hostNetworkForPort(input);
+        return {
+            Label: input.label,
+            Value: input.value,
+            ...(input.to != null ? { To: input.to } : {}),
+            ...(hostNetwork ? { HostNetwork: hostNetwork } : {}),
+        };
+    }
+    UnifiedNomadJobs.buildNomadReservedPort = buildNomadReservedPort;
+    async function maybeReallocateConflictingRuntimePorts(instanceId, reason) {
+        if (!getInstance(instanceId))
+            return { changed: false };
+        const runtime = getInstanceRuntime(instanceId);
+        const ports = Array.isArray(runtime?.ports)
+            ? runtime.ports.filter((port) => (port?.visibility ?? "external") !== "internal")
+            : [];
+        if (ports.length === 0) {
+            return { changed: false };
+        }
+        let changed = false;
+        const seen = new Set();
+        for (const port of ports) {
+            const currentHostPort = port?.hostPort;
+            if (!Number.isInteger(currentHostPort) || currentHostPort <= 0) {
+                return {
+                    changed,
+                    error: `Instance '${instanceId}' has an invalid canonical hostPort for ${port?.taskName ?? "task"}/${port?.name ?? "port"}`,
+                };
+            }
+            const conflictsWithOwnPort = seen.has(currentHostPort);
+            seen.add(currentHostPort);
+            if (!conflictsWithOwnPort && !(await isPortInUse(currentHostPort)))
+                continue;
+            try {
+                const reallocation = await reallocateRuntimeHostPort(instanceId, {
+                    ...(typeof port.taskName === "string" ? { taskName: port.taskName } : {}),
+                    name: String(port.name || ""),
+                });
+                seen.add(reallocation.to);
+                changed = true;
+                console.log(`[nomad] ${instanceId}: reallocated canonical port ${port?.taskName ?? "task"}/${port?.name ?? "port"} ` +
+                    `${reallocation.from} -> ${reallocation.to} (${reason})`);
+            }
+            catch (e) {
+                return {
+                    changed,
+                    error: `Canonical port ${currentHostPort} for ${port?.taskName ?? "task"}/${port?.name ?? "port"} ` +
+                        `is held by another process and reallocation failed: ${e?.message ?? e}`,
+                };
+            }
+        }
+        return { changed };
+    }
+    // ── 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) {
+        const result = {};
+        for (const [k, v] of Object.entries(taskEnv)) {
+            result[k] = v.replace(/\$\{requires\.([^}]+)\}/g, (_, key) => extraEnv[key] ?? "");
+        }
+        return result;
+    }
+    function materializeInstanceIdTokens(value, instanceId) {
+        if (typeof value === "string") {
+            return value.replace(/\$\{instance\.id\}/g, instanceId);
+        }
+        if (Array.isArray(value)) {
+            return value.map((entry) => materializeInstanceIdTokens(entry, instanceId));
+        }
+        if (value && typeof value === "object") {
+            const result = {};
+            for (const [key, entry] of Object.entries(value)) {
+                result[key] = materializeInstanceIdTokens(entry, instanceId);
+            }
+            return result;
+        }
+        return value;
+    }
+    // ── 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 submitGenericAppSpecJob 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 loadCanonicalSpecForInstance(instanceId) {
+        return findInstalledRuntimeRoot(instanceId) ? readCanonicalSpecForInstance(instanceId) : 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(instanceId, 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: `${instanceId}-${task.name}`,
+                output: `external probe: HTTP ${resp.status}`,
+            };
+        }
+        catch (e) {
+            return {
+                name: `${task.name}-health`,
+                status: "failure",
+                service: `${instanceId}-${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 stopExternalProcessInstance(instanceId) {
+        const spec = loadCanonicalSpecForInstance(instanceId);
+        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(instanceId, 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(instanceId, 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 inspectExternalProcessInstance(instanceId, spec) {
+        if (!findInstalledRuntimeRoot(instanceId)) {
+            return { detected: false, conflicts: [], status: null };
+        }
+        const appSpec = spec ?? loadCanonicalSpecForInstance(instanceId);
+        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(instanceId, 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 buildExternalAdoptedInstanceSpec(instanceId, spec) {
+        if (!findInstalledRuntimeRoot(instanceId)) {
+            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(instanceId, 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,
+        };
+    }
+    // ── Job builder ───────────────────────────────────────────────────────────
+    /**
+     * Build a complete Nomad job payload from an AppSpec.
+     *
+     * @param spec      The validated AppSpec.
+     * @param instanceId     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, instanceId, _driver, extraEnv) {
+        const runtimeByTaskName = buildRuntimePortViewByTaskName(instanceId, spec);
+        return compileWorkload({
+            instanceId,
+            jobId: jobId(instanceId),
+            groupName: spec.id,
+            spec,
+            extraEnv,
+            runtimeByTaskName,
+        }).nomadJob;
+    }
+    function buildRuntimePortViewByTaskName(instanceId, spec) {
+        const runtime = getInstanceRuntime(instanceId);
+        const ports = Array.isArray(runtime?.ports) ? runtime.ports : [];
+        if (ports.length === 0)
+            return undefined;
+        const primaryTask = spec.tasks.find((task) => (task.role ?? "service") === "service") ?? spec.tasks[0];
+        const out = {};
+        for (const task of spec.tasks) {
+            const taskPorts = ports.filter((port) => port?.taskName === task.name
+                || (port?.taskName === undefined
+                    && task.name === primaryTask?.name));
+            if (taskPorts.length === 0)
+                continue;
+            out[task.name] = {
+                ports: taskPorts,
+                ...(task.name === primaryTask?.name && runtime?.health ? { health: runtime.health } : {}),
+            };
+        }
+        return Object.keys(out).length > 0 ? out : undefined;
+    }
+    // ── Alloc helpers ─────────────────────────────────────────────────────────
+    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 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, instanceId) {
+        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 taskNamePrefix = `${instanceId}-`;
+        if (serviceName.startsWith(taskNamePrefix)) {
+            const candidate = serviceName.slice(taskNamePrefix.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(instanceId) {
+        return pickLiveAlloc(await getAllocs(instanceId));
+    }
+    // ── 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(instanceId) {
+        const jid = jobId(instanceId);
+        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 instanceId       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 getInstanceInstallRecordStatus(instanceId, primaryTask) {
+        const jid = jobId(instanceId);
+        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(instanceId);
+        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 inspectExternalProcessInstance(instanceId);
+            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, instanceId);
+            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.getInstanceInstallRecordStatus = getInstanceInstallRecordStatus;
+    // ── 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/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 instanceId    Unique instance ID (job name suffix).
+     * @param extraEnv Env vars injected into every task (e.g. resolved capability addresses).
+     */
+    async function submitGenericAppSpecJob(spec, instanceId, extraEnv = {}) {
+        const status = await getInstanceInstallRecordStatus(instanceId);
+        const adoptedExternal = await buildExternalAdoptedInstanceSpec(instanceId, spec);
+        if (adoptedExternal.conflicts.length > 0) {
+            return { ok: false, error: adoptedExternal.conflicts.join("; ") };
+        }
+        let effectiveSpec = adoptedExternal.spec;
+        // Validate all images before submitting
+        for (const task of effectiveSpec.tasks) {
+            if (task.runtime === "container") {
+                if (!task.image || !UnifiedNomadJobs.DOCKER_IMAGE_RE.test(task.image) || task.image.length > UnifiedNomadJobs.MAX_DOCKER_IMAGE_NAME_LEN) {
+                    return { ok: false, error: `Task "${task.name}": invalid docker image "${task.image ?? ""}"` };
+                }
+            }
+        }
+        // Determine predominant driver (first service task wins)
+        const primaryTask = effectiveSpec.tasks.find((t) => (t.role ?? "service") === "service") ?? effectiveSpec.tasks[0];
+        const driver = primaryTask?.runtime === "container" ? "docker" : "raw_exec";
+        // Ensure the required Nomad driver is healthy; restart Nomad if needed.
+        const driverOk = await ensureNomadDriverHealthy(driver);
+        if (!driverOk) {
+            if (driver === "raw_exec") {
+                const rawExecError = await validateRawExecDriverAvailability();
+                if (rawExecError) {
+                    return { ok: false, error: rawExecError };
+                }
+            }
+            return { ok: false, error: `Nomad driver "${driver}" is not available. Check Nomad configuration and restart Nomad.` };
+        }
+        const hostNetworkError = await validateRequiredHostNetworks(effectiveSpec);
+        if (hostNetworkError) {
+            return { ok: false, error: hostNetworkError };
+        }
+        if (status.status !== "running") {
+            const preflight = await maybeReallocateConflictingRuntimePorts(instanceId, "host_port_busy");
+            if (preflight.error)
+                return { ok: false, error: preflight.error };
+        }
+        for (let attempt = 0; attempt < 2; attempt++) {
+            let jobDef;
+            try {
+                jobDef = buildAppJob(effectiveSpec, instanceId, 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(instanceId, 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 maybeReallocateConflictingRuntimePorts(instanceId, "docker_race");
+                if (retry.error)
+                    return { ok: false, error: retry.error };
+                if (retry.changed) {
+                    continue;
+                }
+            }
+            return { ok: false, error: submitError ?? "unknown error" };
+        }
+        return { ok: false, error: "start retry exhausted" };
+    }
+    UnifiedNomadJobs.submitGenericAppSpecJob = submitGenericAppSpecJob;
+    /**
+     * 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(instanceId, timeoutMs = 120_000, pollIntervalMs = 3_000) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const status = await getInstanceInstallRecordStatus(instanceId);
+            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(instanceId, 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 getInstanceInstallRecordStatus(instanceId);
+            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 getInstanceInstallRecordStatus(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 stopGenericAppSpecJob(instanceId, purge = false) {
+        const jid = jobId(instanceId);
+        const liveAllocIds = (await getAllocs(instanceId))
+            .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 stopExternalProcessInstance(instanceId);
+        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(instanceId);
+                if (!lingeringAlloc) {
+                    return { ok: true };
+                }
+                return { ok: false, error: `App '${instanceId}' 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.stopGenericAppSpecJob = stopGenericAppSpecJob;
+    /**
+     * Fetch recent log lines for a task in an app job.
+     *
+     * @param instanceId    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 getInstanceInstallRecordLogs(instanceId, taskName = "", lines = 200, logType = "stderr") {
+        if (!UnifiedNomadJobs.VALID_LOG_TYPES.has(logType))
+            logType = "stderr";
+        let alloc = await getRunningAlloc(instanceId);
+        // If no running alloc, try the most recent alloc (for post-mortem logs).
+        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 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.getInstanceInstallRecordLogs = getInstanceInstallRecordLogs;
+    // ── 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 instanceId     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(instanceId, taskName = "", command, timeoutMs = 120_000, options = {}) {
+        const alloc = await getRunningAlloc(instanceId);
+        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 { getInstanceInstallRecord } = await import("../../app-common/service.js");
+        const appData = getInstanceInstallRecord(instanceId);
+        const matchedTask = appData?.spec.tasks.find((t) => t.name === resolvedTask);
+        if (matchedTask?.runtime === "process") {
+            if (options.user) {
+                return {
+                    stdout: "",
+                    stderr: "app exec --user is only supported for container runtime tasks",
+                    exitCode: 1,
+                };
+            }
+            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}`;
+        const dockerExecArgs = options.user
+            ? ["exec", "--user", options.user, containerName, ...command]
+            : ["exec", containerName, ...command];
+        try {
+            const { stdout, stderr } = await execFileAsync("docker", dockerExecArgs, { 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,
+                };
+            }
+            if (options.user) {
+                return {
+                    stdout: e.stdout ?? "",
+                    stderr: `app exec --user requires Docker exec support for task "${resolvedTask}"`,
+                    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(instanceId, taskName = "", command, handlers = {}, timeoutMs = 120_000) {
+        const alloc = await getRunningAlloc(instanceId);
+        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 { getInstanceInstallRecord } = await import("../../app-common/service.js");
+        const appData = getInstanceInstallRecord(instanceId);
+        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 { }
+        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 = getCoreConfig().nomad_token;
+        if (legacy)
+            process.env.NOMAD_TOKEN = legacy;
+    }
+    UnifiedNomadJobs.ensureNomadToken = ensureNomadToken;
+    // A historical instance-start helper lived here as a parallel lifecycle
+    // codepath. It was superseded by lifecycle-service, then removed during the
+    // canonical-only refactor because it duplicated capability-registry writes.
+    // If a similar entrypoint is needed again, build it on top of lifecycle-service
+    // so it inherits the observer-driven invariants.
+    async function getInstanceStatus(nomadJobId) {
+        const owner = tryResolveExecutionOwner(nomadJobId);
+        if (owner?.type === "app-job") {
+            const st = await getInstanceInstallRecordStatus(nomadJobId);
+            return {
+                status: st.status,
+                pid: st.pid,
+                uptime: st.uptime,
+                memory_mb: st.memory_mb,
+                cpu_percent: st.cpu_percent,
+            };
+        }
+        if (owner?.type === "integration") {
+            return instanceScheduler.getStatus(nomadJobId);
+        }
+        // Raw backend signal only. `status-refresh` translates this into the
+        // canonical product status `{ phase: "failed", reason: "needs-migration" }`
+        // before anything is persisted to instance.json.
+        return {
+            status: "needs-migration",
+            pid: null,
+            uptime: null,
+            memory_mb: null,
+            cpu_percent: null,
+        };
+    }
+    UnifiedNomadJobs.getInstanceStatus = getInstanceStatus;
+    async function submitIntegrationRuntimeJob(nomadJobId) {
+        // No event-path capability-sync. The shared status-observation path projects
+        // capability-registry entries while lifecycle/API callers wait for or request
+        // current status. Raw integration workload submission follows the same
+        // observer convention as generic app jobs.
+        const owner = tryResolveExecutionOwner(nomadJobId);
+        if (owner?.type === "app-job") {
+            return { ok: false, error: `App '${nomadJobId}' 必须通过 lifecycle-service 启动` };
+        }
+        if (owner?.type === "integration") {
+            return await instanceScheduler.submitIntegrationRuntimeJob(nomadJobId);
+        }
+        return { ok: false, error: missingExecutionOwnerMessage(nomadJobId) };
+    }
+    UnifiedNomadJobs.submitIntegrationRuntimeJob = submitIntegrationRuntimeJob;
+    async function stopIntegrationRuntimeJob(nomadJobId, purge = false) {
+        // No event-path capability-sync — see submitIntegrationRuntimeJob.
+        const owner = tryResolveExecutionOwner(nomadJobId);
+        if (owner?.type === "app-job") {
+            return { ok: false, error: `App '${nomadJobId}' 必须通过 lifecycle-service 停止` };
+        }
+        if (owner?.type === "integration") {
+            return await instanceScheduler.stopIntegrationRuntimeJob(nomadJobId, purge);
+        }
+        return { ok: false, error: missingExecutionOwnerMessage(nomadJobId) };
+    }
+    UnifiedNomadJobs.stopIntegrationRuntimeJob = stopIntegrationRuntimeJob;
+    async function getInstanceLogs(nomadJobId, lines = 200, logType = "stderr") {
+        const owner = tryResolveExecutionOwner(nomadJobId);
+        if (owner?.type === "app-job") {
+            return getInstanceInstallRecordLogs(nomadJobId, "", lines, logType);
+        }
+        if (owner?.type === "integration") {
+            return instanceScheduler.getLogs(nomadJobId, lines, logType);
+        }
+        return [];
+    }
+    UnifiedNomadJobs.getInstanceLogs = getInstanceLogs;
+    async function execInInstance(nomadJobId, command, timeoutMs, options = {}) {
+        const owner = tryResolveExecutionOwner(nomadJobId);
+        if (owner?.type === "app-job") {
+            return execInApp(nomadJobId, "", command, timeoutMs ?? 120_000, options);
+        }
+        if (owner?.type === "integration") {
+            return instanceScheduler.exec(nomadJobId, command, timeoutMs, options);
+        }
+        return {
+            stdout: "",
+            stderr: missingExecutionOwnerMessage(nomadJobId),
+            exitCode: 1,
+        };
+    }
+    UnifiedNomadJobs.execInInstance = execInInstance;
+    async function streamExecInInstance(nomadJobId, command, handlers = {}, timeoutMs, taskName = "") {
+        const owner = tryResolveExecutionOwner(nomadJobId);
+        if (owner?.type === "app-job") {
+            return streamExecInApp(nomadJobId, taskName, command, handlers, timeoutMs ?? 120_000);
+        }
+        if (owner?.type === "integration") {
+            const result = await instanceScheduler.exec(nomadJobId, command, timeoutMs);
+            if (result.stdout)
+                handlers.onStdout?.(result.stdout);
+            if (result.stderr)
+                handlers.onStderr?.(result.stderr);
+            return result;
+        }
+        const stderr = missingExecutionOwnerMessage(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 getInstanceInstallRecordStatus = UnifiedNomadJobs.getInstanceInstallRecordStatus;
+export const submitGenericAppSpecJob = UnifiedNomadJobs.submitGenericAppSpecJob;
+export const waitForRunning = UnifiedNomadJobs.waitForRunning;
+export const checkDependencies = UnifiedNomadJobs.checkDependencies;
+export const validateNomadPortHostNetworks = UnifiedNomadJobs.validateNomadPortHostNetworks;
+export const buildNomadReservedPort = UnifiedNomadJobs.buildNomadReservedPort;
+export const stopGenericAppSpecJob = UnifiedNomadJobs.stopGenericAppSpecJob;
+export const getInstanceInstallRecordLogs = UnifiedNomadJobs.getInstanceInstallRecordLogs;
+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 submitIntegrationRuntimeJob = UnifiedNomadJobs.submitIntegrationRuntimeJob;
+export const stopIntegrationRuntimeJob = UnifiedNomadJobs.stopIntegrationRuntimeJob;
+// @internal — exposed for Phase 10.4 unit testing only.
+export const __aggregateHealthStatusForTests = UnifiedNomadJobs.aggregateHealthStatus;
+//# sourceMappingURL=nomad.js.map