jishushell 0.4.2 → 0.4.17

package/dist/services/instance-manager.js

@@ -1,12 +1,15 @@
 import { execFile, execFileSync } from "child_process";
 import { randomBytes } from "crypto";
-import { chmodSync, chownSync, copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from "fs";
+import { chmodSync, chownSync, closeSync, copyFileSync, cpSync, existsSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, } from "fs";
+import { rm as rmAsync } from "fs/promises";
 import { createServer as netCreateServer } from "net";
 import { userInfo } from "os";
 import { dirname, join, resolve } from "path";
-import { INSTANCES_DIR, JISHUSHELL_HOME, getPanelConfig } from "../config.js";
+import { BACKUPS_DIR, INSTANCES_DIR, JISHUSHELL_HOME, getPanelConfig } from "../config.js";
 import { LEGACY_PROVIDER_API_ALIASES } from "../constants.js";
 import { safeReadJson, safeWriteJson } from "../utils/safe-json.js";
+import { ensureDirContainer, writeConfigFile, writeSecretFile } from "../utils/fs.js";
+import { compileTaskRuntime } from "./app-compiler.js";
 const _configChangeListeners = [];
 export function onConfigChange(listener) {
     _configChangeListeners.push(listener);
@@ -118,7 +121,16 @@ 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 `0.0.0.0:port` — under the Linux default socket semantics, this fails
+ * with EADDRINUSE whenever another listener holds the port on `0.0.0.0`, on
+ * any specific interface (e.g. `127.0.0.1`), or via Docker's published port
+ * map. An IPv6-only listener on `::1` is not detected, but that edge case
+ * never comes up in the Nomad+Docker path this project uses.
+ */
+export function isPortInUse(port) {
     if (!Number.isInteger(port) || port < 1 || port > 65535)
         return Promise.resolve(false);
     return new Promise((resolve) => {
@@ -130,13 +142,25 @@ function isPortInUse(port) {
         server.listen(port, "0.0.0.0");
     });
 }
-async function defaultGatewayPort(instanceId) {
+/**
+ * Picks a gateway port for an instance, starting at {@link DEFAULT_GATEWAY_PORT}
+ * and walking upward until a port is both unknown to jishushell's instance
+ * metadata and reports as free on the host. Concurrent callers coordinate
+ * through `_pendingPorts` so they never hand out the same port.
+ *
+ * Intentionally does not hold a reservation indefinitely — the caller is
+ * expected to either persist the port into instance metadata (which then
+ * shows up in `usedGatewayPorts`) or clear `_pendingPorts` on failure.
+ */
+async function allocateGatewayPort(instanceId) {
     const used = usedGatewayPorts(instanceId);
+    const skipped = [];
     let port = DEFAULT_GATEWAY_PORT;
     while (true) {
         if (port > 65535)
             throw new Error("No available gateway port found (all ports 18789-65535 in use)");
         if (used.has(port) || _pendingPorts.has(port)) {
+            skipped.push(port);
             port++;
             continue;
         }
@@ -146,16 +170,18 @@ 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;
         }
@@ -242,8 +268,7 @@ function chownToServiceUser(...paths) {
         }
     }
 }
-async function defaultRuntime(instanceId, openclawHome) {
-    const port = await defaultGatewayPort(instanceId);
+function buildDefaultRuntime(instanceId, port, openclawHome) {
     const home = openclawHome || defaultOpenclawHome(instanceId);
     return {
         command: resolveOpenclawBin(),
@@ -357,7 +382,7 @@ function quoteEnvValue(value) {
     return JSON.stringify(value);
 }
 export function updateEnvFile(path, updates) {
-    mkdirSync(dirname(path), { recursive: true });
+    ensureDirContainer(dirname(path));
     const existing = existsSync(path) ? readFileSync(path, "utf-8").split("\n") : [];
     const remaining = { ...updates };
     const newLines = [];
@@ -389,7 +414,7 @@ export function updateEnvFile(path, updates) {
     const content = output ? output + "\n" : "";
     // Atomic write: tmp then rename to protect against RPi power loss
     const tmp = path + ".tmp";
-    writeFileSync(tmp, content, { mode: 0o600 });
+    writeSecretFile(tmp, content);
     renameSync(tmp, path);
 }
 // ── Provider key helpers ──
@@ -536,6 +561,40 @@ export const CHANNEL_PLUGIN_MAP = {
     // 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;
@@ -546,8 +605,9 @@ export function isChannelPluginInstalled(instanceId, channelId) {
         || (extDirName !== channelId && existsSync(join(stockExtDir, channelId)));
 }
 /**
- * Install a single channel plugin on the host.
- * This is the unified entry point for all plugin installation — never use docker exec.
+ * 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];
@@ -556,14 +616,17 @@ export async function installChannelPlugin(instanceId, channelId) {
     if (isChannelPluginInstalled(instanceId, channelId))
         return;
     const openclawHome = getOpenclawHomeInternal(instanceId);
-    const openclawBin = resolveOpenclawBin();
     const extensionsDir = getChannelExtensionsDir(instanceId);
-    // Ensure the node binary that runs jishushell is on PATH for the child process.
-    // When running under systemd, PATH may not include the nvm node directory, which
-    // causes the `#!/usr/bin/env node` shebang in the openclaw CLI to fail.
+    // 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(":");
-    // Pass through proxy and TLS env vars so fetch works under systemd / restricted environments.
     const proxyEnvKeys = [
         "http_proxy", "HTTP_PROXY", "https_proxy", "HTTPS_PROXY",
         "no_proxy", "NO_PROXY", "NODE_EXTRA_CA_CERTS", "NODE_TLS_REJECT_UNAUTHORIZED",
@@ -588,12 +651,9 @@ export async function installChannelPlugin(instanceId, channelId) {
             env: childEnv,
             timeout: 300_000,
         }, (err, stdout, stderr) => {
-            // openclaw plugins install may exit non-zero due to "plugins.allow is empty" warning
-            // even though the plugin was installed successfully. Check actual directory.
             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)'}`);
-                // Clean up leftover stage directories
                 try {
                     if (existsSync(extensionsDir)) {
                         for (const entry of readdirSync(extensionsDir)) {
@@ -604,7 +664,7 @@ export async function installChannelPlugin(instanceId, channelId) {
                         }
                     }
                 }
-                catch { /* best effort */ }
+                catch (_) { }
                 reject(new Error(msg));
             }
             else {
@@ -621,6 +681,20 @@ export async function installChannelPlugin(instanceId, channelId) {
     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) {
@@ -637,6 +711,67 @@ export async function installChannelPlugin(instanceId, channelId) {
     }
     throw lastErr;
 }
+/**
+ * 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.
+ */
+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");
 }
@@ -644,6 +779,26 @@ function getStockExtensionsDir() {
     return join(JISHUSHELL_HOME, "packages", "openclaw", "lib", "node_modules", "openclaw", "extensions");
 }
 // ── Public API ──
+/**
+ * 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.
+ */
+function probeReadable(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const fd = openSync(path, "r");
+        closeSync(fd);
+        return null;
+    }
+    catch (e) {
+        return e;
+    }
+}
 export function listInstances() {
     if (!existsSync(INSTANCES_DIR))
         return [];
@@ -653,14 +808,33 @@ export function listInstances() {
         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")));
+            if (!statSync(dirPath).isDirectory())
+                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) {
+                instances.push(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) {
-            // 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.
+            // 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}`);
         }
     }
@@ -668,17 +842,26 @@ export function listInstances() {
 }
 export function getInstance(instanceId) {
     const metaPath = instanceMetaPath(instanceId);
-    if (!existsSync(metaPath))
-        return null;
-    try {
-        return JSON.parse(readFileSync(metaPath, "utf-8"));
-    }
-    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}`);
+    // 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 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;
 }
-export async function createInstance(instanceId, name, description = "", cloneFrom, openclawHome) {
+export async function createInstance(instanceId, name, description = "", cloneFrom, openclawHome, appSpec, cloneOptions) {
     const d = instanceDir(instanceId);
     if (existsSync(d))
         throw new Error(`Instance '${instanceId}' already exists`);
@@ -717,21 +900,27 @@ export async function createInstance(instanceId, name, description = "", cloneFr
             // readdirSync failed — directory might not be readable, proceed cautiously
         }
     }
-    mkdirSync(d, { recursive: true, mode: 0o750 });
-    chmodSync(d, 0o750);
+    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 */ }
-    mkdirSync(home, { recursive: true, mode: 0o750 });
-    chmodSync(home, 0o750);
-    mkdirSync(join(home, OPENCLAW_STATE_DIRNAME), { recursive: true, mode: 0o750 });
-    chmodSync(join(home, OPENCLAW_STATE_DIRNAME), 0o750);
-    const runtime = await defaultRuntime(instanceId, home);
+    ensureDirContainer(home);
+    ensureDirContainer(join(home, OPENCLAW_STATE_DIRNAME));
+    const portAlloc = await allocateGatewayPort(instanceId);
+    const baseRuntime = buildDefaultRuntime(instanceId, portAlloc.port, home);
+    let runtime = baseRuntime;
+    if (appSpec) {
+        const serviceTask = appSpec.tasks.find((t) => t.role === "service");
+        if (serviceTask) {
+            const compiled = compileTaskRuntime(serviceTask, instanceId);
+            runtime = { ...baseRuntime, ...compiled };
+        }
+    }
     const allocatedPort = extractGatewayPort(runtime);
-    // Port already reserved inside defaultGatewayPort; just track for cleanup
+    // Port already reserved inside allocateGatewayPort; just track for cleanup
     try {
         const meta = {
             id: instanceId,
@@ -740,13 +929,13 @@ export async function createInstance(instanceId, name, description = "", cloneFr
             openclaw_home: home,
             runtime,
             created_at: new Date().toISOString(),
+            ...(appSpec ? { app_id: appSpec.id } : {}),
         };
         safeWriteJson(instanceMetaPath(instanceId), meta);
         const envFiles = (runtime.env_files || []).map((p) => normalizePath(p));
         for (const ef of envFiles) {
-            mkdirSync(dirname(ef), { recursive: true });
             if (!existsSync(ef))
-                writeFileSync(ef, "", { mode: 0o600 });
+                writeConfigFile(ef, "");
         }
         // After writing env files, ensure the runtime user can read them
         try {
@@ -759,7 +948,7 @@ export async function createInstance(instanceId, name, description = "", cloneFr
         }
         catch { /* ignore - same user or no permission to chown */ }
         const configPath = openclawConfigPathInternal(instanceId);
-        mkdirSync(dirname(configPath), { recursive: true });
+        ensureDirContainer(dirname(configPath));
         if (cloneFrom && !existsSync(configPath)) {
             const srcConfig = resolveExistingConfigPath(cloneFrom);
             if (existsSync(srcConfig)) {
@@ -782,12 +971,26 @@ export async function createInstance(instanceId, name, description = "", cloneFr
                     if (typeof defaultModel === "string" && (defaultModel.startsWith("jsproxy/") || defaultModel.startsWith("js-"))) {
                         delete cloned.agents.defaults.model;
                     }
-                    // Strip IM channel configs — same channel cannot serve multiple instances
-                    if (cloned?.channels)
-                        delete cloned.channels;
+                    // 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)
-                    for (const subdir of ["extensions", "workspace", "skills"]) {
+                    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)) {
@@ -797,7 +1000,7 @@ export async function createInstance(instanceId, name, description = "", cloneFr
                             catch { /* best effort */ }
                         }
                     }
-                    writeFileSync(configPath, JSON.stringify(cloned, null, 2), { mode: 0o600 });
+                    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");
@@ -813,7 +1016,7 @@ export async function createInstance(instanceId, name, description = "", cloneFr
                                 if (existsSync(metaPath)) {
                                     const dstMeta = JSON.parse(readFileSync(metaPath, "utf-8"));
                                     dstMeta["x-jishushell"] = dstXj;
-                                    writeFileSync(metaPath, JSON.stringify(dstMeta, null, 2));
+                                    writeConfigFile(metaPath, JSON.stringify(dstMeta, null, 2));
                                 }
                             }
                         }
@@ -827,7 +1030,7 @@ export async function createInstance(instanceId, name, description = "", cloneFr
             }
         }
         if (!existsSync(configPath)) {
-            writeFileSync(configPath, JSON.stringify(starterConfig(), null, 2), { mode: 0o600 });
+            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) {
@@ -838,6 +1041,34 @@ export async function createInstance(instanceId, name, description = "", cloneFr
                 updateEnvFile(providerEnv, { UPSTREAM_API_KEY: dp.apiKey });
             }
         }
+        // Merge App-level config_defaults into openclaw.json (shallow merge, app values win)
+        if (appSpec?.openclaw?.config_defaults && existsSync(configPath)) {
+            try {
+                const existing = JSON.parse(readFileSync(configPath, "utf-8"));
+                const defaults = appSpec.openclaw.config_defaults;
+                // Deep merge top-level keys
+                for (const [key, value] of Object.entries(defaults)) {
+                    if (typeof value === "object" && value !== null && !Array.isArray(value) && typeof existing[key] === "object" && existing[key] !== null) {
+                        existing[key] = { ...existing[key], ...value };
+                    }
+                    else {
+                        existing[key] = value;
+                    }
+                }
+                writeConfigFile(configPath, JSON.stringify(existing, null, 2));
+            }
+            catch { /* ignore merge errors, keep existing config */ }
+        }
+        // Record App-level skills for later installation into the instance
+        if (appSpec?.openclaw?.skills && Array.isArray(appSpec.openclaw.skills)) {
+            try {
+                const skillsDir = join(dirname(configPath), "skills");
+                ensureDirContainer(skillsDir);
+                const skillMeta = join(skillsDir, ".app-skills.json");
+                safeWriteJson(skillMeta, { app_id: appSpec.id, skills: appSpec.openclaw.skills });
+            }
+            catch { /* ignore */ }
+        }
         // Copy cloned provider.env BEFORE proxy bootstrap so bootstrap can find the API key
         if (cloneFrom && envFiles.length) {
             const srcEnvFiles = getRuntimeEnvFiles(cloneFrom);
@@ -876,6 +1107,17 @@ export async function createInstance(instanceId, name, description = "", cloneFr
                 console.warn(`[instance] chown for ${instanceId} failed:`, e.message);
             }
         }
+        // Attach transient port allocation info for the API response only — never
+        // persisted in instance.json. If the caller (e.g. the create route) sees
+        // skipped ports it can tell the user the default was busy.
+        if (portAlloc.skipped.length > 0) {
+            meta.port_allocation = {
+                assigned: portAlloc.port,
+                requested: DEFAULT_GATEWAY_PORT,
+                reason: "default_busy",
+                skipped: portAlloc.skipped,
+            };
+        }
         return meta;
     }
     finally {
@@ -895,11 +1137,28 @@ export function updateInstance(instanceId, name, description) {
     chownToServiceUser(instanceMetaPath(instanceId));
     return meta;
 }
-export function deleteInstance(instanceId) {
+/** Update instance.json metadata fields (shallow merge at top level). */
+export function updateInstanceMeta(instanceId, patch) {
+    const metaPath = instanceMetaPath(instanceId);
+    const meta = safeReadJson(metaPath, "instance-meta") || {};
+    Object.assign(meta, patch);
+    safeWriteJson(metaPath, meta);
+}
+export async function deleteInstance(instanceId, purgeBackups = false) {
     const d = instanceDir(instanceId);
     if (!existsSync(d))
         return { ok: false, warnings: ["Instance directory not found"] };
     const warnings = [];
+    // Cancel auto-backup timer and any queued jobs for this instance
+    import("./backup-manager.js").then(({ cancelAutoBackup, getQueueStatus, cancelJob }) => {
+        cancelAutoBackup(instanceId);
+        // Cancel queued (not yet running) jobs for this instance
+        const q = getQueueStatus();
+        for (const job of q.queued) {
+            if (job.instanceId === instanceId)
+                cancelJob(job.id);
+        }
+    }).catch(() => { });
     // Cache metadata BEFORE deletion so we can check custom openclaw_home after rm
     const meta = getInstance(instanceId);
     const home = meta?.openclaw_home;
@@ -911,14 +1170,18 @@ export function deleteInstance(instanceId) {
     }).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) {
@@ -929,6 +1192,22 @@ export function deleteInstance(instanceId) {
     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 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 {
+            await rmAsync(backupDir, { recursive: true, force: true });
+        }
+        catch (e) {
+            warnings.push(`Failed to delete backups: ${e.message}`);
+        }
+    }
+    else if (existsSync(backupDir)) {
+        warnings.push(`Backups preserved at ${backupDir}`);
+    }
     return { ok: dirDeleted, warnings: warnings.length ? warnings : undefined };
 }
 export function getConfig(instanceId) {
@@ -958,13 +1237,7 @@ export function saveConfig(instanceId, config) {
         return false;
     if (!existsSync(configPath)) {
         const legacyPath = legacyOpenclawConfigPath(instanceId);
-        mkdirSync(dirname(configPath), { recursive: true });
-        // Ensure the state dir is group-writable so the Docker container (which may
-        // run as a different UID) can create sub-directories via shared group.
-        try {
-            chmodSync(dirname(configPath), 0o770);
-        }
-        catch { /* best effort */ }
+        ensureDirContainer(dirname(configPath));
         if (existsSync(legacyPath))
             copyFileSync(legacyPath, configPath);
     }
@@ -1000,9 +1273,10 @@ export function saveConfig(instanceId, config) {
             configToWrite.plugins.entries.feishu = { enabled: false };
         }
     }
-    // Preserve plugins.installs from existing config on disk —
-    // these are managed by `openclaw plugins install` and must not be overwritten
-    // by the frontend config which doesn't track them.
+    // 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)) {
         try {
             const existing = JSON.parse(readFileSync(configPath, "utf-8"));
@@ -1010,6 +1284,28 @@ export function saveConfig(instanceId, config) {
                 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 };
+                    }
+                }
+            }
         }
         catch { /* best effort */ }
     }
@@ -1018,18 +1314,18 @@ export function saveConfig(instanceId, config) {
         copyFileSync(configPath, configPath + ".bak");
     }
     const configJson = JSON.stringify(configToWrite, null, 2);
-    mkdirSync(dirname(configPath), { recursive: true });
-    writeFileSync(configPath + ".tmp", configJson, { mode: 0o600 });
+    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 (with restricted permissions)
+    // also write to legacy path
     const legacyPath = legacyOpenclawConfigPath(instanceId);
     if (existsSync(legacyPath)) {
         copyFileSync(legacyPath, legacyPath + ".bak");
     }
-    writeFileSync(legacyPath + ".tmp", configJson, { mode: 0o600 });
+    writeConfigFile(legacyPath + ".tmp", configJson);
     JSON.parse(readFileSync(legacyPath + ".tmp", "utf-8"));
     renameSync(legacyPath + ".tmp", legacyPath);
     chownToServiceUser(legacyPath);
@@ -1081,7 +1377,8 @@ export function saveFeishuCredentials(instanceId, creds) {
         appId: creds.appId,
         appSecret: creds.appSecret,
         domain: creds.domain,
-        dmPolicy: "pairing",
+        dmPolicy: "open",
+        allowFrom: ["*"],
     };
     safeWriteJson(configPath, config);
     chownToServiceUser(configPath);
@@ -1099,7 +1396,7 @@ export function saveWeixinCredentials(instanceId, creds) {
     const home = getOpenclawHomeInternal(instanceId);
     const stateDir = join(home, OPENCLAW_STATE_DIRNAME, "openclaw-weixin");
     const accountsDir = join(stateDir, "accounts");
-    mkdirSync(accountsDir, { recursive: true });
+    ensureDirContainer(accountsDir);
     // Save account credentials file (via safeWriteJson for atomic + .bak protection)
     const credObj = {
         token: creds.token,
@@ -1247,11 +1544,30 @@ 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.
+                            const taskNets = d?.AllocatedResources?.Tasks?.gateway?.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;
+                            }
+                        }
                     }
                 }
             }
@@ -1267,7 +1583,11 @@ export async function getGatewayHost(instanceId) {
     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/);
+            // IPv4 dotted-quad: "... 127.0.0.1:18789 ..."
+            // IPv6 bracketed:   "... [::1]:18789 ..."
+            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;
@@ -1279,6 +1599,16 @@ export async function getGatewayHost(instanceId) {
     _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()
@@ -1286,6 +1616,48 @@ export function findInstancesSharingOpenclawHome(instanceId) {
         .filter((inst) => normalizePath(inst.openclaw_home || defaultOpenclawHome(inst.id)) === targetHome)
         .map((inst) => inst.id);
 }
+/**
+ * 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 fromPort = extractGatewayPort(meta.runtime) ?? DEFAULT_GATEWAY_PORT;
+    const alloc = await allocateGatewayPort(instanceId);
+    try {
+        const runtime = (meta.runtime ?? {});
+        const args = Array.isArray(runtime.args) ? [...runtime.args] : [];
+        for (let i = 0; i < args.length; i++) {
+            if (args[i] === "--port" && i + 1 < args.length) {
+                args[i + 1] = String(alloc.port);
+            }
+            else if (typeof args[i] === "string" && args[i].startsWith("--port=")) {
+                args[i] = `--port=${alloc.port}`;
+            }
+        }
+        runtime.args = args;
+        const env = (runtime.env ?? {});
+        env.OPENCLAW_GATEWAY_PORT = String(alloc.port);
+        runtime.env = env;
+        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);
     return listInstances()