jishushell 0.4.10 → 0.4.24

package/dist/services/instance-manager.js

@@ -1,13 +1,32 @@
-import { execFile, execFileSync } from "child_process";
-import { randomBytes } from "crypto";
-import { chmodSync, chownSync, copyFileSync, cpSync, existsSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, } from "fs";
+import { execFileSync } from "child_process";
+import { chownSync, closeSync, existsSync, openSync, readFileSync, readdirSync, renameSync, statSync, } from "fs";
+import { rm as rmAsync } from "fs/promises";
 import { createServer as netCreateServer } from "net";
-import { userInfo } from "os";
+import { networkInterfaces, userInfo } from "os";
 import { dirname, join, resolve } from "path";
-import { BACKUPS_DIR, INSTANCES_DIR, JISHUSHELL_HOME, getPanelConfig } from "../config.js";
-import { LEGACY_PROVIDER_API_ALIASES } from "../constants.js";
+import * as config from "../config.js";
 import { safeReadJson, safeWriteJson } from "../utils/safe-json.js";
-import { ensureDirContainer, writeConfigFile, writeSecretFile } from "../utils/fs.js";
+import { ensureDirContainer, writeSecretFile } from "../utils/fs.js";
+// runtime/index.ts gets imported only for framework-level adapter lookups
+// (defaultGatewayPort fallback). Adapters statically import BACK into this
+// file for primitives; that static cycle is safe because no top-level code
+// in adapters references instance-manager exports.
+import { getAdapter, resolveAgentType } from "./runtime/index.js";
+import { backfillInstanceMeta } from "./runtime/migrations.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"), resolve(process.env.HOME ?? userInfo().homedir, ".jishushell"));
+const APPS_DIR = resolveConfigPath(getConfigValue("APPS_DIR"), join(JISHUSHELL_HOME, "apps"));
+const BACKUPS_DIR = resolveConfigPath(getConfigValue("BACKUPS_DIR"), join(JISHUSHELL_HOME, "backups"));
+const INSTANCES_DIR = resolveConfigPath(getConfigValue("INSTANCES_DIR"), join(JISHUSHELL_HOME, "instances"));
+const getPanelConfigValue = getConfigValue("getPanelConfig");
+const getPanelConfig = typeof getPanelConfigValue === "function"
+    ? getPanelConfigValue
+    : () => ({});
 const _configChangeListeners = [];
 export function onConfigChange(listener) {
     _configChangeListeners.push(listener);
@@ -17,41 +36,66 @@ export function onConfigChange(listener) {
             _configChangeListeners.splice(idx, 1);
     };
 }
-const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
-const DEFAULT_GATEWAY_PORT = 18789;
-const INSTANCE_OPENCLAW_HOME_DIRNAME = "openclaw-home";
-const INSTANCE_MODEL_ENV_FILENAME = "model.env";
-const OPENCLAW_STATE_DIRNAME = ".openclaw";
-const OPENCLAW_CONFIG_FILENAME = "openclaw.json";
-// ── Path helpers ──
-function instanceDir(instanceId) {
-    return join(INSTANCES_DIR, instanceId);
+/**
+ * Fire the config-change listener fan-out. Adapters call this after
+ * `saveNativeConfig()` so LLM proxy / config editors pick up the change.
+ */
+export function notifyConfigChange(instanceId) {
+    for (const listener of _configChangeListeners) {
+        try {
+            listener(instanceId);
+        }
+        catch { /* ignore listener errors */ }
+    }
 }
-function instanceMetaPath(instanceId) {
-    return join(instanceDir(instanceId), "instance.json");
+const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+// ── Path helpers (framework-level) ──
+//
+// Physical definitions live in config.ts alongside INSTANCES_DIR so
+// tests that mock instance-manager.js don't lose path resolution. The
+// re-exports below preserve the existing import surface.
+function appInstanceDir(instanceId) {
+    return join(APPS_DIR, instanceId);
 }
-function defaultOpenclawHome(instanceId) {
-    return join(instanceDir(instanceId), INSTANCE_OPENCLAW_HOME_DIRNAME);
+function hasAppInstallMarkers(dir) {
+    return existsSync(join(dir, "manifest.json")) && existsSync(join(dir, "app-spec.yaml"));
 }
-function defaultModelEnvFile(instanceId) {
-    return join(instanceDir(instanceId), INSTANCE_MODEL_ENV_FILENAME);
+function hasIncompleteAppInstallShadow(dir) {
+    const hasManifest = existsSync(join(dir, "manifest.json"));
+    const hasSpec = existsSync(join(dir, "app-spec.yaml"));
+    return (hasManifest || hasSpec) && !(hasManifest && hasSpec);
 }
-function getOpenclawHomeInternal(instanceId) {
-    const meta = getInstance(instanceId);
-    if (meta?.openclaw_home)
-        return meta.openclaw_home;
-    return defaultOpenclawHome(instanceId);
+function resolveInstanceRoot(instanceId) {
+    const appDir = appInstanceDir(instanceId);
+    if (hasAppInstallMarkers(appDir) || (existsSync(join(appDir, "instance.json")) && !hasIncompleteAppInstallShadow(appDir))) {
+        return appDir;
+    }
+    // V1 legacy grandfathered path: fall through to `instances/<id>/` only when
+    // the legacy dir has real content. New instances (neither dir exists) get
+    // the V2 `apps/<id>/` default so they land in the new layout from day one.
+    const legacyDir = join(INSTANCES_DIR, instanceId);
+    if (existsSync(join(legacyDir, "instance.json"))) {
+        return legacyDir;
+    }
+    return appDir;
 }
-function openclawStateDir(instanceId) {
-    return join(getOpenclawHomeInternal(instanceId), OPENCLAW_STATE_DIRNAME);
+export function instanceDir(instanceId) {
+    return resolveInstanceRoot(instanceId);
 }
-function legacyOpenclawConfigPath(instanceId) {
-    return join(getOpenclawHomeInternal(instanceId), OPENCLAW_CONFIG_FILENAME);
+export function instanceMetaPath(instanceId) {
+    return join(instanceDir(instanceId), "instance.json");
 }
-function openclawConfigPathInternal(instanceId) {
-    return join(openclawStateDir(instanceId), OPENCLAW_CONFIG_FILENAME);
+// §32.2 / §32.8: `defaultOpenclawHome` / `openclawStateDir` /
+// `openclawConfigPathInternal` / `legacyOpenclawConfigPath` /
+// `getOpenclawHomeInternal` / `defaultModelEnvFile` physically migrated
+// into `src/services/runtime/adapters/openclaw.ts`. Callers reach them
+// through `getAdapter("openclaw").resolve*()` methods.
+// Re-export `defaultModelEnvFile` as a dispatch wrapper for any
+// remaining framework callers that need an env file path.
+export function defaultModelEnvFile(instanceId) {
+    return join(instanceDir(instanceId), "model.env");
 }
-function normalizePath(p) {
+export function normalizePath(p) {
     return resolve(p.replace(/^~/, userInfo().homedir));
 }
 // ── JSON / deep merge ──
@@ -80,27 +124,32 @@ function deepMerge(base, overlay) {
 // Track in-flight port allocations to prevent race conditions
 // between concurrent createInstance() calls.
 const _pendingPorts = new Set();
-function extractGatewayPort(runtime) {
+/**
+ * Read the gateway port out of a persisted runtime record. Tries
+ * `runtime.ports[]` first (generic framework contract); on miss,
+ * asks the runtime adapter for its legacy fallback (e.g. OpenClaw's
+ * `env.OPENCLAW_GATEWAY_PORT` / `args --port N`).
+ */
+export function extractGatewayPort(runtime, agentType) {
     if (!runtime)
         return null;
-    const envPort = runtime.env?.OPENCLAW_GATEWAY_PORT;
-    if (envPort) {
-        const p = parseInt(envPort, 10);
-        if (!isNaN(p))
-            return p;
-    }
-    const args = runtime.args || [];
-    for (let i = 0; i < args.length; i++) {
-        const arg = String(args[i]);
-        if (arg === "--port" && i + 1 < args.length) {
-            const p = parseInt(args[i + 1], 10);
-            return isNaN(p) ? null : p;
+    // Primary: RuntimeSpec.ports[] declaration — first gateway-labeled port wins.
+    const ports = Array.isArray(runtime.ports) ? runtime.ports : [];
+    for (const port of ports) {
+        if (port?.name === "gateway" && Number.isInteger(port.hostPort) && port.hostPort > 0) {
+            return port.hostPort;
         }
-        if (arg.startsWith("--port=")) {
-            const p = parseInt(arg.split("=")[1], 10);
-            return isNaN(p) ? null : p;
+    }
+    // Fall back to the adapter's legacy reader. Default agentType "openclaw".
+    try {
+        const adapter = getAdapter(agentType || "openclaw");
+        if (typeof adapter.readLegacyGatewayPort === "function") {
+            return adapter.readLegacyGatewayPort(runtime);
         }
     }
+    catch {
+        /* adapter not registered — no fallback */
+    }
     return null;
 }
 function usedGatewayPorts(excludeId) {
@@ -119,25 +168,83 @@ function safePort(port) {
         throw new Error(`Invalid port: ${port}`);
     return String(port);
 }
-function isPortInUse(port) {
+/**
+ * Probes whether a port is currently held by any process on the host.
+ *
+ * Binds four addresses concurrently — `0.0.0.0`, `127.0.0.1`, `::` (v6-only),
+ * and `::1` — and treats the port as busy if any probe returns EADDRINUSE.
+ * The single-`0.0.0.0` probe used by the earlier revision was sufficient on
+ * Linux (where binding `0.0.0.0` conflicts with any pre-existing loopback
+ * listener on the same port) but silently passed on macOS, where BSD socket
+ * semantics let a wildcard v4 bind coexist with a `127.0.0.1` listener. A
+ * user running a natively-installed openclaw bound to `127.0.0.1:18789`
+ * would then be invisible to jishushell, so port allocation would assign
+ * 18789 to a new instance and the gateway would silently fail to bind at
+ * start time. Probing the loopback addresses directly closes that gap.
+ */
+export function isPortInUse(port) {
     if (!Number.isInteger(port) || port < 1 || port > 65535)
         return Promise.resolve(false);
-    return new Promise((resolve) => {
+    const probeAt = (host, opts = {}) => new Promise((resolve) => {
         const server = netCreateServer();
-        server.once("error", () => resolve(true));
+        server.once("error", (err) => {
+            if (err?.code === "EADDRINUSE")
+                return resolve(true);
+            // EACCES / EADDRNOTAVAIL / ENOTSUP / EINVAL mean we could not even
+            // attempt the bind (restricted port, address family unsupported on
+            // this host, etc). Report "not busy" from this probe so one bad
+            // locus doesn't falsely block the whole port — the other probes
+            // still cover their respective loci.
+            if (err?.code && err.code !== "EACCES" && err.code !== "EADDRNOTAVAIL"
+                && err.code !== "ENOTSUP" && err.code !== "EINVAL" && err.code !== "EAFNOSUPPORT") {
+                console.warn(`[port-probe] bind ${host}:${port} failed with ${err.code}: ${err.message}; treating locus as free`);
+            }
+            resolve(false);
+        });
         server.once("listening", () => {
             server.close(() => resolve(false));
         });
-        server.listen(port, "0.0.0.0");
+        server.listen({ port, host, ...opts });
     });
+    // Run probes sequentially, not in parallel: two probes on the same port
+    // collide with each other (the first bind on 0.0.0.0 makes the second
+    // bind on 127.0.0.1 hit EADDRINUSE), which would make every port look
+    // busy. Short-circuit on the first busy locus to keep the common case
+    // (port free) close to single-probe latency.
+    return (async () => {
+        const loci = [
+            ["0.0.0.0", {}],
+            ["127.0.0.1", {}],
+            ["::", { ipv6Only: true }],
+            ["::1", {}],
+        ];
+        for (const [host, opts] of loci) {
+            if (await probeAt(host, opts))
+                return true;
+        }
+        return false;
+    })();
 }
-async function defaultGatewayPort(instanceId) {
+/**
+ * Kind-agnostic gateway port allocator. Callers (adapters) pass their own
+ * `defaultPort` — the framework no longer hardcodes OpenClaw / Hermes base
+ * ports here. Walks upward from `defaultPort` until a free port is found
+ * that is neither held by an existing instance nor by any process on the
+ * host. Concurrent callers coordinate via `_pendingPorts`.
+ *
+ * Caller must release the allocated port via {@link releasePendingPort}
+ * after persisting it into instance metadata (or on failure).
+ */
+export async function allocateGatewayPort(instanceId, defaultPort) {
     const used = usedGatewayPorts(instanceId);
-    let port = DEFAULT_GATEWAY_PORT;
+    const skipped = [];
+    let port = defaultPort;
     while (true) {
-        if (port > 65535)
-            throw new Error("No available gateway port found (all ports 18789-65535 in use)");
+        if (port > 65535) {
+            throw new Error(`No available gateway port found (all ports ${defaultPort}-65535 in use)`);
+        }
         if (used.has(port) || _pendingPorts.has(port)) {
+            skipped.push(port);
             port++;
             continue;
         }
@@ -147,49 +254,38 @@ async function defaultGatewayPort(instanceId) {
         try {
             if (await isPortInUse(port)) {
                 _pendingPorts.delete(port);
+                skipped.push(port);
                 port++;
                 continue;
             }
-            return port;
+            return { port, skipped };
         }
         catch {
             _pendingPorts.delete(port);
             // Skip this port on a transient OS error rather than failing the entire
             // allocation — a single bad port check should not prevent instance creation.
             console.warn(`[instance] Port ${port} availability check failed, trying next port`);
+            skipped.push(port);
             port++;
             continue;
         }
     }
 }
-// ── Runtime / config builders ──
-function resolveOpenclawBin() {
-    const candidates = [
-        join(JISHUSHELL_HOME, "packages", "openclaw", "bin", "openclaw"),
-        "/usr/local/bin/openclaw",
-        "/usr/bin/openclaw",
-    ];
-    for (const p of candidates) {
-        if (existsSync(p)) {
-            // Ensure executable permission (npm install may strip +x on some platforms)
-            try {
-                chmodSync(p, 0o755);
-            }
-            catch { /* best effort — may be a symlink */ }
-            // If symlink, also chmod the target
-            try {
-                const real = realpathSync(p);
-                if (real !== p)
-                    chmodSync(real, 0o755);
-            }
-            catch { /* best effort */ }
-            return p;
-        }
-    }
-    return candidates[0]; // fallback, will fail with clear error at spawn
+/** Release a port previously reserved by {@link allocateGatewayPort}. */
+export function releasePendingPort(port) {
+    _pendingPorts.delete(port);
 }
+// ── Runtime / config builders ──
 export function getResolvedOpenclawBin() {
-    return resolveOpenclawBin();
+    try {
+        const a = getAdapter("openclaw");
+        return typeof a.resolveBin === "function"
+            ? a.resolveBin()
+            : "/usr/local/bin/openclaw";
+    }
+    catch {
+        return "/usr/local/bin/openclaw";
+    }
 }
 /**
  * When jishushell runs as root (e.g. systemd service), returns the actual
@@ -229,7 +325,7 @@ export function resolveServiceUser() {
  * openclaw process (running as that user) can read/write its own data files.
  * No-op when not running as root.
  */
-function chownToServiceUser(...paths) {
+export function chownToServiceUser(...paths) {
     const svc = resolveServiceUser();
     if (!svc)
         return;
@@ -243,90 +339,9 @@ function chownToServiceUser(...paths) {
         }
     }
 }
-async function defaultRuntime(instanceId, openclawHome) {
-    const port = await defaultGatewayPort(instanceId);
-    const home = openclawHome || defaultOpenclawHome(instanceId);
-    return {
-        command: resolveOpenclawBin(),
-        args: ["gateway", "run", "--port", String(port), "--allow-unconfigured"],
-        cwd: home,
-        user: resolveServiceUser()?.username ?? userInfo().username,
-        env_files: [defaultModelEnvFile(instanceId)],
-        env: {
-            OPENCLAW_GATEWAY_PORT: String(port),
-            NODE_OPTIONS: "--max-old-space-size=2048",
-        },
-        resources: { CPU: 1000, MemoryMB: 2048 },
-    };
-}
-function starterConfig() {
-    const dp = getPanelConfig().default_provider;
-    let providerName = "minimax";
-    let providerConfig = {
-        baseUrl: "https://api.minimaxi.com/v1",
-        api: "openai-completions",
-        models: [{ id: "MiniMax-M2.7", name: "MiniMax M2.7", contextWindow: 204800 }],
-    };
-    let defaultModel = "minimax/MiniMax-M2.7";
-    if (dp?.providerId) {
-        providerName = dp.providerId;
-        providerConfig = {
-            baseUrl: dp.baseUrl,
-            api: dp.api,
-            ...(dp.authHeader ? { authHeader: true } : {}),
-            models: dp.models || [],
-        };
-        const modelId = dp.selectedModelId || dp.models?.[0]?.id || "";
-        defaultModel = `${providerName}/${modelId}`;
-    }
-    const config = {
-        models: { providers: { [providerName]: providerConfig } },
-        agents: { defaults: { model: defaultModel, models: { [defaultModel]: {} } } },
-        channels: {},
-        gateway: {
-            mode: "local",
-            auth: { mode: "token", token: randomBytes(24).toString("hex") },
-            controlUi: { dangerouslyDisableDeviceAuth: true },
-        },
-        plugins: { entries: { feishu: { enabled: false } } },
-    };
-    // Store upstream proxy config so LLM proxy knows where to forward
-    if (dp?.providerId) {
-        config["x-jishushell"] = {
-            proxy: {
-                upstream: {
-                    providerId: dp.providerId,
-                    baseUrl: dp.baseUrl,
-                    api: dp.api,
-                    authHeader: dp.authHeader || false,
-                    models: dp.models || [],
-                    selectedModelId: dp.selectedModelId || dp.models?.[0]?.id || "",
-                    hasApiKey: !!dp.apiKey,
-                },
-            },
-        };
-    }
-    return config;
-}
-// ── Config loading ──
-function loadEffectiveConfig(instanceId) {
-    const runtimePath = openclawConfigPathInternal(instanceId);
-    const legacyPath = legacyOpenclawConfigPath(instanceId);
-    const rExists = existsSync(runtimePath);
-    const lExists = existsSync(legacyPath);
-    if (rExists && lExists) {
-        const legacy = loadJson(legacyPath);
-        const runtime = loadJson(runtimePath);
-        if (legacy && runtime)
-            return deepMerge(legacy, runtime);
-        return runtime || legacy || null;
-    }
-    if (rExists)
-        return loadJson(runtimePath);
-    if (lExists)
-        return loadJson(legacyPath);
-    return null;
-}
+// §32.2 / §32.8: buildDefaultRuntime + starterConfig physically migrated
+// into src/services/runtime/adapters/openclaw.ts. Framework layer no
+// longer owns OpenClaw runtime templates or default config shape.
 // ── Env file helpers ──
 export function parseEnvFile(path) {
     const env = {};
@@ -400,610 +415,106 @@ export function inferProviderApiKeyEnvName(providerId) {
         normalized = "OPENCLAW_PROVIDER";
     return `${normalized}_API_KEY`;
 }
-function hasConfiguredValue(value) {
-    if (typeof value === "string")
-        return value.trim().length > 0;
-    if (typeof value === "object" && value !== null)
-        return Object.keys(value).length > 0;
-    return value != null;
-}
-function injectProviderApiKeys(instanceId, config) {
-    const merged = structuredClone(config);
-    const runtimeEnv = getRuntimeEnv(instanceId);
-    const providers = merged.models?.providers || {};
-    for (const [providerId, provider] of Object.entries(providers)) {
-        if (typeof provider !== "object" || provider === null)
-            continue;
-        const p = provider;
-        const api = p.api;
-        if (typeof api === "string" && api in LEGACY_PROVIDER_API_ALIASES) {
-            p.api = LEGACY_PROVIDER_API_ALIASES[api];
-        }
-        const apiKey = runtimeEnv[inferProviderApiKeyEnvName(providerId)];
-        if (apiKey)
-            p.apiKey = apiKey;
-    }
-    return merged;
-}
-function applyFeishuDebugAccessDefaults(channel) {
-    if (channel.enabled === false)
-        return;
-    if (!hasConfiguredValue(channel.appId))
-        return;
-    if (!hasConfiguredValue(channel.appSecret))
-        return;
-    let dmPolicy = channel.dmPolicy;
-    if (typeof dmPolicy !== "string" || !dmPolicy.trim()) {
-        channel.dmPolicy = "open";
-        dmPolicy = "open";
-    }
-    if (dmPolicy !== "open")
-        return;
-    if (!("resolveSenderNames" in channel))
-        channel.resolveSenderNames = false;
-    let accounts = channel.accounts;
-    if (typeof accounts !== "object" || accounts === null) {
-        accounts = {};
-        channel.accounts = accounts;
-    }
-    let defaultAccount = accounts.default;
-    if (typeof defaultAccount !== "object" || defaultAccount === null) {
-        defaultAccount = {};
-        accounts.default = defaultAccount;
-    }
-    if (!("resolveSenderNames" in defaultAccount))
-        defaultAccount.resolveSenderNames = false;
-    const allowFrom = channel.allowFrom;
-    if (Array.isArray(allowFrom)) {
-        const normalized = allowFrom.map((e) => String(e).trim()).filter(Boolean);
-        if (!normalized.includes("*"))
-            normalized.push("*");
-        channel.allowFrom = normalized;
-        return;
-    }
-    channel.allowFrom = ["*"];
-}
-function prepareConfigForSave(instanceId, config) {
-    const configToWrite = structuredClone(config);
-    // Remove JishuShell metadata — OpenClaw rejects unrecognized keys
-    delete configToWrite["x-jishushell"];
-    const envUpdates = {};
-    const providers = configToWrite.models?.providers || {};
-    const envFiles = getRuntimeEnvFiles(instanceId);
-    const channels = configToWrite.channels || {};
-    const plugins = configToWrite.plugins ??= {};
-    const pluginEntries = plugins.entries ??= {};
-    for (const [providerId, provider] of Object.entries(providers)) {
-        if (typeof provider !== "object" || provider === null)
-            continue;
-        const p = provider;
-        if (typeof p.api === "string" && p.api in LEGACY_PROVIDER_API_ALIASES) {
-            p.api = LEGACY_PROVIDER_API_ALIASES[p.api];
-        }
-        if (!("apiKey" in p))
-            continue;
-        // Keep proxy provider apiKey in config — OpenClaw reads it from config directly.
-        // Only real upstream provider keys get moved to env files for security.
-        // Detect proxy by baseUrl (provider ID now uses upstream name for display).
-        if (typeof p.baseUrl === "string" && p.baseUrl.includes("/proxy/"))
-            continue;
-        const apiKey = p.apiKey;
-        delete p.apiKey;
-        if (envFiles.length) {
-            envUpdates[inferProviderApiKeyEnvName(providerId)] = String(apiKey || "");
-        }
-        else {
-            p.apiKey = apiKey;
-        }
-    }
-    for (const [channelId, channel] of Object.entries(channels)) {
-        if (typeof channel !== "object" || channel === null)
-            continue;
-        const ch = channel;
-        if (channelId === "feishu" || channelId === "lark")
-            applyFeishuDebugAccessDefaults(ch);
-        let pluginEntry = pluginEntries[channelId];
-        if (pluginEntry == null) {
-            pluginEntry = {};
-            pluginEntries[channelId] = pluginEntry;
-        }
-        if (typeof pluginEntry === "object") {
-            pluginEntry.enabled = ch.enabled !== false;
-        }
-    }
-    return [configToWrite, envUpdates];
-}
-// ── Channel plugin helpers ──
-// Channel → plugin package mapping for auto-install.
-// Stock plugins (bundled with newer OpenClaw) are detected via extensions/{id} dir;
-// if missing (older OpenClaw), they get installed as fallback.
-// @larksuite/openclaw-lark installs as "openclaw-lark" dir but registers channel "feishu"
-const CHANNEL_EXT_DIR_ALIAS = {
-    feishu: "openclaw-lark",
-    lark: "openclaw-lark",
-};
-export const CHANNEL_PLUGIN_MAP = {
-    // Official vendor plugins (ByteDance Feishu/Lark)
-    feishu: "@larksuite/openclaw-lark",
-    lark: "@larksuite/openclaw-lark",
-    // Built-in (stock) — fallback install for older OpenClaw versions
-    telegram: "@openclaw/telegram",
-    discord: "@openclaw/discord",
-    slack: "@openclaw/slack",
-    whatsapp: "@openclaw/whatsapp",
-    signal: "@openclaw/signal",
-    line: "@openclaw/line",
-    msteams: "@openclaw/msteams",
-    // Official vendor plugins — need install (not bundled)
-    "openclaw-weixin": "@tencent-weixin/openclaw-weixin",
-};
-/**
- * Known IM plugin entry IDs as they appear under `config.plugins.entries`.
- * This is the union of channel IDs and the dir-alias names (e.g. `feishu` may
- * register the plugin as `openclaw-lark`), which is what must be scrubbed when
- * dissociating an instance from its inherited IM bindings.
- */
-const IM_PLUGIN_ENTRY_IDS = new Set([
-    ...Object.keys(CHANNEL_PLUGIN_MAP),
-    ...Object.values(CHANNEL_EXT_DIR_ALIAS),
-]);
-/**
- * Dissociate a cloned/imported config from its source instance's IM bindings.
- *
- * Mutates the given config in place:
- *   - Deletes the entire `channels` block (same channel cannot serve multiple
- *     instances, so every inherited enabled/credential/account entry must go).
- *   - Deletes matching IM entries from `plugins.entries` so the plugin loader
- *     does not try to boot a channel whose config no longer exists.
- *
- * Used by both domain clone (`createInstance`'s `cloneFrom` path) and the
- * backup import paths (`importInstance`, `createFromBackup`) so that a new
- * instance never inherits a half-configured IM binding.
- */
-export function stripImBindings(config) {
-    if (config?.channels)
-        delete config.channels;
-    const entries = config?.plugins?.entries;
-    if (entries && typeof entries === "object") {
-        for (const key of Object.keys(entries)) {
-            if (IM_PLUGIN_ENTRY_IDS.has(key))
-                delete entries[key];
-        }
-    }
-}
-/** Check if a channel plugin is installed for an instance. */
-export function isChannelPluginInstalled(instanceId, channelId) {
-    const extDirName = CHANNEL_EXT_DIR_ALIAS[channelId] || channelId;
-    const stockExtDir = getStockExtensionsDir();
-    return existsSync(join(getChannelExtensionsDir(instanceId), extDirName))
-        || existsSync(join(stockExtDir, extDirName))
-        // Also accept the built-in directory named after the raw channelId (e.g. "feishu/" in stock)
-        || (extDirName !== channelId && existsSync(join(stockExtDir, channelId)));
-}
-/**
- * Install a single channel plugin.
- * Docker mode: runs install inside the running container via docker exec.
- * Host mode (fallback): spawns the host openclaw binary directly.
- */
-export async function installChannelPlugin(instanceId, channelId) {
-    const pkg = CHANNEL_PLUGIN_MAP[channelId];
-    if (!pkg)
-        throw new Error(`Unknown channel: ${channelId}`);
-    if (isChannelPluginInstalled(instanceId, channelId))
-        return;
-    const openclawHome = getOpenclawHomeInternal(instanceId);
-    const extensionsDir = getChannelExtensionsDir(instanceId);
-    // Docker mode: always install inside container via docker exec
-    const { getNomadDriver } = await import("../config.js");
-    if (getNomadDriver() === "docker") {
-        await installChannelPluginViaDocker(instanceId, channelId, pkg, extensionsDir);
-        return;
-    }
-    const openclawBin = resolveOpenclawBin();
-    // Host mode: spawn openclaw binary directly
-    const nodeBinDir = dirname(process.execPath);
-    const childPath = [nodeBinDir, process.env.PATH].filter(Boolean).join(":");
-    const proxyEnvKeys = [
-        "http_proxy", "HTTP_PROXY", "https_proxy", "HTTPS_PROXY",
-        "no_proxy", "NO_PROXY", "NODE_EXTRA_CA_CERTS", "NODE_TLS_REJECT_UNAUTHORIZED",
-    ];
-    const proxyEnv = {};
-    for (const key of proxyEnvKeys) {
-        if (process.env[key])
-            proxyEnv[key] = process.env[key];
-    }
-    const childEnv = {
-        PATH: childPath,
-        HOME: process.env.HOME,
-        LANG: process.env.LANG,
-        OPENCLAW_HOME: openclawHome,
-        ...proxyEnv,
-    };
-    const MAX_ATTEMPTS = 3;
-    const RETRY_DELAY_MS = 5_000;
-    const attemptInstall = () => new Promise((resolve, reject) => {
-        execFile(openclawBin, ["plugins", "install", pkg], {
-            cwd: openclawHome,
-            env: childEnv,
-            timeout: 300_000,
-        }, (err, stdout, stderr) => {
-            if (err && !isChannelPluginInstalled(instanceId, channelId)) {
-                const msg = [stderr?.trim(), stdout?.trim(), err.message].filter(Boolean).join(" | ");
-                console.error(`[plugins] ${pkg} exit code ${err.code ?? '?'}, stderr: ${stderr?.trim() || '(empty)'}, stdout: ${stdout?.trim() || '(empty)'}`);
-                try {
-                    if (existsSync(extensionsDir)) {
-                        for (const entry of readdirSync(extensionsDir)) {
-                            if (entry.startsWith(".openclaw-install-stage-")) {
-                                rmSync(join(extensionsDir, entry), { recursive: true, force: true });
-                                console.log(`[plugins] Cleaned up stage dir: ${entry}`);
-                            }
-                        }
-                    }
-                }
-                catch (_) { }
-                reject(new Error(msg));
-            }
-            else {
-                if (err)
-                    console.log(`[plugins] ${pkg} installed (ignored non-zero exit: warning only)`);
-                else
-                    console.log(`[plugins] ${pkg} installed`);
-                resolve();
-            }
-        });
-    });
-    console.log(`[plugins] Installing ${pkg} for ${channelId} (host)...`);
-    let lastErr;
-    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
-        try {
-            await attemptInstall();
-            const extDirName = CHANNEL_EXT_DIR_ALIAS[channelId] || channelId;
-            const installedExtDir = join(extensionsDir, extDirName);
-            if (existsSync(installedExtDir)) {
-                ensureDirContainer(installedExtDir);
-                try {
-                    for (const entry of readdirSync(installedExtDir, { withFileTypes: true })) {
-                        if (entry.isDirectory()) {
-                            ensureDirContainer(join(installedExtDir, entry.name));
-                        }
-                    }
-                }
-                catch { /* best effort */ }
-            }
-            ensureDirContainer(extensionsDir);
-            return;
-        }
-        catch (err) {
-            lastErr = err;
-            const isFetchError = /fetch failed/i.test(err.message ?? "");
-            if (isFetchError && attempt < MAX_ATTEMPTS) {
-                console.warn(`[plugins] ${pkg} install attempt ${attempt}/${MAX_ATTEMPTS} failed with fetch error, retrying in ${RETRY_DELAY_MS / 1000}s...`);
-                await new Promise(r => setTimeout(r, RETRY_DELAY_MS));
-                continue;
-            }
-            console.error(`[plugins] Failed to install ${pkg}:`, err.message);
-            break;
-        }
-    }
-    throw lastErr;
-}
+// §32.2 / §32.8: hasConfiguredValue / injectProviderApiKeys /
+// applyFeishuDebugAccessDefaults / prepareConfigForSave physically
+// migrated into `src/services/runtime/adapters/openclaw.ts`.
+// §32.2 / §32.8: Channel plugin helpers (CHANNEL_PLUGIN_MAP,
+// installChannelPlugin, stripImBindings, etc.) physically migrated
+// into `src/services/runtime/adapters/openclaw.ts`.
+// ── Public API ──
 /**
- * Install a channel plugin inside the running Docker container via nomad-manager.exec().
- * Requires the instance to be running — the extensions dir is bind-mounted so
- * the install persists on the host filesystem.
+ * Probe whether a file is readable by the current process. Used to
+ * distinguish "primary missing / corrupted" (recoverable via safeReadJson's
+ * .bak chain) from "primary exists but permission denied" (EACCES — the
+ * common sudo-script footgun that leaves root-owned files). safeReadJson
+ * swallows every read error internally and returns null, so without this
+ * probe an unreadable primary looks identical to a truly-gone instance.
  */
-async function installChannelPluginViaDocker(instanceId, channelId, pkg, extensionsDir) {
-    const { exec } = await import("./nomad-manager.js");
-    const MAX_ATTEMPTS = 3;
-    const RETRY_DELAY_MS = 5_000;
-    console.log(`[plugins] Installing ${pkg} for ${channelId} via docker exec (instance: ${instanceId})...`);
-    let lastErr;
-    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
-        try {
-            const result = await exec(instanceId, ["openclaw", "plugins", "install", pkg], 300_000);
-            // Check if plugin was actually installed (openclaw may exit non-zero with warnings)
-            if (result.exitCode !== 0 && !isChannelPluginInstalled(instanceId, channelId)) {
-                const msg = [result.stderr?.trim(), result.stdout?.trim()].filter(Boolean).join(" | ");
-                console.error(`[plugins] ${pkg} docker exec exit code ${result.exitCode}, output: ${msg}`);
-                throw new Error(msg || `openclaw plugins install exited with code ${result.exitCode}`);
-            }
-            if (result.exitCode !== 0) {
-                console.log(`[plugins] ${pkg} installed via docker (ignored non-zero exit: warning only)`);
-            }
-            else {
-                console.log(`[plugins] ${pkg} installed via docker`);
-            }
-            // Fix ownership on host side
-            const extDirName = CHANNEL_EXT_DIR_ALIAS[channelId] || channelId;
-            const installedExtDir = join(extensionsDir, extDirName);
-            if (existsSync(installedExtDir)) {
-                ensureDirContainer(installedExtDir);
-                try {
-                    for (const entry of readdirSync(installedExtDir, { withFileTypes: true })) {
-                        if (entry.isDirectory()) {
-                            ensureDirContainer(join(installedExtDir, entry.name));
-                        }
-                    }
-                }
-                catch { /* best effort */ }
-            }
-            ensureDirContainer(extensionsDir);
-            return;
-        }
-        catch (err) {
-            lastErr = err;
-            // "Instance is not running" from nomad-manager.exec() — give a clear user-facing message
-            if (/not running/i.test(err.message ?? "")) {
-                throw new Error("请先启动实例后再安装插件（Docker 模式下插件需在容器内安装）");
-            }
-            const isTransient = /fetch failed|ECONNREFUSED/i.test(err.message ?? "");
-            if (isTransient && attempt < MAX_ATTEMPTS) {
-                console.warn(`[plugins] ${pkg} docker install attempt ${attempt}/${MAX_ATTEMPTS} failed, retrying in ${RETRY_DELAY_MS / 1000}s...`);
-                await new Promise(r => setTimeout(r, RETRY_DELAY_MS));
-                continue;
-            }
-            console.error(`[plugins] Failed to install ${pkg} via docker:`, err.message);
-            break;
-        }
-    }
-    throw lastErr;
-}
-function getChannelExtensionsDir(instanceId) {
-    return join(getOpenclawHomeInternal(instanceId), OPENCLAW_STATE_DIRNAME, "extensions");
-}
-function getStockExtensionsDir() {
-    return join(JISHUSHELL_HOME, "packages", "openclaw", "lib", "node_modules", "openclaw", "extensions");
-}
-// ── Public API ──
-export function listInstances() {
-    if (!existsSync(INSTANCES_DIR))
-        return [];
-    const entries = readdirSync(INSTANCES_DIR).sort();
-    const instances = [];
-    for (const name of entries) {
-        const metaPath = join(INSTANCES_DIR, name, "instance.json");
-        const dirPath = join(INSTANCES_DIR, name);
-        try {
-            if (statSync(dirPath).isDirectory() && existsSync(metaPath)) {
-                instances.push(JSON.parse(readFileSync(metaPath, "utf-8")));
-            }
-        }
-        catch (e) {
-            // Permission errors (EACCES) caused by root-owned files are a common deployment
-            // mistake (e.g. running a maintenance script as sudo). Log clearly instead of
-            // silently dropping the instance from the list.
-            console.error(`[instance-manager] cannot read instance '${name}': ${e.message}`);
-        }
-    }
-    return instances;
-}
-export function getInstance(instanceId) {
-    const metaPath = instanceMetaPath(instanceId);
-    if (!existsSync(metaPath))
+function probeReadable(path) {
+    if (!existsSync(path))
         return null;
     try {
-        return JSON.parse(readFileSync(metaPath, "utf-8"));
+        const fd = openSync(path, "r");
+        closeSync(fd);
+        return null;
     }
     catch (e) {
-        // Surface permission errors clearly (EACCES: instance.json owned by root after a sudo script)
-        throw new Error(`Cannot read instance '${instanceId}' metadata: ${e.message}. Check file ownership with: ls -la ${metaPath}`);
+        return e;
     }
 }
-export async function createInstance(instanceId, name, description = "", cloneFrom, openclawHome, cloneOptions) {
-    const d = instanceDir(instanceId);
-    if (existsSync(d))
-        throw new Error(`Instance '${instanceId}' already exists`);
-    const home = openclawHome ? normalizePath(openclawHome) : defaultOpenclawHome(instanceId);
-    // Restrict openclaw_home to be under JISHUSHELL_HOME or /home to prevent path traversal.
-    // Use realpathSync after mkdir to resolve symlinks, preventing symlink-based bypasses.
-    if (openclawHome) {
-        const resolved = resolve(home);
-        if (!resolved.startsWith(JISHUSHELL_HOME) && !resolved.startsWith("/home/")) {
-            throw new Error(`openclaw_home must be under ${JISHUSHELL_HOME} or /home/`);
-        }
-        // Resolve symlinks for the parent dir to catch symlink attacks
-        const parentDir = dirname(resolved);
-        if (existsSync(parentDir)) {
-            const realParent = realpathSync(parentDir);
-            if (!realParent.startsWith(JISHUSHELL_HOME) && !realParent.startsWith("/home/")) {
-                throw new Error(`openclaw_home parent resolves outside allowed paths (symlink detected)`);
-            }
-        }
-        const shared = listInstances().filter((inst) => normalizePath(inst.openclaw_home || defaultOpenclawHome(inst.id)) === normalizePath(home));
-        if (shared.length) {
-            throw new Error(`OpenClaw home '${home}' is already used by instance(s): ${shared.map((i) => i.id).join(", ")}`);
-        }
-    }
-    // Check for orphaned openclaw_home directory (e.g. instance.json deleted but data remains)
-    if (existsSync(home)) {
-        try {
-            const entries = readdirSync(home);
-            if (entries.length > 0) {
-                throw new Error(`OpenClaw home directory '${home}' already exists and is not empty. Remove it manually or choose a different path.`);
-            }
-        }
-        catch (e) {
-            if (e.message.includes("not empty"))
-                throw e;
-            // readdirSync failed — directory might not be readable, proceed cautiously
-        }
-    }
-    ensureDirContainer(d);
-    // Inherit group from INSTANCES_DIR so both root and the real user can access
-    try {
-        const parentGid = statSync(INSTANCES_DIR).gid;
-        chownSync(d, -1, parentGid);
-    }
-    catch { /* non-root without CAP_CHOWN — already correct owner */ }
-    ensureDirContainer(home);
-    ensureDirContainer(join(home, OPENCLAW_STATE_DIRNAME));
-    const runtime = await defaultRuntime(instanceId, home);
-    const allocatedPort = extractGatewayPort(runtime);
-    // Port already reserved inside defaultGatewayPort; just track for cleanup
-    try {
-        const meta = {
-            id: instanceId,
-            name,
-            description,
-            openclaw_home: home,
-            runtime,
-            created_at: new Date().toISOString(),
-        };
-        safeWriteJson(instanceMetaPath(instanceId), meta);
-        const envFiles = (runtime.env_files || []).map((p) => normalizePath(p));
-        for (const ef of envFiles) {
-            if (!existsSync(ef))
-                writeConfigFile(ef, "");
-        }
-        // After writing env files, ensure the runtime user can read them
-        try {
-            const runtimeUser = runtime.user;
-            if (runtimeUser && runtimeUser !== userInfo().username) {
-                for (const ef of envFiles) {
-                    execFileSync("chown", [runtimeUser, ef], { timeout: 5000 });
-                }
-            }
-        }
-        catch { /* ignore - same user or no permission to chown */ }
-        const configPath = openclawConfigPathInternal(instanceId);
-        ensureDirContainer(dirname(configPath));
-        if (cloneFrom && !existsSync(configPath)) {
-            const srcConfig = resolveExistingConfigPath(cloneFrom);
-            if (existsSync(srcConfig)) {
-                // Domain-level clone: copy config but strip proxy identity (token, jsproxy provider)
-                // so the new instance gets its own proxy token via saveInstanceConfig later
-                try {
-                    const cloned = JSON.parse(readFileSync(srcConfig, "utf-8"));
-                    // Remove proxy provider (will be regenerated with new proxy token)
-                    // Detect by baseUrl since provider ID now uses upstream name (e.g. "js-minimax")
-                    const providers = cloned?.models?.providers;
-                    if (providers) {
-                        for (const [pid, prov] of Object.entries(providers)) {
-                            if (typeof prov?.baseUrl === "string" && prov.baseUrl.includes("/proxy/")) {
-                                delete providers[pid];
-                            }
-                        }
-                    }
-                    // Remove proxy model reference from agent defaults (regenerated by bootstrap)
-                    const defaultModel = cloned?.agents?.defaults?.model;
-                    if (typeof defaultModel === "string" && (defaultModel.startsWith("jsproxy/") || defaultModel.startsWith("js-"))) {
-                        delete cloned.agents.defaults.model;
-                    }
-                    // Strip IM channel configs + matching plugin entries — same channel
-                    // cannot serve multiple instances and we don't want the plugin
-                    // loader to boot a half-configured binding.
-                    stripImBindings(cloned);
-                    // Copy extensions directory so plugin references in config remain valid
-                    // Copy workspace directory to preserve agent personality (.md files)
-                    const subdirs = ["extensions", "workspace"];
-                    if (cloneOptions?.include_memory !== false) {
-                        // Memory may exist at .openclaw/memory/ if created by OpenClaw runtime
-                        const memDir = join(dirname(srcConfig), "memory");
-                        if (existsSync(memDir))
-                            subdirs.push("memory");
-                    }
-                    if (cloneOptions?.include_sessions) {
-                        // Sessions at .openclaw/agents/main/sessions/
-                        const sessDir = join(dirname(srcConfig), "agents");
-                        if (existsSync(sessDir))
-                            subdirs.push("agents");
-                    }
-                    for (const subdir of subdirs) {
-                        const srcDir = join(dirname(srcConfig), subdir);
-                        const dstDir = join(dirname(configPath), subdir);
-                        if (existsSync(srcDir) && !existsSync(dstDir)) {
-                            try {
-                                cpSync(srcDir, dstDir, { recursive: true });
-                            }
-                            catch { /* best effort */ }
-                        }
-                    }
-                    writeConfigFile(configPath, JSON.stringify(cloned, null, 2));
-                    // Copy x-jishushell upstream metadata from source instance.json
-                    // (saveConfig stores x-jishushell in instance.json, not openclaw.json)
-                    const srcMetaPath = join(instanceDir(cloneFrom), "instance.json");
-                    if (existsSync(srcMetaPath)) {
-                        try {
-                            const srcMeta = JSON.parse(readFileSync(srcMetaPath, "utf-8"));
-                            const srcXj = srcMeta?.["x-jishushell"];
-                            if (srcXj?.proxy?.upstream) {
-                                const dstXj = { proxy: { upstream: srcXj.proxy.upstream } };
-                                // Clear instance-specific fields
-                                delete dstXj.proxy.upstream.apiKey;
-                                const metaPath = instanceMetaPath(instanceId);
-                                if (existsSync(metaPath)) {
-                                    const dstMeta = JSON.parse(readFileSync(metaPath, "utf-8"));
-                                    dstMeta["x-jishushell"] = dstXj;
-                                    writeConfigFile(metaPath, JSON.stringify(dstMeta, null, 2));
-                                }
-                            }
-                        }
-                        catch { /* ignore metadata copy errors */ }
-                    }
-                }
-                catch {
-                    // Fallback: raw copy if parse fails
-                    copyFileSync(srcConfig, configPath);
-                }
-            }
-        }
-        if (!existsSync(configPath)) {
-            writeConfigFile(configPath, JSON.stringify(starterConfig(), null, 2));
-            // Inject default provider API key from setup into both env files
-            const dp = getPanelConfig().default_provider;
-            if (dp?.apiKey && dp?.providerId && envFiles.length) {
-                const envKey = inferProviderApiKeyEnvName(dp.providerId);
-                updateEnvFile(envFiles[0], { [envKey]: dp.apiKey });
-                // Also write to provider.env as UPSTREAM_API_KEY (LLM proxy reads this first)
-                const providerEnv = join(dirname(envFiles[0]), "provider.env");
-                updateEnvFile(providerEnv, { UPSTREAM_API_KEY: dp.apiKey });
-            }
-        }
-        // Copy cloned provider.env BEFORE proxy bootstrap so bootstrap can find the API key
-        if (cloneFrom && envFiles.length) {
-            const srcEnvFiles = getRuntimeEnvFiles(cloneFrom);
-            const srcEnvFile = srcEnvFiles[0];
-            const dstEnvFile = envFiles[0];
-            // Copy provider.env (upstream API key)
-            if (srcEnvFile) {
-                const srcProvider = join(dirname(srcEnvFile), "provider.env");
-                const dstProvider = join(dirname(dstEnvFile), "provider.env");
-                if (existsSync(srcProvider) && !existsSync(dstProvider)) {
-                    copyFileSync(srcProvider, dstProvider);
-                }
-            }
-            // Note: model.env is NOT copied (new instance needs its own proxy token)
-        }
-        // Bootstrap proxy: generate proxy token and write model.env so instance
-        // is ready to run immediately without requiring a manual "save config" first
-        try {
-            const { bootstrapInstanceProxy } = await import("../services/llm-proxy/index.js");
-            await bootstrapInstanceProxy(instanceId);
-        }
-        catch (e) {
-            console.warn(`[instance] Proxy bootstrap for ${instanceId} deferred: ${e.message}`);
-        }
-        // If running as root, hand ownership of all created files to the service user
-        // so the openclaw process (running as that user) can read/write its own files.
-        const svcUser = resolveServiceUser();
-        if (svcUser) {
+export function listInstances() {
+    const deduped = new Map();
+    for (const rootDir of [APPS_DIR, INSTANCES_DIR]) {
+        if (!existsSync(rootDir))
+            continue;
+        const entries = readdirSync(rootDir).sort();
+        for (const name of entries) {
+            if (deduped.has(name))
+                continue;
+            const metaPath = join(rootDir, name, "instance.json");
+            const dirPath = join(rootDir, name);
             try {
-                execFileSync("chown", ["-R", `${svcUser.uid}:${svcUser.gid}`, d], { timeout: 10_000 });
-                if (!home.startsWith(d + "/") && existsSync(home)) {
-                    execFileSync("chown", ["-R", `${svcUser.uid}:${svcUser.gid}`, home], { timeout: 10_000 });
+                if (!statSync(dirPath).isDirectory())
+                    continue;
+                if (rootDir === APPS_DIR && hasIncompleteAppInstallShadow(dirPath))
+                    continue;
+                if (!existsSync(metaPath))
+                    continue;
+                // Use safeReadJson so primary instance.json that was corrupted or
+                // deleted mid-rename falls back to the .bak chain maintained by
+                // safeWriteJson. Without this, an interrupted safeWriteJson call
+                // would silently drop the instance from every list/get hot path
+                // even though the backup chain still holds valid content on disk.
+                const meta = safeReadJson(metaPath, `instance:${name}`);
+                if (meta) {
+                    deduped.set(name, backfillInstanceMeta(meta));
+                    continue;
+                }
+                // safeReadJson → null can mean any of (a) primary missing + no
+                // backups, (b) all candidates unparseable, (c) permission denied.
+                // (a) and (b) are legitimate "drop from list" cases; (c) is the
+                // sudo-script footgun and must be logged loudly so the operator
+                // doesn't just see an empty instance list with no hint why.
+                const readErr = probeReadable(metaPath);
+                if (readErr && readErr.code === "EACCES") {
+                    console.error(`[instance-manager] cannot read instance '${name}': ${readErr.message}. ` +
+                        `Check file ownership with: ls -la ${metaPath}`);
                 }
             }
             catch (e) {
-                console.warn(`[instance] chown for ${instanceId} failed:`, e.message);
+                // Fallback for failures before the safeReadJson call (e.g. statSync
+                // on a directory we can't enter). Still log instead of silently
+                // dropping the entry.
+                console.error(`[instance-manager] cannot read instance '${name}': ${e.message}`);
             }
         }
-        return meta;
     }
-    finally {
-        if (allocatedPort)
-            _pendingPorts.delete(allocatedPort);
+    return [...deduped.values()];
+}
+export function getInstance(instanceId) {
+    const metaPath = instanceMetaPath(instanceId);
+    // Go through safeReadJson so primary missing/corrupted instance.json
+    // is still served from the .bak chain. Returning null on "truly gone"
+    // (no primary, no backups) keeps the existing 404 behavior intact.
+    const meta = safeReadJson(metaPath, `instance:${instanceId}`);
+    if (meta)
+        return backfillInstanceMeta(meta);
+    // safeReadJson swallows every read error internally, which is exactly
+    // wrong for the EACCES case — a root-owned primary would silently
+    // return null and callers would report "Instance not found" instead
+    // of the actionable "check file ownership" message. Re-probe to
+    // distinguish and throw on permission denial. Missing/corrupted with
+    // no backup still returns null (→ 404 upstream).
+    const readErr = probeReadable(metaPath);
+    if (readErr && readErr.code === "EACCES") {
+        throw new Error(`Cannot read instance '${instanceId}' metadata: ${readErr.message}. ` +
+            `Check file ownership with: ls -la ${metaPath}`);
     }
+    return null;
 }
+// §32.2 / §32.8: `createInstance` physically migrated into
+// `src/services/runtime/adapters/openclaw.ts:OpenClawAdapter.createInstance`.
+// Framework callers now dispatch via `getAdapter(agentType).createInstance(args)`.
 export function updateInstance(instanceId, name, description) {
     const meta = getInstance(instanceId);
     if (!meta)
@@ -1016,14 +527,17 @@ export function updateInstance(instanceId, name, description) {
     chownToServiceUser(instanceMetaPath(instanceId));
     return meta;
 }
-/** Update instance.json metadata fields (shallow merge at top level). */
+// §32.2 / §32.8: `createHermesInstance` + `InstanceCreationRejected`
+// physically migrated into `src/services/runtime/adapters/hermes.ts`
+// and `src/services/runtime/errors.ts`. Framework callers dispatch via
+// `getAdapter(agentType).createInstance(args)` uniformly.
 export function updateInstanceMeta(instanceId, patch) {
     const metaPath = instanceMetaPath(instanceId);
     const meta = safeReadJson(metaPath, "instance-meta") || {};
     Object.assign(meta, patch);
     safeWriteJson(metaPath, meta);
 }
-export function deleteInstance(instanceId, purgeBackups = false) {
+export async function deleteInstance(instanceId, purgeBackups = false) {
     const d = instanceDir(instanceId);
     if (!existsSync(d))
         return { ok: false, warnings: ["Instance directory not found"] };
@@ -1038,9 +552,35 @@ export function deleteInstance(instanceId, purgeBackups = false) {
                 cancelJob(job.id);
         }
     }).catch(() => { });
-    // Cache metadata BEFORE deletion so we can check custom openclaw_home after rm
+    // Cache metadata BEFORE deletion so adapters can inspect it after rm.
     const meta = getInstance(instanceId);
-    const home = meta?.openclaw_home;
+    const agentType = resolveAgentType(meta);
+    // Adapter-owned pre-delete hook. Adapters use this to emit advisories
+    // for resources that live outside the instance dir (legacy
+    // `openclaw_home`, named docker volumes, etc). Errors are collected
+    // into the response so one adapter misbehaving can't block removal.
+    try {
+        const legacyAppType = typeof meta?.app_type === "string" ? meta.app_type.trim() : "";
+        if ((legacyAppType === "custom" || legacyAppType === "ollama") && meta) {
+            const { getAppManager } = await import("./app/registry.js");
+            const manager = getAppManager(legacyAppType);
+            if (manager.onDelete) {
+                await manager.onDelete(instanceId);
+            }
+        }
+        else {
+            const adapter = getAdapter(agentType);
+            if (adapter.hooks?.onDelete && meta) {
+                const hookResult = await adapter.hooks.onDelete({ instanceId, meta });
+                if (hookResult && Array.isArray(hookResult.warnings)) {
+                    warnings.push(...hookResult.warnings);
+                }
+            }
+        }
+    }
+    catch (e) {
+        warnings.push(`adapter onDelete hook failed: ${e.message}`);
+    }
     // Clean up Nomad Variables (async, best-effort)
     import("./nomad-manager.js").then((nm) => {
         nm.purgeInstanceVariables(instanceId).catch((e) => {
@@ -1049,29 +589,33 @@ export function deleteInstance(instanceId, purgeBackups = false) {
     }).catch((e) => {
         console.warn(`[instance] Could not load nomad-manager for cleanup:`, e.message);
     });
+    // Async rm so the Node event loop stays responsive during large deletes:
+    // a fresh instance with a just-installed openclaw package can be 1+ GB
+    // with hundreds of nested dirs, which takes 30-60s to unlink on SD storage.
+    // rmSync would block every other HTTP request for that whole window.
     let dirDeleted = false;
     try {
-        rmSync(d, { recursive: true, force: true });
+        await rmAsync(d, { recursive: true, force: true });
         dirDeleted = true;
     }
     catch {
         try {
-            execFileSync("sudo", ["rm", "-rf", d], { timeout: 10000 });
+            execFileSync("sudo", ["rm", "-rf", d], { timeout: 300000 });
             dirDeleted = true;
         }
         catch (e) {
             warnings.push(`Failed to delete instance directory: ${e.message}`);
         }
     }
-    // Warn if custom openclaw_home exists outside the instance dir
-    if (home && !home.startsWith(d) && existsSync(home)) {
-        warnings.push(`Custom openclaw_home '${home}' was preserved. Delete manually if no longer needed.`);
-    }
-    // Handle backups (stored in separate directory, not affected by instance rmSync)
+    // (Custom openclaw_home orphan warning emitted by OpenClawAdapter.hooks.onDelete.)
+    // Handle backups (stored in separate directory, not affected by the
+    // instance rm above). Backups can be hundreds of MB each and accumulate
+    // across retention windows, so use the same async rm path to keep the
+    // event loop responsive.
     const backupDir = join(BACKUPS_DIR, instanceId);
     if (purgeBackups && existsSync(backupDir)) {
         try {
-            rmSync(backupDir, { recursive: true, force: true });
+            await rmAsync(backupDir, { recursive: true, force: true });
         }
         catch (e) {
             warnings.push(`Failed to delete backups: ${e.message}`);
@@ -1082,285 +626,210 @@ export function deleteInstance(instanceId, purgeBackups = false) {
     }
     return { ok: dirDeleted, warnings: warnings.length ? warnings : undefined };
 }
+// §32.2 / §32.8: getConfig / getStoredConfig / saveConfig
+// physically migrated into OpenClawAdapter. Framework callers now
+// dispatch via `getAdapter(agentType).saveNativeConfig / .getNativeConfig`.
+// Back-compat wrappers below preserve the legacy sync API shape for
+// existing call sites (llm-proxy, routes, backup-manager).
 export function getConfig(instanceId) {
-    const config = loadEffectiveConfig(instanceId);
-    if (!config)
-        return null;
-    // Merge x-jishushell metadata from instance.json
     const meta = getInstance(instanceId);
-    if (meta?.["x-jishushell"]) {
-        config["x-jishushell"] = meta["x-jishushell"];
+    const agentType = resolveAgentType(meta);
+    try {
+        const adapter = getAdapter(agentType);
+        return typeof adapter.getNativeConfig === "function"
+            ? adapter.getNativeConfig(instanceId)
+            : null;
+    }
+    catch {
+        return null;
     }
-    return injectProviderApiKeys(instanceId, config);
 }
 export function getStoredConfig(instanceId) {
-    const config = loadEffectiveConfig(instanceId);
-    if (!config)
-        return null;
     const meta = getInstance(instanceId);
-    if (meta?.["x-jishushell"]) {
-        config["x-jishushell"] = meta["x-jishushell"];
+    const agentType = resolveAgentType(meta);
+    try {
+        const adapter = getAdapter(agentType);
+        return typeof adapter.getStoredNativeConfig === "function"
+            ? adapter.getStoredNativeConfig(instanceId)
+            : null;
+    }
+    catch {
+        return null;
     }
-    return config;
 }
-export function saveConfig(instanceId, config) {
-    const configPath = openclawConfigPathInternal(instanceId);
-    if (!existsSync(instanceDir(instanceId)))
+export async function saveConfig(instanceId, config) {
+    const meta = getInstance(instanceId);
+    const agentType = resolveAgentType(meta);
+    try {
+        const adapter = getAdapter(agentType);
+        if (typeof adapter.saveNativeConfig !== "function")
+            return false;
+        // Adapters may return boolean or Promise<boolean>. Awaiting a plain
+        // boolean is a no-op, so this handles both. Previously we stripped the
+        // Promise and always reported success for async adapters — that masked
+        // failures and left callers unable to detect dirty state.
+        const result = await adapter.saveNativeConfig(instanceId, config);
+        return typeof result === "boolean" ? result : true;
+    }
+    catch (e) {
+        console.warn(`[instance-manager] saveConfig dispatch failed for ${instanceId}: ${e.message}`);
         return false;
-    if (!existsSync(configPath)) {
-        const legacyPath = legacyOpenclawConfigPath(instanceId);
-        ensureDirContainer(dirname(configPath));
-        if (existsSync(legacyPath))
-            copyFileSync(legacyPath, configPath);
     }
-    // Save x-jishushell metadata to instance.json (not openclaw.json)
-    if (config["x-jishushell"]) {
-        const metaPath = instanceMetaPath(instanceId);
-        if (existsSync(metaPath)) {
-            const meta = JSON.parse(readFileSync(metaPath, "utf-8"));
-            meta["x-jishushell"] = config["x-jishushell"];
-            safeWriteJson(metaPath, meta);
-            chownToServiceUser(metaPath);
+}
+// ── Deprecated back-compat dispatch wrappers ──────────────────────────
+//
+// The real implementations live in `OpenClawAdapter`. New code should
+// use `getAdapter(agentType).X(...)` directly. These wrappers exist so
+// existing unit tests and any stragglers in external-facing scripts
+// keep working without churn. They will be removed once the test suite
+// migrates to adapter-scoped imports.
+/**
+ * @deprecated Use `getAdapter("openclaw").channelPluginMap` instead.
+ * Provides the OpenClaw channel-plugin map via a Proxy so old direct-
+ * property reads (e.g. `CHANNEL_PLUGIN_MAP.feishu`) keep working.
+ */
+export const CHANNEL_PLUGIN_MAP = new Proxy({}, {
+    get(_target, key) {
+        if (typeof key !== "string")
+            return undefined;
+        try {
+            return getAdapter("openclaw").channelPluginMap?.[key];
         }
-    }
-    const [configToWrite, envUpdates] = prepareConfigForSave(instanceId, config);
-    // If openclaw-lark is configured as enabled, resolve which feishu plugin should actually be used:
-    // - If built-in feishu/ exists in stock AND openclaw-lark/ is not installed anywhere → switch to
-    //   built-in feishu (removes the stale openclaw-lark reference that breaks container startup).
-    // - If both exist → keep openclaw-lark but disable built-in feishu to avoid conflict.
-    if (configToWrite.plugins?.entries?.["openclaw-lark"]?.enabled) {
-        const stockExtDir = getStockExtensionsDir();
-        const stockFeishu = join(stockExtDir, "feishu");
-        const stockOcl = join(stockExtDir, "openclaw-lark");
-        const instanceOcl = join(getChannelExtensionsDir(instanceId), "openclaw-lark");
-        if (existsSync(stockFeishu) && !existsSync(stockOcl) && !existsSync(instanceOcl)) {
-            // Built-in available, community package absent → switch to built-in
-            configToWrite.plugins.entries.feishu = { enabled: true };
-            delete configToWrite.plugins.entries["openclaw-lark"];
+        catch {
+            return undefined;
         }
-        else if (existsSync(stockFeishu)) {
-            // Both present → disable built-in to avoid conflict with community package
-            configToWrite.plugins ??= {};
-            configToWrite.plugins.entries ??= {};
-            configToWrite.plugins.entries.feishu = { enabled: false };
+    },
+    ownKeys() {
+        try {
+            return Reflect.ownKeys(getAdapter("openclaw").channelPluginMap ?? {});
         }
-    }
-    // Preserve backend-managed fields from existing config on disk —
-    // plugins.installs, plugins.entries, and channels written by scan-to-bind
-    // flows (saveWeixinCredentials / saveFeishuCredentials) are not tracked by
-    // the frontend and would be lost on a frontend config save.
-    if (existsSync(configPath)) {
+        catch {
+            return [];
+        }
+    },
+    has(_target, key) {
+        if (typeof key !== "string")
+            return false;
         try {
-            const existing = JSON.parse(readFileSync(configPath, "utf-8"));
-            if (existing.plugins?.installs) {
-                configToWrite.plugins ??= {};
-                configToWrite.plugins.installs = { ...existing.plugins.installs, ...configToWrite.plugins?.installs };
-            }
-            // Merge plugin entries: for keys present in configToWrite, deep-merge
-            // backend-written sub-fields from disk. Keys absent from configToWrite
-            // (intentionally deleted) are NOT resurrected from existing.
-            if (existing.plugins?.entries && configToWrite.plugins?.entries) {
-                for (const [key, val] of Object.entries(configToWrite.plugins.entries)) {
-                    const old = existing.plugins.entries[key];
-                    if (val && typeof val === "object" && !Array.isArray(val) && old && typeof old === "object") {
-                        configToWrite.plugins.entries[key] = { ...old, ...val };
-                    }
-                }
-            }
-            // Merge channels: for keys present in configToWrite, deep-merge
-            // backend-written sub-fields (e.g. openclaw-weixin accounts) from disk.
-            // Keys absent from configToWrite (user-deleted channels) stay deleted.
-            if (existing.channels && configToWrite.channels) {
-                for (const [key, val] of Object.entries(configToWrite.channels)) {
-                    const old = existing.channels[key];
-                    if (val && typeof val === "object" && !Array.isArray(val) && old && typeof old === "object") {
-                        configToWrite.channels[key] = { ...old, ...val };
-                    }
-                }
-            }
+            return key in (getAdapter("openclaw").channelPluginMap ?? {});
         }
-        catch { /* best effort */ }
-    }
-    // backup
-    if (existsSync(configPath)) {
-        copyFileSync(configPath, configPath + ".bak");
-    }
-    const configJson = JSON.stringify(configToWrite, null, 2);
-    ensureDirContainer(dirname(configPath));
-    writeConfigFile(configPath + ".tmp", configJson);
-    // Verify tmp file is valid JSON before replacing (guards against disk-full partial writes)
-    JSON.parse(readFileSync(configPath + ".tmp", "utf-8"));
-    renameSync(configPath + ".tmp", configPath);
-    chownToServiceUser(configPath);
-    // also write to legacy path
-    const legacyPath = legacyOpenclawConfigPath(instanceId);
-    if (existsSync(legacyPath)) {
-        copyFileSync(legacyPath, legacyPath + ".bak");
-    }
-    writeConfigFile(legacyPath + ".tmp", configJson);
-    JSON.parse(readFileSync(legacyPath + ".tmp", "utf-8"));
-    renameSync(legacyPath + ".tmp", legacyPath);
-    chownToServiceUser(legacyPath);
-    if (Object.keys(envUpdates).length) {
-        const envFiles = getRuntimeEnvFiles(instanceId);
-        if (envFiles.length)
-            updateEnvFile(envFiles[0], envUpdates);
-    }
-    // Plugins are installed inside the container — no host-side auto-install on config save.
-    // Notify listeners (e.g. llm-proxy cache invalidation)
-    for (const listener of _configChangeListeners) {
+        catch {
+            return false;
+        }
+    },
+    getOwnPropertyDescriptor(_target, key) {
+        if (typeof key !== "string")
+            return undefined;
+        let value;
         try {
-            listener(instanceId);
+            value = getAdapter("openclaw").channelPluginMap?.[key];
         }
-        catch { /* ignore listener errors */ }
-    }
-    return true;
-}
-export function getOpenclawHome(instanceId) {
-    return getOpenclawHomeInternal(instanceId);
-}
+        catch {
+            return undefined;
+        }
+        return value !== undefined
+            ? { configurable: true, enumerable: true, writable: false, value }
+            : undefined;
+    },
+});
 /**
- * Save WeChat login credentials for an instance.
- * Save Feishu/Lark credentials from OAuth Device Code flow.
+ * @deprecated Use `getAdapter(agentType).isChannelPluginInstalled(id, channelId)` instead.
  */
-// Feishu app IDs issued by the open platform follow the pattern cli_<hex/alnum>.
-// Validate appId to reject malformed values sourced from OAuth API responses.
-const FEISHU_APP_ID_RE = /^cli_[a-zA-Z0-9]{8,64}$/;
-export function saveFeishuCredentials(instanceId, creds) {
-    if (!FEISHU_APP_ID_RE.test(creds.appId)) {
-        throw new Error(`Invalid Feishu appId format: expected cli_<alnum> (got "${creds.appId}")`);
+export function isChannelPluginInstalled(instanceId, channelId) {
+    try {
+        const meta = getInstance(instanceId);
+        const agentType = resolveAgentType(meta);
+        const adapter = getAdapter(agentType);
+        return typeof adapter.isChannelPluginInstalled === "function"
+            ? adapter.isChannelPluginInstalled(instanceId, channelId)
+            : false;
     }
-    if (!creds.appSecret || typeof creds.appSecret !== "string" || creds.appSecret.length < 4) {
-        throw new Error("Invalid Feishu appSecret: must be a non-empty string");
+    catch {
+        return false;
     }
-    const configPath = openclawConfigPathInternal(instanceId);
-    let config = safeReadJson(configPath, "feishu-creds") || {};
-    // Enable @larksuite/openclaw-lark plugin (installed inside Docker container),
-    // disable built-in @openclaw/feishu to avoid conflict.
-    config.plugins ??= {};
-    config.plugins.entries ??= {};
-    config.plugins.entries.feishu = { enabled: false };
-    config.plugins.entries["openclaw-lark"] = { enabled: true };
-    // Set channel config — official plugin reads from channels.feishu
-    config.channels ??= {};
-    config.channels.feishu = {
-        ...config.channels.feishu,
-        enabled: true,
-        appId: creds.appId,
-        appSecret: creds.appSecret,
-        domain: creds.domain,
-        dmPolicy: "open",
-        allowFrom: ["*"],
-    };
-    safeWriteJson(configPath, config);
-    chownToServiceUser(configPath);
-    console.log(`[instance-manager] Feishu credentials saved for ${instanceId}, domain=${creds.domain}`);
 }
 /**
- * Writes account data + updates openclaw.json to enable the plugin and register the account.
+ * @deprecated Use `getAdapter(agentType).createInstance({ instanceId, name, description, ... })` instead.
+ * Retained for unit tests and legacy scripts; forwards to the
+ * OpenClawAdapter's `createInstance` method.
  */
-const SAFE_ACCOUNT_ID_RE = /^[a-zA-Z0-9@._-]{1,128}$/;
-export function saveWeixinCredentials(instanceId, creds) {
-    // Prevent path traversal via accountId (used as filename)
-    if (!creds.accountId || !SAFE_ACCOUNT_ID_RE.test(creds.accountId) || creds.accountId.includes('..')) {
-        throw new Error(`Invalid accountId: must be 1-128 chars of [a-zA-Z0-9@._-] without '..'`);
-    }
-    const home = getOpenclawHomeInternal(instanceId);
-    const stateDir = join(home, OPENCLAW_STATE_DIRNAME, "openclaw-weixin");
-    const accountsDir = join(stateDir, "accounts");
-    ensureDirContainer(accountsDir);
-    // Save account credentials file (via safeWriteJson for atomic + .bak protection)
-    const credObj = {
-        token: creds.token,
-        baseUrl: creds.baseUrl,
-        userId: creds.userId,
-        savedAt: new Date().toISOString(),
-    };
-    safeWriteJson(join(accountsDir, `${creds.accountId}.json`), credObj);
-    // OpenClaw also needs a "default" account file with the same credentials
-    safeWriteJson(join(accountsDir, "default.json"), credObj);
-    chownToServiceUser(join(accountsDir, `${creds.accountId}.json`), join(accountsDir, "default.json"));
-    // Update accounts.json index (required by the plugin to discover accounts)
-    const indexPath = join(stateDir, "accounts.json");
-    let index = [];
+export async function createInstance(instanceId, name, description, cloneFrom, agentHome, cloneOptions) {
+    const adapter = getAdapter("openclaw");
+    if (typeof adapter.createInstance !== "function") {
+        throw new Error("OpenClawAdapter.createInstance is not available");
+    }
+    return adapter.createInstance({
+        instanceId,
+        name,
+        description,
+        cloneFrom,
+        agentHome,
+        cloneOptions,
+    });
+}
+// §32.2 / §32.8: saveFeishuCredentials / saveWeixinCredentials /
+// getWeixinAccounts / getOpenclawHome physically migrated into
+// `src/services/runtime/adapters/openclaw.ts`. Back-compat dispatch
+// wrappers below keep existing callers working.
+export function getOpenclawHome(instanceId) {
+    const meta = getInstance(instanceId);
+    const agentType = resolveAgentType(meta);
     try {
-        const raw = readFileSync(indexPath, "utf-8");
-        index = JSON.parse(raw);
+        const a = getAdapter(agentType);
+        return typeof a.resolveAgentHome === "function"
+            ? a.resolveAgentHome(instanceId)
+            : meta?.openclaw_home || join(INSTANCES_DIR, instanceId, "openclaw-home");
     }
-    catch { /* start fresh */ }
-    if (!Array.isArray(index))
-        index = [];
-    if (!index.includes(creds.accountId))
-        index.push(creds.accountId);
-    safeWriteJson(indexPath, index);
-    // Update openclaw.json: enable plugin + register account
-    const configPath = openclawConfigPathInternal(instanceId);
-    let config = safeReadJson(configPath, "weixin-creds") || {};
-    // Enable plugin
-    config.plugins ??= {};
-    config.plugins.entries ??= {};
-    config.plugins.entries["openclaw-weixin"] ??= {};
-    config.plugins.entries["openclaw-weixin"].enabled = true;
-    // Enable channel with account
-    config.channels ??= {};
-    config.channels["openclaw-weixin"] ??= {};
-    config.channels["openclaw-weixin"].enabled = true;
-    // Register account with both original and normalized IDs (OpenClaw normalizes @ and . to -)
-    const normalizedId = creds.accountId.replace(/[@.]/g, "-");
-    const accounts = config.channels["openclaw-weixin"].accounts ??= {};
-    accounts[creds.accountId] = { enabled: true };
-    if (normalizedId !== creds.accountId)
-        accounts[normalizedId] = { enabled: true };
-    accounts["default"] = { enabled: true };
-    // Set defaultAccount (required by OpenClaw)
-    if (!config.channels["openclaw-weixin"].defaultAccount) {
-        config.channels["openclaw-weixin"].defaultAccount = "default";
+    catch {
+        return meta?.openclaw_home || join(INSTANCES_DIR, instanceId, "openclaw-home");
     }
-    safeWriteJson(configPath, config);
-    chownToServiceUser(configPath);
-    console.log(`[instance-manager] WeChat credentials saved for ${instanceId}, account=${creds.accountId}`);
 }
-/**
- * Get connected WeChat accounts for an instance.
- */
+export function saveFeishuCredentials(instanceId, creds) {
+    const meta = getInstance(instanceId);
+    const agentType = resolveAgentType(meta);
+    const a = getAdapter(agentType);
+    if (typeof a.saveFeishuCredentials !== "function") {
+        throw new Error(`Runtime "${agentType}" does not support Feishu credentials`);
+    }
+    a.saveFeishuCredentials(instanceId, creds);
+}
+export function saveWeixinCredentials(instanceId, creds) {
+    const meta = getInstance(instanceId);
+    const agentType = resolveAgentType(meta);
+    const a = getAdapter(agentType);
+    if (typeof a.saveWeixinCredentials !== "function") {
+        throw new Error(`Runtime "${agentType}" does not support WeChat credentials`);
+    }
+    a.saveWeixinCredentials(instanceId, creds);
+}
 export function getWeixinAccounts(instanceId) {
-    const home = getOpenclawHomeInternal(instanceId);
-    const stateDir = join(home, OPENCLAW_STATE_DIRNAME, "openclaw-weixin");
-    const accountsDir = join(stateDir, "accounts");
-    if (!existsSync(accountsDir))
-        return [];
-    // Only return accounts listed in the index (skip default.json and other auxiliary files)
-    let indexedIds = [];
+    const meta = getInstance(instanceId);
+    const agentType = resolveAgentType(meta);
     try {
-        indexedIds = JSON.parse(readFileSync(join(stateDir, "accounts.json"), "utf-8"));
+        const a = getAdapter(agentType);
+        return typeof a.getWeixinAccounts === "function"
+            ? a.getWeixinAccounts(instanceId)
+            : [];
     }
-    catch { /* fallback to scanning */ }
-    const results = [];
-    for (const f of readdirSync(accountsDir)) {
-        if (!f.endsWith(".json"))
-            continue;
-        const id = f.replace(/\.json$/, "");
-        if (indexedIds.length > 0 && !indexedIds.includes(id))
-            continue; // skip auxiliary files
-        if (id === "default")
-            continue; // always skip default alias
-        try {
-            const data = JSON.parse(readFileSync(join(accountsDir, f), "utf-8"));
-            results.push({
-                accountId: id,
-                userId: data.userId,
-                savedAt: data.savedAt,
-            });
-        }
-        catch { /* skip */ }
+    catch {
+        return [];
     }
-    return results;
 }
 export function getOpenclawConfigPath(instanceId) {
-    return openclawConfigPathInternal(instanceId);
+    const meta = getInstance(instanceId);
+    const agentType = resolveAgentType(meta);
+    const a = getAdapter(agentType);
+    if (typeof a.resolveConfigPath === "function")
+        return a.resolveConfigPath(instanceId);
+    return join(getOpenclawHome(instanceId), ".openclaw", "openclaw.json");
 }
 export function getLegacyOpenclawConfigPath(instanceId) {
-    return legacyOpenclawConfigPath(instanceId);
+    const meta = getInstance(instanceId);
+    const agentType = resolveAgentType(meta);
+    const a = getAdapter(agentType);
+    if (typeof a.resolveLegacyConfigPath === "function")
+        return a.resolveLegacyConfigPath(instanceId);
+    return join(getOpenclawHome(instanceId), "openclaw.json");
 }
 export function getInstanceRuntime(instanceId) {
     const meta = getInstance(instanceId);
@@ -1370,11 +839,28 @@ export function getInstanceRuntime(instanceId) {
 }
 export function getRuntimeEnvFiles(instanceId) {
     const runtime = getInstanceRuntime(instanceId);
-    const envFiles = (runtime.env_files || []).map((p) => normalizePath(p)).filter(Boolean);
+    const rawEnvFiles = Array.isArray(runtime.env_files)
+        ? runtime.env_files
+        : Array.isArray(runtime.envFiles)
+            ? runtime.envFiles
+            : [];
+    const envFiles = rawEnvFiles.map((p) => normalizePath(p)).filter(Boolean);
     return envFiles.length ? envFiles : [defaultModelEnvFile(instanceId)];
 }
 export function getGatewayPort(instanceId) {
-    return extractGatewayPort(getInstanceRuntime(instanceId)) || DEFAULT_GATEWAY_PORT;
+    const recorded = extractGatewayPort(getInstanceRuntime(instanceId));
+    if (recorded)
+        return recorded;
+    // Fallback: look up the adapter's canonical base port. Framework does
+    // not hardcode per-kind defaults.
+    const meta = getInstance(instanceId);
+    const agentType = resolveAgentType(meta);
+    try {
+        return getAdapter(agentType).defaultGatewayPort ?? 18789;
+    }
+    catch {
+        return 18789;
+    }
 }
 /**
  * Detect the host address where the gateway port is actually listening.
@@ -1389,6 +875,47 @@ export function getGatewayPort(instanceId) {
  */
 const _gwHostCache = new Map();
 const GW_HOST_CACHE_TTL = 30000;
+export function getListeningHostForPort(port) {
+    let result = "127.0.0.1";
+    try {
+        const out = execFileSync("ss", ["-tlnH", "sport", "=", ":" + safePort(port)], {
+            encoding: "utf-8",
+            timeout: 3000,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        for (const line of out.split("\n")) {
+            let match = line.match(/\s([\d.]+):(\d+)\s/);
+            if (!match)
+                match = line.match(/\s\[([0-9a-fA-F:]+)\]:(\d+)\s/);
+            if (match && match[2] === String(port)) {
+                const addr = match[1];
+                result = addr === "0.0.0.0" ? "127.0.0.1" : addr;
+                break;
+            }
+        }
+    }
+    catch { /* fall through */ }
+    return result;
+}
+function getPrimaryIpv4Address() {
+    try {
+        for (const list of Object.values(networkInterfaces())) {
+            for (const iface of list ?? []) {
+                if (!iface.internal && iface.family === "IPv4")
+                    return iface.address;
+            }
+        }
+    }
+    catch { /* fall through */ }
+    return "127.0.0.1";
+}
+export function getAdvertisedHostForPort(port) {
+    const host = getListeningHostForPort(port);
+    if (host && host !== "127.0.0.1" && host !== "0.0.0.0" && host !== "::1" && host !== "::") {
+        return host;
+    }
+    return getPrimaryIpv4Address();
+}
 export async function getGatewayHost(instanceId) {
     const cached = _gwHostCache.get(instanceId);
     if (cached && Date.now() - cached.ts < GW_HOST_CACHE_TTL)
@@ -1399,7 +926,22 @@ export async function getGatewayHost(instanceId) {
         const { getNomadDriver } = await import("../config.js");
         if (getNomadDriver() === "docker") {
             const { getNomadAddr, getNomadToken } = await import("../config.js");
-            const jid = `openclaw-${instanceId}`;
+            // Dispatch job-id construction through the adapter so every runtime
+            // owns its own Nomad job namespace (hermes-<id>, openclaw-<id>, …).
+            // Falls back to a generic `jishushell-` prefix only when the adapter
+            // lookup fails — that branch should never fire for a registered
+            // agent type.
+            const meta = getInstance(instanceId);
+            const agentType = resolveAgentType(meta);
+            let prefix = "jishushell-";
+            try {
+                const a = getAdapter(agentType);
+                if (typeof a.nomadJobPrefix === "string" && a.nomadJobPrefix.length) {
+                    prefix = a.nomadJobPrefix;
+                }
+            }
+            catch { /* use fallback prefix */ }
+            const jid = `${prefix}${instanceId}`;
             const headers = { "Content-Type": "application/json" };
             const token = getNomadToken();
             if (token)
@@ -1416,11 +958,39 @@ export async function getGatewayHost(instanceId) {
                     const detail = await fetch(`${getNomadAddr()}/v1/allocation/${encodeURIComponent(alloc.ID)}`, { headers, signal: AbortSignal.timeout(5000) });
                     if (detail.ok) {
                         const d = await detail.json();
-                        const ports = d?.AllocatedResources?.Shared?.Ports ?? [];
-                        const gwPort = ports.find((p) => p.Label === "gateway");
+                        // Preferred source: AllocatedResources.Shared.Ports (bridge mode).
+                        const sharedPorts = d?.AllocatedResources?.Shared?.Ports ?? [];
+                        const gwPort = sharedPorts.find((p) => p.Label === "gateway");
                         if (gwPort?.HostIP && gwPort.HostIP !== "0.0.0.0") {
                             result = gwPort.HostIP;
                         }
+                        else {
+                            // Host mode / task-level reservation: address lives under
+                            // AllocatedResources.Tasks.<task>.Networks[*].IP. On Nomad
+                            // 1.6.5 with `network_interface = "lo"`, the IP is whichever
+                            // address the OS enumerates first — which can be IPv6 `::1`
+                            // on systems where lo has both `127.0.0.1/8` and `::1/128`
+                            // (the default on most modern Linux distros). Reading it from
+                            // here is the authoritative source and matches what nomad
+                            // configures the docker-proxy bind to use.
+                            //
+                            // Scan every task instead of indexing a hardcoded "gateway"
+                            // task — adapters are free to name the task whatever they
+                            // like, we only require the reserved port carry the
+                            // framework-level `gateway` label.
+                            const tasksMap = d?.AllocatedResources?.Tasks ?? {};
+                            for (const taskName of Object.keys(tasksMap)) {
+                                const taskNets = tasksMap[taskName]?.Networks ?? [];
+                                const net = taskNets.find((n) => {
+                                    const rps = n?.ReservedPorts ?? [];
+                                    return rps.some((p) => p.Label === "gateway");
+                                });
+                                if (net?.IP && net.IP !== "0.0.0.0") {
+                                    result = net.IP;
+                                    break;
+                                }
+                            }
+                        }
                     }
                 }
             }
@@ -1433,27 +1003,74 @@ export async function getGatewayHost(instanceId) {
         }
     }
     catch { /* fall through */ }
-    try {
-        const out = execFileSync("ss", ["-tlnH", "sport", "=", ":" + safePort(port)], { encoding: "utf-8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"] });
-        for (const line of out.split("\n")) {
-            const match = line.match(/\s([\d.]+):(\d+)\s/);
-            if (match && match[2] === String(port)) {
-                const addr = match[1];
-                result = addr === "0.0.0.0" ? "127.0.0.1" : addr;
-                break;
-            }
-        }
-    }
-    catch { /* fall through */ }
+    result = getListeningHostForPort(port);
     _gwHostCache.set(instanceId, { host: result, ts: Date.now() });
     return result;
 }
+/**
+ * Wrap an IPv6 literal in brackets for safe URL host-component / Host-header
+ * use. Bare names ("gateway.local") and IPv4 ("127.0.0.1") contain no colon
+ * and pass through unchanged; anything with a colon is an IPv6 literal and
+ * MUST be bracketed before being concatenated with a port, otherwise
+ * `http://::1:18789/` is unparseable.
+ */
+export function urlHost(host) {
+    return host.includes(":") ? `[${host}]` : host;
+}
 export function findInstancesSharingOpenclawHome(instanceId) {
-    const targetHome = normalizePath(getOpenclawHome(instanceId));
-    return listInstances()
-        .filter((inst) => inst.id !== instanceId)
-        .filter((inst) => normalizePath(inst.openclaw_home || defaultOpenclawHome(inst.id)) === targetHome)
-        .map((inst) => inst.id);
+    const meta = getInstance(instanceId);
+    const agentType = resolveAgentType(meta);
+    try {
+        const a = getAdapter(agentType);
+        return typeof a.findInstancesSharingHome === "function"
+            ? a.findInstancesSharingHome(instanceId)
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Re-pick a gateway port for an existing instance and rewrite its persisted
+ * runtime metadata (`runtime.args` and `runtime.env.OPENCLAW_GATEWAY_PORT`).
+ *
+ * Used when {@link isPortInUse} reports that the previously-assigned port has
+ * been taken by something else between create-time and start-time (e.g. a
+ * host-side openclaw started by the user, an unrelated service that grabbed
+ * the port at boot, or a Docker race on the next allocation). The Nomad job
+ * spec is rebuilt from instance metadata on every submit, so updating
+ * `instance.json` here is sufficient — no other files need patching.
+ */
+export async function reallocateGatewayPort(instanceId) {
+    const meta = safeReadJson(instanceMetaPath(instanceId), "instance-meta");
+    if (!meta)
+        throw new Error(`Cannot reallocate port for unknown instance '${instanceId}'`);
+    const agentType = resolveAgentType(meta);
+    let adapter;
+    try {
+        adapter = getAdapter(agentType);
+    }
+    catch {
+        throw new Error(`Unknown runtime agentType "${agentType}" for instance ${instanceId}`);
+    }
+    const defaultPort = adapter.defaultGatewayPort ?? 18789;
+    const fromPort = extractGatewayPort(meta.runtime, agentType) ?? defaultPort;
+    const alloc = await allocateGatewayPort(instanceId, defaultPort);
+    try {
+        const runtime = (meta.runtime ?? {});
+        // Delegate the kind-specific runtime rewrite to the adapter.
+        if (typeof adapter.reallocateRuntimePort === "function") {
+            adapter.reallocateRuntimePort(runtime, alloc.port);
+        }
+        meta.runtime = runtime;
+        safeWriteJson(instanceMetaPath(instanceId), meta);
+        chownToServiceUser(instanceMetaPath(instanceId));
+        console.log(`[instance] ${instanceId}: gateway port reallocated ${fromPort} -> ${alloc.port}`);
+        return { from: fromPort, to: alloc.port, skipped: alloc.skipped };
+    }
+    finally {
+        _pendingPorts.delete(alloc.port);
+    }
 }
 export function findInstancesSharingGatewayPort(instanceId) {
     const targetPort = getGatewayPort(instanceId);
@@ -1474,15 +1091,34 @@ export function getRuntimeEnv(instanceId) {
     }
     return env;
 }
-// Re-export instanceDir for nomad-manager
+// Re-export instanceDir for nomad-manager under its getInstanceDir alias.
 export { instanceDir as getInstanceDir };
-function resolveExistingConfigPath(instanceId) {
-    const runtimePath = openclawConfigPathInternal(instanceId);
-    if (existsSync(runtimePath))
-        return runtimePath;
-    const legacyPath = legacyOpenclawConfigPath(instanceId);
-    if (existsSync(legacyPath))
-        return legacyPath;
-    return runtimePath;
+// ── Compatibility exports for app-type managers (src/services/app/) ──────────
+// `instanceMetaPath`, `chownToServiceUser`, `notifyConfigChange` already
+// exported above; §32.2/§32.8 migration kept the originals in place so the
+// app-manager layer can still depend on them. The shims below add the
+// naming aliases the cli branch's app managers import.
+/**
+ * Compatibility shim: allocate a gateway port for a new instance and return
+ * just the port number. Wraps `allocateGatewayPort`, which takes a seed port
+ * and returns `{ port, skipped }`. Non-OpenClaw app managers don't have an
+ * agentType-specific default port yet, so we seed with 18789 (OpenClaw's
+ * default) — the allocator walks upward until it finds a free slot so the
+ * actual port chosen is independent of the seed.
+ */
+export async function defaultGatewayPort(instanceId) {
+    const result = await allocateGatewayPort(instanceId, 18789);
+    return result.port;
+}
+/**
+ * Compatibility shim: release a pending port reservation.
+ * Mirrors the cli-branch `releasePort(port)` helper on top of the framework's
+ * existing `releasePendingPort`.
+ */
+export function releasePort(port) {
+    releasePendingPort(port);
 }
+// `resolveExistingConfigPath` is owned by the OpenClaw adapter after §32.2 —
+// callers that still need it live inside `src/services/runtime/adapters/` or
+// `src/services/app/openclaw-manager.ts` (which defines its own copy).
 //# sourceMappingURL=instance-manager.js.map