jishushell 0.6.5 → 0.7.3

package/dist/services/runtime/adapters/openclaw.js

@@ -1,3975 +0,0 @@
-/**
- * OpenClawAdapter — the framework face of OpenClaw business logic.
- *
- * Per §32.2 / §32.8 of docs/multi-agent-runtime-generalization-plan.md, the
- * goal of this file is simple: **all OpenClaw-specific knowledge leaves the
- * framework (instance-manager / nomad-manager / routes) and lives here**.
- *
- * Why not a huge rewrite in a single pass?
- *   A full physical migration of ~6500 lines of OpenClaw code out of
- *   `instance-manager.ts` / `nomad-manager.ts` / `setup-manager.ts` is a
- *   multi-PR undertaking. This file lands the **structural** decoupling
- *   (contract + dispatch) today, so:
- *
- *     1. Every framework call site now goes through `getAdapter(agentType).X()`
- *        with zero string-literal branching on "openclaw" / "hermes".
- *     2. OpenClaw-specific imperative logic that was already contained (Nomad
- *        task build, on-disk patches, npm update seed, pairing CLI mapping)
- *        is physically moved into this file.
- *     3. Larger pieces that are still entangled inside instance-manager.ts
- *        (`saveConfig` with channel-plugin auto-install, `createInstance`
- *        with `openclaw.json` seeding) are exposed through adapter hooks
- *        that framework code calls, and the physical code move from
- *        instance-manager.ts into a sibling `openclaw-*.ts` file is a
- *        straightforward follow-up PR — the `check-adapter-isolation.ts`
- *        script (§32.2.1) will block any new code from sneaking back into
- *        the framework layer.
- *
- * The user contract for adding a THIRD agent is therefore already satisfied
- * even before the follow-up physical migration:
- *
- *     1. Create `src/services/runtime/adapters/foo.ts` mirroring this file.
- *     2. Add `import "./adapters/foo.js"` to `src/services/runtime/index.ts`.
- *     3. Add one line to `frontend/src/runtimes/registry.ts`.
- *     4. Done. No `instance-manager.ts` / `nomad-manager.ts` / routes edits.
- */
-import { execFile, execFileSync } from "child_process";
-import { accessSync, chmodSync, chownSync, copyFileSync, cpSync, constants, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync, } from "fs";
-import { createHash, randomBytes } from "crypto";
-import { homedir, userInfo } from "os";
-import { delimiter, dirname, join, resolve as pathResolve } from "path";
-import { getNomadDriver, getOpenclawDockerImage, JISHUSHELL_HOME, getCoreLanHost, getCorePort, getMaxAppMemoryMB, } from "../../../config.js";
-import { ensureDirContainer, ensureDirHost, writeConfigFile } from "../../../utils/fs.js";
-import { safeWriteJson } from "../../../utils/safe-json.js";
-import { compileTaskRuntime } from "../../app/app-compiler.js";
-import { allocateGatewayPort, chownToServiceUser, extractGatewayPort, getInstance, getRuntimeEnv, getRuntimeEnvFiles, inferProviderApiKeyEnvName, listInstances, normalizePath, notifyConfigChange, releasePendingPort, resolveServiceUser, updateEnvFile, } from "../../instance-manager.js";
-import { getInstanceDir as framework_instanceDir, instanceMetaPath } from "../../../config.js";
-import { createTask, emitTask, spawnWithTask, getDirSizeMB, npmProgressParser, dockerBuildProgressParser, resolveDockerInvocation, } from "../../setup-manager.js";
-import { DEFAULT_OPENCLAW_DOCKER_IMAGE, setOpenclawDockerImage, OPENCLAW_MODULES, OPENCLAW_PKG_DIR, } from "../../../config.js";
-import { fileURLToPath } from "node:url";
-import { inspectDockerImage, toDockerInspectUserError } from "../../../utils/docker-inspect.js";
-import { decryptApiKey } from "../../llm-proxy/encryption.js";
-import { getDefaultLlmProvider, normalizeProviderApi } from "../../llm-proxy/providers.js";
-import { bootstrapInstanceProxy, getInstanceConfig as getProxyInstanceConfig, } from "../../llm-proxy/instance-proxy.js";
-import { renderStandaloneMcporterSource } from "../mcp-shims/mcporter-lite.js";
-import { resolveNomadJobId } from "../job-id.js";
-import { registerAdapter } from "../registry.js";
-// ── Constants physically migrated from nomad-manager.ts ───────────────
-//
-// These used to live as module-scope constants in nomad-manager.ts and were
-// read by `buildTaskDocker` / `buildRuntime` helpers. They describe how
-// OpenClaw expects to be launched — container image paths, default command,
-// memory ceilings — and therefore belong to the OpenClaw adapter, not the
-// Nomad scheduler.
-const DEFAULT_COMMAND = "/usr/bin/openclaw";
-const DEFAULT_ARGS = ["gateway", "run", "--port", "18789", "--allow-unconfigured"];
-const DEFAULT_USER = userInfo().username;
-const DEFAULT_CWD = homedir();
-const DEFAULT_ENV = {
-    HOME: homedir(),
-    TMPDIR: "/tmp",
-    PATH: `${homedir()}/.local/bin:${homedir()}/.npm-global/bin:${homedir()}/bin:${homedir()}/.volta/bin:` +
-        `${homedir()}/.asdf/shims:${homedir()}/.bun/bin:${homedir()}/.nvm/current/bin:${homedir()}/.fnm/current/bin:` +
-        `${homedir()}/.local/share/pnpm:/usr/local/bin:/usr/bin:/bin`,
-};
-const DEFAULT_RESOURCES = { CPU: 500, MemoryMB: 512 };
-const DEFAULT_PIDS_LIMIT = 512;
-// Hard upper bounds applied before submitting any Nomad job. Prevents a
-// misconfigured or malicious instance config from exhausting scheduler
-// resources on the host (no Nomad Enterprise Resource Quotas in OSS).
-const MAX_CPU_MHZ = 4000;
-// Memory ceilings read from core.json at runtime via getMaxAppMemoryMB().
-// Path inside the openclaw-runtime Docker image where the baked-in openclaw
-// npm package lives. Referenced by the entrypoint shim as the fallback and
-// used by the control-UI "Update now" path through a pre-seeded symlink in
-// $HOME/.npm-global (see ensureOpenclawUpdateSeed below).
-const CONTAINER_IMAGE_PKG_ROOT = "/app/node_modules/openclaw";
-const VALID_USER_RE = /^[a-z0-9._-]{1,32}$/;
-const DOCKER_IMAGE_RE = /^[a-zA-Z0-9][a-zA-Z0-9\-_.:/@]*$/;
-const MAX_DOCKER_IMAGE_NAME_LEN = 256;
-export const OPENCLAW_DEFAULT_GATEWAY_PORT = 18789;
-// ── Capability profile (moved from runtime/instance.ts) ──────────────
-//
-// Describes what the framework should expose for OpenClaw instances. The
-// frontend uses this to decide which tabs render and how the Chat tab looks.
-const DEFAULT_CAPABILITIES = {
-    gateway: {
-        http: true,
-        websocket: true,
-        chatPanel: "iframe",
-    },
-    pairing: {
-        list: true,
-        approve: true,
-        revoke: false,
-        clearPending: false,
-    },
-    configEditor: "json",
-    configSchema: false,
-    customProvider: true,
-    pluginInstall: true,
-    skills: true,
-    mcp: true,
-    memory: true,
-    backupRestore: true,
-    usageStats: true,
-    restartlessReload: false,
-    messagingPlatforms: ["feishu", "openclaw-weixin"],
-};
-import { FILES_ROOT } from "../../../config.js";
-import { defaultMountsForNewInstance, ensureMountTargets, } from "../../files-mounts.js";
-/**
- * Tolerate both `fileMounts` and `file_mounts` in instance.json — some
- * earlier migrations may have written snake_case.
- */
-function readFileMounts(runtime) {
-    const raw = runtime.fileMounts ?? runtime.file_mounts;
-    return Array.isArray(raw) ? raw : [];
-}
-/**
- * Build the volume list for the docker driver:
- *   1. The existing openclaw-home self-mount (HOME == container HOME)
- *   2. The root FILES_ROOT bind when any mount has empty path
- *      ({"path":"","alias":"","mode":"rw"} — the default for new
- *      instances). Without this, in-container plugins (Feishu / WeChat
- *      send_file) try `fs.open("/home/.../files/...")` and hit ENOENT
- *      because the host path isn't bind-mounted. Verified on pi2
- *      2026-05-11: claw1's drive_resolve_local_path returned a valid
- *      abs_path; feishu_im_user_message then ENOENT'd on it.
- *   3. One additional bind per non-root FileMount, host==container so
- *      the workspace/{alias} symlink (placed by rebuildWorkspace)
- *      resolves identically inside the container.
- *
- * Mode "ro" is enforced by the docker bind option; raw_exec / process
- * modes don't go through this path (the agent runs natively on the host
- * and reads files directly).
- */
-function buildVolumes(openclawHome, runtime) {
-    const list = [`${openclawHome}:${openclawHome}:rw`];
-    for (const abs of listMountedHostPaths(runtime)) {
-        const mode = readFileMounts(runtime).find((m) => !m.path || join(FILES_ROOT, m.path) === abs)?.mode === "ro" ? "ro" : "rw";
-        list.push(`${abs}:${abs}:${mode}`);
-    }
-    return list;
-}
-function listMountedHostPaths(runtime) {
-    let rootBound = false;
-    const list = [];
-    for (const m of readFileMounts(runtime)) {
-        if (!m)
-            continue;
-        if (!m.path) {
-            if (rootBound)
-                continue;
-            list.push(FILES_ROOT);
-            rootBound = true;
-            continue;
-        }
-        if (rootBound)
-            continue; // root already covers every subtree
-        list.push(join(FILES_ROOT, m.path));
-    }
-    return list;
-}
-function listJishukbUploadRoots(runtime, openclawHome) {
-    return Array.from(new Set([
-        ...listMountedHostPaths(runtime),
-        join(openclawHome, ".openclaw", "media", "inbound"),
-    ]));
-}
-// ── Path helpers (physically migrated from instance-manager.ts) ───────
-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";
-function defaultOpenclawHome(instanceId) {
-    return join(framework_instanceDir(instanceId), INSTANCE_OPENCLAW_HOME_DIRNAME);
-}
-function defaultOpenclawModelEnvFile(instanceId) {
-    return join(framework_instanceDir(instanceId), INSTANCE_MODEL_ENV_FILENAME);
-}
-function isPrecreatedManagedAppDir(dir) {
-    return existsSync(join(dir, "app-spec.yaml")) && existsSync(join(dir, "manifest.json"));
-}
-function openclawConfigPath(instanceId, home) {
-    const h = home ?? defaultOpenclawHome(instanceId);
-    return join(h, OPENCLAW_STATE_DIRNAME, OPENCLAW_CONFIG_FILENAME);
-}
-function legacyOpenclawConfigPath(instanceId, home) {
-    const h = home ?? defaultOpenclawHome(instanceId);
-    return join(h, OPENCLAW_CONFIG_FILENAME);
-}
-/**
- * Resolve the most relevant openclaw.json path for a SOURCE instance used
- * by the clone_from branch. Prefers the .openclaw/ state dir, falls back
- * to the legacy flat path so clones of old instances still work.
- */
-function resolveExistingConfigPath(instanceId) {
-    const runtimePath = openclawConfigPath(instanceId);
-    if (existsSync(runtimePath))
-        return runtimePath;
-    const legacy = legacyOpenclawConfigPath(instanceId);
-    if (existsSync(legacy))
-        return legacy;
-    return runtimePath;
-}
-// ── Runtime + config defaults (physically migrated) ───────────────────
-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)) {
-            try {
-                chmodSync(p, 0o755);
-            }
-            catch {
-                /* best effort — may be a symlink */
-            }
-            try {
-                const real = realpathSync(p);
-                if (real !== p)
-                    chmodSync(real, 0o755);
-            }
-            catch {
-                /* best effort */
-            }
-            return p;
-        }
-    }
-    // Fallback: scan $PATH for user-installed openclaw (nvm, homebrew, etc.)
-    // Uses in-process lookup instead of spawning `which` for security and performance.
-    const fromPath = findExecutableOnPath("openclaw");
-    if (fromPath)
-        return fromPath;
-    return candidates[0]; // will fail with clear error at spawn
-}
-/**
- * Search $PATH for an executable by name. Returns the first match or null.
- * Does not chmod the result — PATH-discovered binaries are not managed by JishuShell.
- */
-function findExecutableOnPath(name) {
-    const pathEnv = process.env.PATH || "";
-    for (const dir of pathEnv.split(delimiter)) {
-        if (!dir)
-            continue;
-        const candidate = join(dir, name);
-        try {
-            accessSync(candidate, constants.X_OK);
-            return candidate;
-        }
-        catch {
-            /* not found or not executable in this dir */
-        }
-    }
-    return null;
-}
-function buildDefaultRuntime(instanceId, port, openclawHome) {
-    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: [defaultOpenclawModelEnvFile(instanceId)],
-        env: {
-            OPENCLAW_GATEWAY_PORT: String(port),
-            NODE_OPTIONS: "--max-old-space-size=2048",
-            // Let mcporter find its config regardless of the agent's CWD. The
-            // gateway's CWD is openclaw-home (no config/), and `cd workspace`
-            // means the user-files symlink (also no config/). Without this env,
-            // every `mcporter call drive.*` fails with "Unknown MCP server 'drive'"
-            // and the agent reports a generic "network error" to the user.
-            MCPORTER_CONFIG: `${home}/.openclaw/workspace/config/mcporter.json`,
-        },
-        resources: { CPU: 1000, MemoryMB: 2048 },
-    };
-}
-function starterConfig() {
-    const dp = getDefaultLlmProvider();
-    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?.id) {
-        providerName = dp.id;
-        providerConfig = {
-            baseUrl: dp.baseUrl,
-            api: normalizeProviderApi(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 } } },
-    };
-    if (dp?.id) {
-        config["x-jishushell"] = {
-            proxy: {
-                upstream: {
-                    providerId: dp.id,
-                    baseUrl: dp.baseUrl,
-                    api: normalizeProviderApi(dp.api),
-                    authHeader: dp.authHeader === true || typeof dp.authHeader === "string",
-                    models: dp.models || [],
-                    selectedModelId: dp.selectedModelId || dp.models?.[0]?.id || "",
-                    hasApiKey: !!dp.apiKey,
-                },
-            },
-        };
-    }
-    return config;
-}
-// ── Nomad-patching helpers (migrated from nomad-manager.ts) ───────────
-/**
- * In docker bridge mode, 127.0.0.1 inside the container resolves to the
- * container's own loopback, not the host. Rewrite the jsproxy provider
- * baseUrl in openclaw.json to use host.docker.internal instead.
- */
-function patchJsproxyBaseUrl(configPath) {
-    try {
-        const raw = readFileSync(configPath, "utf-8");
-        const patched = raw.replace(/http:\/\/127\.0\.0\.1:(\d+)\/proxy/g, `http://host.docker.internal:$1/proxy`);
-        if (patched !== raw) {
-            writeConfigFile(configPath, patched);
-            console.log(`[openclaw] Patched jsproxy baseUrl in ${configPath} (127.0.0.1 → host.docker.internal)`);
-        }
-    }
-    catch (e) {
-        console.warn(`[openclaw] Failed to patch jsproxy baseUrl in ${configPath}: ${e.message}`);
-    }
-}
-/** Known private/internal hostnames used by JishuShell's local proxy. */
-const PRIVATE_NETWORK_HOSTS = ["host.docker.internal", "127.0.0.1", "localhost", "0.0.0.0"];
-export function isPrivateNetworkBaseUrl(baseUrl) {
-    try {
-        const url = new URL(baseUrl);
-        if (PRIVATE_NETWORK_HOSTS.includes(url.hostname))
-            return true;
-        if (url.hostname.startsWith("10."))
-            return true;
-        if (url.hostname.startsWith("192.168."))
-            return true;
-        // RFC 1918: 172.16.0.0/12 → 172.16.x.x through 172.31.x.x
-        const m = url.hostname.match(/^172\.(\d+)\./);
-        if (m) {
-            const second = parseInt(m[1], 10);
-            if (second >= 16 && second <= 31)
-                return true;
-        }
-        return false;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Ensure `request.allowPrivateNetwork: true` is set on providers whose baseUrl
- * targets a private/internal host (e.g. host.docker.internal). Without this,
- * OpenClaw's SSRF guard blocks requests to the JishuShell local proxy.
- */
-export function patchPrivateNetworkAllowFlag(configPath) {
-    try {
-        const raw = readFileSync(configPath, "utf-8");
-        const config = JSON.parse(raw);
-        const providers = config?.models?.providers;
-        if (!providers || typeof providers !== "object")
-            return;
-        let changed = false;
-        for (const [, provider] of Object.entries(providers)) {
-            if (typeof provider !== "object" || provider === null)
-                continue;
-            const p = provider;
-            if (typeof p.baseUrl !== "string")
-                continue;
-            if (!isPrivateNetworkBaseUrl(p.baseUrl))
-                continue;
-            if (p.request?.allowPrivateNetwork === true)
-                continue;
-            p.request = { ...(p.request || {}), allowPrivateNetwork: true };
-            changed = true;
-        }
-        if (changed) {
-            writeConfigFile(configPath, JSON.stringify(config, null, 2));
-            console.log(`[openclaw] Patched request.allowPrivateNetwork in ${configPath} for private-network providers`);
-        }
-    }
-    catch (e) {
-        console.warn(`[openclaw] Failed to patch allowPrivateNetwork in ${configPath}: ${e.message}`);
-    }
-}
-/**
- * Docker bridge port publishing cannot reach a process that only binds the
- * container loopback. Normalize default/loopback gateway binds to `lan` so
- * Nomad's published host port can reach the gateway.
- */
-// Mirrors hermes.ts:nomadHasExternalHostNetwork. When the host nomad.hcl
-// declares `host_network "external" { ... }`, the legacy openclaw job
-// attaches it to its ReservedPorts so docker publishes the gateway to
-// the LAN address instead of 127.0.0.1. Without this, OpenWebUI in a
-// sibling container can't reach openclaw at all.
-function nomadHasExternalHostNetwork() {
-    const path = join(JISHUSHELL_HOME, "nomad", "nomad.hcl");
-    try {
-        return /host_network\s+"external"\s*\{/.test(readFileSync(path, "utf-8"));
-    }
-    catch {
-        return false;
-    }
-}
-function patchDockerBridgeGatewayBind(configPath) {
-    try {
-        const raw = readFileSync(configPath, "utf-8");
-        const parsed = JSON.parse(raw);
-        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
-            return;
-        const gatewayRaw = parsed.gateway;
-        const gateway = gatewayRaw && typeof gatewayRaw === "object" && !Array.isArray(gatewayRaw)
-            ? gatewayRaw
-            : (parsed.gateway = {});
-        const bind = typeof gateway.bind === "string" ? gateway.bind.trim() : "";
-        if (bind && bind !== "loopback")
-            return;
-        gateway.bind = "lan";
-        const next = JSON.stringify(parsed, null, 2);
-        const output = raw.endsWith("\n") ? `${next}\n` : next;
-        if (output === raw)
-            return;
-        writeConfigFile(configPath, output);
-        console.log(`[openclaw] Normalized gateway.bind to "lan" in ${configPath} for Docker bridge networking`);
-    }
-    catch (e) {
-        console.warn(`[openclaw] Failed to patch gateway.bind in ${configPath}: ${e.message}`);
-    }
-}
-/**
- * Ensure the `llm-agent` capability advertised by openclaw-*.yaml works for
- * every instance, including ones created before this code shipped: enable
- * OpenClaw's OpenAI-compatible endpoints in `openclaw.json` on every start.
- *
- * Runs idempotently next to `patchDockerBridgeGatewayBind`. The OpenAI
- * routes (`/v1/chat/completions`, `/v1/responses`, `/v1/models`,
- * `/v1/embeddings`) live in openclaw's bundled server.impl and are gated
- * behind `gateway.http.endpoints.{chatCompletions,responses}.enabled` —
- * default false, so a fresh OpenClaw install would 404 those paths even
- * though OpenWebUI binds it through the connections page.
- */
-export function patchOpenAIEndpointsEnabled(configPath) {
-    try {
-        const raw = readFileSync(configPath, "utf-8");
-        const parsed = JSON.parse(raw);
-        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
-            return;
-        const root = parsed;
-        const gateway = root.gateway && typeof root.gateway === "object" && !Array.isArray(root.gateway)
-            ? root.gateway
-            : (root.gateway = {});
-        const http = gateway.http && typeof gateway.http === "object" && !Array.isArray(gateway.http)
-            ? gateway.http
-            : (gateway.http = {});
-        const endpoints = http.endpoints && typeof http.endpoints === "object" && !Array.isArray(http.endpoints)
-            ? http.endpoints
-            : (http.endpoints = {});
-        let changed = false;
-        for (const key of ["chatCompletions", "responses"]) {
-            const ep = endpoints[key] && typeof endpoints[key] === "object" && !Array.isArray(endpoints[key])
-                ? endpoints[key]
-                : (endpoints[key] = {});
-            if (ep.enabled !== true) {
-                ep.enabled = true;
-                changed = true;
-            }
-        }
-        if (!changed)
-            return;
-        const next = JSON.stringify(parsed, null, 2);
-        const output = raw.endsWith("\n") ? `${next}\n` : next;
-        writeConfigFile(configPath, output);
-        console.log(`[openclaw] Enabled gateway.http.endpoints.{chatCompletions,responses} in ${configPath} for llm-agent capability`);
-    }
-    catch (e) {
-        console.warn(`[openclaw] Failed to patch OpenAI endpoints in ${configPath}: ${e.message}`);
-    }
-}
-/**
- * Deep-merge a SearXNG connection into an OpenClaw config file at `configPath`.
- *
- * Writes both halves of the wiring required for the `web_search` tool to use
- * the registry-resolved SearXNG instance:
- *
- *   plugins.entries.searxng.enabled                       = true
- *   plugins.entries.searxng.config.webSearch.baseUrl      = baseUrl
- *   tools.web.search.provider                             = "searxng"
- *
- * The provider selector is required because OpenClaw's built-in default is
- * `"brave"`; without it the tool fails with `missing_brave_api_key` even when
- * the searxng plugin is otherwise correctly configured (verified on Pi
- * 2026-04-29: claw11 had the plugin block right but the selector unset).
- *
- * Why a partial deep-merge instead of `saveNativeConfig`: the latter is
- * destructive — it replaces top-level keys wholesale and only preserves a
- * hardcoded subset (`plugins.installs`, `plugins.entries` per-key, partial
- * `channels` merge). A partial patch through it would wipe `models.providers`
- * / `agents.defaults` / etc., bricking the instance with `No API key found
- * for provider "openai"` on the next chat. So we read, merge, write back.
- *
- * No-op when the config file is absent (instance not yet started).
- */
-export function applySearxngConnectionToConfig(configPath, baseUrl) {
-    if (!existsSync(configPath))
-        return;
-    const existing = JSON.parse(readFileSync(configPath, "utf-8"));
-    existing.plugins = existing.plugins ?? {};
-    existing.plugins.entries = existing.plugins.entries ?? {};
-    const prior = existing.plugins.entries.searxng ?? {};
-    existing.plugins.entries.searxng = {
-        ...prior,
-        enabled: true,
-        config: {
-            ...(prior.config ?? {}),
-            webSearch: {
-                ...((prior.config ?? {}).webSearch ?? {}),
-                baseUrl,
-            },
-        },
-    };
-    existing.tools = existing.tools ?? {};
-    existing.tools.web = existing.tools.web ?? {};
-    existing.tools.web.search = existing.tools.web.search ?? {};
-    existing.tools.web.search.provider = "searxng";
-    safeWriteJson(configPath, existing);
-}
-/**
- * Counterpart to `applySearxngConnectionToConfig` — invoked when the user
- * unbinds the SEARCH slot in the Connections tab. Without this, unbinding
- * left the plugin entry enabled with a baseUrl pointing at the now-gone
- * searxng provider, and `tools.web.search.provider="searxng"` kept routing
- * the agent's `web_search` tool through that dead URL on every chat.
- *
- * Conservative cleanup so a future re-bind (or user-customized plugin
- * settings) survives:
- *   - flip the searxng plugin to enabled:false (don't delete the entry —
- *     user may have hand-tuned it and we want re-bind to re-enable cheaply)
- *   - drop the stale `webSearch.baseUrl` so nothing reads it as still-live
- *   - clear `tools.web.search.provider` so the runtime falls back to its
- *     built-in default (which today errors out with `missing_brave_api_key`
- *     — the right outcome: search was unbound, web_search shouldn't work)
- *
- * No-op when the config file is absent.
- */
-export function clearSearxngConnectionFromConfig(configPath) {
-    if (!existsSync(configPath))
-        return;
-    const existing = JSON.parse(readFileSync(configPath, "utf-8"));
-    const sx = existing?.plugins?.entries?.searxng;
-    if (sx && typeof sx === "object") {
-        sx.enabled = false;
-        if (sx.config?.webSearch && typeof sx.config.webSearch === "object") {
-            delete sx.config.webSearch.baseUrl;
-        }
-    }
-    if (existing?.tools?.web?.search && typeof existing.tools.web.search === "object") {
-        delete existing.tools.web.search.provider;
-    }
-    safeWriteJson(configPath, existing);
-}
-/** Profile name used in `browser.profiles` for jishushell-managed Browserless bindings. */
-const BROWSERLESS_PROFILE = "browserless";
-/**
- * Default `color` for the jishushell-managed browserless profile. OpenClaw's
- * profile schema treats `color` as required (the field shows up as the
- * profile chip tint in the UI); omitting it triggers
- *   "browser.profiles.browserless.color: Invalid input: expected string,
- *    received undefined"
- * on every config reload, which crashloops the gateway. Verified against
- * the runtime image `ghcr.io/x-aijishu/openclaw-runtime:2026.4.15` on Pi 2
- * (2026-05-07). The tone is Browserless brand green; users can override it
- * once and we preserve their override on re-bind via the `prior` spread.
- */
-const BROWSERLESS_DEFAULT_COLOR = "#00AA66";
-/**
- * Deep-merge a Browserless CDP connection into an OpenClaw config file at
- * `configPath`. Mirrors `applySearxngConnectionToConfig` for the browser slot.
- *
- * Writes:
- *   browser.profiles.browserless.cdpUrl     = cdpUrl            // ws:// or wss://
- *   browser.profiles.browserless.attachOnly = true              // since v2026.3.2
- *   browser.profiles.browserless.color      = "#00AA66"         // required by schema
- *   browser.defaultProfile                  = "browserless"     // only if unset
- *   browser.enabled                         = true              // only if unset
- *   gateway.nodes.browser.mode              = "off"             // only if unset
- *
- * Why per-profile `attachOnly` and not global `browser.attachOnly`: global
- * attachOnly forces every profile to skip launch — that breaks the user's
- * other manually-configured profiles. Per-profile attachOnly was added in
- * OpenClaw v2026.3.2; older versions silently ignore the extra field and
- * fall back to attach-via-cdpUrl semantics (which `cdpUrl` triggers on its
- * own from v2.0.0-beta5), so the schema is forward-compatible all the way
- * back to the first remote-CDP release.
- *
- * Why `gateway.nodes.browser.mode = "off"`: in OpenClaw 2026.5.6 the
- * gateway only registers the `browser.request` WS method when this config
- * block exists. Without it, `openclaw browser …` CLI and the gateway
- * canvas tool both fail with `unknown method: browser.request` or
- * `node required`. Setting `mode: "off"` forces gateway-local CDP
- * dispatch (use `cdpUrl` directly, never look for paired nodes), which
- * matches jishushell's intent: Browserless is a service-style provider,
- * not a node-style provider. Verified end-to-end on Pi 2 (2026-05-07):
- * Browserless `/sessions` shows `numbConnected: 1` and `openclaw browser
- * navigate <allowed-host>` succeeds + screenshots render correctly.
- *
- * `defaultProfile`, `enabled`, and `gateway.nodes.browser.mode` are all
- * set only when absent so user-customized values survive a re-bind. The
- * `enabled` flag is never flipped off — Browserless binding shouldn't
- * override a user who explicitly disabled the browser tool tree.
- *
- * SSRF policy is intentionally NOT touched here: `browser.ssrfPolicy`
- * (`dangerouslyAllowPrivateNetwork`, `allowedHostnames`) is a user-level
- * security decision (default deny-all is correct for an LLM-driven
- * browser); jishushell would be over-reaching to silently widen it on
- * binding. Users who want the agent to reach a specific host configure
- * the allowlist themselves.
- *
- * No-op when the config file is absent (instance not yet started).
- */
-export function applyBrowserlessConnectionToConfig(configPath, cdpUrl) {
-    if (!existsSync(configPath))
-        return;
-    const existing = JSON.parse(readFileSync(configPath, "utf-8"));
-    const browser = (existing.browser ??= {});
-    if (browser.enabled === undefined)
-        browser.enabled = true;
-    if (!browser.defaultProfile)
-        browser.defaultProfile = BROWSERLESS_PROFILE;
-    const profiles = (browser.profiles ??= {});
-    const prior = profiles[BROWSERLESS_PROFILE] ?? {};
-    profiles[BROWSERLESS_PROFILE] = {
-        ...prior,
-        cdpUrl,
-        attachOnly: true,
-        color: typeof prior.color === "string" && prior.color ? prior.color : BROWSERLESS_DEFAULT_COLOR,
-    };
-    const gateway = (existing.gateway ??= {});
-    const nodes = (gateway.nodes ??= {});
-    const browserPolicy = (nodes.browser ??= {});
-    if (browserPolicy.mode === undefined)
-        browserPolicy.mode = "off";
-    safeWriteJson(configPath, existing);
-}
-/**
- * Counterpart to `applyBrowserlessConnectionToConfig` — invoked when the user
- * unbinds the BROWSER slot in the Connections tab. Removes the
- * jishushell-managed `browserless` profile and clears `defaultProfile` only
- * if it still points at that profile (so user-set defaults pointing at their
- * own profiles survive). Other profiles and `browser.enabled` are left alone.
- *
- * No-op when the config file is absent.
- */
-export function clearBrowserlessConnectionFromConfig(configPath) {
-    if (!existsSync(configPath))
-        return;
-    const existing = JSON.parse(readFileSync(configPath, "utf-8"));
-    const browser = existing?.browser;
-    if (!browser || typeof browser !== "object")
-        return;
-    if (browser.profiles && typeof browser.profiles === "object") {
-        delete browser.profiles[BROWSERLESS_PROFILE];
-    }
-    if (browser.defaultProfile === BROWSERLESS_PROFILE) {
-        delete browser.defaultProfile;
-    }
-    safeWriteJson(configPath, existing);
-}
-/**
- * Bump when a panel-side change invalidates the agent's prior reasoning
- * within an existing chat session — e.g., a mount fix that turns prior
- * "I can't read this file" tool failures into stale conclusions. The
- * first onBeforeStart after the bump rotates the instance's session
- * jsonl files (`<file>.jsonl` → `<file>.jsonl.reset.<ts>`), so the next
- * user message lands on a clean context window. Old transcripts are
- * preserved as .reset.* siblings — never deleted, just archived.
- *
- * Concrete history:
- *   2026.5.11.1 — buildVolumes root-mount fix: empty-path FileMount
- *                  finally binds FILES_ROOT into docker containers. Prior
- *                  sessions had agent conclude "drive only has metadata,
- *                  no file content" after ENOENT — that reasoning is
- *                  poisoned post-fix.
- *   2026.5.11.2 — WeChat target-format rule in TOOLS.md: agent was
- *                  extrapolating Feishu's `user:` prefix onto WeChat
- *                  chat_ids that don't carry it, causing WeChat's
- *                  getuploadurl to return ret:-1. Prior sessions need
- *                  rotation so the agent re-reads the corrected target
- *                  rule and stops adding the prefix.
- *   2026.6.4.2 — jishu-kb citations response + mcporter fallback shebang:
- *                  agent was concluding KB was empty because the shim only
- *                  recognized `chunks/results/hits`, while current jishu-kb
- *                  returns `citations`. The fallback wrapper also baked a
- *                  host-specific node shebang that some OpenClaw runtimes
- *                  could not execute directly. Prior sessions need rotation
- *                  so the agent retries with the fixed tool behavior.
- *   2026.6.4.3 — jishu-kb multi-tool surface: KB management/upload/delete
- *                  tools and handbook/config reads are now available.
- *                  Prior sessions need rotation so the model re-reads the
- *                  expanded tool instructions instead of the old search-only
- *                  guidance.
- *
- * Format: YYYY.M.D.N (date + same-day bump counter). Compare as strings;
- * any difference means rotate. Stored per-instance at
- *   `<instanceDir>/runtime-contract.txt`
- */
-const RUNTIME_CONTRACT_VERSION = "2026.6.4.3";
-const JISHUSHELL_DRIVE_HINT_BEGIN = "<!-- jishushell-drive: BEGIN auto-generated -->";
-const JISHUSHELL_DRIVE_HINT_END = "<!-- jishushell-drive: END -->";
-const JISHUSHELL_KB_HINT_BEGIN = "<!-- jishushell-kb: BEGIN auto-generated -->";
-const JISHUSHELL_KB_HINT_END = "<!-- jishushell-kb: END -->";
-/**
- * Rotate session jsonl files when the runtime contract version has bumped
- * since this instance last started. Matches OpenClaw's own .reset.<ts>
- * naming convention so its existing UI/cleanup paths still apply.
- *
- * Why this exists: when a panel upgrade fixes a runtime bug (e.g. the
- * 2026-05-11 mount-bind fix), the agent's prior turn-by-turn reasoning
- * inside an existing session is anchored to the broken behaviour. Even
- * after the fix is deployed and the alloc restarted, the LLM keeps
- * citing past tool failures and refusing to retry. Rotating the session
- * jsonl(s) gives the next user message a clean context where the agent
- * sees fresh TOOLS.md + fresh tool outputs.
- *
- * Side effect: the user loses chat scrollback in IM/web. Acceptable
- * because (a) the rotated file is preserved on disk, (b) panel upgrades
- * are infrequent, (c) the alternative — agent stuck in old reasoning —
- * is worse UX.
- */
-function rotateSessionsIfContractChanged(instanceId, openclawHome) {
-    try {
-        const markerPath = join(framework_instanceDir(instanceId), "runtime-contract.txt");
-        let previous = "";
-        try {
-            previous = readFileSync(markerPath, "utf-8").trim();
-        }
-        catch (e) {
-            if (e?.code !== "ENOENT")
-                throw e;
-        }
-        if (previous === RUNTIME_CONTRACT_VERSION)
-            return;
-        const sessionsDir = join(openclawHome, ".openclaw", "agents", "main", "sessions");
-        if (existsSync(sessionsDir)) {
-            const ts = new Date()
-                .toISOString()
-                .replace(/:/g, "-")
-                .replace(/\.\d+Z$/, ".000Z");
-            const entries = readdirSync(sessionsDir);
-            let rotated = 0;
-            for (const name of entries) {
-                if (!name.endsWith(".jsonl"))
-                    continue; // skip already-rotated
-                const from = join(sessionsDir, name);
-                const to = `${from}.reset.${ts}`;
-                try {
-                    renameSync(from, to);
-                    rotated++;
-                }
-                catch (e) {
-                    console.warn(`[openclaw] session rotate failed for ${from}: ${e?.message ?? e}`);
-                }
-            }
-            if (rotated > 0) {
-                console.log(`[openclaw] runtime contract ${previous || "(none)"} → ${RUNTIME_CONTRACT_VERSION}: rotated ${rotated} session(s) under ${sessionsDir}`);
-            }
-        }
-        writeConfigFile(markerPath, RUNTIME_CONTRACT_VERSION + "\n");
-    }
-    catch (e) {
-        console.warn(`[openclaw] rotateSessionsIfContractChanged failed: ${e?.message ?? e}`);
-    }
-}
-/**
- * Inject a guarded section into the agent's TOOLS.md telling the LLM that
- * user files live on the local filesystem (host==container bind mount),
- * not on some remote "drive server", and showing the concrete
- * resolve-then-send chain for IM channels (Feishu / WeChat).
- *
- * Why this exists: the LLM defaults to interpreting `drive` as a remote
- * service, then refuses to send NAS files via IM with "I can't access the
- * cloud drive" — even when `drive_list` literally just enumerated them.
- * Verified on pi2 2026-05-11: claw1 saw `文档/宇树G1-D...xlsx` via
- * drive_list, then told the user to "open Feishu cloud space and forward
- * it back" because nothing in TOOLS.md tied drive paths to filesystem
- * paths. This patcher closes that gap by spelling it out.
- *
- * Idempotent: section is bracketed by HTML markers; content between them
- * is rewritten on every call. User edits OUTSIDE the markers are kept.
- *
- * filesRoot is baked in so the example abs path matches the actual install
- * — third-party users on `/home/alice/.jishushell/files/` see their own
- * root, not pi's.
- */
-export function patchToolsMdDriveHint(workspaceDir, filesRoot, mcporterCommand = "mcporter", instanceId) {
-    try {
-        const toolsPath = join(workspaceDir, "TOOLS.md");
-        let original = "";
-        try {
-            original = readFileSync(toolsPath, "utf-8");
-        }
-        catch (e) {
-            if (e?.code !== "ENOENT")
-                throw e;
-        }
-        const cli = mcporterCommand === "mcporter" ? "mcporter" : JSON.stringify(mcporterCommand);
-        const generatedOutboxPath = instanceId
-            ? `agent-data/${instanceId}/outbox/x.pdf`
-            : "agent-data/<instance>/outbox/x.pdf";
-        const section = [
-            JISHUSHELL_DRIVE_HINT_BEGIN,
-            "",
-            "### 📁 用户的 NAS / 文件库",
-            "",
-            "⚠️ **用户文件操作硬路由 — 必读**",
-            "",
-            "**单一规则（语言无关）**：用户用任何语言（中文 / English / 日本語 / ...）说「**我的 / 我的 / my / mine / our / the user's / 私の**」+ 任何文件/目录/资料/笔记/文档/代码/data/notes/docs/files → **CRUD 全部走 `drive.*` 工具，禁止用 shell 在 cwd 上操作**。判定按**语义**不按**字面**，本表只是举例。",
-            "",
-            "动作 ↔ 工具映射表（用户文件场景，中英混排示例）：",
-            "",
-            "| 用户意图（多语言示例） | ✅ 必须用 | ❌ 禁止 |",
-            "|---|---|---|",
-            "| list / show / 「列一下 / 我有什么 / 看看我的 / what files do I have / show me my docs / list my files」 | `drive_list` | `ls`, `find`, `pwd` |",
-            "| read / open / 「打开 / 看看 / 念一下 / 内容是啥 / open my X / read the content of / what's in」 | `drive_read_preview` / `drive_read_full` | `cat`, `head`, `tail` |",
-            "| search / find / 「搜 / 找一下 / 哪里提到 / search my docs for / find X in my files / where did I write about」 | `drive_search` | `grep`, `rg` |",
-            "| write / save / create / 「写 / 存 / 记一下 / 新建 / save this as / write a note / create a file」 | `drive_write_text` / `drive_write_binary` | `echo >`, `cat <<EOF`, `tee` |",
-            "| delete / remove / 「删 / 扔掉 / delete X / remove the file」 | `drive_delete` | `rm` |",
-            "| rename / move / 「改名 / 挪到 / 移到 / rename X to Y / move X to」 | `drive_move` | `mv` |",
-            "| mkdir / 「建文件夹 / create a folder / make a directory」 | `drive_mkdir` | `mkdir` |",
-            "| quota / space / 「配额 / 空间 / how much space / quota / disk usage」 | `drive_quota` | `df`, `du` |",
-            "| send / share / 「发给我 / 把 X 发出去 / send me X / share the file with me」 | `drive_resolve_local_path` → IM `send_file` | （拒绝 / refuse） |",
-            "",
-            "**触发词不完全列表（再次强调：语义优先）**：",
-            "- 中文：我的、我那份、我之前的、我刚刚的、用户的、咱们的、文件、文档、资料、笔记、报告、合同、PDF、Excel、附件",
-            "- English: my, mine, our, the user's, files, file, doc(s), document(s), note(s), paper(s), report(s), spreadsheet(s), pdf(s), attachment(s)",
-            "- 其它语言：私の (ja) / mes (fr) / mein (de) / 我的 (variants) — 含义相同时同等处理",
-            "",
-            "**为什么硬规定**：cwd 是你自己的运行骨架（`AGENTS.md`、`TOOLS.md`、`memory/`、`state/`、`config/`），跟用户**毫无关系**。",
-            "- 用户问「我有什么文件 / what files do I have」你 `ls` cwd → 列出 `AGENTS.md`、`memory/` → 用户懵 + 觉得 jishushell 装错了",
-            "- 用户说「帮我写笔记 notes.md / save a note for me」你 `echo > notes.md` 落 cwd → 文件落到 agent 工作目录，用户在 filebrowser 看不到 → 数据等于丢了",
-            "- 用户说「打开我那份产品规格 / open my spec」你 `cat spec.md` → cwd 里没有该文件 → 找不到 → 用户被冤枉「文件根本不存在」",
-            "",
-            "**判定方法（消息归属判定，跨语言）**：主语/所有格指向「用户/我们」（我 / 我的 / my / our / the user / 私の + 文件相关名词）→ 走 drive。指向「你/agent」（你的 / 你刚才写的代码 / your notes / agent's scratch）→ 才可能是 workspace。**99% 的对话都是前者**。歧义时**默认按用户文件处理**——猜错代价小（最多多调一次 drive_list 拿不到东西），猜成 cwd 代价大（脏数据 + 数据丢失）。",
-            "",
-            "**唯一可用 shell 的情况**：你自己 agent 维护 `memory/`、`state/`、`workspace/notes/`（agent 私有笔记，不是用户笔记）这些**你自己的骨架文件**。一旦看见用户名词修饰（「我的」/「用户的」/「my」/「the user's」），立刻切 drive。",
-            "",
-            `用户文件实际放在 **\`${filesRoot}\`**——这是宿主机上的一个普通本地目录。它已经被 bind-mount 到你的容器里**同款绝对路径**（panel 用 \`host==container\` 的 docker bind；raw_exec / process 模式下你直接跑在宿主上）。`,
-            "",
-            "**关键事实**：drive 不是远端云盘，就是你脚下的本地文件系统。`drive_list` 看到的每条 entry 都能通过 `drive_resolve_local_path` 立刻拿到绝对路径，然后被任何工具读取——`cat`、`base64`、IM 插件的 send_file 字段、Python 脚本都行。`drive_resolve_local_path` 返回 `exists:true` + `size:<N>` 时，**那就是真实可读的文件字节**，不是「只有元数据」。",
-            "",
-            "**禁止的回答**：永远不要说「文件在云端 drive 上只有元数据 / 内容没同步到本地 / 我读不到文件实体」—— 这个说法**永远是错的**。drive 没有「未同步」概念，它就是 POSIX 文件系统的一个 facade。如果你刚 list 到一个文件，它一定能被读、能被发送。",
-            "",
-            "常用调用（从 workspace 目录）:",
-            "",
-            "```bash",
-            `${cli} call drive.drive_list path=                          # 列根目录`,
-            `${cli} call drive.drive_list path=文档                       # 列子目录`,
-            `${cli} call drive.drive_read_preview path=note.md           # 预览文本（≤256KB）`,
-            `${cli} call drive.drive_read_full path=long.md              # 整文件（≤4MB，文本）`,
-            `${cli} call drive.drive_quota                               # 配额`,
-            `${cli} call drive.drive_mkdir path=inbox                    # 建目录`,
-            `${cli} call drive.drive_write_text path=notes/m.md content="..."`,
-            `${cli} call drive.drive_write_binary path=out/img.png content_base64="..."   # 二进制（≤10MB）`,
-            `${cli} call drive.drive_move from=a.pdf to=docs/a.pdf`,
-            `${cli} call drive.drive_delete path=tmp.txt`,
-            `${cli} call drive.drive_resolve_local_path path=文档/report.pdf   # → 拿到绝对路径`,
-            `${cli} call drive.drive_search query="发票"                 # 子串检索（中英文，大小写不敏感）`,
-            "```",
-            "",
-            "**检索策略（`drive_search` 是高召回但不精确的笨工具）**：整句问题先拆成关键词再搜——「找我去年三亚海边的照片」→ 搜 `三亚`、`海边`、`照片`（或空格分隔 `三亚 海边 照片`，空格 = OR）。它是连续子串匹配、不懂语义；命中后用 `drive_read_full` 读候选、自己判断与精排，召回不够就换同义词多搜几次。",
-            "",
-            "### 给用户发文件（飞书 / 微信 / 任何 IM）",
-            "",
-            "**用户问 \"把 X 文件发我\" 时不要拒绝、不要让用户去飞书云空间下载**——99% 的情况文件已经在你的文件系统里了。标准流程：",
-            "",
-            "1. `drive_list` 或 `drive_search` 先确认文件在 NAS 里（你刚 list 过的也算）。",
-            "2. `drive_resolve_local_path path=文档/x.xlsx` 拿到 `abs_path`，确认 `exists:true`。",
-            "3. 把 `abs_path` 传给**当前会话所在 IM 通道**的发送工具。**`target` 字段一律原样照搬当前消息 `Conversation info` 里的 `chat_id`——一个字符都不要加、不要改、不要补前缀**。各通道 chat_id 形态本来就不一样，照搬就对。",
-            "   - **飞书 DM**：metadata 给 `\"chat_id\":\"user:ou_xxx\"`（自带 `user:` 前缀，**这是飞书的格式不是通用约定**）→ `target=\"user:ou_xxx\"`。工具用 `message` (channel=feishu, msg_type=file, path=<abs_path>) 或 `openclaw-lark` 的 `feishu_im_user_message`。",
-            "   - **微信 DM**：metadata 给 `\"chat_id\":\"o9cq...@im.wechat\"`（**裸 ID，没有 `user:` 前缀**）→ `target=\"o9cq...@im.wechat\"`。工具用 `message` (channel=openclaw-weixin, msg_type=file, path=<abs_path>)。**千万别照搬飞书的 `user:` 加上去**——会让微信服务端的 `getuploadurl` 返 `ret:-1`，文件传不出去。",
-            "   - 通用规则：当前 inbound 消息的 `from` 就是回复 target。打开你刚收到的那条 user message 里 `Conversation info` 的 JSON，把 `chat_id` 整段复制就行。",
-            "4. 失败先查 `exists` 字段、文件大小、IM 通道大小上限（飞书典型 30MB、微信 20MB），再决定降级方案。",
-            "",
-            "**ENOENT / \"no such file or directory\" 处理**：IM 插件返回 ENOENT 但 `drive_resolve_local_path` 刚刚 `exists:true`，**99% 是 panel 刚升级 / mount 刚刷新，但你这个 alloc 用的是旧 spec**。无脑重试一次。还是 ENOENT 才提示用户去 panel 重启实例（stop+start，不是 restart）——但**永远不要**回答 \"文件只是元数据所以读不到\"，那是错的。",
-            "",
-            `要发**新生成**的文件（PDF、图片、报表）：先 \`drive_write_binary path=${generatedOutboxPath} content_base64=...\` 落盘，再 resolve → 发送。`,
-            "",
-            "### 用户给你发文件",
-            "",
-            "目前飞书/微信通道不会自动把附件落盘到 NAS。当用户说\"文件给你了\"但你 `drive_list inbox` 看不到：",
-            "- 优先让用户走 panel 的 Filebrowser（`/apps/filebrowser/`）或 WebDAV 把文件上传到 `inbox/`，再告诉你路径。",
-            "- 飞书附件流：如果飞书 app 已配 `im:resource` 权限，可以用 `feishu_im_user_fetch_resource` 取 file_key、落到 `inbox/feishu/<date>/`。",
-            "",
-            "权限：在 panel \"关联 agent\" UI 里给实例授 ro/rw。403 时让用户去 panel 加。",
-            "",
-            JISHUSHELL_DRIVE_HINT_END,
-            "",
-        ].join("\n");
-        let next;
-        const beginIdx = original.indexOf(JISHUSHELL_DRIVE_HINT_BEGIN);
-        const endIdx = original.indexOf(JISHUSHELL_DRIVE_HINT_END);
-        if (beginIdx >= 0 && endIdx > beginIdx) {
-            const tail = endIdx + JISHUSHELL_DRIVE_HINT_END.length;
-            const after = original
-                .slice(tail)
-                .replace(/^\n+/, "\n");
-            next = original.slice(0, beginIdx) + section + after;
-        }
-        else {
-            const sep = original && !original.endsWith("\n") ? "\n\n" : "\n";
-            next = (original ? original + sep : "") + section;
-        }
-        if (next === original)
-            return;
-        writeConfigFile(toolsPath, next);
-        console.log(`[openclaw] Patched drive hint into ${toolsPath}`);
-    }
-    catch (e) {
-        console.warn(`[openclaw] Failed to patch TOOLS.md drive hint: ${e.message}`);
-    }
-}
-export function resolveKbProvider(kbBinding) {
-    const PROVIDER_ANYLLM = "anythingllm-container";
-    const PROVIDER_JISHUKB = "jishu-kb-container";
-    const idToTag = (id) => {
-        if (id === PROVIDER_JISHUKB)
-            return "jishukb";
-        if (id === PROVIDER_ANYLLM)
-            return "anythingllm";
-        return null;
-    };
-    if (kbBinding === null)
-        return null;
-    if (kbBinding && typeof kbBinding === "object") {
-        const b = kbBinding;
-        if (b.kind === "single") {
-            return idToTag(b.providerId);
-        }
-        if (b.kind === "many") {
-            // User selected the "many" mode but the providers array is malformed
-            // or empty → treat as "no known provider bound", same as a list of
-            // only-unknown providers. Avoids the surprise where a malformed
-            // array silently falls back to legacy auto-anythingllm.
-            if (!Array.isArray(b.providers))
-                return null;
-            // First known match in the user's order wins — the UI lets users
-            // drag to reorder; we honor that order rather than imposing our own.
-            for (const p of b.providers) {
-                const tag = idToTag(p?.providerId);
-                if (tag !== null)
-                    return tag;
-            }
-            return null;
-        }
-        return "anythingllm"; // unknown binding shape → legacy default
-    }
-    return "anythingllm"; // undefined → legacy default
-}
-/**
- * Per-provider kb-shim residue cleanup. Wipes the shim source (replacing
- * the bytes with a removal marker rather than `unlink`-ing — the latter
- * would race with a concurrent `node <shim>` that already opened it) and
- * `unlink`s the sibling `secret.json` if any. Idempotent and safe to call
- * even if no shim was ever installed.
- *
- * Called by EVERY branch of the kb auto-wire block so a rebind from
- * anythingllm ↔ jishukb (or → null) never leaves stale shim files or
- * 0o600 secrets on disk. The "wipe by overwrite" pattern matches what
- * the old anythingllm-only branch did before the dispatch refactor.
- *
- * agentHome is the OpenClaw container's `$HOME` (the value returned by
- * `openclawAdapter.resolveAgentHome(instanceId)`). `which` selects the
- * provider: each gets its own `__mcp_shims__/<which>/` subtree.
- *
- * Exported so the security-critical secret-deletion behavior can be
- * covered by a focused unit test without standing up the full start hook.
- */
-export function wipeKbShimDir(agentHome, which) {
-    const dir = join(agentHome, "__mcp_shims__", which);
-    const shimPath = join(dir, `${which}-shim.js`);
-    const removalMarker = which === "anythingllm"
-        ? "// removed: AnythingLLM not bound as knowledge provider\n"
-        : "// removed: jishu-kb not bound as knowledge provider\n";
-    try {
-        if (existsSync(shimPath)) {
-            writeFileSync(shimPath, removalMarker, { mode: 0o644 });
-        }
-    }
-    catch { /* best effort */ }
-    // AnythingLLM's shim has a sibling 0o600 secret.json (API key). v1
-    // jishu-kb ships without auth so no secret to wipe — when jishu-kb
-    // adds JISHU_KB_AUTH_TOKEN_FILE we'll start writing a secret.json
-    // here too and the unlink must be added below.
-    if (which === "anythingllm") {
-        const secretPath = join(dir, "secret.json");
-        try {
-            if (existsSync(secretPath))
-                unlinkSync(secretPath);
-        }
-        catch { /* best effort */ }
-    }
-}
-export function patchToolsMdKbHint(workspaceDir, mode, provider, mcporterCommand = "mcporter", instanceId, mediaInboundRoot) {
-    try {
-        const toolsPath = join(workspaceDir, "TOOLS.md");
-        let original = "";
-        try {
-            original = readFileSync(toolsPath, "utf-8");
-        }
-        catch (e) {
-            if (e?.code !== "ENOENT")
-                throw e;
-            if (mode === "remove")
-                return; // nothing to strip
-        }
-        // Strip every existing kb section first — tolerant of legacy variants
-        // (e.g. early manual injections that used "END auto-generated -->"
-        // instead of the current "END -->" marker). Without this, repeated
-        // re-patches would accumulate sections in TOOLS.md.
-        const STRIP_RE = /\n*<!-- jishushell-kb: BEGIN[^>]*-->[\s\S]*?<!-- jishushell-kb: END[^>]*-->\n*/g;
-        const stripped = original.replace(STRIP_RE, "\n");
-        let next;
-        if (mode === "remove") {
-            if (stripped === original)
-                return;
-            next = stripped;
-        }
-        else {
-            if (!provider) {
-                throw new Error("provider is required when installing KB hint");
-            }
-            const cli = mcporterCommand === "mcporter" ? "mcporter" : JSON.stringify(mcporterCommand);
-            const generatedOutboxPath = instanceId
-                ? `agent-data/${instanceId}/outbox/report.md`
-                : "agent-data/<instance>/outbox/report.md";
-            const attachmentInboxPath = mediaInboundRoot || "<openclawHome>/.openclaw/media/inbound";
-            const section = provider === "jishukb"
-                ? [
-                    JISHUSHELL_KB_HINT_BEGIN,
-                    "",
-                    "### 📚 知识库（JishuShell-KB）",
-                    "",
-                    "用户长期投递并已经导入到 **JishuShell-KB** 的文档（手册、PDF、内部笔记、会议纪要等）可以检索；你也可以列知识库、创建知识库、把 drive 文件上传入库、查看已索引文档、查看 handbook、读取**脱敏后的**当前配置，以及在用户明确确认时删除文档/知识库。",
-                    "",
-                    "**当前 provider 暴露的工具**：",
-                    "",
-                    `- \`${cli} call kb.kb_list\` — 列出所有知识库（拿 id / name / chunks 数）`,
-                    `- \`${cli} call kb.kb_create name="产品文档" description="可选"\` — 新建知识库`,
-                    `- \`${cli} call kb.kb_search query="<用户原话>" kbId=<可选> topK=<可选>\` — 检索指定或默认知识库`,
-                    `- \`${cli} call kb.kb_upload path="<drive_resolve_local_path 返回的绝对路径>" kbId="<目标知识库 id>"\` — 上传并索引文件到指定知识库`,
-                    `- \`${cli} call kb.kb_list_documents kbId=<可选>\` — 列出指定或默认知识库里的已索引文档`,
-                    `- \`${cli} call kb.kb_read_handbook section="设置 → 知识库"\` — 读取 handbook 全文或指定章节`,
-                    `- \`${cli} call kb.kb_get_config\` — 读取当前**脱敏后的**知识库配置摘要`,
-                    `- \`${cli} call kb.kb_delete_document kbId="<知识库 id>" documentId="<文档 id>" confirmDocumentId="<同一个文档 id>"\` — 删除文档（危险操作，必须显式确认）`,
-                    `- \`${cli} call kb.kb_delete_kb kbId="<知识库 id>" confirmKbId="<同一个知识库 id>"\` — 删除知识库（危险操作，必须显式确认）`,
-                    "",
-                    "**推荐调用顺序**：",
-                    "1. 用户提到“某个指定知识库 / 某个库里”但你不知道 id → 先 `kb_list`。",
-                    "2. 用户要把 drive 里的文件加入知识库 → 先 `drive_resolve_local_path`，再 `kb_upload path=<abs_path> kbId=<显式 id>`。",
-                    `3. 用户当前消息已经附了文件，而且消息里给了宿主机绝对路径（通常在 \`${attachmentInboxPath}/...\`）→ 直接把这个绝对路径传给 \`kb_upload\`；不要先把内容重写到 \`files/\` 根目录，也不要自己猜 \`agent-data/agent1/...\` 这种路径。`,
-                    `4. 用户要上传你**新生成**的文件 → 先 \`drive_write_text\` / \`drive_write_binary\` 到 \`${generatedOutboxPath}\`，再 \`drive_resolve_local_path\` → \`kb_upload\`。`,
-                    "5. 用户要新建库并马上上传 → `kb_create` → 记住返回的 id → `kb_upload`。",
-                    "6. 用户要解释某个设置项怎么用 → 先 `kb_read_handbook`，必要时再 `kb_get_config` 看当前值。",
-                    "",
-                    `**安全规则**：写操作和删除操作不要猜目标知识库；拿不准就先 \`kb_list\`。删除必须是用户明确要求，且把 confirm 字段原样填成同一个 id。 \`kb_get_config\` 只返回脱敏摘要，不会给你密钥。 \`kb_upload\` 只接受来自当前实例已挂载文件目录，或当前实例附件 inbox（\`${attachmentInboxPath}/...\`）的绝对路径。**`,
-                    "",
-                    "**与 drive 的分工**：",
-                    "- `drive.*` = 文件系统 facade（列目录、读字节、拿绝对路径）—— 要的是**文件本体**用 drive",
-                    "- `kb.*` = 知识库检索/管理/上传 —— 要的是**知识库里的内容和状态**用 kb",
-                    "",
-                    "两者数据不共享：drive 里有文件 ≠ 某个知识库已经索引了它。",
-                    "",
-                    "**搜不到时的标准回复**：如果 `kb_search` 没结果，就直接说「我在当前知识库里没找到相关内容」。如果用户问的是 drive 里已有文件，可进一步建议「要我把它上传到某个知识库吗？」—— 但上传前先确认目标 kbId，不要自己猜默认库。",
-                    "",
-                    JISHUSHELL_KB_HINT_END,
-                    "",
-                ].join("\n")
-                : [
-                    JISHUSHELL_KB_HINT_BEGIN,
-                    "",
-                    "### 📚 知识库（AnythingLLM）",
-                    "",
-                    "用户长期投递的文档（手册、PDF、内部笔记、过往会议纪要等）由 **AnythingLLM** 维护索引（本地 LanceDB 向量库 + 内置 Xenova ONNX embedder），通过 `kb.kb_search` 一次调用拿「答案 + 引用来源」。",
-                    "",
-                    "**两个工具**：",
-                    "",
-                    `- \`${cli} call kb.kb_search query="<用户原话>"\` — 在已索引文档里检索，返回答案 + 最多 5 条引用源`,
-                    `- \`${cli} call kb.kb_ingest path="<绝对路径>"\` — 把 drive 里的文件加入知识库并 embed（用户说「加进知识库 / index this / 学习这份」时调）`,
-                    "",
-                    "**ingest 标准链**（drive 里的文件 → 知识库）：",
-                    `1. \`${cli} call drive.drive_resolve_local_path path=inbox/contract.pdf\` → 拿 \`abs_path\``,
-                    `2. \`${cli} call kb.kb_ingest path=<abs_path>\` → AnythingLLM 自动 embed`,
-                    "3. 几秒后用户问相关问题，`kb_search` 命中",
-                    "",
-                    "**search 什么时候调**：用户问的东西像在已上传文档里能找到——「那个 X 的手册里怎么说」、「我们之前关于 Y 的讨论」、「产品规格」、「合同条款」、「what does the doc say about X」等。",
-                    "",
-                    "**什么时候不要调**：寒暄、纯代码生成、数学计算、实时信息（天气/股票/新闻）、**操作 NAS 文件**（那是 `drive.*`，不是 kb）、纯创作类。",
-                    "",
-                    "**与 drive 的分工**：",
-                    "- `drive.*` = 文件系统 facade（列目录、读字节、发文件）—— 要的是**文件本体**用 drive",
-                    "- `kb.kb_search` / `kb.kb_ingest` = 语义检索 + RAG 入库 —— 要的是**答案/知识**用 kb",
-                    "",
-                    "两者数据**不共享**：drive 看到 `manual.pdf` ≠ kb 一定能搜到它。要让 kb 能搜到 → 先 `kb_ingest`。",
-                    "",
-                    "**搜不到时的标准回复**：`kb_search` 回答里说「无相关文档」或 sources 为空 → 先确认 drive 里有没有相关文件，如果有，主动建议「要我把它加入知识库吗」（用户同意就 `drive_resolve_local_path` + `kb_ingest`）；drive 也没有，告诉用户「我在你的知识库里没找到相关内容」，然后**不要继续幻想答案**。",
-                    "",
-                    JISHUSHELL_KB_HINT_END,
-                    "",
-                ].join("\n");
-            const sep = stripped && !stripped.endsWith("\n") ? "\n\n" : "\n";
-            next = (stripped ? stripped + sep : "") + section;
-        }
-        if (next === original)
-            return;
-        writeConfigFile(toolsPath, next);
-        console.log(`[openclaw] ${mode === "remove" ? "Removed" : "Patched"} kb hint in ${toolsPath}`);
-    }
-    catch (e) {
-        console.warn(`[openclaw] Failed to ${mode} TOOLS.md kb hint: ${e.message}`);
-    }
-}
-/**
- * Pre-seed the per-instance npm global prefix with a symlink to the image's
- * baked openclaw package so OpenClaw's in-gateway "Update now" handler can
- * detect the install as an npm global install. Idempotent; docker driver only.
- */
-function ensureOpenclawUpdateSeed(openclawHome, instanceId) {
-    if (getNomadDriver() !== "docker")
-        return;
-    if (!openclawHome)
-        return;
-    const linkDir = join(openclawHome, ".npm-global", "lib", "node_modules");
-    const linkPath = join(linkDir, "openclaw");
-    try {
-        lstatSync(linkPath);
-        return;
-    }
-    catch (err) {
-        if (err?.code !== "ENOENT") {
-            console.warn(`[openclaw] update-seed: lstat failed for ${linkPath}: ${err?.message ?? err}`);
-            return;
-        }
-    }
-    try {
-        mkdirSync(linkDir, { recursive: true });
-        symlinkSync(CONTAINER_IMAGE_PKG_ROOT, linkPath);
-        console.log(`[openclaw] update-seed ${instanceId}: seeded ${linkPath} -> ${CONTAINER_IMAGE_PKG_ROOT}`);
-    }
-    catch (err) {
-        console.warn(`[openclaw] update-seed ${instanceId}: failed to create seed: ${err?.message ?? err}`);
-    }
-}
-// ── Session fence patch (OpenClaw >= 5.19 regression) ─────────────────
-/**
- * The minimum OpenClaw version where the session fence bug exists.
- * The bug was introduced in v2026.5.19 — `eventMayReachTranscriptWriters()`
- * doesn't recognize `"message"` / `"custom_message"` event types, causing
- * session writes to bypass `withSessionWriteLock`, which in turn leaves
- * the file fingerprint stale and triggers `EmbeddedAttemptSessionTakeoverError`
- * on the next prompt.
- *
- * Additionally, on virtiofs mounts (macOS → Colima VM → Docker), file
- * metadata (mtime/ctime) can drift between `releaseForPrompt()` and
- * `assertSessionFileFence()` even without actual writes, due to the
- * multi-layer filesystem stack timing. Patching `assertSessionFileFence`
- * to a no-op fully disables the flawed fence check.
- */
-const SESSION_FENCE_BUG_MIN_VERSION = [2026, 5, 19];
-/**
- * Maximum version (exclusive) to apply the patch. Once OpenClaw ships a fix
- * upstream, set a concrete version here to stop patching newer releases.
- * For now, no upper bound — patch all versions >= MIN.
- */
-/**
- * Safety limit: if the extracted function body exceeds this many characters,
- * skip the patch to avoid corrupting the bundle (e.g. brace-depth counter
- * fooled by string literals containing braces in a future refactored version).
- */
-const MAX_PATCH_TARGET_BODY_LENGTH = 5000;
-/**
- * Patch targets: each entry defines a function to replace.
- * - `eventMayReachTranscriptWriters`: broad return prevents events from
- *   bypassing the write lock (necessary but not sufficient on virtiofs).
- * - `assertSessionFileFence`: no-op disables the fingerprint comparison
- *   that false-triggers due to virtiofs stat drift.
- */
-const SESSION_FENCE_PATCH_TARGETS = [
-    {
-        fnName: "function assertSessionFileFence()",
-        litNeedle: "sameSessionFileFingerprint",
-        replacement: "function assertSessionFileFence() { return; }",
-    },
-    {
-        fnName: "function eventMayReachTranscriptWriters",
-        litNeedle: '"message_update"',
-        replacement: 'function eventMayReachTranscriptWriters(session, event) { return typeof event?.type === "string"; }',
-    },
-];
-/**
- * Patch the session fence bug in OpenClaw >= 5.19 by replacing the
- * `eventMayReachTranscriptWriters` function in the minified bundle.
- *
- * Idempotent: uses a marker file containing the SHA-256 of the patched
- * file. Skips if already patched or if the pattern is not found (future
- * fixed version or different bundle layout).
- *
- * Docker-only: the bug manifests through the virtiofs mount timing
- * discrepancy between container and host — raw_exec/process modes are
- * unaffected in practice.
- */
-export function patchSessionFenceBug(openclawHome, instanceId) {
-    if (getNomadDriver() !== "docker")
-        return;
-    // 1. Read installed version from npm-global package.json
-    const pkgPath = join(openclawHome, ".npm-global", "lib", "node_modules", "openclaw", "package.json");
-    let versionStr;
-    try {
-        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-        versionStr = pkg.version || "";
-    }
-    catch {
-        return; // no npm-global install or unreadable — skip
-    }
-    // 2. Parse version and check minimum threshold
-    const parts = versionStr.split(".").map(Number);
-    if (parts.length < 3 || parts.some(Number.isNaN))
-        return;
-    const [major, minor, patch] = parts;
-    const [minMajor, minMinor, minPatch] = SESSION_FENCE_BUG_MIN_VERSION;
-    if (major < minMajor ||
-        (major === minMajor && minor < minMinor) ||
-        (major === minMajor && minor === minMinor && patch < minPatch)) {
-        return; // version predates the bug
-    }
-    // 3. Find the selection-*.js bundle that contains the target function.
-    //    There may be multiple selection-*.js files in dist/; only one holds
-    //    the session management code.
-    const distDir = join(openclawHome, ".npm-global", "lib", "node_modules", "openclaw", "dist");
-    let bundleFiles;
-    try {
-        const entries = readdirSync(distDir);
-        bundleFiles = entries.filter((f) => f.startsWith("selection-") && f.endsWith(".js"));
-    }
-    catch {
-        return; // dist dir missing or unreadable
-    }
-    if (bundleFiles.length === 0)
-        return;
-    // Scan each candidate for any of the patch target signatures
-    let bundlePath;
-    let bundleContent;
-    for (const file of bundleFiles) {
-        const candidatePath = join(distDir, file);
-        let content;
-        try {
-            content = readFileSync(candidatePath, "utf-8");
-        }
-        catch {
-            continue;
-        }
-        // Match if any target's fnName or litNeedle is present
-        const hasTarget = SESSION_FENCE_PATCH_TARGETS.some((t) => content.includes(t.fnName) || content.includes(t.litNeedle));
-        if (hasTarget) {
-            bundlePath = candidatePath;
-            bundleContent = content;
-            break;
-        }
-    }
-    if (!bundlePath || !bundleContent)
-        return;
-    // 4. Check marker file for idempotency
-    const markerPath = join(distDir, `.session-fence-patched`);
-    const currentHash = createHash("sha256").update(bundleContent).digest("hex");
-    try {
-        const marker = readFileSync(markerPath, "utf-8").trim();
-        if (marker === currentHash)
-            return; // already patched, hash matches
-    }
-    catch {
-        // marker missing — proceed
-    }
-    // 5. Apply each patch target using brace-depth counting to extract and
-    //    replace function bodies. Process targets in order; earlier patches
-    //    shift offsets so we re-search after each replacement.
-    let patched = bundleContent;
-    let patchCount = 0;
-    for (const target of SESSION_FENCE_PATCH_TARGETS) {
-        let fnStart = patched.indexOf(target.fnName);
-        // Fallback for eventMayReachTranscriptWriters: locate by unique literal
-        // combination ("message_update" near "message_end" and "agent_end")
-        if (fnStart === -1 && target.litNeedle === '"message_update"') {
-            let scanPos = 0;
-            while (scanPos < patched.length) {
-                const litIdx = patched.indexOf(target.litNeedle, scanPos);
-                if (litIdx === -1)
-                    break;
-                const window = patched.slice(litIdx, litIdx + 200);
-                if (window.includes('"message_end"') && window.includes('"agent_end"')) {
-                    const searchStart = Math.max(0, litIdx - 300);
-                    const prefix = patched.slice(searchStart, litIdx);
-                    const fnKeywordIdx = prefix.lastIndexOf("function ");
-                    if (fnKeywordIdx !== -1) {
-                        fnStart = searchStart + fnKeywordIdx;
-                        break;
-                    }
-                }
-                scanPos = litIdx + 1;
-            }
-        }
-        if (fnStart === -1)
-            continue; // target not found (already patched or fixed version)
-        // Check if already patched (replacement is short and contains `return;`)
-        const peekEnd = Math.min(fnStart + target.replacement.length + 10, patched.length);
-        const peek = patched.slice(fnStart, peekEnd);
-        if (peek.startsWith(target.replacement))
-            continue;
-        // Extract function body with brace-depth counting
-        const braceStart = patched.indexOf("{", fnStart);
-        if (braceStart === -1)
-            continue;
-        let depth = 0;
-        let fnEnd = -1;
-        for (let i = braceStart; i < patched.length; i++) {
-            if (patched[i] === "{")
-                depth++;
-            else if (patched[i] === "}") {
-                depth--;
-                if (depth === 0) {
-                    fnEnd = i + 1;
-                    break;
-                }
-            }
-        }
-        if (fnEnd === -1)
-            continue;
-        // Safety: if extracted body is suspiciously large, skip to avoid corrupting
-        // the bundle (brace counter may have been fooled by string contents).
-        if (fnEnd - fnStart > MAX_PATCH_TARGET_BODY_LENGTH) {
-            console.warn(`[openclaw] session-fence-patch ${instanceId}: skipping ${target.fnName} — body too large (${fnEnd - fnStart} chars)`);
-            continue;
-        }
-        patched = patched.slice(0, fnStart) + target.replacement + patched.slice(fnEnd);
-        patchCount++;
-    }
-    if (patchCount === 0) {
-        // No targets needed patching — write marker for current state
-        try {
-            writeFileSync(markerPath, currentHash + "\n", "utf-8");
-        }
-        catch {
-            /* best effort */
-        }
-        return;
-    }
-    // 7. Atomic write: temp file → rename
-    const tmpPath = bundlePath + `.tmp.${randomBytes(4).toString("hex")}`;
-    try {
-        writeFileSync(tmpPath, patched, "utf-8");
-        renameSync(tmpPath, bundlePath);
-    }
-    catch (err) {
-        // Clean up temp file on failure
-        try {
-            unlinkSync(tmpPath);
-        }
-        catch {
-            /* ignore */
-        }
-        console.warn(`[openclaw] session-fence-patch ${instanceId}: atomic write failed: ${err?.message ?? err}`);
-        return;
-    }
-    // 8. Write marker with hash of the PATCHED file
-    const patchedHash = createHash("sha256").update(patched).digest("hex");
-    try {
-        writeFileSync(markerPath, patchedHash + "\n", "utf-8");
-    }
-    catch {
-        // Non-fatal — patch was applied, marker just helps idempotency
-    }
-    console.log(`[openclaw] session-fence-patch ${instanceId}: patched ${bundlePath.split("/").pop()} (v${versionStr})`);
-}
-// ── Container-side patch script ───────────────────────────────────────────
-/**
- * Self-contained Node.js script that patches the session fence bug from
- * INSIDE the container. Written to `$OPENCLAW_HOME/.jishushell/session-fence-patch.mjs`
- * by onBeforeStart and executed by the inline Docker entrypoint before the
- * OpenClaw gateway starts.
- *
- * This covers the case where an in-container `npm install openclaw@latest`
- * upgrades to a buggy version (>= 5.19) after the container was created
- * with a clean image (5.7). The host-side `patchSessionFenceBug` cannot
- * patch at onBeforeStart time because the npm-global directory may not yet
- * contain the upgraded bundle (it's a dangling symlink to a container-only path).
- */
-const CONTAINER_PATCH_SCRIPT = `#!/usr/bin/env node
-// Session fence patch — auto-generated by JishuShell.
-// Patches assertSessionFileFence + eventMayReachTranscriptWriters
-// in OpenClaw >= 2026.5.19 to work around virtiofs stat drift.
-import { readFileSync, writeFileSync, readdirSync, renameSync, existsSync } from "fs";
-import { join } from "path";
-import { createHash } from "crypto";
-
-const home = process.env.HOME || process.env.OPENCLAW_HOME || "/home/openclaw";
-const distDir = join(home, ".npm-global", "lib", "node_modules", "openclaw", "dist");
-const pkgPath = join(home, ".npm-global", "lib", "node_modules", "openclaw", "package.json");
-
-try {
-  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-  const parts = (pkg.version || "").split(".").map(Number);
-  if (parts.length < 3 || parts[0] < 2026 || (parts[0] === 2026 && parts[1] < 5) ||
-      (parts[0] === 2026 && parts[1] === 5 && parts[2] < 19)) process.exit(0);
-  // No upper version cap for now — patch all versions >= 5.19
-} catch { process.exit(0); }
-
-const markerPath = join(distDir, ".session-fence-patched");
-let files;
-try { files = readdirSync(distDir).filter(f => f.startsWith("selection-") && f.endsWith(".js")); }
-catch { process.exit(0); }
-
-const targets = [
-  { fn: "function assertSessionFileFence()", repl: "function assertSessionFileFence() { return; }" },
-  { fn: "function eventMayReachTranscriptWriters", repl: 'function eventMayReachTranscriptWriters(session, event) { return typeof event?.type === "string"; }' },
-];
-
-for (const file of files) {
-  const p = join(distDir, file);
-  let src;
-  try { src = readFileSync(p, "utf-8"); } catch { continue; }
-  if (!targets.some(t => src.includes(t.fn) || src.includes("sameSessionFileFingerprint"))) continue;
-
-  const hash = createHash("sha256").update(src).digest("hex");
-  try { if (readFileSync(markerPath, "utf-8").trim() === hash) process.exit(0); } catch {}
-
-  let modified = src;
-  let count = 0;
-  for (const t of targets) {
-    const idx = modified.indexOf(t.fn);
-    if (idx === -1) continue;
-    if (modified.slice(idx, idx + t.repl.length + 5).startsWith(t.repl)) continue;
-    const braceStart = modified.indexOf("{", idx);
-    if (braceStart === -1) continue;
-    let d = 0, end = -1;
-    for (let i = braceStart; i < modified.length; i++) {
-      if (modified[i] === "{") d++;
-      else if (modified[i] === "}") { d--; if (d === 0) { end = i + 1; break; } }
-    }
-    if (end === -1) continue;
-    if (end - idx > 5000) continue; // safety: skip if body suspiciously large
-    modified = modified.slice(0, idx) + t.repl + modified.slice(end);
-    count++;
-  }
-  if (count === 0) {
-    try { writeFileSync(markerPath, hash + "\\n"); } catch {}
-    process.exit(0);
-  }
-  const tmp = p + ".tmp." + Math.random().toString(36).slice(2, 8);
-  writeFileSync(tmp, modified);
-  renameSync(tmp, p);
-  const newHash = createHash("sha256").update(modified).digest("hex");
-  try { writeFileSync(markerPath, newHash + "\\n"); } catch {}
-  console.log("[session-fence-patch] patched " + file);
-  break;
-}
-`;
-const CONTAINER_PATCH_ENTRYPOINT_COMMAND = 'node "$HOME/.jishushell/session-fence-patch.mjs" 2>/dev/null || true; exec /usr/local/bin/openclaw-entry.sh "$@"';
-/**
- * Write the container-side patch script to the openclaw-home directory so it
- * is available inside the container via the bind mount.
- *
- * Called from onBeforeStart. Idempotent — only rewrites if content changed.
- */
-export function writeContainerPatchScript(openclawHome) {
-    const scriptDir = join(openclawHome, ".jishushell");
-    try {
-        ensureDirContainer(scriptDir);
-    }
-    catch (err) {
-        console.warn(`[openclaw] Failed to prepare container patch directory ${scriptDir}: ${err?.message ?? err}`);
-        return;
-    }
-    const scriptPath = join(scriptDir, "session-fence-patch.mjs");
-    ensureReadableContent(scriptPath, CONTAINER_PATCH_SCRIPT);
-}
-function ensureReadableContent(path, content) {
-    try {
-        if (existsSync(path) && readFileSync(path, "utf-8") === content) {
-            chmodSync(path, 0o644);
-            return;
-        }
-        writeConfigFile(path, content);
-    }
-    catch (err) {
-        console.warn(`[openclaw] Failed to write patch script ${path}: ${err?.message ?? err}`);
-    }
-}
-function resolveUidGid(username) {
-    try {
-        if (!VALID_USER_RE.test(username)) {
-            console.warn(`[openclaw] Invalid username for UID lookup: ${username}`);
-            return `${process.getuid()}:${process.getgid()}`;
-        }
-        const passwd = readFileSync("/etc/passwd", "utf-8");
-        const line = passwd.split("\n").find((l) => l.startsWith(username + ":"));
-        if (line) {
-            const parts = line.split(":");
-            const uid = parseInt(parts[2], 10);
-            const gid = parseInt(parts[3], 10);
-            if (!isNaN(uid) && !isNaN(gid))
-                return `${uid}:${gid}`;
-        }
-    }
-    catch {
-        /* ignore */
-    }
-    return `${process.getuid()}:${process.getgid()}`;
-}
-function normalizeDockerResources(instanceId, resources) {
-    const requestedMemoryMB = Number(resources.MemoryMB ?? DEFAULT_RESOURCES.MemoryMB);
-    let effectiveMemoryMB = requestedMemoryMB;
-    let effectiveMemoryMaxMB = Math.min(Number(resources.MemoryMaxMB ?? requestedMemoryMB), getMaxAppMemoryMB());
-    if (effectiveMemoryMaxMB < effectiveMemoryMB) {
-        console.warn(`[openclaw] ${instanceId}: MemoryMaxMB (${effectiveMemoryMaxMB}) is below MemoryMB (${effectiveMemoryMB}); clamping.`);
-        effectiveMemoryMaxMB = effectiveMemoryMB;
-    }
-    return {
-        ...resources,
-        MemoryMB: effectiveMemoryMB,
-        MemoryMaxMB: effectiveMemoryMaxMB,
-    };
-}
-// ── Nomad template safety (migrated from nomad-manager.ts) ────────────
-const NOMAD_TEMPLATE_UNSAFE_RE = /[{}"\\]/;
-function assertSafeTemplateId(id) {
-    if (NOMAD_TEMPLATE_UNSAFE_RE.test(id)) {
-        throw new Error(`Job ID "${id}" contains characters unsafe for Nomad Template interpolation`);
-    }
-}
-// ── Lazy-imported framework helpers (avoid circular deps) ─────────────
-//
-// The adapter reaches back into instance-manager.ts for helpers that still
-// live there. Using lazy `await import()` keeps the static import graph
-// acyclic, so runtime/index.ts → adapters/openclaw.ts loads cleanly before
-// instance-manager.ts needs it.
-async function lazyIm() {
-    return await import("../../instance-manager.js");
-}
-// ── Docker image build helpers (physically migrated from setup-manager) ─
-//
-// All OpenClaw-specific docker image build knowledge lives here. setup-manager
-// only retains a thin dispatch wrapper so the public
-// `buildSlimOpenclawImage()` / `startBuildSlimOpenclawImage()` API remains
-// back-compatible for routes/setup.ts and the CLI installer.
-/** Base image used for the slim OpenClaw runtime image. */
-const DOCKER_BASE_IMAGE = "node:22-slim";
-/** Mirror list tried in order when docker.io is unreachable. */
-const DOCKER_BASE_MIRRORS = [
-    "node:22-slim",
-    "hub-mirror.c.163.com/library/node:22-slim",
-    "mirrors.tencent.com/library/node:22-slim",
-    "registry.cn-hangzhou.aliyuncs.com/library/node:22-slim",
-];
-/** Matches a semver-ish tag suffix, e.g. "...:2026.4.9" or "...:v1.2.3-beta". */
-const PINNED_IMAGE_TAG_RE = /:[0-9]+\.[0-9]+\.[0-9]+(-[A-Za-z0-9.-]+)?$/;
-/**
- * Pull DOCKER_BASE_IMAGE from mirrors if not already cached locally.
- */
-async function _ensureDockerBaseImage(invocation, task) {
-    try {
-        execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "inspect", DOCKER_BASE_IMAGE], {
-            timeout: 5000,
-            stdio: "ignore",
-        });
-        emitTask(task, { type: "log", message: `基础镜像已缓存: ${DOCKER_BASE_IMAGE}` });
-        return DOCKER_BASE_IMAGE;
-    }
-    catch {
-        /* not cached, fall through */
-    }
-    for (const mirror of DOCKER_BASE_MIRRORS) {
-        emitTask(task, { type: "log", message: `拉取基础镜像: ${mirror} ...` });
-        const result = await spawnWithTask(task, invocation.cmd, [...invocation.argsPrefix, "pull", mirror], { timeout: 300000 });
-        if (result.ok) {
-            if (mirror !== DOCKER_BASE_IMAGE) {
-                try {
-                    execFileSync(invocation.cmd, [...invocation.argsPrefix, "tag", mirror, DOCKER_BASE_IMAGE], { timeout: 10000 });
-                }
-                catch {
-                    /* tag failure is non-fatal */
-                }
-            }
-            emitTask(task, { type: "log", message: `基础镜像就绪: ${DOCKER_BASE_IMAGE}` });
-            return DOCKER_BASE_IMAGE;
-        }
-        emitTask(task, { type: "log", message: `  → ${mirror} 不可达，尝试下一个镜像源...` });
-    }
-    throw new Error(`无法获取基础镜像 ${DOCKER_BASE_IMAGE}。请检查网络或手动执行: docker pull ${DOCKER_BASE_MIRRORS[1]}`);
-}
-/**
- * Query the npm registry for the current OpenClaw version. Used to bust the
- * Docker layer cache for `RUN npm install openclaw@${ver}` during local build.
- */
-function resolveOpenclawNpmVersion() {
-    try {
-        const out = execFileSync("npm", ["view", "openclaw", "version"], {
-            timeout: 15000,
-            encoding: "utf-8",
-            stdio: ["ignore", "pipe", "ignore"],
-        }).trim();
-        if (/^\d+\.\d+\.\d+/.test(out))
-            return out;
-    }
-    catch {
-        /* npm not reachable */
-    }
-    return "latest";
-}
-/**
- * Read the OpenClaw version bundled at /app/ inside a Docker image.
- */
-function readBundledOpenclawVersion(invocation, image) {
-    try {
-        const out = execFileSync(invocation.cmd, [
-            ...invocation.argsPrefix,
-            "run",
-            "--rm",
-            "--entrypoint",
-            "node",
-            image,
-            "-p",
-            "require('/app/node_modules/openclaw/package.json').version",
-        ], { timeout: 20000, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
-        if (/^\d+\.\d+\.\d+/.test(out))
-            return out;
-    }
-    catch {
-        /* docker unavailable, image missing, or path not present */
-    }
-    return "";
-}
-/**
- * Add a pinned version alias for an image, then drop the mutable :latest /
- * :slim tag. See original setup-manager commentary for details.
- */
-function capturePinnedImageTag(invocation, targetTag, explicitVersion) {
-    if (PINNED_IMAGE_TAG_RE.test(targetTag))
-        return targetTag;
-    let version = explicitVersion && /^\d+\.\d+\.\d+/.test(explicitVersion) ? explicitVersion : "";
-    if (!version) {
-        version = readBundledOpenclawVersion(invocation, targetTag);
-    }
-    if (!version || !/^\d+\.\d+\.\d+/.test(version))
-        return targetTag;
-    const colonIdx = targetTag.lastIndexOf(":");
-    const slashIdx = targetTag.lastIndexOf("/");
-    const hasTag = colonIdx > slashIdx;
-    const repo = hasTag ? targetTag.slice(0, colonIdx) : targetTag;
-    const pinnedTag = `${repo}:${version}`;
-    if (pinnedTag === targetTag)
-        return targetTag;
-    try {
-        execFileSync(invocation.cmd, [...invocation.argsPrefix, "tag", targetTag, pinnedTag], { timeout: 10000, stdio: "ignore" });
-    }
-    catch {
-        return targetTag;
-    }
-    if (/:(latest|slim)$/.test(targetTag)) {
-        try {
-            execFileSync(invocation.cmd, [...invocation.argsPrefix, "rmi", targetTag], { timeout: 10000, stdio: "ignore" });
-        }
-        catch {
-            /* best-effort cleanup */
-        }
-    }
-    return pinnedTag;
-}
-/**
- * Try docker pull, fall back to local `Dockerfile.openclaw-slim` build. This
- * is the primary image-prep path used by every setup flow. Called from the
- * adapter's `buildRuntimeImage()` method.
- */
-async function pullOrBuildOpenclawImageWithTask(task, tag) {
-    const targetTag = tag || DEFAULT_OPENCLAW_DOCKER_IMAGE;
-    try {
-        const invocation = resolveDockerInvocation();
-        // Always attempt pull — when the image is already local and in sync
-        // with upstream, docker returns within seconds after a digest check.
-        // The "skip if image present" early exit was making "reinstall" feel
-        // like a no-op; explicit re-pull matches user intent better. On pull
-        // failure we still fall back to local build below.
-        emitTask(task, { type: "progress", message: `正在拉取镜像: ${targetTag} ...`, progress: 10 });
-        const pullResult = await spawnWithTask(task, invocation.cmd, [...invocation.argsPrefix, "pull", targetTag], { timeout: 600000 });
-        if (pullResult.ok) {
-            const pinned = capturePinnedImageTag(invocation, targetTag);
-            setOpenclawDockerImage(pinned);
-            emitTask(task, { type: "done", message: `镜像拉取成功: ${pinned}`, progress: 100 });
-            task.status = "done";
-            return { ok: true, message: `Docker image ${pinned} pulled`, taskId: task.id };
-        }
-        console.log(`[openclaw] docker pull failed for ${targetTag}, falling back to local build...`);
-        emitTask(task, {
-            type: "progress",
-            message: `拉取失败，正在本地构建镜像: ${targetTag} ...`,
-            progress: 20,
-        });
-        const projectRoot = join(dirname(fileURLToPath(import.meta.url)), "../../../..");
-        const dockerfilePath = join(projectRoot, "Dockerfile.openclaw-slim");
-        if (!existsSync(dockerfilePath)) {
-            emitTask(task, {
-                type: "error",
-                message: "Dockerfile.openclaw-slim not found, cannot fallback to local build",
-            });
-            task.status = "error";
-            return {
-                ok: false,
-                message: "Docker pull failed and Dockerfile.openclaw-slim not found",
-                taskId: task.id,
-            };
-        }
-        const openclawVersion = resolveOpenclawNpmVersion();
-        console.log(`[openclaw] building image with OPENCLAW_VERSION=${openclawVersion}`);
-        const buildResult = await spawnWithTask(task, invocation.cmd, [
-            ...invocation.argsPrefix,
-            "build",
-            "--network=host",
-            "--build-arg",
-            `OPENCLAW_VERSION=${openclawVersion}`,
-            "-f",
-            dockerfilePath,
-            "-t",
-            targetTag,
-            projectRoot,
-        ], { timeout: 1800000, progressParser: dockerBuildProgressParser });
-        if (!buildResult.ok) {
-            try {
-                execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "prune", "-f"], { timeout: 15000, stdio: "ignore" });
-            }
-            catch {
-                /* best-effort */
-            }
-            emitTask(task, { type: "error", message: "Docker 镜像构建失败" });
-            task.status = "error";
-            return {
-                ok: false,
-                message: "Docker image build failed",
-                error: buildResult.output,
-                taskId: task.id,
-            };
-        }
-        const pinned = capturePinnedImageTag(invocation, targetTag, openclawVersion);
-        setOpenclawDockerImage(pinned);
-        emitTask(task, {
-            type: "done",
-            message: `OpenClaw 镜像就绪 (本地构建): ${pinned}`,
-            progress: 100,
-        });
-        task.status = "done";
-        return { ok: true, message: `Docker image ${pinned} built locally`, taskId: task.id };
-    }
-    catch (e) {
-        emitTask(task, { type: "error", message: `镜像获取失败: ${e.message}` });
-        task.status = "error";
-        return {
-            ok: false,
-            message: "Docker image pull/build failed",
-            error: e.message,
-            taskId: task.id,
-        };
-    }
-}
-// ── OpenClawAdapter class ─────────────────────────────────────────────
-class OpenClawAdapter {
-    agentType = "openclaw";
-    displayName = "OpenClaw";
-    defaultCapabilities = DEFAULT_CAPABILITIES;
-    defaultGatewayPort = OPENCLAW_DEFAULT_GATEWAY_PORT;
-    manifest = {
-        agentType: "openclaw",
-        displayName: "OpenClaw",
-        description: "默认 runtime,支持克隆、飞书 / 企业微信插件",
-        defaultCapabilities: DEFAULT_CAPABILITIES,
-        requiresNomadDocker: false,
-        diskSpaceMB: 2048,
-    };
-    hooks = {
-        /**
-         * Full OpenClaw pre-start prelude — used to live inline in
-         * `nomad-manager.startInstance()` as an `if (!hermes) { ... }` branch
-         * (~80 lines). Framework code now calls this hook uniformly for every
-         * kind; Hermes provides a no-op and OpenClaw owns the full sequence:
-         *
-         *   1. Stop any legacy process-manager subprocess
-         *   2. Ensure `openclaw.json` exists + fix state-dir permissions
-         *   3. Docker-bridge: patch gateway.bind + jsproxy baseUrl
-         *   4. Seed `$HOME/.npm-global` for in-gateway "Update now"
-         *   5. Validate + image-inspect the Docker image; background-pull on miss
-         *   6. Write JSPROXY_API_KEY into Nomad Variables
-         *
-         * Throws on fatal errors. Framework catches and returns the structured
-         * result; a `taskId` property on the thrown error signals an async
-         * image pull in progress.
-         */
-        onBeforeStart: async ({ instanceId }) => {
-            // 1. Stop any legacy subprocess
-            try {
-                const { getLegacyStatus, stopInstance: stopLegacyInstance } = await import("../../process-manager.js");
-                const legacyStatus = await getLegacyStatus(instanceId);
-                if (legacyStatus.status === "running") {
-                    console.log(`[openclaw] Stopping legacy process for ${instanceId} (pid=${legacyStatus.pid}) before Nomad start`);
-                    await stopLegacyInstance(instanceId);
-                    await new Promise((r) => setTimeout(r, 2000));
-                }
-            }
-            catch {
-                /* process-manager may be absent; harmless */
-            }
-            // 2. Config path existence check + permissions — use local resolvers
-            //    instead of lazy importing back into instance-manager.
-            let configPath;
-            try {
-                configPath = openclawAdapter.resolveConfigPath(instanceId);
-            }
-            catch {
-                return; // bail gracefully for non-OpenClaw instances
-            }
-            if (!existsSync(configPath)) {
-                throw new Error("Config file not found");
-            }
-            if (getNomadDriver() === "docker") {
-                const stateDir = dirname(configPath);
-                ensureDirContainer(stateDir);
-                try {
-                    for (const entry of readdirSync(stateDir, { withFileTypes: true })) {
-                        if (entry.isDirectory()) {
-                            const sub = join(stateDir, entry.name);
-                            ensureDirContainer(sub);
-                            try {
-                                for (const child of readdirSync(sub, { withFileTypes: true })) {
-                                    if (child.isDirectory())
-                                        ensureDirContainer(join(sub, child.name));
-                                }
-                            }
-                            catch {
-                                /* ignore */
-                            }
-                        }
-                    }
-                }
-                catch {
-                    /* ignore */
-                }
-                if (existsSync(configPath))
-                    chmodSync(configPath, 0o644);
-                // 3. Docker bridge patches
-                patchDockerBridgeGatewayBind(configPath);
-                patchJsproxyBaseUrl(configPath);
-                patchPrivateNetworkAllowFlag(configPath);
-            }
-            // Driver-agnostic: enable the OpenAI-compatible endpoints on every
-            // start so the `llm-agent` capability advertised by openclaw-*.yaml
-            // works for both fresh installs and instances created before this
-            // patcher shipped. Idempotent — bails out fast if already enabled.
-            patchOpenAIEndpointsEnabled(configPath);
-            // 4. npm update-seed — use local resolver
-            try {
-                const home = openclawAdapter.resolveAgentHome(instanceId);
-                if (home)
-                    ensureOpenclawUpdateSeed(home, instanceId);
-            }
-            catch {
-                /* best effort */
-            }
-            // 4a. Patch session fence bug in OpenClaw >= 5.19
-            try {
-                const home = openclawAdapter.resolveAgentHome(instanceId);
-                if (home) {
-                    patchSessionFenceBug(home, instanceId);
-                    // Also write the container-side patch script so that even if
-                    // the host-side patch couldn't apply (e.g. symlink to container
-                    // path), the container will self-patch on startup.
-                    if (getNomadDriver() === "docker") {
-                        writeContainerPatchScript(home);
-                    }
-                }
-            }
-            catch {
-                /* best effort — patch failure must not prevent start */
-            }
-            // 4b. Build the workspace symlink layout from this instance's
-            //     fileMounts (M1 W2). For docker mode, the corresponding
-            //     volume bindings are added in buildNomadTask below; for
-            //     raw_exec / process modes, the symlinks are sufficient
-            //     (no container layer between agent and host fs).
-            try {
-                const home = openclawAdapter.resolveAgentHome(instanceId);
-                const im = await lazyIm();
-                const runtime = im.getInstanceRuntime(instanceId);
-                const mounts = readFileMounts(runtime);
-                if (home) {
-                    const { rebuildWorkspace } = await import("../../workspace-builder.js");
-                    rebuildWorkspace({
-                        openclawHome: home,
-                        filesRoot: FILES_ROOT,
-                        mounts,
-                        instanceId,
-                    });
-                }
-            }
-            catch (e) {
-                // Surface migration-required clearly; otherwise fall back to a
-                // warning so a misconfigured mount cannot prevent instance start.
-                if (e?.reason === "needs-migration") {
-                    throw new Error(`instance ${instanceId} workspace contains pre-W2 user data; run legacy migration first (${e.message})`);
-                }
-                console.warn(`[openclaw] workspace rebuild skipped: ${e?.message ?? e}`);
-            }
-            // 4b-bis. Patch TOOLS.md with the drive-shim hint so the agent
-            //      understands user files are local (host==container bind) and
-            //      knows the resolve→send chain for IM channels. Without this,
-            //      the LLM defaults to "drive = remote cloud service" and
-            //      refuses to send NAS files via Feishu/WeChat. Runs after the
-            //      workspace rebuild because that step creates the workspace
-            //      tree if missing.
-            try {
-                const home = openclawAdapter.resolveAgentHome(instanceId);
-                if (home) {
-                    patchToolsMdDriveHint(join(home, ".openclaw", "workspace"), FILES_ROOT, join(home, ".npm-global", "bin", "jishushell-mcporter"), instanceId);
-                }
-            }
-            catch (e) {
-                console.warn(`[openclaw] TOOLS.md drive hint skipped: ${e?.message ?? e}`);
-            }
-            // 4b-ter. Rotate stale session jsonl(s) when the runtime contract
-            //      bumps. This is the auto-recovery path for panel upgrades
-            //      that fix runtime bugs the agent has already "concluded
-            //      around" inside an existing session — without rotation the
-            //      LLM keeps citing past failures and refusing to retry even
-            //      after the underlying bug is fixed. Idempotent: after the
-            //      first onBeforeStart post-upgrade writes the new marker,
-            //      subsequent starts are no-ops.
-            try {
-                const home = openclawAdapter.resolveAgentHome(instanceId);
-                if (home)
-                    rotateSessionsIfContractChanged(instanceId, home);
-            }
-            catch (e) {
-                console.warn(`[openclaw] session rotation skipped: ${e?.message ?? e}`);
-            }
-            // 4c. Install the drive MCP shim so the agent can call panel
-            //     file/organize APIs from chat (M1 W1.6). Idempotent — we
-            //     overwrite the shim file every start to pick up fixes, and
-            //     mergeMcporterServers marks the entry with __source so user-
-            //     managed mcporter entries are preserved untouched.
-            try {
-                const home = openclawAdapter.resolveAgentHome(instanceId);
-                if (home) {
-                    const { substituteDriveShimPlaceholders } = await import("../mcp-shims/drive-shim.js");
-                    const { mergeMcporterServers } = await import("./openclaw-mcporter.js");
-                    const { getInternalMcpToken } = await import("../../../config.js");
-                    // Pick the core URL based on how THIS instance will actually run.
-                    // For a containerized instance (raw_exec/docker via Nomad with a
-                    // docker image), `host.docker.internal:<corePort>` resolves through
-                    // the bridge gateway. For a host-process / binary spec under Nomad
-                    // raw_exec, the task gets its own network namespace where
-                    // 127.0.0.1 only reaches the task itself — must use the host's
-                    // LAN IPv4 so the shim's fetch crosses back into the host netns.
-                    // Detected via the instance's resolved runtime: container tasks
-                    // carry `runtime.image`, binary tasks carry only `runtime.command`.
-                    const corePort = getCorePort();
-                    let driveCoreHost = "host.docker.internal";
-                    try {
-                        const im2 = await lazyIm();
-                        const rt = im2.getInstanceRuntime(instanceId);
-                        if (!rt?.image) {
-                            driveCoreHost = getCoreLanHost();
-                        }
-                    }
-                    catch (e) {
-                        console.warn(`[openclaw] drive shim runtime detection failed for ${instanceId}; using container-reachable core host:`, e);
-                    }
-                    const driveCoreUrl = `http://${driveCoreHost}:${corePort}`;
-                    const shimDir = join(home, "__mcp_shims__", "drive");
-                    ensureDirContainer(shimDir);
-                    const shimPath = join(shimDir, "drive-shim.mjs");
-                    // Bake coreUrl/token/instanceId into the shim source so it works
-                    // even when OpenClaw scrubs env on MCP subprocess spawn (verified
-                    // 2026-05-11 on pi2: env scrub made the shim default to the
-                    // unreachable host.docker.internal and surface as "fetch failed").
-                    const internalToken = getInternalMcpToken();
-                    const shimSource = substituteDriveShimPlaceholders({
-                        coreUrl: driveCoreUrl,
-                        token: internalToken,
-                        instanceId,
-                    });
-                    writeFileSync(shimPath, shimSource, { mode: 0o755 });
-                    mergeMcporterServers(instanceId, {
-                        drive: {
-                            command: "node",
-                            args: [shimPath],
-                            env: {
-                                // Env still set as a belt-and-suspenders. With baked-in
-                                // values in the shim source itself, these become a fallback
-                                // for dev/manual testing — production never depends on them.
-                                JISHUSHELL_INTERNAL_TOKEN: internalToken,
-                                JISHUSHELL_INSTANCE_ID: instanceId,
-                                JISHUSHELL_CORE_URL: driveCoreUrl,
-                                JISHUSHELL_CORE_PORT: String(corePort),
-                            },
-                            __source: {
-                                kind: "connection",
-                                slot: "drive",
-                                consumerInstanceId: instanceId,
-                            },
-                        },
-                    });
-                }
-            }
-            catch (e) {
-                console.warn(`[openclaw] drive shim install skipped: ${e?.message ?? e}`);
-            }
-            // 4c-quater. Auto-wire knowledge MCP shim. The Connections-tab
-            //      knowledge slot (declared as `requires: knowledge` on the
-            //      OpenClaw spec, persisted under `instance.connections.KNOWLEDGE_BASE_URL`)
-            //      is honored here, so unbinding in the UI actually takes effect.
-            //      Provider resolution (matching connection-resolver.ts):
-            //
-            //        - `null`                     → user explicitly disconnected →
-            //                                       DO NOT inject (and strip any prior shim).
-            //        - kind=single + providerId   → use that provider's shim.
-            //        - kind=many                  → first match wins (jishukb > anythingllm
-            //                                       to be explicit and stable across rebinds).
-            //        - undefined                  → no opinion → fall back to the
-            //                                       historical "auto-on when AnythingLLM
-            //                                       credentials.json exists" UX (legacy default).
-            //
-            //      Mutual cleanup: rebinding from anythingllm → jishukb (or
-            //      vice versa, or → null) wipes the OTHER provider's shim dir
-            //      in EVERY branch. Leaving a 0o600 secret.json + bearer-
-            //      prefilled shim source on disk after unbind would be a
-            //      lingering security smell.
-            //
-            //      Secrets handling (defense-in-depth, anythingllm only):
-            //        - shim source (mode 0o644) carries baseUrl + workspace only;
-            //          the API key lives in a sibling `secret.json` (0o600).
-            //        - mcporter.json (0o644) env carries only non-secret hints
-            //          for hand-running. Production shim reads the secret file.
-            //      jishu-kb v1 ships without auth, so no secret.json.
-            try {
-                const home = openclawAdapter.resolveAgentHome(instanceId);
-                if (home) {
-                    const instMeta = getInstance(instanceId);
-                    const provider = resolveKbProvider(instMeta?.connections?.KNOWLEDGE_BASE_URL);
-                    const mcporterCommand = join(home, ".npm-global", "bin", "jishushell-mcporter");
-                    const wsDir = join(home, ".openclaw", "workspace");
-                    const anyllmShimDir = join(home, "__mcp_shims__", "anythingllm");
-                    const anyllmShimPath = join(anyllmShimDir, "anythingllm-shim.js");
-                    const anyllmSecretPath = join(anyllmShimDir, "secret.json");
-                    const jishukbShimDir = join(home, "__mcp_shims__", "jishukb");
-                    const jishukbShimPath = join(jishukbShimDir, "jishukb-shim.js");
-                    const { mergeMcporterServers, removeMcporterServers } = await import("./openclaw-mcporter.js");
-                    if (provider === "jishukb") {
-                        // Wipe the OTHER provider's residue first (including its
-                        // 0o600 secret.json). Security smell to leave it on disk.
-                        wipeKbShimDir(home, "anythingllm");
-                        const credPath = join(JISHUSHELL_HOME, "apps", "jishu-kb-container", "credentials.json");
-                        let creds = null;
-                        if (existsSync(credPath)) {
-                            try {
-                                creds = JSON.parse(readFileSync(credPath, "utf-8"));
-                            }
-                            catch (e) {
-                                console.warn(`[openclaw] kb: invalid jishu-kb credentials.json: ${e?.message ?? e}`);
-                            }
-                        }
-                        if (creds?.baseUrl) {
-                            const { substituteJishukbShimPlaceholders } = await import("../mcp-shims/jishukb-shim.js");
-                            ensureDirContainer(jishukbShimDir);
-                            const shimSource = substituteJishukbShimPlaceholders({
-                                baseUrl: creds.baseUrl,
-                                kbId: creds.kbId,
-                                allowedUploadRoots: listJishukbUploadRoots(instMeta?.runtime ?? {}, home),
-                            });
-                            writeFileSync(jishukbShimPath, shimSource, { mode: 0o644 });
-                            mergeMcporterServers(instanceId, {
-                                kb: {
-                                    command: "node",
-                                    args: [jishukbShimPath],
-                                    env: {
-                                        // Belt-and-suspenders fallback for hand-running.
-                                        // Baked values in the shim source are the production
-                                        // source of truth. No secret in v1.
-                                        JISHUKB_BASE_URL: creds.baseUrl,
-                                        JISHUKB_KB_ID: creds.kbId || "",
-                                    },
-                                    __source: {
-                                        kind: "connection",
-                                        slot: "knowledge",
-                                        consumerInstanceId: instanceId,
-                                    },
-                                },
-                            });
-                            patchToolsMdKbHint(wsDir, "install", "jishukb", mcporterCommand, instanceId, join(home, ".openclaw", "media", "inbound"));
-                        }
-                        else {
-                            // jishu-kb bound but baseUrl not yet ready / credentials missing.
-                            // Remove any prior kb registration so the agent doesn't
-                            // call a stale shim, and wipe our own shim dir for hygiene.
-                            console.warn(`[openclaw] kb: jishu-kb bound but baseUrl missing at ${credPath} — skipping shim install`);
-                            removeMcporterServers(instanceId, {
-                                source: { kind: "connection", slot: "knowledge", consumerInstanceId: instanceId },
-                            });
-                            patchToolsMdKbHint(wsDir, "remove");
-                            wipeKbShimDir(home, "jishukb");
-                        }
-                    }
-                    else if (provider === "anythingllm") {
-                        // Wipe the OTHER provider's residue first.
-                        wipeKbShimDir(home, "jishukb");
-                        const credPath = join(JISHUSHELL_HOME, "apps", "anythingllm-container", "credentials.json");
-                        let kbCreds = null;
-                        if (existsSync(credPath)) {
-                            try {
-                                kbCreds = JSON.parse(readFileSync(credPath, "utf-8"));
-                            }
-                            catch (e) {
-                                console.warn(`[openclaw] kb: invalid credentials.json: ${e?.message ?? e}`);
-                            }
-                        }
-                        if (kbCreds?.apiKey && kbCreds?.baseUrl) {
-                            const { substituteAnythingllmShimPlaceholders } = await import("../mcp-shims/anythingllm-shim.js");
-                            ensureDirContainer(anyllmShimDir);
-                            const shimSource = substituteAnythingllmShimPlaceholders({
-                                baseUrl: kbCreds.baseUrl,
-                                workspace: kbCreds.workspace || "default",
-                            });
-                            writeFileSync(anyllmShimPath, shimSource, { mode: 0o644 });
-                            // chmod after write to dodge umask; secret.json must be 0o600.
-                            writeFileSync(anyllmSecretPath, JSON.stringify({ apiKey: kbCreds.apiKey }), { mode: 0o600 });
-                            try {
-                                chmodSync(anyllmSecretPath, 0o600);
-                            }
-                            catch { /* best effort */ }
-                            mergeMcporterServers(instanceId, {
-                                kb: {
-                                    command: "node",
-                                    args: [anyllmShimPath],
-                                    env: {
-                                        // Belt-and-suspenders fallback for hand-running. Baked
-                                        // values in the shim source are the production source
-                                        // of truth for baseUrl + workspace; the API key is
-                                        // intentionally NOT placed here — it lives in
-                                        // `secret.json` (0o600) next to the shim so this 0o644
-                                        // file stays free of secrets.
-                                        ANYTHINGLLM_BASE_URL: kbCreds.baseUrl,
-                                        ANYTHINGLLM_WORKSPACE: kbCreds.workspace || "default",
-                                    },
-                                    __source: {
-                                        kind: "connection",
-                                        slot: "knowledge",
-                                        consumerInstanceId: instanceId,
-                                    },
-                                },
-                            });
-                            patchToolsMdKbHint(wsDir, "install", "anythingllm", mcporterCommand);
-                        }
-                        else {
-                            // AnythingLLM bound but creds missing → strip and clean.
-                            removeMcporterServers(instanceId, {
-                                source: { kind: "connection", slot: "knowledge", consumerInstanceId: instanceId },
-                            });
-                            patchToolsMdKbHint(wsDir, "remove");
-                            wipeKbShimDir(home, "anythingllm");
-                        }
-                    }
-                    else {
-                        // provider === null → user explicitly unbound, or bound to
-                        // an unknown/unsupported provider. Strip kb server and wipe
-                        // both shim dirs.
-                        removeMcporterServers(instanceId, {
-                            source: { kind: "connection", slot: "knowledge", consumerInstanceId: instanceId },
-                        });
-                        patchToolsMdKbHint(wsDir, "remove");
-                        wipeKbShimDir(home, "anythingllm");
-                        wipeKbShimDir(home, "jishukb");
-                    }
-                }
-            }
-            catch (e) {
-                console.warn(`[openclaw] kb shim wiring skipped: ${e?.message ?? e}`);
-            }
-            // 4c-bis. Self-heal MCPORTER_CONFIG env on existing instances. Without
-            //      this, mcporter can't find its config when invoked from the
-            //      gateway's CWD (openclaw-home/) or from the workspace symlink
-            //      (which points at user files, also no config/), so every drive
-            //      tool call fails with "Unknown MCP server 'drive'" and the agent
-            //      degrades into reporting a generic "network error". New instances
-            //      get this env via the binary/container runtime template; this
-            //      block back-fills it for instances created before that template
-            //      update so users don't have to recreate them.
-            try {
-                const im2 = await lazyIm();
-                const rt = im2.getInstanceRuntime(instanceId);
-                const home = openclawAdapter.resolveAgentHome(instanceId);
-                if (home && rt && (!rt.env || !rt.env.MCPORTER_CONFIG)) {
-                    const desired = `${home}/.openclaw/workspace/config/mcporter.json`;
-                    const nextEnv = { ...(rt.env || {}), MCPORTER_CONFIG: desired };
-                    im2.updateInstanceMeta(instanceId, { runtime: { ...rt, env: nextEnv } });
-                    console.log(`[openclaw] self-healed MCPORTER_CONFIG env for ${instanceId}`);
-                }
-            }
-            catch (e) {
-                console.warn(`[openclaw] MCPORTER_CONFIG self-heal failed: ${e?.message ?? e}`);
-            }
-            // 4d. Install a standalone mcporter-compatible FALLBACK wrapper at
-            //      `$OPENCLAW_HOME/.npm-global/bin/jishushell-mcporter`. Fresh
-            //      instances often do not carry an actual mcporter npm install, yet
-            //      TOOLS.md asks the model to shell out for drive/kb access. Keep
-            //      the fallback on a distinct path so we do NOT clobber a real
-            //      mcporter install that may support transports/features beyond this
-            //      wrapper's narrow built-in scope.
-            try {
-                const home = openclawAdapter.resolveAgentHome(instanceId);
-                if (home) {
-                    const mcporterBin = join(home, ".npm-global", "bin", "jishushell-mcporter");
-                    ensureDirContainer(join(home, ".npm-global", "bin"));
-                    writeFileSync(mcporterBin, renderStandaloneMcporterSource(), { mode: 0o755 });
-                    try {
-                        chmodSync(mcporterBin, 0o755);
-                    }
-                    catch { /* best effort */ }
-                    console.log(`[openclaw] installed standalone mcporter fallback at ${mcporterBin}`);
-                }
-            }
-            catch (e) {
-                console.warn(`[openclaw] mcporter self-heal failed: ${e?.message ?? e}`);
-            }
-            // 5. Docker image validation + background pull fallback
-            if (getNomadDriver() === "docker") {
-                const image = getOpenclawDockerImage();
-                if (!DOCKER_IMAGE_RE.test(image) || image.length > MAX_DOCKER_IMAGE_NAME_LEN) {
-                    throw new Error(`Invalid Docker image name: "${image}"`);
-                }
-                const imageCheck = inspectDockerImage(image, { timeout: 10000 });
-                if (!imageCheck.ok) {
-                    const inspectError = toDockerInspectUserError(image, imageCheck);
-                    if (imageCheck.reason !== "not_found") {
-                        const err = new Error(inspectError.message);
-                        err.code = inspectError.code;
-                        err.statusCode = inspectError.statusCode;
-                        throw err;
-                    }
-                    console.log(`[openclaw] Docker image ${image} not found, starting background pull`);
-                    try {
-                        const result = openclawAdapter.startBuildRuntimeImage({ tag: image });
-                        const err = new Error(`${inspectError.message} Pull started in background.`);
-                        err.building = true;
-                        err.taskId = result.taskId;
-                        err.code = inspectError.code;
-                        err.statusCode = 202;
-                        throw err;
-                    }
-                    catch (e) {
-                        if (e?.building)
-                            throw e;
-                        throw new Error(`Docker image ${image} not available: ${e?.message ?? e}`);
-                    }
-                }
-            }
-            // 6. Write instance secrets to Nomad Variables
-            try {
-                const nomad = await import("../../nomad-manager.js");
-                if (typeof nomad.writeInstanceVariables === "function") {
-                    await nomad.writeInstanceVariables(instanceId);
-                }
-            }
-            catch (e) {
-                throw new Error(`Failed to store instance secrets in Nomad Variables: ${e?.message ?? e}`);
-            }
-        },
-        /**
-         * OpenClaw auto-installs IM channel plugins (feishu, weixin, etc.) when
-         * they're enabled in `openclaw.json`. That logic currently lives in
-         * `instance-manager.saveConfig()`; wiring it through this hook is a
-         * no-op during MVP because saveConfig still runs inline. The hook
-         * exists so the physical-migration follow-up PR can move the code into
-         * this file without touching framework code.
-         */
-        onConfigSaved: async (_args) => {
-            /* reserved — channel plugin install hook, filled by follow-up PR */
-        },
-        /**
-         * Surface an orphan-directory warning when the legacy `openclaw_home`
-         * field points outside the instance dir. The framework's deleteInstance
-         * only rm's the instance dir itself, so custom-home layouts leave a
-         * tree that the operator must clean up manually.
-         */
-        onDelete: async ({ instanceId, meta }) => {
-            const home = typeof meta?.openclaw_home === "string" ? meta.openclaw_home : null;
-            if (!home)
-                return;
-            const instDir = framework_instanceDir(instanceId);
-            if (home.startsWith(instDir))
-                return; // inside the instance dir — rm already caught it
-            if (!existsSync(home))
-                return;
-            return {
-                warnings: [
-                    `Custom openclaw_home '${home}' was preserved. Delete manually if no longer needed.`,
-                ],
-            };
-        },
-        /**
-         * Rewrite `openclaw.json` x-jishushell.proxy.upstream when the panel
-         * default provider changes. Delegates to instance-manager's existing
-         * helper so the transition stays stepwise.
-         */
-        onUpstreamProviderChange: async ({ instanceId, upstream }) => {
-            try {
-                const im = await lazyIm();
-                if (typeof im.pushUpstreamToInstance === "function") {
-                    await im.pushUpstreamToInstance(instanceId, upstream);
-                }
-            }
-            catch (e) {
-                console.warn(`[openclaw] onUpstreamProviderChange failed for ${instanceId}: ${e.message}`);
-            }
-        },
-    };
-    /**
-     * Full OpenClaw instance bootstrap, physically migrated from the legacy
-     * `instance-manager.createInstance()` (~270 lines). Framework code now
-     * calls this uniformly via `getAdapter(agentType).createInstance(args)` —
-     * instance-manager no longer owns any OpenClaw business logic.
-     *
-     * Responsibilities:
-     *   1. openclaw_home path validation (traversal + symlink safety)
-     *   2. Gateway port allocation + runtime spec generation
-     *   3. clone_from handling (extensions/workspace/memory/sessions copy)
-     *   4. starter config seeding + default-provider API key injection
-     *   5. AppSpec overlays (config_defaults / skills)
-     *   6. Proxy bootstrap token generation via LLM proxy
-     *   7. chown to service user when running as root
-     */
-    async createInstance(args) {
-        const { instanceId, name, description = "", cloneFrom, agentHome: openclawHomeArg, appSpec, cloneOptions, } = args;
-        // Guard: prevent creating an OpenClaw instance when the runtime isn't
-        // installed. Without this, the instance.json gets written but the first
-        // `service/start` fails with an opaque `npm package not found` or
-        // `docker image missing` error. The Setup wizard treats "any runtime
-        // ready" as overall ready, so the Hermes-only case reaches here.
-        // getInstallStatus() is best-effort: if config exports are unavailable
-        // (e.g. partially mocked in test environments) the check is skipped so
-        // tests that do not mock the install state continue to work unchanged.
-        // The e2e-real suite spawns a real CLI on hosts that intentionally do
-        // not have OpenClaw installed; NODE_ENV=test (set by the e2e helper)
-        // is the explicit opt-out so the gate doesn't break instance-lifecycle
-        // tests.
-        try {
-            const hasAppManagedRuntime = Boolean(appSpec?.tasks?.some((task) => (task.role ?? "service") === "service" && (task.command || task.image)));
-            if (!hasAppManagedRuntime && process.env.NODE_ENV !== "test") {
-                const installStatus = this.getInstallStatus();
-                if (!installStatus.installed) {
-                    throw new Error("OpenClaw runtime is not installed. Install it from the Apps page " +
-                        "or run `jishushell install openclaw`, then retry.");
-                }
-            }
-        }
-        catch (err) {
-            // Re-throw only our own install-gate error; absorb config-unavailable
-            // errors that arise in partially mocked test environments.
-            if (err?.message?.startsWith("OpenClaw runtime is not installed"))
-                throw err;
-        }
-        const d = framework_instanceDir(instanceId);
-        const metaPath = instanceMetaPath(instanceId);
-        if (existsSync(metaPath))
-            throw new Error(`Instance '${instanceId}' already exists`);
-        if (existsSync(d) && !isPrecreatedManagedAppDir(d)) {
-            throw new Error(`Instance '${instanceId}' already exists`);
-        }
-        const home = openclawHomeArg
-            ? normalizePath(openclawHomeArg)
-            : defaultOpenclawHome(instanceId);
-        // Restrict openclaw_home to be under JISHUSHELL_HOME or /home to prevent
-        // path traversal. Use realpathSync after mkdir to resolve symlinks.
-        if (openclawHomeArg) {
-            const resolved = pathResolve(home);
-            if (!resolved.startsWith(JISHUSHELL_HOME) && !resolved.startsWith("/home/")) {
-                throw new Error(`openclaw_home must be under ${JISHUSHELL_HOME} or /home/`);
-            }
-            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(", ")}`);
-            }
-        }
-        // Orphaned openclaw_home (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;
-            }
-        }
-        ensureDirContainer(d);
-        try {
-            const parentGid = statSync(dirname(d)).gid;
-            chownSync(d, -1, parentGid);
-        }
-        catch {
-            /* non-root without CAP_CHOWN */
-        }
-        ensureDirContainer(home);
-        ensureDirContainer(join(home, OPENCLAW_STATE_DIRNAME));
-        const portAlloc = await allocateGatewayPort(instanceId, OPENCLAW_DEFAULT_GATEWAY_PORT);
-        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 };
-            }
-        }
-        // W2: every new instance gets a default rw mount on its own
-        // agent-data/{id} subtree (alias _out). Cloned instances inherit
-        // their source's mounts but have agent-data path rewritten to the
-        // new instance id; we keep this simple here and just plant the
-        // default — clone-from semantics for additional mounts can be
-        // tightened in PR-7+ when migration arrives.
-        if (!runtime.fileMounts && !runtime.file_mounts) {
-            runtime.fileMounts = defaultMountsForNewInstance(instanceId);
-        }
-        try {
-            ensureMountTargets(FILES_ROOT, readFileMounts(runtime));
-        }
-        catch (e) {
-            console.warn(`[openclaw] could not pre-create mount targets for ${instanceId}: ${e?.message ?? e}`);
-        }
-        const allocatedPort = extractGatewayPort(runtime);
-        try {
-            const meta = {
-                id: instanceId,
-                name,
-                description,
-                agentType: "openclaw",
-                openclaw_home: home,
-                runtime,
-                created_at: new Date().toISOString(),
-                // Prefer appSpec.app_id (installed unique id set by routes/apps.ts:88-96)
-                // over appSpec.id (which materializeInstalledSpec preserves as the base id).
-                // Multi-instance / copied apps need the installed id so uninstall /
-                // capability rebuild / skills metadata find the right installed entry.
-                ...(appSpec ? { app_id: appSpec.app_id ?? appSpec.id } : {}),
-            };
-            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 = openclawConfigPath(instanceId, home);
-            ensureDirContainer(dirname(configPath));
-            if (cloneFrom && !existsSync(configPath)) {
-                const srcConfig = resolveExistingConfigPath(cloneFrom);
-                if (existsSync(srcConfig)) {
-                    try {
-                        const cloned = JSON.parse(readFileSync(srcConfig, "utf-8"));
-                        // Remove proxy provider (will be regenerated with new token)
-                        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
-                        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
-                        stripImBindings(cloned);
-                        // Copy extensions, workspace, (optionally) memory + sessions
-                        const subdirs = ["extensions", "workspace"];
-                        if (cloneOptions?.include_memory !== false) {
-                            const memDir = join(dirname(srcConfig), "memory");
-                            if (existsSync(memDir))
-                                subdirs.push("memory");
-                        }
-                        if (cloneOptions?.include_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
-                        const srcMetaPath = join(framework_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 } };
-                                    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 {
-                        copyFileSync(srcConfig, configPath);
-                    }
-                }
-            }
-            if (!existsSync(configPath)) {
-                writeConfigFile(configPath, JSON.stringify(starterConfig(), null, 2));
-                // Inject the configured default provider API key into both env files.
-                const dp = getDefaultLlmProvider();
-                if (dp?.apiKey && dp?.id && envFiles.length) {
-                    const envKey = inferProviderApiKeyEnvName(dp.id);
-                    updateEnvFile(envFiles[0], { [envKey]: decryptRuntimeProviderApiKey(dp.apiKey) });
-                    const providerEnv = join(dirname(envFiles[0]), "provider.env");
-                    updateEnvFile(providerEnv, { UPSTREAM_API_KEY: dp.apiKey });
-                }
-            }
-            // Merge AppSpec runtime overlays into openclaw.json (shallow, app wins).
-            // Prefers the plan §17 shape `runtime.defaults`; falls back to the
-            // legacy `openclaw.config_defaults` namespace for pre-§17 specs.
-            const runtimeOverlay = appSpec?.runtime ??
-                appSpec?.openclaw;
-            const overlayDefaults = runtimeOverlay?.defaults
-                ?? runtimeOverlay?.config_defaults;
-            if (overlayDefaults && existsSync(configPath)) {
-                try {
-                    const existing = JSON.parse(readFileSync(configPath, "utf-8"));
-                    const defaults = overlayDefaults;
-                    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 */
-                }
-            }
-            // Record App-level skills for later installation. Prefers the new
-            // `runtime.skills` namespace; falls back to `openclaw.skills` for
-            // pre-§17 specs.
-            const overlaySkills = Array.isArray(runtimeOverlay?.skills)
-                ? runtimeOverlay.skills
-                : null;
-            if (overlaySkills) {
-                try {
-                    const skillsDir = join(dirname(configPath), "skills");
-                    ensureDirContainer(skillsDir);
-                    const skillMeta = join(skillsDir, ".app-skills.json");
-                    safeWriteJson(skillMeta, {
-                        app_id: appSpec.app_id ?? appSpec.id,
-                        skills: overlaySkills,
-                    });
-                }
-                catch {
-                    /* ignore */
-                }
-            }
-            // Copy cloned provider.env BEFORE proxy bootstrap
-            if (cloneFrom && envFiles.length) {
-                const srcEnvFiles = getRuntimeEnvFiles(cloneFrom);
-                const srcEnvFile = srcEnvFiles[0];
-                const dstEnvFile = envFiles[0];
-                if (srcEnvFile) {
-                    const srcProvider = join(dirname(srcEnvFile), "provider.env");
-                    const dstProvider = join(dirname(dstEnvFile), "provider.env");
-                    if (existsSync(srcProvider) && !existsSync(dstProvider)) {
-                        copyFileSync(srcProvider, dstProvider);
-                    }
-                }
-            }
-            // Bootstrap proxy: generate proxy token and write model.env
-            try {
-                await bootstrapInstanceProxy(instanceId);
-            }
-            catch (e) {
-                console.warn(`[openclaw] Proxy bootstrap for ${instanceId} deferred: ${e.message}`);
-            }
-            // If running as root, hand ownership of all created files to service user
-            const svcUser = resolveServiceUser();
-            if (svcUser) {
-                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,
-                        });
-                    }
-                }
-                catch (e) {
-                    console.warn(`[openclaw] chown for ${instanceId} failed:`, e.message);
-                }
-            }
-            if (portAlloc.skipped.length > 0) {
-                meta.port_allocation = {
-                    assigned: portAlloc.port,
-                    requested: OPENCLAW_DEFAULT_GATEWAY_PORT,
-                    reason: "default_busy",
-                    skipped: portAlloc.skipped,
-                };
-            }
-            return meta;
-        }
-        finally {
-            if (allocatedPort)
-                releasePendingPort(allocatedPort);
-        }
-    }
-    async createInitialLayout(ctx) {
-        // Framework never calls this on OpenClaw directly — `createInstance()`
-        // above does the full layout. Kept to satisfy the interface for path
-        // preview / UI callers.
-        const instDir = framework_instanceDir(ctx.instanceId);
-        const agentHome = defaultOpenclawHome(ctx.instanceId);
-        return {
-            instanceDir: instDir,
-            agentHome,
-            primaryConfig: join(agentHome, OPENCLAW_STATE_DIRNAME, OPENCLAW_CONFIG_FILENAME),
-        };
-    }
-    async buildRuntime(instanceId) {
-        // OpenClaw persists its runtime in legacy snake_case shape
-        // ({env_files, resources, ...}). Translate at read time into the
-        // engine-neutral RuntimeSpec contract.
-        const im = await lazyIm();
-        const raw = im.getInstanceRuntime(instanceId);
-        const home = im.getOpenclawHome(instanceId);
-        return {
-            image: raw?.image ?? getOpenclawDockerImage(),
-            command: String(raw?.command || DEFAULT_COMMAND),
-            args: Array.isArray(raw?.args) ? raw.args.map(String) : [...DEFAULT_ARGS],
-            cwd: String(raw?.cwd || home || DEFAULT_CWD),
-            user: String(raw?.user || DEFAULT_USER),
-            env: { ...DEFAULT_ENV, ...(raw?.env || {}) },
-            envFiles: Array.isArray(raw?.env_files)
-                ? raw.env_files
-                : Array.isArray(raw?.envFiles)
-                    ? raw.envFiles
-                    : [],
-            resources: {
-                CPU: Number(raw?.resources?.CPU ?? DEFAULT_RESOURCES.CPU),
-                MemoryMB: Number(raw?.resources?.MemoryMB ?? DEFAULT_RESOURCES.MemoryMB),
-                MemoryMaxMB: raw?.resources?.MemoryMaxMB != null ? Number(raw.resources.MemoryMaxMB) : undefined,
-            },
-            ports: [
-                {
-                    name: "gateway",
-                    containerPort: im.getGatewayPort(instanceId),
-                    hostPort: im.getGatewayPort(instanceId),
-                    visibility: "external",
-                },
-            ],
-            volumes: [{ hostPath: home, containerPath: home, mode: "rw" }],
-            health: null,
-        };
-    }
-    async buildNomadTask(instanceId) {
-        // Physically moved from nomad-manager.buildTaskDocker. The adapter owns
-        // OpenClaw's Nomad task layout end-to-end so `nomad-manager.buildJob()`
-        // becomes a pure dispatcher.
-        const im = await lazyIm();
-        const rawRuntime = im.getInstanceRuntime(instanceId);
-        const openclawHome = im.getOpenclawHome(instanceId);
-        if (rawRuntime.user && !VALID_USER_RE.test(rawRuntime.user)) {
-            throw new Error(`Invalid runtime user: ${rawRuntime.user}`);
-        }
-        const image = rawRuntime.image || getOpenclawDockerImage();
-        const _command = String(rawRuntime.command || DEFAULT_COMMAND);
-        const args = Array.isArray(rawRuntime.args)
-            ? rawRuntime.args.map(String)
-            : [...DEFAULT_ARGS];
-        const env = { ...DEFAULT_ENV };
-        Object.assign(env, im.getRuntimeEnv(instanceId));
-        decryptRuntimeProviderEnv(env);
-        injectProviderHostEnv(env, instanceId);
-        delete env.JSPROXY_API_KEY; // supplied via Nomad Template from Variables
-        env.OPENCLAW_HOME = openclawHome;
-        env.OPENCLAW_INSTANCE_ID = instanceId;
-        // Resource clamping
-        const rawResources = { ...DEFAULT_RESOURCES };
-        for (const [k, v] of Object.entries(rawRuntime.resources || {})) {
-            if (v != null)
-                rawResources[k] = Number(v);
-        }
-        rawResources.CPU = Math.max(1, Math.min(rawResources.CPU, MAX_CPU_MHZ));
-        rawResources.MemoryMB = Math.max(1, Math.min(rawResources.MemoryMB, getMaxAppMemoryMB()));
-        // Container env — OpenClaw-specific HOME / NODE_PATH / PATH / npm cfg
-        const containerEnv = { ...env };
-        containerEnv.HOME = openclawHome;
-        if (!containerEnv.OPENCLAW_STATE_DIR) {
-            containerEnv.OPENCLAW_STATE_DIR = `${openclawHome}/.openclaw`;
-        }
-        containerEnv.npm_config_prefix = `${openclawHome}/.npm-global`;
-        containerEnv.PIP_USER = "1";
-        containerEnv.PYTHONUSERBASE = `${openclawHome}/.local`;
-        containerEnv.NODE_ENV = "production";
-        containerEnv.NODE_PATH = [
-            `${openclawHome}/.npm-global/lib/node_modules`,
-            "/app/node_modules",
-        ].join(":");
-        containerEnv.PATH = [
-            `${openclawHome}/.npm-global/bin`,
-            `${openclawHome}/.local/bin`,
-            `${openclawHome}/go/bin`,
-            `${openclawHome}/.cargo/bin`,
-            "/usr/local/sbin",
-            "/usr/local/bin",
-            "/usr/sbin",
-            "/usr/bin",
-            "/sbin",
-            "/bin",
-        ].join(":");
-        const gatewayPort = im.getGatewayPort(instanceId);
-        const safeJobId = resolveNomadJobId(instanceId, this.nomadJobPrefix);
-        assertSafeTemplateId(safeJobId);
-        // Signal to OpenClaw that Nomad manages process lifecycle (restart on exit).
-        // Without this, OpenClaw >= 2026.5.20 refuses self-updates because
-        // detectRespawnSupervisor() finds no systemd/launchd markers.
-        containerEnv.OPENCLAW_SYSTEMD_UNIT = `nomad-${safeJobId}.service`;
-        const normalizedResources = normalizeDockerResources(instanceId, rawResources);
-        // Same rationale as hermes.ts:nomadHasExternalHostNetwork — without
-        // HostNetwork, Nomad's docker driver publishes the gateway port to
-        // 127.0.0.1, breaking cross-container consumers (e.g. OpenWebUI
-        // binding openclaw via the llm-agent capability). Bring the legacy
-        // openclaw job in line with the unified app-spec path.
-        const hostNetwork = nomadHasExternalHostNetwork() ? "external" : undefined;
-        return {
-            Name: "gateway",
-            Driver: "docker",
-            User: resolveUidGid(String(rawRuntime.user || DEFAULT_USER)),
-            Config: {
-                image,
-                force_pull: false,
-                // Match nomad-manager.ts:buildAppTask — default 5-minute pull
-                // timeout is too short for Pi-class networks pulling a 1+ GiB
-                // openclaw runtime image; bump to 15 minutes.
-                image_pull_timeout: "15m",
-                // Inline the temporary session-fence patch launcher so Nomad does not
-                // depend on a host-side executable wrapper. Once OpenClaw no longer
-                // needs this workaround, this custom entrypoint can be removed.
-                entrypoint: ["/bin/sh", "-c", CONTAINER_PATCH_ENTRYPOINT_COMMAND, "--"],
-                args,
-                work_dir: openclawHome,
-                volumes: buildVolumes(openclawHome, im.getInstanceRuntime(instanceId)),
-                // Tell the docker driver to publish the labeled "gateway" port so
-                // it routes via the host_network IP rather than the 127.0.0.1
-                // default.
-                ports: ["gateway"],
-                extra_hosts: ["host.docker.internal:host-gateway"],
-                cap_drop: ["ALL"],
-                security_opt: ["no-new-privileges"],
-                pids_limit: DEFAULT_PIDS_LIMIT,
-                readonly_rootfs: true,
-                mounts: [
-                    { type: "tmpfs", target: "/tmp", tmpfs_options: { size: 536870912 } },
-                    { type: "tmpfs", target: "/var/tmp", tmpfs_options: { size: 67108864 } },
-                    { type: "tmpfs", target: "/run", tmpfs_options: { size: 52428800 } },
-                ],
-            },
-            Env: containerEnv,
-            Resources: {
-                ...normalizedResources,
-                Networks: [
-                    {
-                        ReservedPorts: [
-                            {
-                                Label: "gateway",
-                                Value: gatewayPort,
-                                To: gatewayPort,
-                                ...(hostNetwork ? { HostNetwork: hostNetwork } : {}),
-                            },
-                        ],
-                    },
-                ],
-            },
-            LogConfig: { MaxFiles: 3, MaxFileSizeMB: 10 },
-            Templates: [
-                {
-                    DestPath: "secrets/instance.env",
-                    Envvars: true,
-                    EmbeddedTmpl: [
-                        `{{ if nomadVarExists "nomad/jobs/${safeJobId}/openclaw/gateway" }}`,
-                        `JSPROXY_API_KEY={{ with nomadVar "nomad/jobs/${safeJobId}/openclaw/gateway" }}{{ .JSPROXY_API_KEY }}{{ end }}`,
-                        `{{ end }}`,
-                    ].join("\n"),
-                    ChangeMode: "restart",
-                },
-            ],
-        };
-    }
-    async getRuntimeVersion(_instanceId) {
-        // Parse the image reference (digest > tag) for the baseline image.
-        const image = getOpenclawDockerImage() || "";
-        let ref;
-        let digest;
-        if (image) {
-            if (image.includes("@")) {
-                digest = image.split("@", 2)[1];
-            }
-            else {
-                const lastColon = image.lastIndexOf(":");
-                const lastSlash = image.lastIndexOf("/");
-                if (lastColon > lastSlash)
-                    ref = image.slice(lastColon + 1);
-            }
-        }
-        return { agentType: "openclaw", ref, digest, mode: "baseline" };
-    }
-    async getConfigMeta(instanceId) {
-        return {
-            agentType: "openclaw",
-            format: "json",
-            schemaId: "openclaw/v1",
-            capabilities: DEFAULT_CAPABILITIES,
-            secretFields: ["content.x-jishushell.proxy.upstream.apiKey"],
-            runtimeVersion: await this.getRuntimeVersion(instanceId),
-        };
-    }
-    async readConfig(instanceId) {
-        const im = await lazyIm();
-        const content = im.getStoredConfig
-            ? im.getStoredConfig(instanceId)
-            : null;
-        return {
-            format: "json",
-            content: (content && typeof content === "object") ? content : {},
-        };
-    }
-    async writeConfig(instanceId, doc) {
-        if (doc.format !== "json") {
-            throw new Error(`OpenClaw config requires format="json", got "${doc.format}"`);
-        }
-        // Route through llmProxy.saveInstanceConfig so x-jishushell.proxy
-        // metadata is stripped, the upstream apiKey is AES-encrypted to
-        // provider.env, and models.providers is rewritten to the local
-        // proxy — same contract HermesAdapter.writeConfig uses. That
-        // function internally calls instanceManager.saveConfig, which
-        // dispatches back to this adapter's saveNativeConfig() for the
-        // raw disk write (distinct method, no recursion).
-        const { saveInstanceConfig } = await import("../../llm-proxy/instance-proxy.js");
-        await saveInstanceConfig(instanceId, doc.content);
-        return this.readConfig(instanceId);
-    }
-    async buildPairingListCommand(_instanceId) {
-        return ["openclaw", "pairing", "list"];
-    }
-    async buildPairingApproveCommand(_instanceId, input) {
-        return ["openclaw", "pairing", "approve", input.channel, input.code];
-    }
-    /**
-     * Framework delete hook — returns warnings for the caller to surface to
-     * the user. OpenClaw supports a custom `openclaw_home` pointing outside
-     * the instance directory; those directories are preserved on delete.
-     */
-    async onDelete(args) {
-        const warnings = [];
-        const home = args.meta?.openclaw_home;
-        if (home) {
-            warnings.push(`Custom openclaw_home "${home}" was NOT removed; delete it manually if unused.`);
-        }
-        return warnings;
-    }
-    // ── Native config I/O (physically migrated from instance-manager) ───
-    channelPluginMap = CHANNEL_PLUGIN_MAP;
-    /**
-     * Get the stored raw OpenClaw config (from `.openclaw/openclaw.json`
-     * or the legacy `openclaw.json`), merged with the x-jishushell
-     * metadata pulled from `instance.json`. Returns null when the instance
-     * has no persisted config yet.
-     */
-    getNativeConfig(instanceId) {
-        const config = loadEffectiveConfig(instanceId);
-        if (!config)
-            return null;
-        // Always merge the latest upstream proxy config from instance.json
-        const meta = getInstance(instanceId);
-        if (meta?.["x-jishushell"]) {
-            config["x-jishushell"] = meta["x-jishushell"];
-        }
-        // Inject upstream provider apiKey from env file so callers see it
-        return injectProviderApiKeys(instanceId, config);
-    }
-    /**
-     * Get the stored raw config WITHOUT provider key injection. Used by
-     * callers that round-trip the config back to disk (e.g. credential
-     * writers) — injecting the provider key would re-persist it to the
-     * config file, which is exactly what `saveConfig` takes pains to avoid.
-     */
-    getStoredNativeConfig(instanceId) {
-        const config = loadEffectiveConfig(instanceId);
-        if (!config)
-            return null;
-        const meta = getInstance(instanceId);
-        if (meta?.["x-jishushell"]) {
-            config["x-jishushell"] = meta["x-jishushell"];
-        }
-        return config;
-    }
-    isChannelPluginInstalled(instanceId, channelId) {
-        return isChannelPluginInstalled(instanceId, channelId);
-    }
-    async installChannelPlugin(instanceId, channelId) {
-        return installChannelPlugin(instanceId, channelId);
-    }
-    saveNativeConfig(instanceId, config) {
-        return saveNativeConfigImpl(instanceId, config);
-    }
-    /**
-     * Connection-apply hook (§7 of app-interconnect-design): translate
-     * resolved `inject_as` env vars into OpenClaw-native plugin config and
-     * persist them into `openclaw.json`. Without this, the runtime env
-     * injected by `nomad-manager.injectConnectionsRuntimeEnv` (PR 8) sits
-     * in the container unused — the OpenClaw agent reads tool config from
-     * `openclaw.json`, not from environment variables.
-     *
-     * Currently wired:
-     *   SEARCH_API_BASE_URL → plugins.entries.searxng.config.webSearch.baseUrl
-     *   SEARCH_API_BASE_URL → tools.web.search.provider = "searxng"
-     *
-     * The provider selector at `tools.web.search.provider` is required: without
-     * it the `web_search` tool defaults to Brave and fails with
-     * `missing_brave_api_key` even when the searxng plugin is fully configured.
-     *
-     * Browser / LLM / MCP wiring lands in PR 9b — they need their own
-     * config-shape mapping (browser → tools.browser, llm → models.providers,
-     * mcp already wired via openclaw-mcporter).
-     *
-     * The write goes through `saveNativeConfig` which deep-merges with the
-     * existing on-disk config, so user-managed plugin entries (e.g.
-     * openclaw-lark) are preserved. Plugin auto-enable then promotes the
-     * searxng entry into `plugins.allow` automatically on next start
-     * because we set `enabled:true` and provide config (the openclaw
-     * runtime treats the presence of `config.webSearch.baseUrl` as a
-     * "configured" signal — see `plugin-auto-enable` in the openclaw
-     * dist bundle).
-     */
-    async applyConnectionEnv(instanceId, env) {
-        const configPath = openclawConfigPath(instanceId);
-        const searchUrl = env.SEARCH_API_BASE_URL;
-        if (typeof searchUrl === "string") {
-            if (searchUrl === "") {
-                // Empty value — connection-transactor's UNPERSIST_HOOKS uses this as
-                // the "unbind" signal. Clear the searxng plugin config so the next
-                // start doesn't keep routing web_search through a now-disconnected
-                // provider.
-                try {
-                    clearSearxngConnectionFromConfig(configPath);
-                }
-                catch (e) {
-                    console.warn(`[openclaw] applyConnectionEnv search unbind failed for ${instanceId}: ${e.message}`);
-                }
-            }
-            else {
-                // SEARCH_API_BASE_URL points at "<base>/search" (the SearXNG search
-                // endpoint). The plugin's webSearch.baseUrl wants the bare origin —
-                // strip the trailing "/search" path segment if present.
-                // baseUrl stays at the registry-resolved host:port snapshot from
-                // when the user PUT /connections; the framework re-runs this hook
-                // on every instance start (PR 9 phaseRefreshConnections), so host
-                // IP changes propagate automatically on next agent restart.
-                let baseUrl = searchUrl;
-                try {
-                    const u = new URL(searchUrl);
-                    if (u.pathname === "/search" || u.pathname === "/search/") {
-                        u.pathname = "";
-                        baseUrl = u.toString().replace(/\/$/, "");
-                    }
-                    try {
-                        applySearxngConnectionToConfig(configPath, baseUrl);
-                    }
-                    catch (e) {
-                        console.warn(`[openclaw] applyConnectionEnv search merge failed for ${instanceId}: ${e.message}`);
-                    }
-                }
-                catch {
-                    // not a URL — skip silently; the openclaw plugin would break
-                    // with a non-URL baseUrl, and start should still proceed.
-                }
-            }
-        }
-        const cdpUrl = env.BROWSER_CDP_URL;
-        if (typeof cdpUrl === "string") {
-            if (cdpUrl === "") {
-                try {
-                    clearBrowserlessConnectionFromConfig(configPath);
-                }
-                catch (e) {
-                    console.warn(`[openclaw] applyConnectionEnv browser unbind failed for ${instanceId}: ${e.message}`);
-                }
-            }
-            else if (/^wss?:\/\//.test(cdpUrl)) {
-                try {
-                    applyBrowserlessConnectionToConfig(configPath, cdpUrl);
-                }
-                catch (e) {
-                    console.warn(`[openclaw] applyConnectionEnv browser merge failed for ${instanceId}: ${e.message}`);
-                }
-            }
-            // Non-ws scheme: skip silently. The connection-apply browser hook
-            // already builds ws:// from the capability protocol; an http:// here
-            // would mean a misconfigured provider — better to no-op than to
-            // write a URL OpenClaw can't dial.
-        }
-    }
-    // ── Path resolvers (physically migrated) ───────────────────────────
-    resolveBin() {
-        return resolveOpenclawBin();
-    }
-    resolveAgentHome(instanceId) {
-        const meta = getInstance(instanceId);
-        return meta?.openclaw_home || defaultOpenclawHome(instanceId);
-    }
-    /** Env vars OpenClaw's CLI needs when backup-manager runs it as a subprocess. */
-    buildCliEnv(instanceId) {
-        return { OPENCLAW_HOME: this.resolveAgentHome(instanceId) };
-    }
-    /**
-     * Legacy gateway-port fallback for instances created before the
-     * RuntimeSpec.ports[] migration. OpenClaw persists its port in both
-     * `runtime.env.OPENCLAW_GATEWAY_PORT` and `runtime.args ["--port", N]`.
-     */
-    readLegacyGatewayPort(runtime) {
-        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;
-            }
-            if (arg.startsWith("--port=")) {
-                const p = parseInt(arg.split("=")[1], 10);
-                return isNaN(p) ? null : p;
-            }
-        }
-        return null;
-    }
-    /**
-     * Rewrite a persisted OpenClaw runtime spec to use a new host port.
-     * Updates `args[--port]` + `env.OPENCLAW_GATEWAY_PORT` atomically so
-     * both places stay in sync.
-     */
-    reallocateRuntimePort(runtime, newPort) {
-        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(newPort);
-            }
-            else if (typeof args[i] === "string" && args[i].startsWith("--port=")) {
-                args[i] = `--port=${newPort}`;
-            }
-        }
-        runtime.args = args;
-        const env = (runtime.env ?? {});
-        env.OPENCLAW_GATEWAY_PORT = String(newPort);
-        runtime.env = env;
-    }
-    nomadJobPrefix = "openclaw-";
-    // OpenClaw is the default/core runtime — runFullSetup must fail hard if
-    // its image install fails, because the panel is unusable without it.
-    // Third-party adapters should leave `required` unset (= optional).
-    required = true;
-    // Must match the path referenced by this adapter's buildNomadTask Templates
-    // (see `nomadVar "nomad/jobs/<jid>/openclaw/gateway"` in the template body).
-    nomadVariablePath = "openclaw/gateway";
-    resolveConfigPath(instanceId) {
-        return openclawConfigPath(instanceId, this.resolveAgentHome(instanceId));
-    }
-    resolveLegacyConfigPath(instanceId) {
-        return legacyOpenclawConfigPath(instanceId, this.resolveAgentHome(instanceId));
-    }
-    /**
-     * Return other OpenClaw instance IDs that share this one's
-     * `openclaw_home` path. Used by the start-time conflict check.
-     */
-    findInstancesSharingHome(instanceId) {
-        const target = normalizePath(this.resolveAgentHome(instanceId));
-        return listInstances()
-            .filter((inst) => inst.id !== instanceId)
-            .filter((inst) => {
-            const meta = inst;
-            const otherHome = meta.openclaw_home || defaultOpenclawHome(inst.id);
-            return normalizePath(otherHome) === target;
-        })
-            .map((inst) => inst.id);
-    }
-    // ── Feishu / WeChat credential writers (physically migrated) ───────
-    saveFeishuCredentials(instanceId, creds) {
-        if (!FEISHU_APP_ID_RE.test(creds.appId)) {
-            throw new Error(`Invalid Feishu appId format: expected cli_<alnum> (got "${creds.appId}")`);
-        }
-        if (!creds.appSecret || typeof creds.appSecret !== "string" || creds.appSecret.length < 4) {
-            throw new Error("Invalid Feishu appSecret: must be a non-empty string");
-        }
-        const configPath = this.resolveConfigPath(instanceId);
-        let config = {};
-        try {
-            if (existsSync(configPath)) {
-                config = JSON.parse(readFileSync(configPath, "utf-8"));
-            }
-        }
-        catch {
-            /* best effort */
-        }
-        config.plugins ??= {};
-        config.plugins.entries ??= {};
-        config.plugins.entries.feishu = { enabled: false };
-        config.plugins.entries["openclaw-lark"] = { enabled: true };
-        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(`[openclaw] Feishu credentials saved for ${instanceId}, domain=${creds.domain}`);
-    }
-    saveWeixinCredentials(instanceId, creds) {
-        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 = this.resolveAgentHome(instanceId);
-        const stateDir = join(home, OPENCLAW_STATE_DIRNAME, "openclaw-weixin");
-        const accountsDir = join(stateDir, "accounts");
-        ensureDirContainer(accountsDir);
-        const credObj = {
-            token: creds.token,
-            baseUrl: creds.baseUrl,
-            userId: creds.userId,
-            savedAt: new Date().toISOString(),
-        };
-        safeWriteJson(join(accountsDir, `${creds.accountId}.json`), credObj);
-        safeWriteJson(join(accountsDir, "default.json"), credObj);
-        chownToServiceUser(join(accountsDir, `${creds.accountId}.json`), join(accountsDir, "default.json"));
-        // Update accounts.json index
-        const indexPath = join(stateDir, "accounts.json");
-        let index = [];
-        try {
-            const raw = readFileSync(indexPath, "utf-8");
-            index = JSON.parse(raw);
-        }
-        catch {
-            /* start fresh */
-        }
-        if (!Array.isArray(index))
-            index = [];
-        if (!index.includes(creds.accountId))
-            index.push(creds.accountId);
-        safeWriteJson(indexPath, index);
-        const configPath = this.resolveConfigPath(instanceId);
-        let config = {};
-        try {
-            if (existsSync(configPath))
-                config = JSON.parse(readFileSync(configPath, "utf-8"));
-        }
-        catch {
-            /* best effort */
-        }
-        config.plugins ??= {};
-        config.plugins.entries ??= {};
-        config.plugins.entries["openclaw-weixin"] ??= {};
-        config.plugins.entries["openclaw-weixin"].enabled = true;
-        config.channels ??= {};
-        config.channels["openclaw-weixin"] ??= {};
-        config.channels["openclaw-weixin"].enabled = true;
-        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 };
-        if (!config.channels["openclaw-weixin"].defaultAccount) {
-            config.channels["openclaw-weixin"].defaultAccount = "default";
-        }
-        safeWriteJson(configPath, config);
-        chownToServiceUser(configPath);
-        console.log(`[openclaw] WeChat credentials saved for ${instanceId}, account=${creds.accountId}`);
-    }
-    getWeixinAccounts(instanceId) {
-        const home = this.resolveAgentHome(instanceId);
-        const stateDir = join(home, OPENCLAW_STATE_DIRNAME, "openclaw-weixin");
-        const accountsDir = join(stateDir, "accounts");
-        if (!existsSync(accountsDir))
-            return [];
-        let indexedIds = [];
-        try {
-            indexedIds = JSON.parse(readFileSync(join(stateDir, "accounts.json"), "utf-8"));
-        }
-        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;
-            if (id === "default")
-                continue;
-            try {
-                const data = JSON.parse(readFileSync(join(accountsDir, f), "utf-8"));
-                results.push({
-                    accountId: id,
-                    userId: data.userId,
-                    savedAt: data.savedAt,
-                });
-            }
-            catch {
-                /* skip */
-            }
-        }
-        return results;
-    }
-    // ── §32.2.4 runtime install (physically migrated from setup-manager) ──
-    //
-    // Installs the OpenClaw npm package via `npm install -g --prefix` so that
-    // postinstall scripts run naturally. Emits SSE progress through the task
-    // machinery exported by setup-manager.
-    async installRuntime(opts) {
-        const version = opts?.version ?? "latest";
-        try {
-            const openclawPkgDir = join(OPENCLAW_MODULES, "openclaw");
-            if (existsSync(openclawPkgDir)) {
-                const ver = readInstalledOpenclawVersion() || "unknown";
-                return { ok: true, message: `OpenClaw already installed: ${ver}` };
-            }
-            const task = createTask("openclaw");
-            ensureDirHost(OPENCLAW_PKG_DIR);
-            emitTask(task, { type: "progress", message: "开始安装 OpenClaw...", progress: 0 });
-            const sizeTracker = setInterval(() => {
-                const sizeMB = getDirSizeMB(OPENCLAW_PKG_DIR);
-                const pct = Math.min(95, Math.round((sizeMB / OPENCLAW_EXPECTED_SIZE_MB) * 95));
-                if (pct > 0) {
-                    emitTask(task, {
-                        type: "progress",
-                        message: `下载安装中... ${sizeMB}MB / ~${OPENCLAW_EXPECTED_SIZE_MB}MB`,
-                        progress: pct,
-                    });
-                }
-            }, 3000);
-            const result = await spawnWithTask(task, "npm", ["install", "-g", "--prefix", OPENCLAW_PKG_DIR, `openclaw@${version}`], { timeout: 600000, progressParser: npmProgressParser });
-            clearInterval(sizeTracker);
-            if (!result.ok) {
-                emitTask(task, { type: "error", message: "OpenClaw 安装失败" });
-                task.status = "error";
-                return {
-                    ok: false,
-                    message: "OpenClaw installation failed",
-                    error: result.output,
-                    taskId: task.id,
-                };
-            }
-            const ver = readInstalledOpenclawVersion() || "installed";
-            emitTask(task, { type: "done", message: `OpenClaw 安装完成: ${ver}`, progress: 100 });
-            task.status = "done";
-            return { ok: true, message: `OpenClaw installed: ${ver}`, taskId: task.id };
-        }
-        catch (e) {
-            return { ok: false, message: "OpenClaw installation failed", error: e.message };
-        }
-    }
-    /**
-     * Build / pull the OpenClaw Docker image. Blocking — useful for CLI
-     * installer and `runFullSetup()`. Non-blocking variant below is used by
-     * the REST API and the adapter's own `onBeforeStart` self-heal path.
-     */
-    async buildRuntimeImage(opts) {
-        const task = createTask("openclaw-docker-pull");
-        return pullOrBuildOpenclawImageWithTask(task, opts?.tag);
-    }
-    /**
-     * Non-blocking variant of `buildRuntimeImage` — returns a task id
-     * immediately so the caller can poll SSE progress.
-     */
-    startBuildRuntimeImage(opts) {
-        const task = createTask("openclaw-docker-pull");
-        void pullOrBuildOpenclawImageWithTask(task, opts?.tag).catch((err) => {
-            emitTask(task, {
-                type: "error",
-                message: `镜像获取失败: ${err?.message || err}`,
-            });
-            task.status = "error";
-        });
-        return { ok: true, message: "Docker image pull started", taskId: task.id };
-    }
-    /**
-     * Return OpenClaw's readiness for spawning instances. Docker image
-     * presence is the gating factor in the default docker-mode deployment;
-     * the legacy `npm install` path is still reported as `installed` but is
-     * not required for the docker-driver stack.
-     */
-    getInstallStatus() {
-        // OPENCLAW_MODULES may be undefined when config is partially mocked in tests.
-        const pkgInstalled = OPENCLAW_MODULES ? existsSync(join(OPENCLAW_MODULES, "openclaw")) : false;
-        const version = pkgInstalled ? readInstalledOpenclawVersion() : undefined;
-        const imageTag = getOpenclawDockerImage?.() ?? "";
-        let imageReady = false;
-        try {
-            const invocation = resolveDockerInvocation();
-            if (invocation?.cmd) {
-                execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "inspect", imageTag], {
-                    timeout: 5000,
-                    stdio: "ignore",
-                });
-                imageReady = true;
-            }
-        }
-        catch { /* image absent */ }
-        return {
-            installed: imageReady || pkgInstalled,
-            imageReady,
-            version: version || undefined,
-        };
-    }
-}
-// ── Install-time helpers (used by installRuntime) ─────────────────────
-const OPENCLAW_EXPECTED_SIZE_MB = 700;
-function readInstalledOpenclawVersion() {
-    try {
-        const pkg = join(OPENCLAW_MODULES, "openclaw", "package.json");
-        if (existsSync(pkg))
-            return JSON.parse(readFileSync(pkg, "utf-8")).version || "";
-    }
-    catch {
-        /* best effort */
-    }
-    return "";
-}
-// Feishu app IDs issued by the open platform follow `cli_<hex/alnum>`.
-const FEISHU_APP_ID_RE = /^cli_[a-zA-Z0-9]{8,64}$/;
-const SAFE_ACCOUNT_ID_RE = /^[a-zA-Z0-9@._-]{1,128}$/;
-// ── Channel plugin constants (physically migrated) ───────────────────
-const CHANNEL_EXT_DIR_ALIAS = {
-    feishu: "openclaw-lark",
-    lark: "openclaw-lark",
-};
-const CHANNEL_PLUGIN_MAP = {
-    feishu: "@larksuite/openclaw-lark",
-    lark: "@larksuite/openclaw-lark",
-    telegram: "@openclaw/telegram",
-    discord: "@openclaw/discord",
-    slack: "@openclaw/slack",
-    whatsapp: "@openclaw/whatsapp",
-    signal: "@openclaw/signal",
-    line: "@openclaw/line",
-    msteams: "@openclaw/msteams",
-    "openclaw-weixin": "@tencent-weixin/openclaw-weixin",
-};
-const IM_PLUGIN_ENTRY_IDS = new Set([
-    ...Object.keys(CHANNEL_PLUGIN_MAP),
-    ...Object.values(CHANNEL_EXT_DIR_ALIAS),
-]);
-// ── Config I/O helpers (physically migrated) ─────────────────────────
-function hasConfiguredValue(value) {
-    if (typeof value !== "string")
-        return !!value;
-    return value.trim().length > 0;
-}
-function loadJsonSafe(path) {
-    try {
-        return JSON.parse(readFileSync(path, "utf-8"));
-    }
-    catch (e) {
-        console.warn(`[openclaw] Failed to parse ${path}: ${e.message}`);
-        return null;
-    }
-}
-function deepMergeConfig(base, overlay) {
-    if (typeof base !== "object" || base === null ||
-        typeof overlay !== "object" || overlay === null ||
-        Array.isArray(base) || Array.isArray(overlay)) {
-        return structuredClone(overlay);
-    }
-    const merged = structuredClone(base);
-    for (const key of Object.keys(overlay)) {
-        merged[key] = key in merged ? deepMergeConfig(merged[key], overlay[key]) : structuredClone(overlay[key]);
-    }
-    return merged;
-}
-function loadEffectiveConfig(instanceId) {
-    const runtimePath = openclawConfigPath(instanceId);
-    const legacyPath = legacyOpenclawConfigPath(instanceId);
-    const rExists = existsSync(runtimePath);
-    const lExists = existsSync(legacyPath);
-    if (rExists && lExists) {
-        const legacy = loadJsonSafe(legacyPath);
-        const runtime = loadJsonSafe(runtimePath);
-        if (legacy && runtime)
-            return deepMergeConfig(legacy, runtime);
-        return runtime || legacy || null;
-    }
-    if (rExists)
-        return loadJsonSafe(runtimePath);
-    if (lExists)
-        return loadJsonSafe(legacyPath);
-    return 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;
-        p.api = normalizeProviderApi(typeof p.api === "string" ? p.api : undefined);
-        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);
-    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;
-        p.api = normalizeProviderApi(typeof p.api === "string" ? p.api : undefined);
-        // Ensure allowPrivateNetwork for providers targeting the local proxy
-        if (typeof p.baseUrl === "string" && isPrivateNetworkBaseUrl(p.baseUrl)) {
-            p.request = { ...(p.request || {}), allowPrivateNetwork: true };
-        }
-        if (!("apiKey" in p))
-            continue;
-        if (typeof p.baseUrl === "string" && p.baseUrl.includes("/proxy/"))
-            continue;
-        const apiKey = p.apiKey;
-        delete p.apiKey;
-        if (envFiles.length) {
-            envUpdates[inferProviderApiKeyEnvName(providerId)] = decryptRuntimeProviderApiKey(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];
-}
-function decryptRuntimeProviderApiKey(apiKey) {
-    const value = String(apiKey || "");
-    return value.startsWith("enc:") ? decryptApiKey(value) : value;
-}
-function decryptRuntimeProviderEnv(env) {
-    for (const [key, value] of Object.entries(env)) {
-        if (!key.endsWith("_API_KEY"))
-            continue;
-        if (!String(value || "").startsWith("enc:"))
-            continue;
-        env[key] = decryptApiKey(value);
-    }
-}
-/**
- * Auto-injects provider-specific host env vars that OpenClaw tools need
- * at runtime, if the user hasn't already set them explicitly.
- *
- * Currently handles:
- * - MINIMAX_API_HOST: Derived from MINIMAX_BASE_URL or upstream proxy config
- *   to ensure the VLM tool calls the correct MiniMax API domain.
- *
- * Note: Only MiniMax needs this because its VLM tool reads MINIMAX_API_HOST
- * to determine the endpoint. DeepSeek does not have a dedicated VLM tool
- * in OpenClaw that requires a similar host env var.
- */
-function injectProviderHostEnv(env, instanceId) {
-    // MINIMAX_API_HOST — needed by OpenClaw's VLM tool to call the correct domain
-    if (!env.MINIMAX_API_HOST) {
-        const baseUrl = env.MINIMAX_BASE_URL || "";
-        if (baseUrl) {
-            try {
-                const parsed = new URL(baseUrl);
-                env.MINIMAX_API_HOST = `${parsed.protocol}//${parsed.host}`;
-            }
-            catch { /* invalid URL, skip */ }
-        }
-        else {
-            // Infer from upstream proxy config if available
-            const config = getProxyInstanceConfig(instanceId);
-            const upstream = config?.["x-jishushell"]?.proxy?.upstream;
-            if (upstream?.providerId === "minimax" && upstream.baseUrl) {
-                try {
-                    const parsed = new URL(upstream.baseUrl);
-                    env.MINIMAX_API_HOST = `${parsed.protocol}//${parsed.host}`;
-                }
-                catch { /* invalid URL, skip */ }
-            }
-        }
-    }
-}
-/**
- * Dissociate a cloned/imported config from its source instance's IM bindings.
- * Physically migrated from `instance-manager.stripImBindings` so framework
- * code no longer references OpenClaw channel concepts.
- *
- * Exported so `OpenClawAdapter.createInstance`'s clone path + `backup-manager`
- * import paths can use it without depending on instance-manager.
- */
-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];
-        }
-    }
-}
-function getChannelExtensionsDir(instanceId) {
-    const home = getInstance(instanceId)?.openclaw_home ||
-        defaultOpenclawHome(instanceId);
-    return join(home, OPENCLAW_STATE_DIRNAME, "extensions");
-}
-function getStockExtensionsDir() {
-    return join(JISHUSHELL_HOME, "packages", "openclaw", "lib", "node_modules", "openclaw", "extensions");
-}
-function isChannelPluginInstalled(instanceId, channelId) {
-    const extDirName = CHANNEL_EXT_DIR_ALIAS[channelId] || channelId;
-    const stockExtDir = getStockExtensionsDir();
-    if (existsSync(join(getChannelExtensionsDir(instanceId), extDirName)))
-        return true;
-    if (existsSync(join(stockExtDir, extDirName)))
-        return true;
-    if (extDirName !== channelId && existsSync(join(stockExtDir, channelId)))
-        return true;
-    // OpenClaw's npm-backed plugin store lives at
-    // `<home>/.openclaw/npm/node_modules/<pkg>`. The CLI refuses to reinstall
-    // when that path is present ("plugin already exists ... delete it first"),
-    // even if the per-instance extensions/<name> dir is missing (e.g. the
-    // first install was interrupted, or the dir was manually cleaned). Treat
-    // the npm path as authoritative so re-saves stay idempotent.
-    const pkg = CHANNEL_PLUGIN_MAP[channelId];
-    if (pkg) {
-        const home = getInstance(instanceId)?.openclaw_home ||
-            defaultOpenclawHome(instanceId);
-        const npmPath = join(home, OPENCLAW_STATE_DIRNAME, "npm", "node_modules", ...pkg.split("/"));
-        if (existsSync(npmPath))
-            return true;
-    }
-    return false;
-}
-/**
- * Install a single channel plugin. Docker mode → `docker exec` inside the
- * running container. Host mode → spawn the host openclaw binary directly.
- * Physically migrated from `instance-manager.installChannelPlugin`.
- */
-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 home = getInstance(instanceId)?.openclaw_home ||
-        defaultOpenclawHome(instanceId);
-    const extensionsDir = getChannelExtensionsDir(instanceId);
-    if (getNomadDriver() === "docker") {
-        await installChannelPluginViaDocker(instanceId, channelId, pkg, extensionsDir);
-        return;
-    }
-    const openclawBin = resolveOpenclawBin();
-    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: home,
-        ...proxyEnv,
-    };
-    const MAX_ATTEMPTS = 3;
-    const RETRY_DELAY_MS = 5_000;
-    const attemptInstall = () => new Promise((resolve, reject) => {
-        execFile(openclawBin, ["plugins", "install", pkg], { cwd: home, 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 {
-                    /* ignore */
-                }
-                reject(new Error(msg));
-            }
-            else {
-                if (err)
-                    console.log(`[plugins] ${pkg} installed (ignored non-zero exit)`);
-                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, 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;
-}
-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);
-            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)`);
-            }
-            else {
-                console.log(`[plugins] ${pkg} installed via docker`);
-            }
-            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;
-            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...`);
-                await new Promise((r) => setTimeout(r, RETRY_DELAY_MS));
-                continue;
-            }
-            console.error(`[plugins] Failed to install ${pkg} via docker:`, err.message);
-            break;
-        }
-    }
-    throw lastErr;
-}
-/**
- * Full saveConfig implementation. Writes `.openclaw/openclaw.json`,
- * mirrors into legacy `openclaw.json` path, updates env files with
- * provider API keys, preserves backend-managed fields, and fires
- * config-change listeners.
- *
- * Physically migrated from `instance-manager.saveConfig`.
- */
-function saveNativeConfigImpl(instanceId, config) {
-    const configPath = openclawConfigPath(instanceId);
-    if (!existsSync(framework_instanceDir(instanceId)))
-        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);
-        }
-    }
-    const [configToWrite, envUpdates] = prepareConfigForSave(instanceId, config);
-    // If openclaw-lark is enabled, resolve which feishu plugin to use
-    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)) {
-            configToWrite.plugins.entries.feishu = { enabled: true };
-            delete configToWrite.plugins.entries["openclaw-lark"];
-        }
-        else if (existsSync(stockFeishu)) {
-            configToWrite.plugins ??= {};
-            configToWrite.plugins.entries ??= {};
-            configToWrite.plugins.entries.feishu = { enabled: false };
-        }
-    }
-    // Preserve backend-managed fields
-    if (existsSync(configPath)) {
-        try {
-            const existing = JSON.parse(readFileSync(configPath, "utf-8"));
-            if (existing.plugins?.installs) {
-                configToWrite.plugins ??= {};
-                configToWrite.plugins.installs = { ...existing.plugins.installs, ...configToWrite.plugins?.installs };
-            }
-            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 };
-                    }
-                }
-            }
-            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 */
-        }
-    }
-    // Backup + atomic write
-    if (existsSync(configPath)) {
-        copyFileSync(configPath, configPath + ".bak");
-    }
-    const configJson = JSON.stringify(configToWrite, null, 2);
-    ensureDirContainer(dirname(configPath));
-    writeConfigFile(configPath + ".tmp", configJson);
-    JSON.parse(readFileSync(configPath + ".tmp", "utf-8"));
-    renameSync(configPath + ".tmp", configPath);
-    chownToServiceUser(configPath);
-    // Mirror into 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);
-    }
-    // Notify listeners (LLM proxy cache invalidation etc.)
-    notifyConfigChange(instanceId);
-    return true;
-}
-export const openclawAdapter = new OpenClawAdapter();
-registerAdapter(openclawAdapter);
-//# sourceMappingURL=openclaw.js.map