jishushell 0.5.15 → 0.6.5

package/dist/services/nomad-manager.js

@@ -20,8 +20,10 @@ import { StringDecoder } from "string_decoder";
 import { promisify } from "util";
 import { parse } from "yaml";
 import * as config from "../config.js";
-import { getGatewayPort, getInstance, getInstanceRuntime, instanceMetaPath, getRuntimeEnv, isPortInUse, reallocateGatewayPort, } from "./instance-manager.js";
+import { extractGatewayPort, getGatewayPort, getInstance, getInstanceRuntime, instanceMetaPath, getRuntimeEnv, isPortInUse, reallocateGatewayPort, } from "./instance-manager.js";
 import { getAdapter, resolveAgentType } from "./runtime/index.js";
+import { resolveNomadJobId } from "./runtime/job-id.js";
+import { resolveRuntimeIdentity } from "./runtime-identity.js";
 function getConfigValue(name) {
     return name in config ? config[name] : undefined;
 }
@@ -34,7 +36,7 @@ const _INSTANCES_DIR = resolveConfigPath(getConfigValue("INSTANCES_DIR"), join(J
 const getNomadAddrValue = getConfigValue("getNomadAddr");
 const getNomadDriverValue = getConfigValue("getNomadDriver");
 const getNomadTokenValue = getConfigValue("getNomadToken");
-const getPanelConfigValue = getConfigValue("getPanelConfig");
+const getCoreConfigValue = getConfigValue("getCoreConfig");
 const getNomadAddr = typeof getNomadAddrValue === "function"
     ? getNomadAddrValue
     : () => "http://127.0.0.1:4646";
@@ -44,8 +46,8 @@ const getNomadDriver = typeof getNomadDriverValue === "function"
 const getNomadToken = typeof getNomadTokenValue === "function"
     ? getNomadTokenValue
     : () => "";
-const getPanelConfig = typeof getPanelConfigValue === "function"
-    ? getPanelConfigValue
+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\-_.:/@]*$/;
@@ -111,6 +113,9 @@ function resolveTaskName(instanceId) {
     }
 }
 function getLegacyManagedAppType(instanceId) {
+    const identity = resolveRuntimeIdentity(instanceId);
+    if (identity?.installMode === "app-dir")
+        return null;
     const meta = getInstance(instanceId);
     const appType = typeof meta?.app_type === "string" ? meta.app_type.trim() : "";
     return appType === "custom" || appType === "ollama" ? appType : null;
@@ -136,9 +141,16 @@ async function getAppDirInstalledApp(instanceId) {
         return null;
     return appData;
 }
-// Tracks the panel's listening port so bridge-mode containers can reach it via host.docker.internal.
-let _panelPort = 8090;
-export function setPanelPort(port) { _panelPort = port; }
+async function getAdapterManagedAppDirInstalledApp(instanceId) {
+    const appData = await getAppDirInstalledApp(instanceId);
+    if (!appData)
+        return null;
+    const identity = resolveRuntimeIdentity(instanceId);
+    return identity?.driver === "runtime-adapter" ? appData : null;
+}
+// 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; }
 // §32.2 / §32.8: patchJsproxyBaseUrl / patchDockerBridgeGatewayBind /
 // ensureOpenclawUpdateSeed previously lived here (~140 lines). They are now
 // owned by `src/services/runtime/adapters/openclaw.ts` and invoked via
@@ -249,12 +261,7 @@ function nomadAuthHeaders() {
 // command / args / env / resources now live inside each adapter's
 // `buildNomadTask` — nomad-manager never looks at them directly.
 function jobId(instanceId) {
-    const prefix = jobPrefixFor(instanceId);
-    if (!prefix)
-        return instanceId;
-    if (instanceId.startsWith(prefix))
-        return instanceId;
-    return `${prefix}${instanceId}`;
+    return resolveNomadJobId(instanceId, jobPrefixFor(instanceId));
 }
 /** Exported only for unit tests — not part of the public API. */
 export function __jobIdForTests(instanceId) {
@@ -540,24 +547,35 @@ async function injectConnectionsRuntimeEnv(instanceId, task) {
     }
 }
 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 null;
+            return [];
         const allocs = await resp.json();
-        for (const status of ["running", "pending"]) {
-            for (const alloc of allocs) {
-                if (alloc.ClientStatus === status)
-                    return alloc;
-            }
-        }
-        return null;
+        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) {
@@ -570,7 +588,7 @@ export async function shouldAutoStart(instanceId) {
         //       on-disk instance config is still present and MUST be
         //       resubmitted on the next jishushell startup, otherwise every
         //       OpenClaw instance silently disappears after the upgrade.
-        //   (b) Brand-new instance created without a default_provider, never
+        //   (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
@@ -604,7 +622,12 @@ export async function getStatus(instanceId) {
     catch {
         return { ...stopped, status: "unknown", error: "Nomad unreachable" };
     }
-    const alloc = await getRunningAlloc(instanceId);
+    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;
@@ -642,32 +665,19 @@ export async function getStatus(instanceId) {
         }
     }
     catch { /* ignore */ }
-    // Fallback: Nomad cgroup stats are often zero on cgroup v2 (e.g. Raspberry Pi).
-    // Use `docker stats` directly when Nomad reports 0.
-    if (!result.memory_mb && allocId) {
-        try {
-            // Validate allocId to prevent shell injection (Nomad UUIDs are hex + hyphens)
-            if (!/^[a-f0-9-]+$/i.test(allocId))
-                throw new Error("invalid allocId");
-            const containerName = `${resolveTaskName(instanceId)}-${allocId}`;
-            const { execFile } = await import("child_process");
-            const { promisify } = await import("util");
-            const execFileAsync = promisify(execFile);
-            const { stdout } = await execFileAsync("docker", ["stats", "--no-stream", "--format", "{{.MemUsage}}", containerName], { timeout: 5000 });
-            const raw = stdout.trim();
-            // Format: "499.6MiB / 3GiB" or "123.4MB / 2GB"
-            const match = raw.match(/^([\d.]+)\s*(MiB|GiB|MB|GB|KiB|KB)/i);
-            if (match) {
-                let mb = parseFloat(match[1]);
-                const unit = match[2].toLowerCase();
-                if (unit === "gib" || unit === "gb")
-                    mb *= 1024;
-                else if (unit === "kib" || unit === "kb")
-                    mb /= 1024;
-                result.memory_mb = Math.round(mb * 10) / 10;
-            }
+    // 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;
         }
-        catch { /* ignore */ }
     }
     return result;
 }
@@ -679,6 +689,20 @@ async function phaseRunningCheck(instanceId) {
     }
     return { ok: true };
 }
+async function phaseResetTerminalJobBeforeStart(instanceId) {
+    const status = await getStatus(instanceId);
+    if (!["failed", "dead", "complete"].includes(String(status.status)))
+        return;
+    try {
+        const resp = await nomadDelete(`/v1/job/${jobId(instanceId)}?purge=false`);
+        if (!resp.ok && resp.status !== 404) {
+            console.warn(`[nomad] ${instanceId}: failed to stop terminal job before start (HTTP ${resp.status}): ${await resp.text()}`);
+        }
+    }
+    catch (e) {
+        console.warn(`[nomad] ${instanceId}: failed to stop terminal job before start: ${e?.message ?? e}`);
+    }
+}
 /**
  * Phase 2: home-conflict check — dispatched through the adapter so
  * framework code carries no agentType-specific knowledge. Adapters that
@@ -737,9 +761,21 @@ async function phasePreStartHook(adapter, instanceId) {
     }
     catch (e) {
         if (e && typeof e === "object" && e.building && e.taskId) {
-            return { ok: false, error: e.message, building: true, taskId: e.taskId };
+            return {
+                ok: false,
+                error: e.message,
+                building: true,
+                taskId: e.taskId,
+                ...(typeof e.code === "string" ? { code: e.code } : {}),
+                ...(typeof e.statusCode === "number" ? { statusCode: e.statusCode } : {}),
+            };
         }
-        return { ok: false, error: e?.message || String(e) };
+        return {
+            ok: false,
+            error: e?.message || String(e),
+            ...(typeof e?.code === "string" ? { code: e.code } : {}),
+            ...(typeof e?.statusCode === "number" ? { statusCode: e.statusCode } : {}),
+        };
     }
 }
 /**
@@ -773,45 +809,23 @@ async function phaseRefreshConnections(adapter, instanceId) {
         return;
     try {
         const meta = getInstance(instanceId);
-        const connections = meta?.connections;
-        if (!meta || !connections || Object.keys(connections).length === 0)
+        if (!meta)
             return;
+        const { getApp, refreshCapabilityRegistry } = await import("./app/app-manager.js");
         const { loadCapabilitySpecForLegacyInstance } = await import("./runtime/migrations.js");
-        const spec = loadCapabilitySpecForLegacyInstance(meta);
+        const appData = getApp(instanceId);
+        const spec = appData?.spec ?? loadCapabilitySpecForLegacyInstance(meta);
         if (!spec)
             return;
-        const { resolveConnections } = await import("./connection-resolver.js");
-        const { resolved } = resolveConnections(spec, { connections }, "preCreate");
-        if (resolved.length === 0)
-            return;
-        const { PERSIST_HOOKS } = await import("./connection-apply.js");
-        const merged = {};
-        const seenEnvKeys = new Set();
-        // Accumulate env across all resolved bindings via a stub
-        // writeConnectionEnv that just collects into `merged`. We don't
-        // run the real persist hooks here because those would re-write
-        // generic-app `connections-env` (already handled by
-        // injectConnectionsRuntimeEnv); we only want the env so we can
-        // pass it to adapter.applyConnectionEnv below.
-        const stubCtx = {
-            registry: await import("./capability-registry.js"),
-            adapter: { applyConnectionEnv: undefined },
-            async writeConnectionEnv(_inst, env) {
-                for (const [k, v] of Object.entries(env)) {
-                    merged[k] = v;
-                    seenEnvKeys.add(k);
-                }
-            },
-        };
-        for (const binding of resolved) {
-            const hook = PERSIST_HOOKS[binding.category];
-            if (!hook)
-                continue;
-            await hook(meta, binding, stubCtx);
-        }
-        if (seenEnvKeys.size === 0)
+        await refreshCapabilityRegistry();
+        const { renderRuntimeConnectionsEnv } = await import("./connection-apply.js");
+        const env = await renderRuntimeConnectionsEnv(spec, {
+            id: instanceId,
+            connections: meta.connections,
+        });
+        if (Object.keys(env).length === 0)
             return;
-        await adapter.applyConnectionEnv(instanceId, merged);
+        await adapter.applyConnectionEnv(instanceId, env);
     }
     catch (e) {
         console.warn(`[nomad] connections refresh failed for ${instanceId}: ${e?.message ?? e}`);
@@ -874,8 +888,8 @@ async function phaseSubmit(instanceId, initialAllocation) {
  * callers that only read `ok`/`error` continue to work.
  */
 export async function startInstance(instanceId) {
-    const appDirInstalledApp = await getAppDirInstalledApp(instanceId);
-    if (appDirInstalledApp) {
+    const identity = resolveRuntimeIdentity(instanceId);
+    if (identity?.driver === "app-job" || identity?.driver === "local-model") {
         const { startApp } = await import("./app/app-manager.js");
         return startApp(instanceId);
     }
@@ -890,11 +904,16 @@ export async function startInstance(instanceId) {
             extra.code = running.code;
         return failed("running_check", extra);
     }
+    await phaseResetTerminalJobBeforeStart(instanceId);
     const legacyManager = await getLegacyAppManager(instanceId);
     if (legacyManager) {
         const prep = await legacyManager.prepareStart(instanceId);
         if (!prep.ok) {
             const extra = { error: prep.error ?? "prepareStart failed" };
+            if (prep.code)
+                extra.code = prep.code;
+            if (typeof prep.statusCode === "number")
+                extra.statusCode = prep.statusCode;
             if (prep.building)
                 extra.building = true;
             if (prep.taskId)
@@ -916,6 +935,10 @@ export async function startInstance(instanceId) {
         const hook = await phasePreStartHook(adapter, instanceId);
         if (!hook.ok) {
             const extra = { error: hook.error };
+            if (hook.code)
+                extra.code = hook.code;
+            if (typeof hook.statusCode === "number")
+                extra.statusCode = hook.statusCode;
             if (hook.building)
                 extra.building = true;
             if (hook.taskId)
@@ -929,63 +952,20 @@ export async function startInstance(instanceId) {
     const submit = await phaseSubmit(instanceId, port.portAllocation);
     if (!submit.ok)
         return failed("submit", { error: submit.error });
-    // Auto-register capability providers for legacy instances so they appear
-    // in the Connections UI alongside app-installed apps. App-dir installed
-    // apps short-circuit at the top of this function and don't reach here.
-    await registerLegacyCapabilitiesTopLevel(instanceId);
+    await syncCapabilitiesForInstance(instanceId);
     return {
         ok: true,
         eval_id: submit.evalId,
         ...(submit.portAllocation ? { port_allocation: submit.portAllocation } : {}),
     };
 }
-/**
- * Best-effort capability registration for legacy (non-app-installed)
- * hermes/openclaw instances. Loaded synthetic spec via the migrations
- * helper; failures are logged but never block start/stop.
- */
-async function registerLegacyCapabilitiesTopLevel(instanceId) {
+async function syncCapabilitiesForInstance(instanceId) {
     try {
-        const meta = getInstance(instanceId);
-        if (!meta)
-            return;
-        const { loadCapabilitySpecForLegacyInstance } = await import("./runtime/migrations.js");
-        const synthSpec = loadCapabilitySpecForLegacyInstance(meta);
-        if (!synthSpec?.provides?.length)
-            return;
-        // The synthetic spec's `name` is the yaml template's display name
-        // ("Hermes Agent" / "OpenClaw Container"). For Connections-tab UX we
-        // want the candidate to surface the user's instance name (e.g. "h",
-        // "claw11"), so override before handing it to registerCapabilities.
-        const instanceName = typeof meta.name === "string" && meta.name
-            ? meta.name
-            : instanceId;
-        const namedSpec = { ...synthSpec, name: instanceName };
-        // The synthetic spec has `tasks: []`, so `resolveProvideEndpoint`
-        // can't compute the actual gateway port and falls back to the yaml's
-        // declared port (e.g. openclaw default 18789). Legacy instances may
-        // have been allocated a different port at creation time (port
-        // collision avoidance). Pass the live `getGatewayPort` so the
-        // capability registry advertises the port consumers can actually
-        // reach.
-        const portOverride = getGatewayPort(instanceId);
-        const { registerCapabilities } = await import("./app/app-manager.js");
-        registerCapabilities(instanceId, namedSpec, portOverride > 0 ? portOverride : undefined);
+        const { syncCapabilitiesForApp } = await import("./app/app-manager.js");
+        await syncCapabilitiesForApp(instanceId);
     }
     catch (e) {
-        console.warn(`[legacy-capabilities] register failed for ${instanceId}: ${e?.message ?? e}`);
-    }
-}
-async function unregisterLegacyCapabilitiesTopLevel(instanceId, purge) {
-    try {
-        const { markCapabilitiesStopped, unregisterCapabilities } = await import("./app/app-manager.js");
-        if (purge)
-            unregisterCapabilities(instanceId);
-        else
-            markCapabilitiesStopped(instanceId);
-    }
-    catch (e) {
-        console.warn(`[legacy-capabilities] unregister failed for ${instanceId}: ${e?.message ?? e}`);
+        console.warn(`[capability-sync] sync failed for ${instanceId}: ${e?.message ?? e}`);
     }
 }
 export async function stopInstance(instanceId, purge = false) {
@@ -999,12 +979,11 @@ export async function stopInstance(instanceId, purge = false) {
                 }
                 catch { /* ignore */ }
             }
-            await unregisterLegacyCapabilitiesTopLevel(instanceId, purge);
+            await syncCapabilitiesForInstance(instanceId);
             return { ok: true };
         }
         if (resp.status === 404) {
-            // Already stopped — still mark capabilities stopped so the UI reflects state.
-            await unregisterLegacyCapabilitiesTopLevel(instanceId, purge);
+            await syncCapabilitiesForInstance(instanceId);
             return { ok: false, error: "Instance is not running" };
         }
         return { ok: false, error: await resp.text() };
@@ -1015,62 +994,10 @@ export async function stopInstance(instanceId, purge = false) {
     }
 }
 export async function restartInstance(instanceId) {
-    // Prefer the native Nomad allocation restart API over stop+start:
-    //   PUT /v1/client/allocation/{allocID}/restart
-    // This preserves alloc history, EvalID, and avoids rescheduling.
-    // Only falls back to stop+start when no running/pending alloc exists.
-    const alloc = await getRunningAlloc(instanceId);
-    if (alloc) {
-        // Run the adapter's onBeforeStart even on native restart so pre-start
-        // migrations (e.g. Hermes's OPENAI_* env sync) still apply. The hook
-        // contract says it must be idempotent, so this is safe on every
-        // restart — including cases where the spec didn't change.
-        try {
-            const legacyManager = await getLegacyAppManager(instanceId);
-            if (legacyManager) {
-                const prep = await legacyManager.prepareStart(instanceId);
-                if (!prep.ok) {
-                    console.warn(`[nomad] prepareStart on restart failed for ${instanceId}: ${prep.error}`);
-                }
-            }
-            else {
-                const meta = getInstance(instanceId);
-                const agentType = resolveAgentType(meta);
-                const adapter = getAdapter(agentType);
-                // PR 9 — refresh connection-derived config (mcp_servers /
-                // openclaw.json plugins) from current capability registry so
-                // host IP changes propagate on restart without manual re-bind.
-                // Symmetric with the same call in startInstance.
-                await phaseRefreshConnections(adapter, instanceId);
-                if (adapter.hooks?.onBeforeStart) {
-                    await adapter.hooks.onBeforeStart({ instanceId });
-                }
-            }
-        }
-        catch (e) {
-            console.warn(`[nomad] onBeforeStart on restart failed for ${instanceId}: ${e.message}`);
-        }
-        try {
-            const resp = await nomadPut(`/v1/client/allocation/${alloc.ID}/restart`, {
-                TaskName: resolveTaskName(instanceId),
-                AllTasks: false,
-            });
-            if (resp.ok) {
-                // Re-register capabilities — yaml provides may have changed since
-                // the last start (e.g. a panel upgrade adding `llm-agent`).
-                await registerLegacyCapabilitiesTopLevel(instanceId);
-                return { ok: true, alloc_id: alloc.ID };
-            }
-            // Non-2xx from the restart endpoint falls through to stop+start
-            const errText = await resp.text();
-            console.warn(`[nomad] Native restart failed for ${instanceId} (HTTP ${resp.status}): ${errText} — falling back to stop+start`);
-        }
-        catch (e) {
-            console.warn(`[nomad] Native restart error for ${instanceId}: ${e.message} — falling back to stop+start`);
-        }
+    const stopResult = await stopInstance(instanceId);
+    if (!stopResult.ok && !stopResult.error?.includes("not running") && !stopResult.error?.includes("not found")) {
+        return stopResult;
     }
-    // Fallback: stop the job and re-submit it
-    await stopInstance(instanceId);
     await new Promise((r) => setTimeout(r, 2000));
     return startInstance(instanceId);
 }
@@ -1127,6 +1054,82 @@ export async function getLogs(instanceId, lines = 200, logType = "stderr") {
     return [];
 }
 const execFileAsync = promisify(execFileCb);
+const DOCKER_STATS_TTL_MS = 30_000;
+/** Field separator for the batched `docker stats --format` line. Exported so
+ *  tests can construct mock output without hardcoding the literal. */
+export const DOCKER_STATS_FIELD_SEP = "__JS__";
+let _dockerStatsEntry = null;
+let _dockerStatsInFlight = null;
+/** Test-only: reset the shared docker-stats snapshot so each test starts from
+ *  a cold cache (the 30s TTL + single-flight would otherwise leak one test's
+ *  mocked snapshot into the next). Not used by production code paths. */
+export function __resetDockerStatsCacheForTests() {
+    _dockerStatsEntry = null;
+    _dockerStatsInFlight = null;
+}
+function parseDockerMemUsageMb(memUsage) {
+    // Format: "499.6MiB / 3GiB" — the used side is everything before "/".
+    const used = (memUsage.split("/")[0] ?? "").trim();
+    const match = used.match(/^([\d.]+)\s*(MiB|GiB|MB|GB|KiB|KB|B)?/i);
+    if (!match)
+        return 0;
+    let mb = parseFloat(match[1]);
+    if (!Number.isFinite(mb))
+        return 0;
+    const unit = (match[2] ?? "MiB").toLowerCase();
+    if (unit === "gib" || unit === "gb")
+        mb *= 1024;
+    else if (unit === "kib" || unit === "kb")
+        mb /= 1024;
+    else if (unit === "b")
+        mb /= 1024 * 1024;
+    return Math.round(mb * 10) / 10;
+}
+async function loadDockerStatsSnapshot() {
+    const snapshot = new Map();
+    try {
+        const fmt = `{{.Name}}${DOCKER_STATS_FIELD_SEP}{{.MemUsage}}${DOCKER_STATS_FIELD_SEP}{{.CPUPerc}}`;
+        const { stdout } = await execFileAsync("docker", ["stats", "--no-stream", "--format", fmt], { timeout: 8_000 });
+        for (const line of stdout.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            const [name, memUsage, cpuPerc] = trimmed.split(DOCKER_STATS_FIELD_SEP);
+            if (!name)
+                continue;
+            snapshot.set(name, {
+                memory_mb: parseDockerMemUsageMb(memUsage ?? ""),
+                cpu_percent: Math.round((parseFloat(cpuPerc ?? "") || 0) * 10) / 10,
+            });
+        }
+    }
+    catch {
+        /* docker missing / timeout / daemon down → empty map, caller degrades */
+    }
+    return snapshot;
+}
+/**
+ * Returns a per-container stats map, refreshing at most once per
+ * DOCKER_STATS_TTL_MS. Concurrent callers (the `Promise.all` over every
+ * instance in `GET /api/instances`) share a single in-flight docker call.
+ */
+async function getDockerMemSnapshot() {
+    const now = Date.now();
+    if (_dockerStatsEntry && now - _dockerStatsEntry.ts < DOCKER_STATS_TTL_MS) {
+        return _dockerStatsEntry.data;
+    }
+    if (_dockerStatsInFlight)
+        return _dockerStatsInFlight;
+    _dockerStatsInFlight = loadDockerStatsSnapshot()
+        .then((data) => {
+        _dockerStatsEntry = { data, ts: Date.now() };
+        return data;
+    })
+        .finally(() => {
+        _dockerStatsInFlight = null;
+    });
+    return _dockerStatsInFlight;
+}
 export async function exec(instanceId, command, timeoutMs = 120_000) {
     const alloc = await getRunningAlloc(instanceId);
     if (!alloc || alloc.ClientStatus !== "running") {
@@ -1169,8 +1172,10 @@ export const DEFAULT_ENV = {
 };
 export const DEFAULT_RESOURCES = { CPU: 500, MemoryMB: 512 };
 export const MAX_CPU_MHZ = 4000; // 4 GHz per task
-export const MAX_MEMORY_MB = 4096; // 4 GB reservation
-export const MAX_MEMORY_MAX_MB = 4096; // 4 GB hard limit (memory_max)
+/** @deprecated Use {@link getMaxAppMemoryMB} from config.ts for the live ceiling. */
+export const MAX_MEMORY_MB = 4096; // 4 GB fallback — overridden by core.json max_app_memory_mb
+/** @deprecated Use {@link getMaxAppMemoryMB} from config.ts for the live ceiling. */
+export const MAX_MEMORY_MAX_MB = 4096; // 4 GB fallback — overridden by core.json max_app_memory_mb
 /**
  * Clamp container memory reservation/limit to the framework ceilings and
  * ensure `MemoryMaxMB >= MemoryMB`. Shared by every container-runtime app
@@ -1178,9 +1183,10 @@ export const MAX_MEMORY_MAX_MB = 4096; // 4 GB hard limit (memory_max)
  * guard-rails before handing a task spec to Nomad.
  */
 export function normalizeDockerResources(instanceId, runtime) {
+    const ceiling = config.getMaxAppMemoryMB();
     const requestedMemoryMB = Number(runtime.resources?.MemoryMB ?? DEFAULT_RESOURCES.MemoryMB);
-    let effectiveMemoryMB = Math.min(requestedMemoryMB, MAX_MEMORY_MB);
-    let effectiveMemoryMaxMB = Math.min(Number(runtime.resources?.MemoryMaxMB ?? requestedMemoryMB), MAX_MEMORY_MAX_MB);
+    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;
@@ -1219,8 +1225,7 @@ var UnifiedNomadJobs;
     const DEFAULT_MEMORY_MB = 512;
     // Hard upper bounds: prevents misconfigured specs from exhausting scheduler resources.
     const MAX_CPU_MHZ = 4000; // 4 GHz
-    const MAX_MEMORY_MB = 4096; // 4 GB reservation
-    const MAX_MEMORY_MAX_MB = 4096; // 4 GB hard limit
+    // 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();
@@ -1228,6 +1233,9 @@ var UnifiedNomadJobs;
         return join(APPS_DIR, appId);
     }
     function isAppJob(id) {
+        const identity = resolveRuntimeIdentity(id);
+        if (identity)
+            return identity.driver === "app-job";
         const dir = appDirForId(id);
         if (existsSync(join(dir, "manifest.json")) || existsSync(join(dir, "app-spec.yaml"))) {
             return true;
@@ -1409,7 +1417,7 @@ var UnifiedNomadJobs;
             // "mi"/"mib"/"m"/"mb" or bare integer
             mb = Math.round(val);
         }
-        return Math.max(1, Math.min(mb, MAX_MEMORY_MB));
+        return Math.max(1, Math.min(mb, config.getMaxAppMemoryMB()));
     }
     UnifiedNomadJobs.parseMemoryMB = parseMemoryMB;
     // ── Interval parser ───────────────────────────────────────────────────────
@@ -1440,28 +1448,44 @@ var UnifiedNomadJobs;
             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 Nomad rejects job submission with
-        // "unknown host network". Falls back to "external" when unset.
+        // 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 && nomadConfigDeclaresHostNetwork(requested))
-            return requested;
+        if (requested)
+            return nomadConfigDeclaresHostNetwork(requested) ? requested : undefined;
         return nomadConfigDeclaresHostNetwork("external") ? "external" : undefined;
     }
-    function specRequiresExternalHostNetwork(spec) {
-        return spec.tasks.some((task) => task.runtime !== "container"
-            && (task.ports ?? []).some((port) => (port.visibility ?? "external") !== "internal"));
+    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 validateRequiredHostNetworks(spec) {
-        if (!specRequiresExternalHostNetwork(spec))
-            return null;
-        if (!nomadConfigDeclaresHostNetwork("external"))
+    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)
@@ -1473,8 +1497,10 @@ var UnifiedNomadJobs;
             const loadedNetworks = new Set(hostNetworks
                 .map((network) => String(network?.Name ?? "").trim())
                 .filter(Boolean));
-            if (!loadedNetworks.has("external")) {
-                return 'Nomad 运行中的 agent 尚未加载 host_network "external"。请先重启 Nomad，再启动该应用。';
+            for (const network of requiredNetworks) {
+                if (!loadedNetworks.has(network)) {
+                    return `Nomad 运行中的 agent 尚未加载 host_network "${network}"。请先重启 Nomad，再启动该应用。`;
+                }
             }
         }
         catch {
@@ -1482,6 +1508,20 @@ var UnifiedNomadJobs;
         }
         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;
     function reservedPortsForTask(task) {
         // visibility=internal ports are intra-group only (e.g. SearXNG sidecar
         // reachable from the gateway task via 127.0.0.1 inside the bridge
@@ -1489,26 +1529,124 @@ var UnifiedNomadJobs;
         // port slot AND, combined with docker publishing below, expose the
         // endpoint externally. Skip them entirely — they stay inside the task
         // group's network namespace.
+        // Attach the named host_network for any externally-visible port —
+        // including container tasks. Without it, Nomad falls back to
+        // HostNetwork="default" (loopback) and the docker driver publishes
+        // to 127.0.0.1, breaking cross-container consumers. The earlier
+        // restriction to non-container tasks was overcautious: our task
+        // groups use host networking (Mode: "") rather than Nomad bridge
+        // mode, so attaching host_network is safe.
         return (task.ports ?? [])
             .filter((port) => (port.visibility ?? "external") !== "internal")
-            .map((port) => ({
-            Label: portLabel(task.name, port.name),
-            Value: port.host_port ?? port.port,
-            ...(task.runtime === "container" ? { To: port.container_port ?? port.port } : {}),
-            // Attach the named host_network for any externally-visible port —
-            // including container tasks. Without it, Nomad falls back to
-            // HostNetwork="default" (loopback) and the docker driver publishes
-            // to 127.0.0.1, breaking cross-container consumers (e.g. OpenWebUI
-            // calling hermes / openclaw via the connections page). The earlier
-            // restriction to non-container tasks was overcautious — our task
-            // groups use host networking (Mode: "") rather than Nomad bridge
-            // mode, so attaching host_network is safe and is exactly what
-            // searxng-container has been doing in practice all along.
-            ...(hostNetworkForPort(port)
-                ? { HostNetwork: hostNetworkForPort(port) }
-                : {}),
+            .map((port) => buildNomadReservedPort({
+            label: portLabel(task.name, port.name),
+            value: port.host_port ?? port.port,
+            ...(task.runtime === "container" ? { to: port.container_port ?? port.port } : {}),
+            visibility: port.visibility,
+            host_network: port.host_network,
         }));
     }
+    function isExternalAppTaskPort(port) {
+        return (port.visibility ?? "external") !== "internal";
+    }
+    function readDeclaredHostPort(port) {
+        const candidate = port.host_port ?? port.port;
+        return Number.isInteger(candidate) && candidate > 0 ? candidate : null;
+    }
+    function applyPersistedAppSpecPortOverrides(appId, spec) {
+        const meta = getInstance(appId);
+        if (!meta)
+            return spec;
+        const runtime = getInstanceRuntime(appId);
+        const runtimePorts = Array.isArray(runtime.ports) ? runtime.ports : [];
+        const persistedGatewayPort = extractGatewayPort(runtime, resolveAgentType(meta));
+        const totalExternalPorts = spec.tasks.reduce((count, task) => count + (task.ports ?? []).filter((port) => isExternalAppTaskPort(port)).length, 0);
+        let changed = false;
+        const tasks = spec.tasks.map((task) => {
+            if (!Array.isArray(task.ports) || task.ports.length === 0)
+                return task;
+            let taskChanged = false;
+            const ports = task.ports.map((port) => {
+                if (!isExternalAppTaskPort(port))
+                    return port;
+                const currentHostPort = readDeclaredHostPort(port);
+                if (!currentHostPort)
+                    return port;
+                let nextHostPort = null;
+                // Scope the runtime-port match to BOTH the owning task AND the port name.
+                // Multi-service-task apps (e.g. WeKnora's `app` + `ui`, both with a port
+                // named "http") record every external port tagged with its taskName; a
+                // name-only match would rewrite the `ui` task's host port to the `app`
+                // task's allocation and collide them. Tolerate legacy runtime records
+                // that predate the taskName tag by allowing an untagged name match.
+                const namedRuntimePort = typeof port.name === "string" && port.name
+                    ? (runtimePorts.find((candidate) => candidate?.taskName === task.name
+                        && candidate?.name === port.name
+                        && Number.isInteger(candidate?.hostPort)
+                        && candidate.hostPort > 0)
+                        ?? runtimePorts.find((candidate) => candidate?.taskName === undefined
+                            && candidate?.name === port.name
+                            && Number.isInteger(candidate?.hostPort)
+                            && candidate.hostPort > 0))
+                    : null;
+                if (namedRuntimePort) {
+                    nextHostPort = namedRuntimePort.hostPort;
+                }
+                else if (runtimePorts.length === 1
+                    && totalExternalPorts === 1
+                    && Number.isInteger(runtimePorts[0]?.hostPort)
+                    && runtimePorts[0].hostPort > 0) {
+                    nextHostPort = runtimePorts[0].hostPort;
+                }
+                else if (totalExternalPorts === 1
+                    && persistedGatewayPort != null
+                    && persistedGatewayPort > 0) {
+                    nextHostPort = persistedGatewayPort;
+                }
+                if (!nextHostPort || nextHostPort === currentHostPort)
+                    return port;
+                changed = true;
+                taskChanged = true;
+                return { ...port, host_port: nextHostPort };
+            });
+            return taskChanged ? { ...task, ports } : task;
+        });
+        return changed ? { ...spec, tasks } : spec;
+    }
+    async function maybeReallocateAppSpecHostPort(appId, spec, reason) {
+        if (!getInstance(appId))
+            return { spec, changed: false };
+        const effectiveSpec = applyPersistedAppSpecPortOverrides(appId, spec);
+        const currentGatewayPort = getGatewayPort(appId);
+        if (!Number.isInteger(currentGatewayPort) || currentGatewayPort <= 0) {
+            return { spec: effectiveSpec, changed: false };
+        }
+        const declaredPorts = effectiveSpec.tasks.flatMap((task) => (task.ports ?? [])
+            .filter((port) => isExternalAppTaskPort(port))
+            .map((port) => readDeclaredHostPort(port))
+            .filter((port) => port != null));
+        if (!declaredPorts.includes(currentGatewayPort)) {
+            return { spec: effectiveSpec, changed: false };
+        }
+        if (!(await isPortInUse(currentGatewayPort))) {
+            return { spec: effectiveSpec, changed: false };
+        }
+        try {
+            const reallocation = await reallocateGatewayPort(appId);
+            console.log(`[nomad] ${appId}: reallocated AppSpec host port ${reallocation.from} -> ${reallocation.to} (${reason})`);
+            return {
+                spec: applyPersistedAppSpecPortOverrides(appId, spec),
+                changed: true,
+            };
+        }
+        catch (e) {
+            return {
+                spec: effectiveSpec,
+                changed: false,
+                error: `AppSpec host port ${currentGatewayPort} is held by another process and reallocation failed: ${e?.message ?? e}`,
+            };
+        }
+    }
     // ── Health check → Nomad service check builder ────────────────────────────
     function buildServiceCheck(task, appId) {
         const health = task.health;
@@ -1572,8 +1710,6 @@ var UnifiedNomadJobs;
         return result;
     }
     function interpolateEnvRequires(taskEnv, extraEnv) {
-        if (Object.keys(extraEnv).length === 0)
-            return taskEnv;
         const result = {};
         for (const [k, v] of Object.entries(taskEnv)) {
             result[k] = v.replace(/\$\{requires\.([^}]+)\}/g, (_, key) => extraEnv[key] ?? "");
@@ -2227,7 +2363,7 @@ var UnifiedNomadJobs;
         const args = (task.args ?? []).map(String);
         const cpu = parseCpuMHz(task.resources?.cpu);
         const mem = parseMemoryMB(task.resources?.memory);
-        const memMax = Math.min(mem, MAX_MEMORY_MAX_MB);
+        const memMax = Math.min(mem, config.getMaxAppMemoryMB());
         const env = {
             ...extraEnv,
             ...interpolateEnvRequires(task.env ?? {}, extraEnv),
@@ -2245,6 +2381,7 @@ var UnifiedNomadJobs;
             const src = v.source.replace(/^~(?=\/|$)/, homedir());
             return `${src}:${v.target}${v.readonly ? ":ro" : ":rw"}`;
         });
+        const workDir = typeof task.cwd === "string" ? task.cwd.trim() : "";
         // Resolve container task user. On Linux we default to the panel
         // process's host uid:gid so bind-mounted data dirs (owned by the panel
         // user, typically `pi`) are writable without forcing the container to
@@ -2290,6 +2427,15 @@ var UnifiedNomadJobs;
                 .map((c) => typeof c === "string" ? c.trim().toUpperCase().replace(/^CAP_/, "") : "")
                 .filter((c) => ALLOWED_CAPS.has(c))
             : [];
+        // Public-DNS override. Defaults to AliDNS / DNSPod / Cloudflare; can be
+        // disabled or replaced via core.json `container_dns`. The override is
+        // necessary because docker's "copy host's resolv.conf" default rewrites
+        // 127.0.0.53 (systemd-resolved loopback) back to whatever upstream the
+        // host learned from DHCP, re-introducing into the container any DNS
+        // hijack the host had bypassed via DoT/DoH — silent failure mode that
+        // surfaces as 3-second-timeout on every outbound request from inside
+        // search/scraper apps on home networks. Empty list = no override.
+        const containerDns = config.getContainerDns();
         const taskDef = {
             Name: task.name,
             Driver: "docker",
@@ -2306,10 +2452,12 @@ var UnifiedNomadJobs;
                 // unreachable registry still surfaces as a failure within a
                 // bounded window.
                 image_pull_timeout: "15m",
+                ...(workDir ? { work_dir: workDir } : {}),
                 ...(task.command ? { command: String(task.command) } : {}),
                 args,
                 ...(publishedPorts.length > 0 ? { ports: publishedPorts } : {}),
                 extra_hosts: ["host.docker.internal:host-gateway"],
+                ...(containerDns.length > 0 ? { dns_servers: containerDns } : {}),
                 cap_drop: ["ALL"],
                 ...(capAdd.length > 0 ? { cap_add: capAdd } : {}),
                 security_opt: ["no-new-privileges"],
@@ -2648,28 +2796,17 @@ var UnifiedNomadJobs;
             }
         }
         catch { /* ignore */ }
-        // Fallback: use `docker stats` when Nomad cgroup stats are zero (cgroup v2 / Pi).
-        // Only applicable for docker-driver tasks.
-        if (!result.memory_mb && allocId && ptName) {
-            try {
-                if (!/^[a-f0-9-]+$/i.test(allocId))
-                    throw new Error("invalid allocId");
-                const containerName = `${ptName}-${allocId}`;
-                const execFileAsync = promisify(execFileCb);
-                const { stdout } = await execFileAsync("docker", ["stats", "--no-stream", "--format", "{{.MemUsage}}", containerName], { timeout: 5_000 });
-                const raw = stdout.trim();
-                const match = raw.match(/^([\d.]+)\s*(MiB|GiB|MB|GB|KiB|KB)/i);
-                if (match) {
-                    let mb = parseFloat(match[1]);
-                    const unit = match[2].toLowerCase();
-                    if (unit === "gib" || unit === "gb")
-                        mb *= 1024;
-                    else if (unit === "kib" || unit === "kb")
-                        mb /= 1024;
-                    result.memory_mb = Math.round(mb * 10) / 10;
-                }
+        // 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;
             }
-            catch { /* ignore */ }
         }
         return result;
     }
@@ -2749,15 +2886,11 @@ var UnifiedNomadJobs;
      */
     async function startAppJob(spec, appId, extraEnv = {}) {
         const status = await getAppStatus(appId);
-        if (status.status === "running") {
-            // Already running is a success state — no need to resubmit.
-            return { ok: true };
-        }
         const adoptedExternal = await buildExternalAdoptedSpec(appId, spec);
         if (adoptedExternal.conflicts.length > 0) {
             return { ok: false, error: adoptedExternal.conflicts.join("; ") };
         }
-        const effectiveSpec = adoptedExternal.spec;
+        let effectiveSpec = applyPersistedAppSpecPortOverrides(appId, adoptedExternal.spec);
         // Validate all images before submitting
         for (const task of effectiveSpec.tasks) {
             if (task.runtime === "container") {
@@ -2784,31 +2917,54 @@ var UnifiedNomadJobs;
         if (hostNetworkError) {
             return { ok: false, error: hostNetworkError };
         }
-        let jobDef;
-        try {
-            jobDef = buildAppJob(effectiveSpec, appId, driver, extraEnv);
-        }
-        catch (e) {
-            return { ok: false, error: `Job build failed: ${e.message}` };
+        if (driver === "docker") {
+            const preflight = await maybeReallocateAppSpecHostPort(appId, effectiveSpec, "host_port_busy");
+            if (preflight.error)
+                return { ok: false, error: preflight.error };
+            effectiveSpec = preflight.spec;
         }
-        try {
-            const resp = await nomadPost("/v1/jobs", jobDef);
-            if (resp.ok) {
-                const data = await resp.json();
-                return { ok: true, eval_id: data.EvalID };
+        for (let attempt = 0; attempt < 2; attempt++) {
+            let jobDef;
+            try {
+                jobDef = buildAppJob(effectiveSpec, appId, driver, extraEnv);
             }
-            const text = await resp.text();
-            return { ok: false, error: text };
-        }
-        catch (e) {
-            const isNetErr = e?.message === "fetch failed" || e?.cause?.code === "ECONNREFUSED";
-            return {
-                ok: false,
-                error: isNetErr
-                    ? `Nomad 服务不可达 (${getNomadAddr()})，请先启动 Nomad`
-                    : e.message,
-            };
+            catch (e) {
+                return { ok: false, error: `Job build failed: ${e.message}` };
+            }
+            let submitError = null;
+            let netErr = false;
+            try {
+                const resp = await nomadPost("/v1/jobs", jobDef);
+                if (resp.ok) {
+                    const data = await resp.json();
+                    // When the app was previously failed, verify it actually transitions
+                    // away from the failed state rather than reporting false success.
+                    if (status.status === "failed") {
+                        const recovered = await waitForRecovery(appId, 15_000, 2_000);
+                        if (!recovered) {
+                            return { ok: false, error: "App start submitted but instance remains in failed state. Check app logs for details.", eval_id: data.EvalID };
+                        }
+                    }
+                    return { ok: true, eval_id: data.EvalID };
+                }
+                submitError = await resp.text();
+            }
+            catch (e) {
+                netErr = e?.message === "fetch failed" || e?.cause?.code === "ECONNREFUSED";
+                submitError = netErr ? `Nomad 服务不可达 (${getNomadAddr()})，请先启动 Nomad` : e.message;
+            }
+            if (attempt === 0 && driver === "docker" && !netErr) {
+                const retry = await maybeReallocateAppSpecHostPort(appId, effectiveSpec, "docker_race");
+                if (retry.error)
+                    return { ok: false, error: retry.error };
+                if (retry.changed) {
+                    effectiveSpec = retry.spec;
+                    continue;
+                }
+            }
+            return { ok: false, error: submitError ?? "unknown error" };
         }
+        return { ok: false, error: "start retry exhausted" };
     }
     UnifiedNomadJobs.startAppJob = startAppJob;
     /**
@@ -2828,6 +2984,21 @@ var UnifiedNomadJobs;
         return false;
     }
     UnifiedNomadJobs.waitForRunning = waitForRunning;
+    /**
+     * Poll until the app job leaves the "failed" state or times out.
+     * Used after start submission to verify actual recovery before reporting success.
+     * Returns true if the app transitions away from "failed" (to pending/running/etc).
+     */
+    async function waitForRecovery(appId, timeoutMs = 15_000, pollIntervalMs = 2_000) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, pollIntervalMs));
+            const status = await getAppStatus(appId);
+            if (status.status !== "failed")
+                return true;
+        }
+        return false;
+    }
     async function checkDependencies(spec) {
         if (!spec.depends_on || Object.keys(spec.depends_on).length === 0) {
             return { ok: true, errors: [] };
@@ -3394,7 +3565,7 @@ var UnifiedNomadJobs;
             }
             catch { }
         }
-        const legacy = getPanelConfig().nomad_token;
+        const legacy = getCoreConfig().nomad_token;
         if (legacy)
             process.env.NOMAD_TOKEN = legacy;
     }
@@ -3443,6 +3614,20 @@ var UnifiedNomadJobs;
                 cpu_percent: st.cpu_percent,
             };
         }
+        const identity = resolveRuntimeIdentity(nomadJobId);
+        if (identity?.driver === "app-job" || identity?.driver === "local-model") {
+            const st = await getAppStatus(nomadJobId);
+            return {
+                status: st.status,
+                pid: st.pid,
+                uptime: st.uptime,
+                memory_mb: st.memory_mb,
+                cpu_percent: st.cpu_percent,
+            };
+        }
+        if (identity?.driver === "runtime-adapter") {
+            return instanceScheduler.getStatus(nomadJobId);
+        }
         if (existsSync(instanceMetaPath(nomadJobId))) {
             return instanceScheduler.getStatus(nomadJobId);
         }
@@ -3452,55 +3637,6 @@ var UnifiedNomadJobs;
         return getGenericJobStatus(nomadJobId);
     }
     UnifiedNomadJobs.getInstanceStatus = getInstanceStatus;
-    /**
-     * Capability registration shim for **legacy** (non-app-installed)
-     * hermes/openclaw instances. Loads the synthetic spec via
-     * loadCapabilitySpecForLegacyInstance and routes provides through the
-     * app-manager registry helpers, so legacy instances surface in
-     * Connections candidate lists like app-installed ones.
-     *
-     * Errors are swallowed and logged — capability registration is best-
-     * effort; a failure here must not block start/stop.
-     */
-    async function registerLegacyCapabilities(instanceId) {
-        try {
-            const meta = getInstance(instanceId);
-            if (!meta)
-                return;
-            const { loadCapabilitySpecForLegacyInstance } = await import("./runtime/migrations.js");
-            const synthSpec = loadCapabilitySpecForLegacyInstance(meta);
-            if (!synthSpec?.provides?.length)
-                return;
-            // Same instance-name override + portOverride passthrough as
-            // registerLegacyCapabilitiesTopLevel — Connections candidates should
-            // show the user's instance name and advertise the actually-allocated
-            // gateway port (not the yaml default).
-            const instanceName = typeof meta.name === "string" && meta.name
-                ? meta.name
-                : instanceId;
-            const namedSpec = { ...synthSpec, name: instanceName };
-            const portOverride = getGatewayPort(instanceId);
-            const { registerCapabilities } = await import("./app/app-manager.js");
-            registerCapabilities(instanceId, namedSpec, portOverride > 0 ? portOverride : undefined);
-        }
-        catch (e) {
-            console.warn(`[legacy-capabilities] register failed for ${instanceId}: ${e?.message ?? e}`);
-        }
-    }
-    async function unregisterLegacyCapabilities(instanceId, purge) {
-        try {
-            const { markCapabilitiesStopped, unregisterCapabilities } = await import("./app/app-manager.js");
-            if (purge) {
-                unregisterCapabilities(instanceId);
-            }
-            else {
-                markCapabilitiesStopped(instanceId);
-            }
-        }
-        catch (e) {
-            console.warn(`[legacy-capabilities] unregister failed for ${instanceId}: ${e?.message ?? e}`);
-        }
-    }
     async function startInstance(nomadJobId) {
         const instanceBackedApp = await getInstanceBackedInstalledApp(nomadJobId);
         if (instanceBackedApp) {
@@ -3512,6 +3648,8 @@ var UnifiedNomadJobs;
             // instance file isn't readable yet.
             let extraEnv = {};
             try {
+                const { refreshCapabilityRegistry } = await import("./app/app-manager.js");
+                await refreshCapabilityRegistry();
                 const { resolveConnections, resolvedToLegacyEnv } = await import("./connection-resolver.js");
                 const legacyInstanceManager = await import("./instance-manager.js");
                 const meta = legacyInstanceManager.getInstance(nomadJobId);
@@ -3541,16 +3679,31 @@ var UnifiedNomadJobs;
             const result = await startAppJob(instanceBackedApp.spec, nomadJobId, extraEnv);
             if (!result.ok)
                 return result;
-            const { registerCapabilities, runPostStartSteps } = await import("./app/app-manager.js");
-            if (instanceBackedApp.spec.provides?.length) {
-                registerCapabilities(nomadJobId, instanceBackedApp.spec);
-            }
-            if (instanceBackedApp.spec.lifecycle?.post_start?.length) {
-                const running = await waitForRunning(nomadJobId);
-                if (running) {
-                    await runPostStartSteps(instanceBackedApp.spec);
-                }
-            }
+            const { runPostStartSteps, syncCapabilitiesForApp, waitForAppRuntimeRunning } = await import("./app/app-manager.js");
+            const running = instanceBackedApp.spec.provides?.length || instanceBackedApp.spec.lifecycle?.post_start?.length
+                ? await waitForAppRuntimeRunning(nomadJobId, instanceBackedApp.spec.lifecycle?.post_start?.length ? 120_000 : 30_000)
+                : false;
+            if (running && instanceBackedApp.spec.lifecycle?.post_start?.length) {
+                await runPostStartSteps(instanceBackedApp.spec);
+            }
+            await syncCapabilitiesForApp(nomadJobId);
+            return result;
+        }
+        if (await getAdapterManagedAppDirInstalledApp(nomadJobId)) {
+            const result = await instanceScheduler.startInstance(nomadJobId);
+            if (result.ok)
+                await syncCapabilitiesForInstance(nomadJobId);
+            return result;
+        }
+        const identity = resolveRuntimeIdentity(nomadJobId);
+        if (identity?.driver === "app-job" || identity?.driver === "local-model") {
+            const { startApp } = await import("./app/app-manager.js");
+            return startApp(nomadJobId);
+        }
+        if (identity?.driver === "runtime-adapter") {
+            const result = await instanceScheduler.startInstance(nomadJobId);
+            if (result.ok)
+                await syncCapabilitiesForInstance(nomadJobId);
             return result;
         }
         if (isAppJob(nomadJobId)) {
@@ -3559,14 +3712,14 @@ var UnifiedNomadJobs;
         if (existsSync(instanceMetaPath(nomadJobId))) {
             const result = await instanceScheduler.startInstance(nomadJobId);
             if (result.ok)
-                await registerLegacyCapabilities(nomadJobId);
+                await syncCapabilitiesForInstance(nomadJobId);
             return result;
         }
         if (nomadJobId.startsWith(OPENCLAW_PREFIX)) {
             const inner = nomadJobId.slice(OPENCLAW_PREFIX.length);
             const result = await instanceScheduler.startInstance(inner);
             if (result.ok)
-                await registerLegacyCapabilities(inner);
+                await syncCapabilitiesForInstance(inner);
             return result;
         }
         if (!isAppJob(nomadJobId)) {
@@ -3579,8 +3732,26 @@ var UnifiedNomadJobs;
         if (await getInstanceBackedInstalledApp(nomadJobId)) {
             const result = await stopAppJob(nomadJobId, purge);
             if (result.ok || result.error?.includes("not running") || result.error?.includes("not found")) {
-                const { unregisterCapabilities } = await import("./app/app-manager.js");
-                unregisterCapabilities(nomadJobId);
+                await syncCapabilitiesForInstance(nomadJobId);
+            }
+            return result;
+        }
+        if (await getAdapterManagedAppDirInstalledApp(nomadJobId)) {
+            const result = await instanceScheduler.stopInstance(nomadJobId, purge);
+            if (result.ok || result.error?.includes("not running") || result.error?.includes("not found")) {
+                await syncCapabilitiesForInstance(nomadJobId);
+            }
+            return result;
+        }
+        const identity = resolveRuntimeIdentity(nomadJobId);
+        if (identity?.driver === "app-job" || identity?.driver === "local-model") {
+            const { stopApp } = await import("./app/app-manager.js");
+            return stopApp(nomadJobId, purge);
+        }
+        if (identity?.driver === "runtime-adapter") {
+            const result = await instanceScheduler.stopInstance(nomadJobId, purge);
+            if (result.ok || result.error?.includes("not running") || result.error?.includes("not found")) {
+                await syncCapabilitiesForInstance(nomadJobId);
             }
             return result;
         }
@@ -3590,7 +3761,7 @@ var UnifiedNomadJobs;
         if (existsSync(instanceMetaPath(nomadJobId))) {
             const result = await instanceScheduler.stopInstance(nomadJobId, purge);
             if (result.ok || result.error?.includes("not running") || result.error?.includes("not found")) {
-                await unregisterLegacyCapabilities(nomadJobId, purge);
+                await syncCapabilitiesForInstance(nomadJobId);
             }
             return result;
         }
@@ -3598,7 +3769,7 @@ var UnifiedNomadJobs;
             const inner = nomadJobId.slice(OPENCLAW_PREFIX.length);
             const result = await instanceScheduler.stopInstance(inner, purge);
             if (result.ok || result.error?.includes("not running") || result.error?.includes("not found")) {
-                await unregisterLegacyCapabilities(inner, purge);
+                await syncCapabilitiesForInstance(inner);
             }
             return result;
         }
@@ -3619,20 +3790,37 @@ var UnifiedNomadJobs;
             }
             return startInstance(nomadJobId);
         }
+        if (await getAdapterManagedAppDirInstalledApp(nomadJobId)) {
+            const result = await instanceScheduler.restartInstance(nomadJobId);
+            if (result.ok)
+                await syncCapabilitiesForInstance(nomadJobId);
+            return result;
+        }
+        const identity = resolveRuntimeIdentity(nomadJobId);
+        if (identity?.driver === "app-job" || identity?.driver === "local-model") {
+            const { restartApp } = await import("./app/app-manager.js");
+            return restartApp(nomadJobId);
+        }
+        if (identity?.driver === "runtime-adapter") {
+            const result = await instanceScheduler.restartInstance(nomadJobId);
+            if (result.ok)
+                await syncCapabilitiesForInstance(nomadJobId);
+            return result;
+        }
         if (isAppJob(nomadJobId)) {
             return { ok: false, error: `App '${nomadJobId}' 必须通过 app-manager 重启` };
         }
         if (existsSync(instanceMetaPath(nomadJobId))) {
             const result = await instanceScheduler.restartInstance(nomadJobId);
             if (result.ok)
-                await registerLegacyCapabilities(nomadJobId);
+                await syncCapabilitiesForInstance(nomadJobId);
             return result;
         }
         if (nomadJobId.startsWith(OPENCLAW_PREFIX)) {
             const inner = nomadJobId.slice(OPENCLAW_PREFIX.length);
             const result = await instanceScheduler.restartInstance(inner);
             if (result.ok)
-                await registerLegacyCapabilities(inner);
+                await syncCapabilitiesForInstance(inner);
             return result;
         }
         if (!isAppJob(nomadJobId)) {
@@ -3647,6 +3835,13 @@ var UnifiedNomadJobs;
         }
         if (isAppJob(nomadJobId))
             return getAppLogs(nomadJobId, "", lines, logType);
+        const identity = resolveRuntimeIdentity(nomadJobId);
+        if (identity?.driver === "app-job" || identity?.driver === "local-model") {
+            return getAppLogs(nomadJobId, "", lines, logType);
+        }
+        if (identity?.driver === "runtime-adapter") {
+            return instanceScheduler.getLogs(nomadJobId, lines, logType);
+        }
         if (existsSync(instanceMetaPath(nomadJobId))) {
             return instanceScheduler.getLogs(nomadJobId, lines, logType);
         }
@@ -3665,6 +3860,13 @@ var UnifiedNomadJobs;
         if (isAppJob(nomadJobId)) {
             return execInApp(nomadJobId, "", command, timeoutMs ?? 120_000);
         }
+        const identity = resolveRuntimeIdentity(nomadJobId);
+        if (identity?.driver === "app-job" || identity?.driver === "local-model") {
+            return execInApp(nomadJobId, "", command, timeoutMs ?? 120_000);
+        }
+        if (identity?.driver === "runtime-adapter") {
+            return instanceScheduler.exec(nomadJobId, command, timeoutMs);
+        }
         if (existsSync(instanceMetaPath(nomadJobId))) {
             return instanceScheduler.exec(nomadJobId, command, timeoutMs);
         }
@@ -3684,6 +3886,18 @@ var UnifiedNomadJobs;
         if (isAppJob(nomadJobId)) {
             return streamExecInApp(nomadJobId, taskName, command, handlers, timeoutMs ?? 120_000);
         }
+        const identity = resolveRuntimeIdentity(nomadJobId);
+        if (identity?.driver === "app-job" || identity?.driver === "local-model") {
+            return streamExecInApp(nomadJobId, taskName, command, handlers, timeoutMs ?? 120_000);
+        }
+        if (identity?.driver === "runtime-adapter") {
+            const result = await instanceScheduler.exec(nomadJobId, command, timeoutMs);
+            if (result.stdout)
+                handlers.onStdout?.(result.stdout);
+            if (result.stderr)
+                handlers.onStderr?.(result.stderr);
+            return result;
+        }
         if (existsSync(instanceMetaPath(nomadJobId))) {
             const result = await instanceScheduler.exec(nomadJobId, command, timeoutMs);
             if (result.stdout)
@@ -3719,6 +3933,8 @@ export const getAppStatus = UnifiedNomadJobs.getAppStatus;
 export const startAppJob = UnifiedNomadJobs.startAppJob;
 export const waitForRunning = UnifiedNomadJobs.waitForRunning;
 export const checkDependencies = UnifiedNomadJobs.checkDependencies;
+export const validateNomadPortHostNetworks = UnifiedNomadJobs.validateNomadPortHostNetworks;
+export const buildNomadReservedPort = UnifiedNomadJobs.buildNomadReservedPort;
 export const stopAppJob = UnifiedNomadJobs.stopAppJob;
 export const restartAppJob = UnifiedNomadJobs.restartAppJob;
 export const getAppLogs = UnifiedNomadJobs.getAppLogs;