jishushell 0.6.5 → 0.7.3

package/dist/services/integrations/openclaw/integration.js

@@ -0,0 +1,4629 @@
+/**
+ * OpenClawIntegration — the framework face of OpenClaw business logic.
+ *
+ * Legacy AppIntegration implementation retained during migration toward the
+ * model described in docs/core-app-architecture.md. The
+ * short-term goal remains: OpenClaw-specific knowledge should leave generic
+ * framework code and live behind this integration boundary.
+ *
+ * Why not a huge rewrite in a single pass?
+ *   A full physical migration of ~6500 lines of OpenClaw code out of
+ *   `instance-manager.ts` / the Nomad driver / `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 `getIntegration(integrationKind).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 integration 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-integration-isolation.ts`
+ *        script blocks new integration-specific code from sneaking back into the
+ *        framework layer.
+ *
+ * This is legacy AppIntegration compatibility. New app lifecycle work should
+ * follow docs/core-app-architecture.md instead of extending this as the
+ * primary app model:
+ *
+ *     1. Create `src/services/integrations/foo/integration.ts` mirroring this file.
+ *     2. Add a side-effect registration import to `src/services/integrations/index.ts`.
+ *     3. Add one line to `frontend/src/runtimes/registry.ts`.
+ *     4. Done. No `instance-manager.ts` / runtime driver / 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, getInternalMcpToken, } from "../../../config.js";
+import { ensureDirContainer, ensureDirHost, writeConfigFile } from "../../../utils/fs.js";
+import { safeWriteJson } from "../../../utils/safe-json.js";
+import { chownToServiceUser, getInstance, getRuntimeEnvFiles, listInstances, normalizePath, notifyConfigChange, resolveServiceUser, updateInstanceMeta, updateEnvFile, } from "../../instances/manager.js";
+import { applyTemporaryBrowserAllowlistToConfigObject, browserlessEndpointAllowedHostname, DEFAULT_BROWSER_ALLOWED_HOSTNAMES, mergeBrowserAllowedHostnames, readTemporaryBrowserAllowedHostnames, stripTemporaryBrowserAllowlistFromConfigObject, } from "../../capabilities/browser-policy.js";
+import { getInstanceDir as framework_instanceDir, instanceMetaPath } from "../../../config.js";
+import { createTask, emitTask, spawnWithTask, getDirSizeMB, npmProgressParser, dockerBuildProgressParser, resolveDockerInvocation, } from "../../setup/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 { getDefaultLlmProvider, normalizeProviderApi } from "../../llm-proxy/providers.js";
+import { bootstrapInstanceProxy, getInstanceConfig as getProxyInstanceConfig, } from "../../llm-proxy/instance-proxy.js";
+import { renderStandaloneMcporterSource } from "./mcporter-lite.js";
+import { resolveNomadJobId } from "../../runtime/job-id.js";
+import { DEFINITION_FILENAME, MANIFEST_FILENAME, RESOLVED_SPEC_FILENAME, } from "../../app-common/paths.js";
+import { registerIntegration } from "../registry.js";
+import { isOwnedByInstance, writeOwnershipMarker } from "../../runtime/ownership-marker.js";
+import { mcporterPath, removeMcporterServers } from "./mcporter.js";
+import { removeOpenclawMcpServers, upsertOpenclawMcpServer, } from "./native-mcp.js";
+// ── Constants physically migrated from the Nomad driver ───────────────
+//
+// These used to live as module-scope constants in the Nomad driver 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 integration, not the
+// Nomad scheduler.
+const DEFAULT_COMMAND = "/usr/bin/openclaw";
+// Default invocation for a fresh OpenClaw container. `--port 18789` is the
+// process's container-internal listener (= `containerPort`), NOT a host port.
+// Host-side publishing is decided by Core's allocator and persisted into
+// `runtime.ports[].hostPort`; the OpenClaw binary itself always speaks on
+// 18789 inside the container regardless of how Core maps it on the outside.
+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 };
+// 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_CONTAINER_PORT = 18789;
+export const OPENCLAW_PREFERRED_HOST_PORT = OPENCLAW_DEFAULT_CONTAINER_PORT;
+/**
+ * Resolve the container-internal listening port the OpenClaw process binds.
+ *
+ * Belongs to the runtime hot path (called from `OpenClawIntegration.buildRuntime`)
+ * and must therefore obey the canonical port model: the only allowed sources
+ * are `runtime.ports[].containerPort` (Core's persisted desired runtime) or
+ * the OpenClaw binary's documented default.
+ */
+function resolveOpenclawContainerPort(rawRuntime) {
+    const ports = Array.isArray(rawRuntime?.ports) ? rawRuntime.ports : [];
+    for (const port of ports) {
+        if (port?.name === "gateway" && Number.isInteger(port?.containerPort) && port.containerPort > 0) {
+            return port.containerPort;
+        }
+    }
+    for (const port of ports) {
+        if (Number.isInteger(port?.containerPort) && port.containerPort > 0) {
+            return port.containerPort;
+        }
+    }
+    return OPENCLAW_DEFAULT_CONTAINER_PORT;
+}
+// ── 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 = {
+    ui: {
+        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"],
+};
+export const OPENCLAW_CONTROL_UI_PROXY_RE = /^\/api\/integrations\/openclaw\/instances\/([a-z0-9][a-z0-9-]{0,62})\/control-ui(?:\/(.*))?$/;
+const OPENCLAW_CONTROL_UI_PUBLIC_PROXY = {
+    basePathPattern: OPENCLAW_CONTROL_UI_PROXY_RE,
+    authBypass: true,
+    websocket: true,
+    buildHeaders: ({ match }) => {
+        try {
+            const cfg = loadEffectiveConfig(match.instanceId);
+            const token = cfg?.gateway?.auth?.token;
+            if (typeof token === "string" && token.trim()) {
+                return { authorization: `Bearer ${token.trim()}` };
+            }
+        }
+        catch {
+            // Best effort: if config is unavailable, OpenClaw returns its normal auth error.
+        }
+        return {};
+    },
+    resolveTarget: async ({ match, query }) => {
+        const im = await lazyIm();
+        const port = im.getPrimaryHostPort(match.instanceId);
+        const host = await im.getPrimaryHostForInstance(match.instanceId);
+        const suffix = match.suffix.replace(/^\/+/, "");
+        return {
+            protocol: "http",
+            host,
+            port,
+            path: `/${suffix}${query}`,
+        };
+    },
+};
+export async function ensureOpenclawControlUiAllowedOrigin(instanceId, origin) {
+    const normalizedOrigin = origin.trim();
+    if (!normalizedOrigin)
+        return false;
+    const im = await lazyIm();
+    const config = im.getStoredConfig(instanceId);
+    if (!config)
+        return false;
+    const gateway = config.gateway ??= {};
+    const controlUi = gateway.controlUi ??= {};
+    const existing = Array.isArray(controlUi.allowedOrigins)
+        ? controlUi.allowedOrigins.map((value) => String(value))
+        : [];
+    const normalized = new Set(existing.map((value) => value.trim().toLowerCase()).filter(Boolean));
+    if (normalized.has("*") || normalized.has(normalizedOrigin.toLowerCase()))
+        return false;
+    controlUi.allowedOrigins = [...existing.filter((value) => value.trim()), normalizedOrigin];
+    await im.saveConfig(instanceId, config);
+    return true;
+}
+import { FILES_ROOT } from "../../../config.js";
+function readFileMounts(runtime) {
+    const raw = runtime.fileMounts;
+    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;
+}
+// ── 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 openclawHomeFromMetadata(meta, instanceId) {
+    const integrationHome = meta?.paths?.integrationHome;
+    return typeof integrationHome === "string" && integrationHome.trim()
+        ? integrationHome
+        : defaultOpenclawHome(instanceId);
+}
+function defaultOpenclawModelEnvFile(instanceId) {
+    return join(framework_instanceDir(instanceId), INSTANCE_MODEL_ENV_FILENAME);
+}
+function isPrecreatedManagedAppDir(dir) {
+    return existsSync(join(dir, DEFINITION_FILENAME))
+        && existsSync(join(dir, RESOLVED_SPEC_FILENAME))
+        && existsSync(join(dir, MANIFEST_FILENAME));
+}
+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 only as a clone/import boundary reader so clones of
+ * old instances still work. Normal runtime config reads call
+ * `migrateLegacyOuterConfigOnce()` instead of treating this legacy path as a
+ * second source of truth.
+ */
+function resolveExistingConfigPath(instanceId) {
+    const runtimePath = openclawConfigPath(instanceId);
+    if (existsSync(runtimePath))
+        return runtimePath;
+    const legacy = legacyOpenclawConfigPath(instanceId);
+    if (existsSync(legacy))
+        return legacy;
+    return runtimePath;
+}
+function migrateLegacyOuterConfigOnce(instanceId) {
+    const runtimePath = openclawConfigPath(instanceId);
+    const legacyPath = legacyOpenclawConfigPath(instanceId);
+    if (!existsSync(legacyPath))
+        return;
+    // Step 6 one-shot fallback reader: historical OpenClaw installs stored
+    // config at `$OPENCLAW_HOME/openclaw.json`. Normal runtime must now read and
+    // write only `$OPENCLAW_HOME/.openclaw/openclaw.json`; this boundary converts
+    // old disk state into the canonical path and removes the old mirror so it
+    // cannot resurrect fields on a later save.
+    if (!existsSync(runtimePath)) {
+        ensureDirContainer(dirname(runtimePath));
+        copyFileSync(legacyPath, runtimePath);
+        chownToServiceUser(runtimePath);
+    }
+    rmSync(legacyPath, { force: true });
+}
+const OPENCLAW_BROWSER_SESSION_INDEX_RELATIVE_PATH = [
+    OPENCLAW_STATE_DIRNAME,
+    "agents",
+    "main",
+    "sessions",
+    "sessions.json",
+];
+const OPENCLAW_BROWSER_SESSION_SUMMARY_MAX_FILE_SIZE = 10 * 1024 * 1024;
+function isBrowserSummaryRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeBrowserSummaryText(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function normalizeBrowserSummaryTimestamp(value) {
+    const text = normalizeBrowserSummaryText(value);
+    if (!text)
+        return null;
+    const parsed = new Date(text);
+    return Number.isNaN(parsed.getTime()) ? null : parsed.toISOString();
+}
+function unavailableBrowserConsumerActivitySummary() {
+    return {
+        recentSession: {
+            state: "unavailable",
+            sessionKey: null,
+            lastMessageAt: null,
+            origin: null,
+            channel: null,
+        },
+        lastBrowserAttempt: {
+            state: "unavailable",
+            action: null,
+            profile: null,
+            url: null,
+            error: null,
+            timestamp: null,
+        },
+    };
+}
+function noSessionsBrowserConsumerActivitySummary() {
+    return {
+        recentSession: {
+            state: "no_sessions",
+            sessionKey: null,
+            lastMessageAt: null,
+            origin: null,
+            channel: null,
+        },
+        lastBrowserAttempt: {
+            state: "none",
+            action: null,
+            profile: null,
+            url: null,
+            error: null,
+            timestamp: null,
+        },
+    };
+}
+function isInsideResolvedHome(resolvedHome, resolvedPath) {
+    return resolvedPath === resolvedHome || resolvedPath.startsWith(`${resolvedHome}/`);
+}
+function resolveSafeOpenclawBrowserSummaryFile(resolvedHome, candidatePath) {
+    if (!candidatePath || !existsSync(candidatePath))
+        return null;
+    try {
+        const resolvedPath = realpathSync(candidatePath);
+        if (!isInsideResolvedHome(resolvedHome, resolvedPath))
+            return null;
+        const stats = statSync(resolvedPath);
+        if (!stats.isFile() || stats.size > OPENCLAW_BROWSER_SESSION_SUMMARY_MAX_FILE_SIZE)
+            return null;
+        return resolvedPath;
+    }
+    catch {
+        return null;
+    }
+}
+function readOpenclawBrowserSessionIndex(openclawHome) {
+    let resolvedHome;
+    try {
+        resolvedHome = realpathSync(openclawHome);
+    }
+    catch {
+        return "unavailable";
+    }
+    const sessionsIndex = join(openclawHome, ...OPENCLAW_BROWSER_SESSION_INDEX_RELATIVE_PATH);
+    if (!existsSync(sessionsIndex))
+        return "no_sessions";
+    const resolvedIndex = resolveSafeOpenclawBrowserSummaryFile(resolvedHome, sessionsIndex);
+    if (!resolvedIndex)
+        return "unavailable";
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(resolvedIndex, "utf-8"));
+    }
+    catch {
+        return "unavailable";
+    }
+    if (!isBrowserSummaryRecord(raw))
+        return "unavailable";
+    return {
+        resolvedHome,
+        sessions: Object.entries(raw).map(([sessionKey, sessionMeta]) => ({
+            sessionKey,
+            sessionFile: normalizeBrowserSummaryText(sessionMeta?.sessionFile),
+            origin: normalizeBrowserSummaryText(sessionMeta?.origin?.label),
+            channel: normalizeBrowserSummaryText(sessionMeta?.origin?.provider),
+        })),
+    };
+}
+function browserAttemptIsNewer(candidate, current) {
+    const candidateTs = candidate.timestamp ? Date.parse(candidate.timestamp) : Number.NaN;
+    const currentTs = current.timestamp ? Date.parse(current.timestamp) : Number.NaN;
+    const safeCandidateTs = Number.isFinite(candidateTs) ? candidateTs : Number.NEGATIVE_INFINITY;
+    const safeCurrentTs = Number.isFinite(currentTs) ? currentTs : Number.NEGATIVE_INFINITY;
+    if (safeCandidateTs !== safeCurrentTs)
+        return safeCandidateTs > safeCurrentTs;
+    if (current.state === "none" && candidate.state !== "none")
+        return true;
+    return false;
+}
+function summarizeOpenclawBrowserAttemptFromContent(content) {
+    const toolCalls = new Map();
+    let lastStatusProfile = null;
+    let lastAttempt = {
+        state: "none",
+        action: null,
+        profile: null,
+        url: null,
+        error: null,
+        timestamp: null,
+    };
+    for (const line of content.split("\n")) {
+        if (!line.trim())
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isBrowserSummaryRecord(entry) || entry.type !== "message")
+            continue;
+        const message = isBrowserSummaryRecord(entry.message) ? entry.message : {};
+        const timestamp = normalizeBrowserSummaryTimestamp(entry.timestamp);
+        const contentBlocks = Array.isArray(message.content) ? message.content : [];
+        for (const block of contentBlocks) {
+            if (!isBrowserSummaryRecord(block) || block.type !== "toolCall" || block.name !== "browser")
+                continue;
+            const args = isBrowserSummaryRecord(block.arguments) ? block.arguments : {};
+            toolCalls.set(String(block.id ?? ""), {
+                action: normalizeBrowserSummaryText(args.action),
+                profile: normalizeBrowserSummaryText(args.profile),
+                url: normalizeBrowserSummaryText(args.url),
+                timestamp,
+            });
+        }
+        if (message.role !== "toolResult" || message.toolName !== "browser")
+            continue;
+        const call = toolCalls.get(String(message.toolCallId ?? "")) ?? {
+            action: null,
+            profile: null,
+            url: null,
+            timestamp,
+        };
+        const details = isBrowserSummaryRecord(message.details) ? message.details : {};
+        const statusProfile = normalizeBrowserSummaryText(details.profile);
+        if (call.action === "status" && statusProfile) {
+            lastStatusProfile = statusProfile;
+            lastAttempt = {
+                state: "status_only",
+                action: call.action,
+                profile: statusProfile,
+                url: call.url,
+                error: null,
+                timestamp: timestamp ?? call.timestamp,
+            };
+            continue;
+        }
+        if (call.action !== "open" && call.action !== "navigate")
+            continue;
+        const error = normalizeBrowserSummaryText(details.error);
+        const profile = call.profile ?? statusProfile;
+        const ok = typeof details.ok === "boolean" ? details.ok : !error;
+        const state = error
+            ? (profile === "openclaw"
+                && lastStatusProfile === "browserless"
+                && error.includes("No supported browser found")
+                ? "wrong_profile_selected"
+                : "browser_failed_before_session")
+            : (ok ? "browser_open_succeeded" : "browser_failed_before_session");
+        lastAttempt = {
+            state,
+            action: call.action,
+            profile,
+            url: call.url ?? normalizeBrowserSummaryText(details.url),
+            error,
+            timestamp: timestamp ?? call.timestamp,
+        };
+    }
+    return lastAttempt;
+}
+export function summarizeRecentOpenclawBrowserSession(instanceId) {
+    const openclawHome = openclawHomeFromMetadata(getInstance(instanceId), instanceId);
+    if (!openclawHome)
+        return unavailableBrowserConsumerActivitySummary();
+    const index = readOpenclawBrowserSessionIndex(openclawHome);
+    if (index === "unavailable")
+        return unavailableBrowserConsumerActivitySummary();
+    if (index === "no_sessions")
+        return noSessionsBrowserConsumerActivitySummary();
+    const summary = noSessionsBrowserConsumerActivitySummary();
+    for (const session of index.sessions) {
+        const resolvedSessionFile = resolveSafeOpenclawBrowserSummaryFile(index.resolvedHome, session.sessionFile);
+        if (!resolvedSessionFile)
+            continue;
+        let content;
+        try {
+            content = readFileSync(resolvedSessionFile, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        let lastMessageAt = null;
+        for (const line of content.split("\n")) {
+            if (!line.trim())
+                continue;
+            let entry;
+            try {
+                entry = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (!isBrowserSummaryRecord(entry) || entry.type !== "message")
+                continue;
+            const timestamp = normalizeBrowserSummaryTimestamp(entry.timestamp);
+            if (timestamp)
+                lastMessageAt = timestamp;
+        }
+        if (lastMessageAt && (summary.recentSession.state !== "available"
+            || !summary.recentSession.lastMessageAt
+            || summary.recentSession.lastMessageAt < lastMessageAt)) {
+            summary.recentSession = {
+                state: "available",
+                sessionKey: session.sessionKey,
+                lastMessageAt,
+                origin: session.origin,
+                channel: session.channel,
+            };
+        }
+        const attempt = summarizeOpenclawBrowserAttemptFromContent(content);
+        if (browserAttemptIsNewer(attempt, summary.lastBrowserAttempt)) {
+            summary.lastBrowserAttempt = attempt;
+        }
+    }
+    return summary;
+}
+// ── 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 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;
+}
+async function finalizeOpenclawCreatedInstance(instanceId, createArgs) {
+    const appSpec = createArgs?.appSpec;
+    const cloneFrom = createArgs?.cloneFrom;
+    const cloneOptions = createArgs?.cloneOptions;
+    const d = framework_instanceDir(instanceId);
+    const im = await lazyIm();
+    const home = openclawHomeFromMetadata(getInstance(instanceId), instanceId);
+    const envFiles = getRuntimeEnvFiles(instanceId);
+    const runtime = im.getInstanceRuntime(instanceId);
+    const configPath = openclawConfigPath(instanceId, home);
+    for (const ef of envFiles) {
+        if (!existsSync(ef))
+            writeConfigFile(ef, "");
+    }
+    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 */
+    }
+    ensureDirContainer(dirname(configPath));
+    if (cloneFrom && !existsSync(configPath)) {
+        const srcConfig = resolveExistingConfigPath(cloneFrom);
+        if (existsSync(srcConfig)) {
+            try {
+                const cloned = JSON.parse(readFileSync(srcConfig, "utf-8"));
+                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];
+                            continue;
+                        }
+                        if (typeof prov === "object" && prov !== null) {
+                            delete prov.apiKey;
+                        }
+                    }
+                }
+                const defaultModel = cloned?.agents?.defaults?.model;
+                if (typeof defaultModel === "string" &&
+                    (defaultModel.startsWith("jsproxy/") || defaultModel.startsWith("js-"))) {
+                    delete cloned.agents.defaults.model;
+                }
+                stripImBindings(cloned);
+                if (!cloned.gateway)
+                    cloned.gateway = {};
+                if (!cloned.gateway.auth)
+                    cloned.gateway.auth = { mode: "token" };
+                cloned.gateway.auth.token = randomBytes(24).toString("hex");
+                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));
+                const srcMeta = getInstance(cloneFrom);
+                const srcXj = srcMeta?.["x-jishushell"];
+                if (srcXj?.proxy?.upstream) {
+                    const dstXj = structuredClone({ proxy: { upstream: srcXj.proxy.upstream } });
+                    delete dstXj.proxy.upstream.apiKey;
+                    updateInstanceMeta(instanceId, { "x-jishushell": dstXj });
+                }
+            }
+            catch (error) {
+                throw new Error(`Cannot clone OpenClaw config from ${cloneFrom}: ${error?.message ?? error}`);
+            }
+        }
+    }
+    if (!existsSync(configPath)) {
+        writeConfigFile(configPath, JSON.stringify(starterConfig(), null, 2));
+        const dp = getDefaultLlmProvider();
+        if (dp?.apiKey && dp?.id && envFiles.length) {
+            const providerEnv = join(dirname(envFiles[0]), "provider.env");
+            updateEnvFile(providerEnv, { UPSTREAM_API_KEY: dp.apiKey });
+        }
+    }
+    const runtimeOverlay = appSpec?.runtime;
+    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 */
+        }
+    }
+    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, {
+                instanceId,
+                definitionId: appSpec?.id ?? instanceId,
+                skills: overlaySkills,
+            });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    // Clones intentionally inherit the source instance's Core-managed upstream
+    // credential. provider.env contains only the AES-encrypted upstream key and
+    // is never exposed to the OpenClaw process; the clone still gets its own
+    // JSPROXY_API_KEY in model.env below.
+    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);
+            }
+        }
+    }
+    try {
+        await bootstrapInstanceProxy(instanceId);
+    }
+    catch (e) {
+        console.warn(`[openclaw] Proxy bootstrap for ${instanceId} deferred: ${e.message}`);
+    }
+    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);
+        }
+    }
+}
+// ── Nomad-patching helpers (migrated from the runtime driver) ──────────
+/**
+ * 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.
+ */
+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: on every Browserless bind, the bound CDP endpoint hostname is
+ * merged into `allowedHostnames` so OpenClaw can connect to the trusted
+ * Browserless service even when it is advertised on a private LAN address.
+ * On first bind (when the `allowedHostnames` list is empty or absent), a
+ * small set of common public-internet hosts is also pre-populated so users
+ * don't have to whitelist every popular site one by one. The public defaults
+ * are a one-time bootstrap — once the user has any entries, further binds
+ * leave those entries untouched except for refreshing the active endpoint.
+ *
+ * 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,
+    };
+    if (existing.meta?._js_allowAll) {
+        delete browser.ssrfPolicy;
+    }
+    else {
+        const ssrfPolicy = (browser.ssrfPolicy ??= {});
+        const existingAllowedHostnames = Array.isArray(ssrfPolicy.allowedHostnames)
+            ? ssrfPolicy.allowedHostnames.map((entry) => String(entry))
+            : [];
+        const bootstrapHostnames = existingAllowedHostnames.length === 0
+            ? DEFAULT_BROWSER_ALLOWED_HOSTNAMES
+            : existingAllowedHostnames;
+        ssrfPolicy.allowedHostnames = mergeBrowserAllowedHostnames(bootstrapHostnames, browserlessEndpointAllowedHostname(cdpUrl));
+    }
+    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.
+ *   2026.6.10.1 — Browserless profile rule in TOOLS.md: Browserless-bound
+ *                  instances now spell out that `browser.open` should not
+ *                  default to `profile: "openclaw"` after status/doctor
+ *                  already report `browserless via cdp`.
+ *   2026.6.11.1 — Browserless shared-browser handoff rule: Browserless is
+ *                  now described as a user-takeover-capable shared browser
+ *                  surface.
+ *   2026.6.12.1 — Browserless site-side anti-bot classification rule:
+ *                  site WAF/captcha blocks are not Browser Allowlist misses.
+ *   2026.6.24.1 — Immich MCP routing rule in TOOLS.md: photo-library
+ *                  requests must use the injected immich.* tools instead of
+ *                  probing docker, ports, or host directories from inside
+ *                  the OpenClaw container.
+ *
+ * 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.24.1";
+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 -->";
+const JISHUSHELL_IMMICH_HINT_BEGIN = "<!-- jishushell-immich: BEGIN auto-generated -->";
+const JISHUSHELL_IMMICH_HINT_END = "<!-- jishushell-immich: END -->";
+const JISHUSHELL_BROWSERLESS_HINT_BEGIN = "<!-- jishushell-browserless: BEGIN auto-generated -->";
+const JISHUSHELL_BROWSERLESS_HINT_END = "<!-- jishushell-browserless: 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;
+            let rotateFailed = false;
+            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) {
+                    rotateFailed = true;
+                    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}`);
+            }
+            if (rotateFailed)
+                return;
+        }
+        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 patchToolsMdBrowserlessHint(workspaceDir, mode) {
+    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;
+        }
+        const stripRe = /\n*<!-- jishushell-browserless: BEGIN[^>]*-->[\s\S]*?<!-- jishushell-browserless: END[^>]*-->\n*/g;
+        const stripped = original.replace(stripRe, "\n");
+        let next;
+        if (mode === "remove") {
+            if (stripped === original)
+                return;
+            next = stripped;
+        }
+        else {
+            const section = [
+                JISHUSHELL_BROWSERLESS_HINT_BEGIN,
+                "",
+                "### Browserless shared-browser rule",
+                "",
+                "In JishuShell, Browserless is a shared interactive browser surface:",
+                "- the agent opens and drives pages with the `browser` tool;",
+                "- the user can take over the same Browserless session from the JishuShell panel's Browserless debugger;",
+                "- login forms, captchas, permission prompts, cookie banners, MFA, and similar blockers are handoff points, not terminal failures.",
+                "",
+                "Follow these rules whenever you use the `browser` tool:",
+                "",
+                "1. If `browser status` or `browser doctor` reports `profile = \"browserless\"` / `browserless via cdp`, keep subsequent page-opening actions on Browserless.",
+                "2. For ordinary website opening, prefer omitting `profile` entirely so the configured default can apply.",
+                "3. If you must set a profile explicitly, use `profile: \"browserless\"` unless the user explicitly asked for a different named profile.",
+                "4. Do not switch to `profile: \"openclaw\"` just because the target site may need login. Browserless is the login-capable path in this setup.",
+                "5. If the user explicitly asks to open a browser, says \"I will log in\", \"let me handle it\", or wants to clear a captcha / permission prompt themselves, do not stop at `browser.status`. After the health check, call `browser.open` on the requested site, or `about:blank` if no site was given, so a live Browserless session exists for takeover.",
+                "6. After opening the page, explicitly tell the user to continue in the Browserless debugger / panel and wait for them. The expected workflow is open -> handoff -> user acts -> agent resumes.",
+                "7. Do not claim that `attachOnly`, `headless`, or the lack of a local OS window means the user cannot interact. In this setup the visual surface is the Browserless debugger in JishuShell.",
+                "8. If login, captcha, cookie consent, permissions, MFA, or payment confirmation appears, keep the Browserless session alive and hand control to the user instead of abandoning the task.",
+                "9. If Browserless status is healthy but a later `browser.open` with `profile: \"openclaw\"` would search for a local browser executable, that is the wrong choice for this instance.",
+                "10. If `browser.open` fails with `browser endpoint blocked by policy`, immediately tell the user the blocked hostname, that the block happened before Browserless, where to unblock it in Panel -> this instance -> Browser Allowlist, and ask the user to tell you after whitelisting so you can retry. Do not silently fall back to web_fetch / web_search before delivering that notice.",
+                "11. If `browser.open` succeeds but the page/status/body shows a target-site anti-bot / WAF / verification block, for example `whaleguard block`, `HTTP 432`, `403`, `captcha`, `verify`, or a blank page saying it was blocked, do not tell the user to add the host to the Browser Allowlist. The site was reached and then rejected the browser/session.",
+                "12. For Ctrip / WhaleGuard specifically, do not keep retrying the blocked deep link such as `flights.ctrip.com/online/list/...`. Open `https://www.ctrip.com/` first, keep the Browserless session alive, ask the user to take over in the Browserless debugger to log in / pass verification / perform the search manually, and wait.",
+                "13. Do not claim that a live page/session is ready for takeover unless `browser.open` actually succeeded. A healthy Browserless status alone is not proof that the user already has a visible page to interact with.",
+                "",
+                JISHUSHELL_BROWSERLESS_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"} browserless hint in ${toolsPath}`);
+    }
+    catch (e) {
+        console.warn(`[openclaw] Failed to ${mode} TOOLS.md browserless hint: ${e.message}`);
+    }
+}
+export function resolveKbProvider(kbBinding) {
+    const LEGACY_PROVIDER_ANYLLM = "anythingllm-container";
+    const LEGACY_PROVIDER_JISHUKB = "jishu-kb-container";
+    const capabilityToTag = (capability) => {
+        if (capability === "knowledge-jishukb")
+            return "jishukb";
+        if (capability === "knowledge-anythingllm")
+            return "anythingllm";
+        return null;
+    };
+    const legacyProviderIdToTag = (providerId) => {
+        if (providerId === LEGACY_PROVIDER_JISHUKB)
+            return "jishukb";
+        if (providerId === LEGACY_PROVIDER_ANYLLM)
+            return "anythingllm";
+        return null;
+    };
+    const entryToTag = (entry) => {
+        if (!entry || typeof entry !== "object")
+            return null;
+        // Canonical connection bindings store the provider instance id in
+        // providerId and the concrete provider kind in capability. The provider
+        // instance id is user-controlled (`jishu-kb`, `my-kb`, ...), so runtime
+        // wiring must key off capability, not template/provider-id strings.
+        return capabilityToTag(entry.capability) ?? legacyProviderIdToTag(entry.providerId);
+    };
+    if (kbBinding === null)
+        return null;
+    if (kbBinding && typeof kbBinding === "object") {
+        const b = kbBinding;
+        if (b.kind === "single") {
+            return entryToTag(b);
+        }
+        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 = entryToTag(p);
+                if (tag !== null)
+                    return tag;
+            }
+            return null;
+        }
+        return null;
+    }
+    return null;
+}
+function providerCredentialsPath(providerId) {
+    return join(JISHUSHELL_HOME, "provider-credentials", providerId, "credentials.json");
+}
+function legacyProviderCredentialsPath(providerId) {
+    return join(JISHUSHELL_HOME, "apps", providerId, "credentials.json");
+}
+function cleanupEmptyLegacyProviderDir(providerId) {
+    const dir = join(JISHUSHELL_HOME, "apps", providerId);
+    try {
+        if (existsSync(dir) && readdirSync(dir).length === 0) {
+            rmSync(dir, { recursive: false, force: true });
+        }
+    }
+    catch {
+        /* best effort */
+    }
+}
+function resolveProviderCredentialsPath(providerId) {
+    const nextPath = providerCredentialsPath(providerId);
+    if (existsSync(nextPath))
+        return nextPath;
+    const legacyPath = legacyProviderCredentialsPath(providerId);
+    if (!existsSync(legacyPath))
+        return nextPath;
+    try {
+        ensureDirHost(dirname(nextPath));
+        renameSync(legacyPath, nextPath);
+        cleanupEmptyLegacyProviderDir(providerId);
+        console.log(`[openclaw] migrated ${providerId} credentials to ${nextPath}`);
+        return nextPath;
+    }
+    catch (error) {
+        console.warn(`[openclaw] failed to migrate ${providerId} credentials from legacy apps/ path:`, error?.message ?? error);
+        return legacyPath;
+    }
+}
+export async function resolveJishukbDefaultKbIdForOpenClaw(baseUrl, configuredKbId) {
+    const kbId = typeof configuredKbId === "string" ? configuredKbId.trim() : "";
+    if (kbId && kbId !== "default")
+        return kbId;
+    try {
+        const { ensureDefaultKb } = await import("../jishukb/integration.js");
+        await ensureDefaultKb(baseUrl);
+        return "default";
+    }
+    catch (error) {
+        console.warn(`[openclaw] kb: jishu-kb default KB is not usable; wiring without a default kbId: ` +
+            `${error?.message ?? error}`);
+        return "";
+    }
+}
+function rewriteJishukbMcpUrlForOpenClawRuntime(url, runtime) {
+    if (!runtime?.image)
+        return url;
+    try {
+        const parsed = new URL(url);
+        if (["127.0.0.1", "localhost", "0.0.0.0", "::1", "[::1]"].includes(parsed.hostname)) {
+            parsed.hostname = "host.docker.internal";
+            return parsed.toString();
+        }
+    }
+    catch {
+        return url;
+    }
+    return url;
+}
+/**
+ * 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.
+ *
+ * integrationHome is the OpenClaw container's `$HOME` (the value returned by
+ * `openclawIntegration.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(integrationHome, which) {
+    const dir = join(integrationHome, "__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, unavailableReason) {
+    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 (mode === "unavailable") {
+            const reason = typeof unavailableReason === "string" && unavailableReason.trim()
+                ? unavailableReason.trim().replace(/\s+/g, " ").slice(0, 500)
+                : "native MCP is not registered";
+            const section = [
+                JISHUSHELL_KB_HINT_BEGIN,
+                "",
+                "### 📚 知识库（JishuShell-KB）暂不可用",
+                "",
+                "OpenClaw 已绑定 **JishuShell-KB**，但 JishuShell 当前没有检测到可用的 **native MCP** 服务，所以本轮不能调用 `kb.*` 工具。",
+                "",
+                `**检测原因**：${reason}`,
+                "",
+                "**必须这样处理**：",
+                "- 不要声称已经检索过知识库，也不要尝试使用旧 shim、mcporter 或自己拼 HTTP 请求。",
+                "- 如果用户要查询、上传或管理知识库，直接提醒用户：需要升级 JishuShell-KB 到包含 remote MCP 的版本，并确认 `JISHU_KB_MCP_HTTP` / MCP auth 已配置后重启 OpenClaw。",
+                "- 在 native MCP 恢复前，知识库能力视为不可用。",
+                "",
+                JISHUSHELL_KB_HINT_END,
+                "",
+            ].join("\n");
+            const sep = stripped && !stripped.endsWith("\n") ? "\n\n" : "\n";
+            next = (stripped ? stripped + sep : "") + section;
+        }
+        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 nativeKbTool = (name) => `kb__${name}`;
+            const section = provider === "jishukb"
+                ? [
+                    JISHUSHELL_KB_HINT_BEGIN,
+                    "",
+                    "### 📚 知识库（JishuShell-KB）",
+                    "",
+                    "用户长期投递并已经导入到 **JishuShell-KB** 的文档（手册、PDF、内部笔记、会议纪要等）可以检索；你也可以列知识库、创建知识库、把 drive 文件或 URL 上传入库、查看已索引文档/分块/原文/FAQ、查看 ingest job、查看 handbook、读取**脱敏后的**当前配置，以及在用户明确确认时执行删除/重索引/取消任务。",
+                    "",
+                    "这些能力由 OpenClaw native MCP 暴露；直接调用 `kb__*` 工具，不要通过 shell、mcporter 或手写 HTTP 请求访问 KB。",
+                    "",
+                    "**当前 provider 暴露的工具**：",
+                    "",
+                    `- \`${nativeKbTool("kb_list")}\` — 列出所有知识库（拿 id / name / documents 文件数 / chunks 分块数；用户问“几个文件”时看 documents，不要用 chunks）`,
+                    `- \`${nativeKbTool("kb_get_capabilities")}\` — 查看 KB 当前支持的外部控制能力、上传格式和限制（不含密钥）`,
+                    `- \`${nativeKbTool("kb_create")}\` — 新建知识库`,
+                    `- \`${nativeKbTool("kb_get")}\` — 查看某个知识库的元数据、文件数、分块数、任务数和安全配置摘要`,
+                    `- \`${nativeKbTool("kb_search")}\` — 检索指定或默认知识库`,
+                    `- \`${nativeKbTool("kb_upload")}\` — 上传并索引文件到指定知识库`,
+                    `- \`${nativeKbTool("kb_import_url")}\` — 抓取可读 URL 并入库，默认异步返回 job`,
+                    `- \`${nativeKbTool("kb_list_documents")}\` — 列出指定或默认知识库里的已索引文档`,
+                    `- \`${nativeKbTool("kb_get_document")}\` — 查看单个文档的元数据和派生计数`,
+                    `- \`${nativeKbTool("kb_list_document_chunks")}\` — 查看某个文档的索引分块（文本会截断）`,
+                    `- \`${nativeKbTool("kb_read_document_raw")}\` — 读取某个文档的原始存储文本（仅在用户要看原文时用，输出会截断）`,
+                    `- \`${nativeKbTool("kb_list_document_faq")}\` — 查看某个文档生成的 FAQ 建议`,
+                    `- \`${nativeKbTool("kb_reindex_document")}\` — 重建文档索引（写操作，必须显式确认）`,
+                    `- \`${nativeKbTool("kb_list_jobs")}\` — 查看导入/索引任务`,
+                    `- \`${nativeKbTool("kb_get_job")}\` — 查看单个任务状态`,
+                    `- \`${nativeKbTool("kb_retry_job")}\` — 重试失败/取消的任务（仅在用户要求时用）`,
+                    `- \`${nativeKbTool("kb_cancel_job")}\` — 取消任务（必须显式确认）`,
+                    `- \`${nativeKbTool("kb_read_handbook")}\` — 读取 handbook 全文或指定章节`,
+                    `- \`${nativeKbTool("kb_get_config")}\` — 读取当前**脱敏后的**知识库配置摘要`,
+                    `- \`${nativeKbTool("kb_delete_document")}\` — 删除文档（危险操作，必须显式确认）`,
+                    `- \`${nativeKbTool("kb_delete_kb")}\` — 删除知识库（危险操作，必须显式确认）`,
+                    "",
+                    "**推荐调用顺序**：",
+                    `1. 用户问“知识库里有几个文件 / 包含哪些文件” → 先 \`${nativeKbTool("kb_list_documents")}\`；如果不知道 kbId，先 \`${nativeKbTool("kb_list")}\`，再对目标库调用 \`${nativeKbTool("kb_list_documents")}\`。文件数按 documents 或 list_documents 返回数组长度计算，不要按 chunks 计算。`,
+                    `2. 用户提到“某个指定知识库 / 某个库里”但你不知道 id → 先 \`${nativeKbTool("kb_list")}\`。`,
+                    `3. 用户要把 drive 里的文件加入知识库 → 先解析本地路径，再调用 \`${nativeKbTool("kb_upload")}\`，并显式传目标 kbId。`,
+                    `4. 用户当前消息已经附了文件，而且消息里给了宿主机绝对路径（通常在 \`${attachmentInboxPath}/...\`）→ 直接把这个绝对路径传给 \`${nativeKbTool("kb_upload")}\`；不要先把内容重写到 \`files/\` 根目录，也不要自己猜 \`agent-data/agent1/...\` 这种路径。`,
+                    `5. 用户要把网页/文章 URL 加入知识库 → 先确认目标 kbId，再调用 \`${nativeKbTool("kb_import_url")}\`；返回 job 后用 \`${nativeKbTool("kb_get_job")}\` 或 \`${nativeKbTool("kb_list_jobs")}\` 看进度。`,
+                    `6. 用户要上传你**新生成**的文件 → 先写到 \`${generatedOutboxPath}\`，再解析本地路径，最后调用 \`${nativeKbTool("kb_upload")}\`。`,
+                    `7. 用户要新建库并马上上传 → \`${nativeKbTool("kb_create")}\` → 记住返回的 id → \`${nativeKbTool("kb_upload")}\` / \`${nativeKbTool("kb_import_url")}\`。`,
+                    `8. 用户要查看某个命中文档的细节 → 先 \`${nativeKbTool("kb_list_documents")}\` 找 documentId，再 \`${nativeKbTool("kb_get_document")}\`；需要解释命中原因用 \`${nativeKbTool("kb_list_document_chunks")}\`，只有用户明确要看原文时才用 \`${nativeKbTool("kb_read_document_raw")}\`。`,
+                    `9. 用户要修复索引/重跑失败导入 → 先 \`${nativeKbTool("kb_list_jobs")}\` / \`${nativeKbTool("kb_get_job")}\` 看状态；重试用 \`${nativeKbTool("kb_retry_job")}\`，重索引用 \`${nativeKbTool("kb_reindex_document")}\`。`,
+                    `10. 用户要解释某个设置项怎么用 → 先 \`${nativeKbTool("kb_read_handbook")}\`，必要时再 \`${nativeKbTool("kb_get_config")}\` 看当前值。`,
+                    "",
+                    `**安全规则**：写操作、删除操作、重索引、取消任务都不要猜目标知识库；拿不准就先 \`${nativeKbTool("kb_list")}\`。删除/重索引/取消必须是用户明确要求，且把 confirm 字段原样填成同一个 id。 \`${nativeKbTool("kb_get_config")}\` 和 \`${nativeKbTool("kb_get_capabilities")}\` 不会给你密钥。 \`${nativeKbTool("kb_upload")}\` 只接受来自当前实例已挂载文件目录，或当前实例附件 inbox（\`${attachmentInboxPath}/...\`）的绝对路径；如果 remote MCP capabilities 显示 path upload 关闭，就只能使用内容/URL 上传。 \`${nativeKbTool("kb_read_document_raw")}\` 只在用户要看原文时使用。**`,
+                    "",
+                    "**与 drive 的分工**：",
+                    "- `drive.*` = 文件系统 facade（列目录、读字节、拿绝对路径）—— 要的是**文件本体**用 drive",
+                    "- `kb__*` = 知识库检索/管理/上传 —— 要的是**知识库里的内容和状态**用 kb",
+                    "",
+                    "两者数据不共享：drive 里有文件 ≠ 某个知识库已经索引了它。",
+                    "",
+                    `**搜不到时的标准回复**：如果 \`${nativeKbTool("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}`);
+    }
+}
+export function patchToolsMdKbUnavailableHint(workspaceDir, reason) {
+    patchToolsMdKbHint(workspaceDir, "unavailable", undefined, "mcporter", undefined, undefined, reason);
+}
+/**
+ * Inject or remove the Immich MCP usage contract in TOOLS.md.
+ *
+ * Immich is registered through OpenClaw's native `mcp.servers` config, so the
+ * model receives standard tool schemas and calls them directly. This section
+ * only supplies product behavior and safety guidance; it must not teach the
+ * model to shell out through mcporter.
+ */
+export function patchToolsMdImmichHint(workspaceDir, mode, serverName = "immich") {
+    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;
+        }
+        const stripRe = /\n*<!-- jishushell-immich: BEGIN[^>]*-->[\s\S]*?<!-- jishushell-immich: END[^>]*-->\n*/g;
+        const stripped = original.replace(stripRe, "\n");
+        let next;
+        if (mode === "remove") {
+            if (stripped === original)
+                return;
+            next = stripped;
+        }
+        else {
+            const tool = (name) => `${serverName}__${name}`;
+            const section = [
+                JISHUSHELL_IMMICH_HINT_BEGIN,
+                "",
+                "### 🖼️ Immich 照片库",
+                "",
+                `Immich 已通过 OpenClaw 原生 MCP 接入。用户询问照片、视频、图库状态、相册、标签、人物、人脸、地图位置或重复照片时，必须调用 \`${serverName}__*\` 工具，并严格按照工具提供的参数 Schema 传参。`,
+                "",
+                `⚠️ **不要用 shell 探测 Immich 是否安装**：OpenClaw 运行在自己的容器里；容器内没有 \`docker\` 命令、没有宿主机监听端口或 Immich 数据目录，并不代表宿主机没有运行 Immich。禁止用 \`docker ps\`、\`ss\`、\`find /\`、\`ls /opt\` 等结果判断 Immich 状态。连接状态只以 \`${tool("get_library_summary")}\` / \`${tool("ping")}\` 的结果为准。`,
+                "",
+                "**主要工具**：",
+                "",
+                `- \`${tool("get_library_summary")}\` — 首选健康检查；返回连接、版本和图库统计`,
+                `- \`${tool("get_photo_library_status")}\` — 查看 AI Box 默认照片目录是否已接入及已扫描数量`,
+                `- \`${tool("scan_photo_library")}\` — 扫描 AI Box 默认照片目录；首次调用会自动创建 External Library`,
+                `- \`${tool("create_photo_upload_session")}\` — 创建短期网页上传链接；照片和视频由浏览器直接传到 AI Box；同一页面在过期前可完成并扫描多个上传批次`,
+                `- \`${tool("list_assets")}\` — 列出照片/视频`,
+                `- \`${tool("search_metadata")}\` — 按结构化元数据搜索`,
+                `- \`${tool("search_smart")}\` — 用自然语言或相似图片获取 Immich Smart Search / CLIP 相似候选排序`,
+                `- \`${tool("get_asset_info")}\` — 查看单个资源`,
+                `- \`${tool("list_albums")}\` / \`${tool("get_album")}\` / \`${tool("delete_album")}\` — 相册`,
+                `- \`${tool("list_tags")}\` / \`${tool("get_tag")}\` / \`${tool("delete_tag")}\` — 标签`,
+                `- \`${tool("list_people")}\` / \`${tool("search_people")}\` — 人物`,
+                `- \`${tool("get_duplicates")}\` — 重复项`,
+                `- \`${tool("generate_review_gallery")}\` — 创建用户自选照片的 review 页面；确认后 Core 直接执行`,
+                "",
+                "**标准工具策略**：",
+                `1. 先按用户意图选择工具，不要用 shell、mcporter 或 memory_search 代替 Immich MCP。健康检查用 \`${tool("get_library_summary")}\` / \`${tool("ping")}\`；扫描用 \`${tool("scan_photo_library")}\`，返回 \`scan_queued\` 时只说明扫描已开始，不要声称所有照片已经导入完成；上传用 \`${tool("create_photo_upload_session")}\`，上传页面可在过期前连续完成多个批次。`,
+                `2. 读取和搜索只负责收集候选资源：普通列表用 \`${tool("list_assets")}\`，结构化条件搜索用 \`${tool("search_metadata")}\`，自然语言视觉语义或“找相似照片”用 \`${tool("search_smart")}\`，相册内容用 \`${tool("get_album")}\`，重复项用 \`${tool("get_duplicates")}\`。工具返回短 JSON 和 asset id；不要把 thumbnail base64、文件内容或大量 asset id 展示给用户。`,
+                `   \`${tool("search_smart")}\` 的实际语义是 Immich 返回一页按语义相似度排序的候选，默认 \`size=50\`、最大 \`100\`；它不是二分类器，也不保证返回“所有符合条件”的照片。小图库里可能几乎所有照片都会出现在第一页。向用户表述时使用“相似候选 / 候选结果 / 排序结果”，不要说“已经找到了所有 X 照片”或“这些全都是 X”。`,
+                `3. 相册和标签是目标容器。用户要求把照片加入某个新相册或新标签时，先用 \`${tool("create_album")}\` 或 \`${tool("create_tag")}\` 创建目标；如果目标是否存在或应复用不明确，先查列表或向用户确认。`,
+                `4. 删除相册或标签前，必须先用 \`${tool("get_album")}\` / \`${tool("get_tag")}\` 或列表结果核对资源名称和 id，并在对话里明确询问用户确认。调用 \`${tool("delete_album")}\` 不会删除照片；调用 \`${tool("delete_tag")}\` 不会删除照片，但会把该标签从所有关联照片上移除。`,
+                `5. 所有需要用户从候选照片中确认子集、确认批量修改、或决定哪些重复项应处理的操作，都必须通过 \`${tool("generate_review_gallery")}\` 创建 review interaction。适用动作包括加入/移出相册、打标签/取消标签、移入回收站、处理重复项。`,
+                `6. 对搜索驱动的批量操作采用通用的 human-in-the-loop 候选审核流程：先用读取/搜索工具得到候选集，把需要用户可见审核的候选放入 \`asset_ids\`；只有能解释清楚依据的高置信项才放入 \`preselected_asset_ids\`，让 review UI 默认勾选。最终执行仍以用户在页面中的确认和修改为准。`,
+                `7. 不要把所有 CLIP 命中无条件当作推荐项。Smart Search 结果只能直接作为候选，推荐项应基于多信号判断：分数 score（如果工具返回）、搜索排名、文件名、相册/标签/人物、地点、日期、资源类型等。精确结构化条件、明确 asset id、或用户给出的确定集合可以默认全选；纯视觉搜索且缺少可靠阈值或存在歧义时，只预选高置信项，不能判断的保持未选，必要时先请用户缩小条件。`,
+                `8. 用户表达“所有/全部/帮我找并加入/自动整理”时，不要把筛选工作完全丢给用户；应创建 review 页面给出候选，并在有高置信推荐项时默认选中。若候选只来自 Smart Search 且无法可靠区分，应明确说明这是相似候选排序，需要用户在页面中最终确认，而不是假装已经自动识别全部。用户表达“我来选、从图库挑、让我自己选择、选择几张”时，省略 \`preselected_asset_ids\`，让用户手动选择。`,
+                `9. 调用 \`${tool("generate_review_gallery")}\` 时，\`action\` 必须使用工具 schema 中的枚举原值：\`add_assets_to_album\`、\`remove_assets_from_album\`、\`tag_assets\`、\`untag_assets\`、\`delete_assets_to_trash\`、\`resolve_duplicates\`。不要自造 \`add-to-album\`、\`select-assets\`、\`manage-album\` 等动作名。`,
+                `10. 创建 review interaction 后，只把返回的 \`urls.web\` 和简短说明发给用户。如果提供了 \`preselected_asset_ids\`，说明“已默认选中推荐项，可直接确认或取消误选”；如果没有预选项，说明“这是候选页面，需要你确认哪些要处理”。用户在页面点击确认后，Core 会直接执行；不要要求用户回到对话框继续确认，也不要自行声称已经执行，除非工具返回的执行状态明确表示完成。`,
+                "11. 如果候选集过大或用户意图不足以确定候选范围，先请用户用时间、地点、收藏、文件名、相册、标签、人物或其他结构化条件缩小范围；不要为了避免使用 review UI 而先列编号让用户在对话里挑。",
+                "12. 删除照片只表示移入 Immich 回收站。永久删除和清空回收站不可用，不要声称已经永久删除。",
+                "13. MCP 调用失败时，原样说明工具错误；不要改用 shell 猜测工具参数，也不要据此断言 Immich 未安装。",
+                "",
+                JISHUSHELL_IMMICH_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"} immich hint in ${toolsPath}`);
+    }
+    catch (e) {
+        console.warn(`[openclaw] Failed to ${mode} TOOLS.md immich 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()}`;
+}
+// Host peripheral device nodes worth passing into a privileged OpenClaw
+// container so the agent reaches cameras / GPU / audio like a native install.
+// Directory roots are fully expanded; the prefixes match numbered top-level
+// nodes (e.g. /dev/video0, /dev/media1, /dev/mali0).
+const PERIPHERAL_DEV_ROOTS = ["/dev/dri", "/dev/snd"];
+const PERIPHERAL_DEV_PREFIXES = ["/dev/video", "/dev/media", "/dev/v4l-subdev", "/dev/mali", "/dev/dma_heap"];
+// Raw-disk / kernel-memory / device-mapper nodes that must NEVER be passed
+// into a container, even if a hand-edited `runtime.devices` entry — or a
+// symlink sitting under a peripheral prefix (e.g. /dev/videoX -> /dev/sda) —
+// resolves to one. Peripheral passthrough must not silently become raw host
+// disk or physical-memory access. Prefix match (anchored at /dev/) so
+// partitions like /dev/sda1 and /dev/nvme0n1p2 are covered too.
+const FORBIDDEN_DEVICE_RE = /^\/dev\/(mem|kmem|kmsg|port|sd[a-z]|hd[a-z]|vd[a-z]|nvme\d|mmcblk\d|sr\d|md\d|loop\d|dm-\d|mapper\/|disk\/|block\/)/;
+/**
+ * Enumerate the host's media/accelerator device nodes (plus any explicit
+ * extras from `runtime.devices`) so a privileged container can open them.
+ * Returns docker `devices` entries (real, symlink-resolved paths, deduped)
+ * and the set of owning group gids — the (non-root) container user is added
+ * to those gids via `group_add` so the 0660 root:video / root:render /
+ * root:audio nodes are actually accessible inside the container. Missing
+ * nodes are skipped, so this is a no-op on hosts without such hardware.
+ */
+function collectPrivilegedDevices(extraPaths = []) {
+    const candidates = new Set(extraPaths);
+    for (const root of PERIPHERAL_DEV_ROOTS) {
+        try {
+            for (const name of readdirSync(root))
+                candidates.add(`${root}/${name}`);
+        }
+        catch { /* root absent on this host */ }
+    }
+    try {
+        for (const name of readdirSync("/dev")) {
+            const full = `/dev/${name}`;
+            if (PERIPHERAL_DEV_PREFIXES.some((p) => full.startsWith(p)))
+                candidates.add(full);
+        }
+    }
+    catch { /* /dev unreadable (non-Linux) */ }
+    const devices = [];
+    const gids = new Set();
+    const seen = new Set();
+    for (const path of candidates) {
+        let real;
+        try {
+            real = realpathSync(path);
+        }
+        catch {
+            continue;
+        }
+        if (seen.has(real))
+            continue;
+        seen.add(real);
+        // Defense-in-depth: only ever expose real /dev nodes, and never raw
+        // disk / memory / device-mapper targets — applies to auto-discovered
+        // nodes (catches a malicious symlink under a peripheral prefix) and to
+        // explicit runtime.devices entries alike.
+        if (!real.startsWith("/dev/") || FORBIDDEN_DEVICE_RE.test(real)) {
+            console.warn(`[openclaw] refusing device passthrough "${path}" -> "${real}" (outside /dev or on denylist)`);
+            continue;
+        }
+        let st;
+        try {
+            st = statSync(real);
+        }
+        catch {
+            continue;
+        }
+        if (!st.isCharacterDevice() && !st.isBlockDevice())
+            continue;
+        devices.push({ host_path: real, container_path: real, cgroup_permissions: "rw" });
+        if (typeof st.gid === "number" && st.gid > 0)
+            gids.add(st.gid);
+    }
+    return { devices, groupAdd: [...gids].map(String) };
+}
+// ── Nomad template safety (migrated from the runtime driver) ──────────
+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 integration reaches back into instance-manager.ts for helpers that still
+// live there. Using lazy `await import()` keeps the static import graph
+// acyclic, so integrations/index.ts -> integrations/openclaw/integration.ts loads cleanly before
+// instance-manager.ts needs it.
+async function lazyIm() {
+    return await import("../../instances/manager.js");
+}
+async function resolveCoreConnectionForOpenclaw(instanceId) {
+    const corePort = getCorePort();
+    let coreHost = "host.docker.internal";
+    try {
+        const im = await lazyIm();
+        const runtime = im.getInstanceRuntime(instanceId);
+        if (!runtime?.image)
+            coreHost = getCoreLanHost();
+    }
+    catch (error) {
+        console.warn(`[openclaw] core URL runtime detection failed for ${instanceId}; using container-reachable host:`, error);
+    }
+    return {
+        coreUrl: `http://${coreHost}:${corePort}`,
+        internalToken: getInternalMcpToken(),
+    };
+}
+async function syncImmichMcpForOpenclawInstance(instanceId) {
+    const home = openclawIntegration.resolveAgentHome(instanceId);
+    const configPath = openclawConfigPath(instanceId, home);
+    const { resolveImmichConfig, } = await import("../immich/config.js");
+    const config = await resolveImmichConfig();
+    const source = {
+        kind: "connection",
+        slot: "photos",
+        consumerInstanceId: instanceId,
+    };
+    const shimDir = join(home, "__mcp_shims__", "immich");
+    const shimPath = join(shimDir, "immich-shim.js");
+    const secretPath = join(shimDir, "secret.json");
+    const wsDir = join(home, ".openclaw", "workspace");
+    if (config?.baseUrl && config.apiKey) {
+        const { IMMICH_SHIM_SECRET_FILENAME, substituteImmichShimPlaceholders, } = await import("../immich/immich-shim.js");
+        ensureDirContainer(shimDir);
+        const { coreUrl, internalToken, } = await resolveCoreConnectionForOpenclaw(instanceId);
+        writeFileSync(shimPath, substituteImmichShimPlaceholders({
+            baseUrl: config.baseUrl,
+            photoLibraryEnabled: config.mode === "managed",
+            coreUrl,
+            instanceId,
+        }), { mode: 0o644 });
+        writeFileSync(join(shimDir, IMMICH_SHIM_SECRET_FILENAME), JSON.stringify({ apiKey: config.apiKey, internalToken }) + "\n", { mode: 0o600 });
+        try {
+            chmodSync(secretPath, 0o600);
+        }
+        catch { /* best effort */ }
+        const nativeServerName = upsertOpenclawMcpServer(configPath, "immich", {
+            command: "node",
+            args: [shimPath],
+            __source: source,
+        });
+        if (!nativeServerName)
+            return "missing-config";
+        removeMcporterServers(instanceId, { source });
+        patchToolsMdImmichHint(wsDir, "install", nativeServerName);
+        notifyConfigChange(instanceId);
+        return "installed";
+    }
+    removeOpenclawMcpServers(configPath, { source });
+    removeMcporterServers(instanceId, { source });
+    rmSync(shimDir, { recursive: true, force: true });
+    patchToolsMdImmichHint(wsDir, "remove");
+    notifyConfigChange(instanceId);
+    return "removed";
+}
+function isOpenclawInstanceMetadata(instance) {
+    return Array.isArray(instance.integrations)
+        && instance.integrations.some((entry) => entry?.kind === "openclaw");
+}
+// ── 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.
+/** 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.-]+)?$/;
+/**
+ * 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
+ * integration'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,
+        };
+    }
+}
+// ── OpenClawIntegration class ─────────────────────────────────────────────
+class OpenClawIntegration {
+    kind = "openclaw";
+    displayName = "OpenClaw";
+    defaultCapabilities = DEFAULT_CAPABILITIES;
+    publicProxy = OPENCLAW_CONTROL_UI_PUBLIC_PROXY;
+    preferredHostPort = OPENCLAW_PREFERRED_HOST_PORT;
+    manifest = {
+        kind: "openclaw",
+        displayName: "OpenClaw",
+        description: "默认 runtime,支持克隆、飞书 / 企业微信插件",
+        defaultCapabilities: DEFAULT_CAPABILITIES,
+        requiresNomadDocker: false,
+        diskSpaceMB: 2048,
+        catalogGroup: "agents",
+        catalogIcon: "openclaw",
+        defaultTab: "chat",
+        supportsClone: true,
+        connectionRole: "agent",
+        defaultConnectionApplyMode: "proxy-upstream",
+        requiredForSetupReady: true,
+        defaultCreateAppSpecId: "openclaw-container",
+        createAppSpecAliases: ["openclaw", "openclaw-container.yaml"],
+        autoStartRequiresDefaultLlmProvider: true,
+        embeddedUiSurface: "integration-control-ui",
+    };
+    async registerRoutes(app) {
+        const { registerOpenclawRoutes } = await import("./routes.js");
+        registerOpenclawRoutes(app);
+    }
+    hooks = {
+        onCreatePrepare: async (ctx) => this.prepareInitialLayout(ctx),
+        onPrepareControlUiOrigin: async ({ instanceId, origin, action }) => {
+            const added = await ensureOpenclawControlUiAllowedOrigin(instanceId, origin);
+            if (added) {
+                console.log(`[openclaw-control-ui] prepared allowed origin for ${instanceId} action=${action} origin=${origin}`);
+            }
+            return added;
+        },
+        /**
+         * Full OpenClaw pre-start prelude — used to live inline in
+         * the Nomad driver's start path 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. Ensure `openclaw.json` exists + fix state-dir permissions
+         *   2. Docker-bridge: patch gateway.bind + jsproxy baseUrl
+         *   3. Seed `$HOME/.npm-global` for in-gateway "Update now"
+         *   4. Validate + image-inspect the Docker image; background-pull on miss
+         *   5. 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.
+         *
+         * Step 13 (2026-06-09): the historical "stop legacy host-mode
+         * subprocess" step has been removed. Host-mode / process-manager
+         * driven instances are no longer supported on the runtime path;
+         * `jishushell migrate legacy` must convert them to canonical
+         * `apps/<id>` layout before they can be started under Nomad.
+         */
+        onBeforeStart: async ({ instanceId }) => {
+            // 1. Config path existence check + permissions — use local resolvers
+            //    instead of lazy importing back into instance-manager.
+            let configPath;
+            try {
+                configPath = openclawIntegration.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 = openclawIntegration.resolveAgentHome(instanceId);
+                if (home)
+                    ensureOpenclawUpdateSeed(home, instanceId);
+            }
+            catch {
+                /* best effort */
+            }
+            // 4a. Patch session fence bug in OpenClaw >= 5.19
+            try {
+                const home = openclawIntegration.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 = openclawIntegration.resolveAgentHome(instanceId);
+                const im = await lazyIm();
+                const runtime = im.getInstanceRuntime(instanceId);
+                const mounts = readFileMounts(runtime);
+                if (home) {
+                    const { rebuildWorkspace } = await import("../../workspaces/builder.js");
+                    rebuildWorkspace({
+                        integrationHome: 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 = openclawIntegration.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}`);
+            }
+            try {
+                const home = openclawIntegration.resolveAgentHome(instanceId);
+                if (home) {
+                    const configPath = openclawConfigPath(instanceId, home);
+                    const runtimeConfig = existsSync(configPath)
+                        ? JSON.parse(readFileSync(configPath, "utf-8"))
+                        : {};
+                    const shouldInstallBrowserlessHint = runtimeConfig?.browser?.defaultProfile === BROWSERLESS_PROFILE;
+                    patchToolsMdBrowserlessHint(join(home, ".openclaw", "workspace"), shouldInstallBrowserlessHint ? "install" : "remove");
+                }
+            }
+            catch (e) {
+                console.warn(`[openclaw] TOOLS.md browserless 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 = openclawIntegration.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 = openclawIntegration.resolveAgentHome(instanceId);
+                if (home) {
+                    const { substituteDriveShimPlaceholders } = await import("./drive-shim.js");
+                    const { mergeMcporterServers } = await import("./mcporter.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();
+                    const { coreUrl: driveCoreUrl, internalToken, } = await resolveCoreConnectionForOpenclaw(instanceId);
+                    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 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 known match in user order wins.
+            //        - undefined/unknown          → no provider; migration/repair may
+            //                                       materialize old defaults into an
+            //                                       explicit binding, but runtime never
+            //                                       guesses from credentials.json.
+            //
+            //      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.
+            //      JishuKB remote MCP auth is stored on the managed KB runtime and
+            //      provider credentials, not in the legacy shim directory.
+            try {
+                const home = openclawIntegration.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 { mergeMcporterServers, removeMcporterServers } = await import("./mcporter.js");
+                    const { removeOpenclawMcpServers, upsertFixedOpenclawMcpServer } = await import("./native-mcp.js");
+                    const kbSource = { kind: "connection", slot: "knowledge", consumerInstanceId: instanceId };
+                    const openclawCfgPath = openclawConfigPath(instanceId, home);
+                    const cleanupManagedKb = (unavailableReason) => {
+                        removeMcporterServers(instanceId, { source: kbSource });
+                        removeOpenclawMcpServers(openclawCfgPath, { source: kbSource });
+                        notifyConfigChange(instanceId);
+                        if (unavailableReason) {
+                            patchToolsMdKbUnavailableHint(wsDir, unavailableReason);
+                        }
+                        else {
+                            patchToolsMdKbHint(wsDir, "remove");
+                        }
+                        wipeKbShimDir(home, "jishukb");
+                    };
+                    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 = resolveProviderCredentialsPath("jishu-kb-container");
+                        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 mediaInbound = join(home, ".openclaw", "media", "inbound");
+                            ensureDirContainer(mediaInbound);
+                            const authToken = typeof creds.mcpAuthToken === "string" ? creds.mcpAuthToken.trim() : "";
+                            const { discoverJishukbRemoteMcp, preflightJishukbRemoteMcp } = await import("./jishukb-native-mcp.js");
+                            const discovery = await discoverJishukbRemoteMcp({
+                                baseUrl: creds.baseUrl,
+                                authToken,
+                                expectedProfile: "openclaw",
+                            });
+                            if (!discovery.ok || !discovery.url) {
+                                const reason = `remote jishu-kb MCP discovery failed: ${discovery.reason || "no endpoint"}`;
+                                console.warn(`[openclaw] kb: ${reason}`);
+                                cleanupManagedKb(reason);
+                            }
+                            else {
+                                if (discovery.authRequired && !authToken) {
+                                    const reason = "remote jishu-kb MCP requires bearer auth but credentials are missing mcpAuthToken";
+                                    console.warn(`[openclaw] kb: ${reason}`);
+                                    cleanupManagedKb(reason);
+                                }
+                                else {
+                                    const preflight = await preflightJishukbRemoteMcp({
+                                        url: discovery.url,
+                                        authToken,
+                                        expectedProfile: "openclaw",
+                                    });
+                                    if (!preflight.ok) {
+                                        const reason = `remote jishu-kb MCP preflight failed: ${preflight.reason}`;
+                                        console.warn(`[openclaw] kb: ${reason}`);
+                                        cleanupManagedKb(reason);
+                                    }
+                                    else {
+                                        const registeredUrl = rewriteJishukbMcpUrlForOpenClawRuntime(discovery.url, instMeta?.runtime ?? {});
+                                        const entry = {
+                                            url: registeredUrl,
+                                            transport: "streamable-http",
+                                            connectionTimeoutMs: 8_000,
+                                            __source: kbSource,
+                                        };
+                                        if (authToken) {
+                                            entry.headers = { Authorization: `Bearer ${authToken}` };
+                                        }
+                                        wipeKbShimDir(home, "jishukb");
+                                        removeMcporterServers(instanceId, { source: kbSource });
+                                        const result = upsertFixedOpenclawMcpServer(openclawCfgPath, "kb", entry);
+                                        if (!result.ok) {
+                                            const reason = result.reason === "name-conflict"
+                                                ? "user-managed native MCP server 'kb' blocks managed JishuKB registration"
+                                                : "OpenClaw native config is missing; managed JishuKB registration skipped";
+                                            console.warn(`[openclaw] kb: ${reason}`);
+                                            cleanupManagedKb(reason);
+                                        }
+                                        else {
+                                            notifyConfigChange(instanceId);
+                                            patchToolsMdKbHint(wsDir, "install", "jishukb", "native", instanceId, mediaInbound);
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                        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.
+                            const reason = `jishu-kb bound but baseUrl missing at ${credPath}; native MCP registration skipped`;
+                            console.warn(`[openclaw] kb: ${reason}`);
+                            cleanupManagedKb(reason);
+                        }
+                    }
+                    else if (provider === "anythingllm") {
+                        // Wipe the OTHER provider's residue first.
+                        wipeKbShimDir(home, "jishukb");
+                        removeOpenclawMcpServers(openclawCfgPath, { source: kbSource });
+                        notifyConfigChange(instanceId);
+                        const credPath = resolveProviderCredentialsPath("anythingllm-container");
+                        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("./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.
+                        cleanupManagedKb();
+                        wipeKbShimDir(home, "anythingllm");
+                    }
+                }
+            }
+            catch (e) {
+                console.warn(`[openclaw] kb shim wiring skipped: ${e?.message ?? e}`);
+            }
+            // 4c-quinquies. Auto-wire Immich MCP when the Immich integration has
+            // endpoint credentials. The endpoint can be external or a managed
+            // immich-container instance. OpenClaw receives the stdio shim through
+            // its native `mcp.servers` config, the API key and Core internal token
+            // stay in a 0o600 sibling secret file, and user review interactions are
+            // created through Core-owned Immich routes.
+            try {
+                await syncImmichMcpForOpenclawInstance(instanceId);
+            }
+            catch (e) {
+                console.warn(`[openclaw] immich 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 = openclawIntegration.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 = openclawIntegration.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 = openclawIntegration.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("../../runtime/drivers/nomad.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 */
+        },
+        onCreate: async ({ instanceId, createArgs }) => {
+            await finalizeOpenclawCreatedInstance(instanceId, createArgs);
+        },
+        /**
+         * Surface an orphan-directory warning when the canonical integration home
+         * 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 — UNLESS the Step 5
+         * ownership marker proves Core created the tree as part of THIS
+         * instance, in which case it is safe to remove.
+         */
+        onDelete: async ({ instanceId, meta }) => {
+            const home = openclawHomeFromMetadata(meta, instanceId);
+            const instDir = framework_instanceDir(instanceId);
+            if (home.startsWith(instDir))
+                return; // inside the instance dir — rm already caught it
+            if (!existsSync(home))
+                return;
+            // Step 5: marker match is the canonical proof of Core ownership.
+            // Without it we MUST NOT delete — the directory might be user data
+            // (e.g. a hand-curated `~/.openclaw-data`) that happened to be
+            // selected as the integration home for read-only reuse.
+            if (isOwnedByInstance(home, instanceId)) {
+                try {
+                    rmSync(home, { recursive: true, force: true });
+                    return;
+                }
+                catch (e) {
+                    return {
+                        warnings: [
+                            `Failed to remove Core-owned OpenClaw integration home '${home}': ${e?.message ?? e}. Delete manually.`,
+                        ],
+                    };
+                }
+            }
+            return {
+                warnings: [
+                    `Custom OpenClaw integration home '${home}' was preserved (no Core ownership marker found). 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}`);
+            }
+        },
+    };
+    async prepareInitialLayout(ctx) {
+        const instDir = framework_instanceDir(ctx.instanceId);
+        const metaPath = instanceMetaPath(ctx.instanceId);
+        if (existsSync(metaPath))
+            throw new Error(`Instance '${ctx.instanceId}' already exists`);
+        if (existsSync(instDir) && !isPrecreatedManagedAppDir(instDir)) {
+            throw new Error(`Instance '${ctx.instanceId}' already exists`);
+        }
+        const integrationHome = ctx.integrationHome
+            ? normalizePath(ctx.integrationHome)
+            : defaultOpenclawHome(ctx.instanceId);
+        if (ctx.integrationHome) {
+            const resolved = pathResolve(integrationHome);
+            if (!resolved.startsWith(JISHUSHELL_HOME) && !resolved.startsWith("/home/")) {
+                throw new Error(`OpenClaw integration 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 integration home parent resolves outside allowed paths (symlink detected)`);
+                }
+            }
+            const shared = listInstances().filter((inst) => normalizePath(openclawHomeFromMetadata(inst, inst.id)) ===
+                normalizePath(integrationHome));
+            if (shared.length) {
+                throw new Error(`OpenClaw home '${integrationHome}' is already used by instance(s): ${shared
+                    .map((i) => i.id)
+                    .join(", ")}`);
+            }
+        }
+        if (existsSync(integrationHome)) {
+            try {
+                const entries = readdirSync(integrationHome);
+                if (entries.length > 0) {
+                    // Step 5 (bootstrap ownership marker): non-empty directories are
+                    // disambiguated via the ownership marker rather than treated as
+                    // "already installed".
+                    //   - Marker present AND `instanceId` matches → this is debris
+                    //     from a previous failed install of THE SAME instance id.
+                    //     Safe to wipe the contents and retry from scratch (preserve
+                    //     the directory itself so chown/permissions stay stable).
+                    //   - Marker present but a different `instanceId` → another
+                    //     instance owns this tree (catches the case where the path
+                    //     conflict check above missed because the other instance
+                    //     was already deleted but the home was left behind).
+                    //   - Marker absent → user data (e.g. a hand-curated
+                    //     `~/.openclaw-data` populated before installing JishuShell).
+                    //     Refuse to touch it.
+                    if (isOwnedByInstance(integrationHome, ctx.instanceId)) {
+                        for (const entry of entries) {
+                            rmSync(join(integrationHome, entry), { recursive: true, force: true });
+                        }
+                    }
+                    else {
+                        throw new Error(`OpenClaw home directory '${integrationHome}' 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(instDir);
+        try {
+            const parentGid = statSync(dirname(instDir)).gid;
+            chownSync(instDir, -1, parentGid);
+        }
+        catch {
+            /* non-root without CAP_CHOWN */
+        }
+        ensureDirContainer(integrationHome);
+        // Step 5: write the ownership marker as soon as the home directory
+        // exists. Doing this BEFORE any other subdir creation makes the
+        // marker the earliest persisted signal of Core ownership — if any
+        // subsequent setup step throws, the next install retry's pre-check
+        // will see the matching marker and proceed via the "wipe and retry"
+        // branch above. The marker is consulted only by install pre-check,
+        // install rollback, and uninstall — never by start/status/proxy
+        // paths (presence MUST NOT be interpreted as "instance running").
+        writeOwnershipMarker(integrationHome, {
+            instanceId: ctx.instanceId,
+            integrationKind: "openclaw",
+        });
+        ensureDirContainer(join(integrationHome, OPENCLAW_STATE_DIRNAME));
+        return {
+            instanceDir: instDir,
+            integrationHome,
+            primaryConfig: join(integrationHome, OPENCLAW_STATE_DIRNAME, OPENCLAW_CONFIG_FILENAME),
+            secretEnv: defaultOpenclawModelEnvFile(ctx.instanceId),
+        };
+    }
+    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 = openclawHomeFromMetadata(getInstance(instanceId), instanceId);
+        const env = { ...DEFAULT_ENV, ...(raw?.env || {}) };
+        if (home && !env.MCPORTER_CONFIG) {
+            env.MCPORTER_CONFIG = `${home}/.openclaw/workspace/config/mcporter.json`;
+        }
+        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,
+            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: resolveOpenclawContainerPort(raw),
+                    hostPort: im.getPrimaryHostPort(instanceId),
+                    visibility: "external",
+                },
+            ],
+            volumes: [{ hostPath: home, containerPath: home, mode: "rw" }],
+            health: null,
+        };
+    }
+    async getPersistedRuntimeSpec(instanceId) {
+        const im = await lazyIm();
+        const rawRuntime = im.getInstanceRuntime(instanceId);
+        const openclawHome = openclawHomeFromMetadata(getInstance(instanceId), instanceId);
+        const runtime = await this.buildRuntime(instanceId);
+        const env = { ...(runtime.env ?? {}) };
+        injectProviderHostEnv(env, instanceId);
+        delete env.JSPROXY_API_KEY;
+        return {
+            ...runtime,
+            // WorkloadCompiler contributes the compatibility entrypoint, so keep the
+            // persisted command empty here to avoid emitting both `command` and
+            // `entrypoint` in the docker config.
+            command: "",
+            user: resolveUidGid(String(rawRuntime.user || DEFAULT_USER)),
+            env,
+            volumes: buildVolumes(openclawHome, rawRuntime).map((entry) => {
+                const [hostPath, containerPath, mode = "rw"] = entry.split(":");
+                return {
+                    hostPath,
+                    containerPath,
+                    mode: mode === "ro" ? "ro" : "rw",
+                };
+            }),
+        };
+    }
+    async buildRuntimeContribution(instanceId) {
+        const im = await lazyIm();
+        const openclawHome = openclawHomeFromMetadata(getInstance(instanceId), instanceId);
+        const safeJobId = resolveNomadJobId(instanceId, this.nomadJobPrefix);
+        assertSafeTemplateId(safeJobId);
+        // Opt-in privilege relaxation (per-instance runtime.privileged). Default
+        // keeps the hardened container (read-only rootfs + the base cap_drop=ALL /
+        // no-new-privileges applied by the workload compiler). When enabled, the
+        // driverConfig deep-merges over that base to relax it to native-install-
+        // like permissions — writable rootfs, docker default caps (cap_drop=[]),
+        // no-new-privileges off — and passes through host peripheral devices +
+        // group_add of their owning gids. Toggle via `jishushell job privileged`.
+        const rawRuntime = im.getInstanceRuntime(instanceId);
+        const privileged = rawRuntime.privileged === true;
+        const peripherals = privileged
+            ? collectPrivilegedDevices(Array.isArray(rawRuntime.devices) ? rawRuntime.devices.map(String) : [])
+            : { devices: [], groupAdd: [] };
+        if (privileged) {
+            console.warn(`[openclaw] instance ${instanceId} running with privileged=true — hardening relaxed (writable rootfs, default caps, no-new-privileges off); ${peripherals.devices.length} host device(s) passed through, group_add=[${peripherals.groupAdd.join(",")}]`);
+        }
+        const driverConfig = {
+            entrypoint: ["/bin/sh", "-c", CONTAINER_PATCH_ENTRYPOINT_COMMAND, "--"],
+            readonly_rootfs: !privileged,
+            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 } },
+            ],
+            ...(privileged
+                ? {
+                    cap_drop: [],
+                    security_opt: [],
+                    ...(peripherals.devices.length > 0 ? { devices: peripherals.devices } : {}),
+                    ...(peripherals.groupAdd.length > 0 ? { group_add: peripherals.groupAdd } : {}),
+                }
+                : {}),
+        };
+        return {
+            tasks: {
+                gateway: {
+                    env: {
+                        HOME: openclawHome,
+                        OPENCLAW_HOME: openclawHome,
+                        OPENCLAW_INSTANCE_ID: instanceId,
+                        OPENCLAW_STATE_DIR: `${openclawHome}/.openclaw`,
+                        OPENCLAW_SYSTEMD_UNIT: `nomad-${safeJobId}.service`,
+                        npm_config_prefix: `${openclawHome}/.npm-global`,
+                        PIP_USER: "1",
+                        PYTHONUSERBASE: `${openclawHome}/.local`,
+                        NODE_ENV: "production",
+                        NODE_PATH: [
+                            `${openclawHome}/.npm-global/lib/node_modules`,
+                            "/app/node_modules",
+                        ].join(":"),
+                        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(":"),
+                    },
+                    driverConfig,
+                    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 { integrationKind: "openclaw", ref, digest, mode: "baseline" };
+    }
+    async getConfigMeta(instanceId) {
+        return {
+            integrationKind: "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 HermesIntegration.writeConfig uses. That
+        // function internally calls instanceManager.saveConfig, which
+        // dispatches back to this integration'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];
+    }
+    // ── 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;
+        const tempHosts = readTemporaryBrowserAllowedHostnames(instanceId);
+        const stripped = stripTemporaryBrowserAllowlistFromConfigObject(config, tempHosts);
+        // Always merge the latest upstream proxy config from instance.json
+        const meta = getInstance(instanceId);
+        if (meta?.["x-jishushell"]) {
+            stripped["x-jishushell"] = meta["x-jishushell"];
+        }
+        return stripped;
+    }
+    /**
+     * 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 tempHosts = readTemporaryBrowserAllowedHostnames(instanceId);
+        const stripped = stripTemporaryBrowserAllowlistFromConfigObject(config, tempHosts);
+        const meta = getInstance(instanceId);
+        if (meta?.["x-jishushell"]) {
+            stripped["x-jishushell"] = meta["x-jishushell"];
+        }
+        return stripped;
+    }
+    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: translate resolved `inject_as` env vars into
+     * OpenClaw-native plugin config and
+     * persist them into `openclaw.json`. Without this, the runtime env
+     * injected by the Nomad driver's connection env phase 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 wiring needs its own config-shape mapping
+     * (browser → tools.browser, llm → models.providers).
+     *
+     * The write goes through `saveNativeConfig` which preserves relevant fields
+     * from the existing canonical 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 (lifecycle connection refresh), 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.
+        }
+    }
+    listConnectionSideEffectFiles(args) {
+        const home = openclawHomeFromMetadata(getInstance(args.instanceId), args.instanceId);
+        const envFile = getRuntimeEnvFiles(args.instanceId)[0] ?? defaultOpenclawModelEnvFile(args.instanceId);
+        return [
+            join(dirname(envFile), "provider.env"),
+            openclawConfigPath(args.instanceId, home),
+            mcporterPath(args.instanceId),
+        ];
+    }
+    // ── Path resolvers (physically migrated) ───────────────────────────
+    resolveBin() {
+        return resolveOpenclawBin();
+    }
+    getSystemVersion() {
+        try {
+            return execFileSync(resolveOpenclawBin(), ["--version"], { encoding: "utf-8", timeout: 5_000 }).trim() || "unknown";
+        }
+        catch {
+            return "unknown";
+        }
+    }
+    resolveAgentHome(instanceId) {
+        const meta = getInstance(instanceId);
+        return openclawHomeFromMetadata(meta, instanceId);
+    }
+    summarizeRecentBrowserSession(instanceId) {
+        return summarizeRecentOpenclawBrowserSession(instanceId);
+    }
+    async syncImmichMcpForAllInstances() {
+        const updated = [];
+        const skipped = [];
+        for (const instance of listInstances()) {
+            const instanceId = typeof instance.id === "string" ? instance.id : "";
+            if (!instanceId)
+                continue;
+            try {
+                if (!isOpenclawInstanceMetadata(instance))
+                    continue;
+                await syncImmichMcpForOpenclawInstance(instanceId);
+                updated.push(instanceId);
+            }
+            catch (error) {
+                skipped.push({ instanceId, error: error?.message ?? String(error) });
+            }
+        }
+        return { updated, skipped };
+    }
+    /** Env vars OpenClaw's CLI needs when backup-manager runs it as a subprocess. */
+    buildCliEnv(instanceId) {
+        return { OPENCLAW_HOME: this.resolveAgentHome(instanceId) };
+    }
+    /**
+     * Rewrite only the host-side published gateway port (canonical Step 2
+     * integration contract).
+     *
+     * Domain semantics:
+     *   - `hostPort` is Core-allocated and may be rewritten freely.
+     *   - `containerPort` is the in-container OpenClaw listener and MUST stay
+     *     stable across host-port reallocations.
+     *
+     * Missing canonical `runtime.ports[]` is a migration error for ordinary
+     * lifecycle paths; this method must not synthesize runtime facts.
+     */
+    reallocateRuntimePort(runtime, newPort) {
+        if (Array.isArray(runtime.ports) && runtime.ports.length > 0) {
+            runtime.ports = runtime.ports.map((port, index) => {
+                const isGateway = port?.name === "gateway" || index === 0;
+                return isGateway
+                    ? { ...port, hostPort: newPort }
+                    : port;
+            });
+            return;
+        }
+        throw new Error("[openclaw-integration] reallocateRuntimePort: instance is missing canonical "
+            + "runtime.ports[]; run migration or repair before reallocating.");
+    }
+    nomadJobPrefix = "openclaw-";
+    // Must match the path referenced by this integration'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
+     * canonical integration-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 = openclawHomeFromMetadata(meta, 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;
+    }
+    // ── Legacy runtime install ────────────────────────────────────────────
+    //
+    // 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 integration'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 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 */ }
+        // Prefer the version pinned into the docker image tag — that is what
+        // instances actually run in the default docker deployment. The host-npm
+        // package.json (readInstalledOpenclawVersion) is unrelated to the running
+        // container, so reporting it made the UI show "latest" while the container
+        // still ran the old build after an update. Fall back to host-npm only when
+        // no image is ready (legacy npm path).
+        const imageVersion = imageReady ? versionFromImageTag(imageTag) : "";
+        const version = imageVersion || (pkgInstalled ? readInstalledOpenclawVersion() : "");
+        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 "";
+}
+/**
+ * Extract a semver-ish version from a pinned image tag, e.g.
+ * `ghcr.io/x-aijishu/openclaw-runtime:2026.6.10` -> `2026.6.10`. Returns "" when
+ * the tag carries no version (mutable `:latest`/`:slim`, or the only colon is a
+ * registry port).
+ */
+function versionFromImageTag(imageTag) {
+    if (!imageTag)
+        return "";
+    const colonIdx = imageTag.lastIndexOf(":");
+    const slashIdx = imageTag.lastIndexOf("/");
+    if (colonIdx <= slashIdx)
+        return "";
+    const tag = imageTag.slice(colonIdx + 1);
+    return /^\d+\.\d+\.\d+/.test(tag) ? tag : "";
+}
+// 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 loadEffectiveConfig(instanceId) {
+    migrateLegacyOuterConfigOnce(instanceId);
+    const runtimePath = openclawConfigPath(instanceId);
+    if (existsSync(runtimePath))
+        return loadJsonSafe(runtimePath);
+    return null;
+}
+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(config) {
+    const configToWrite = structuredClone(config);
+    delete configToWrite["x-jishushell"];
+    const providers = configToWrite.models?.providers || {};
+    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;
+        // Step 7: normal OpenClaw config saves must not write legacy
+        // provider-specific *_API_KEY env variables. API keys for the active
+        // upstream are persisted by llm-proxy.saveInstanceConfig() into
+        // provider.env; if a raw provider apiKey leaks into this lower-level save
+        // path, strip it from openclaw.json rather than creating a second secret
+        // source.
+        delete p.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;
+}
+/**
+ * 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 `OpenClawIntegration.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 = openclawHomeFromMetadata(getInstance(instanceId), 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 = openclawHomeFromMetadata(getInstance(instanceId), 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 = openclawHomeFromMetadata(getInstance(instanceId), 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("../../runtime/drivers/nomad.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`, updates
+ * env files with provider API keys, preserves backend-managed fields, and
+ * fires config-change listeners.
+ *
+ * Step 6 boundary: normal saves must not mirror into the legacy outer
+ * `$OPENCLAW_HOME/openclaw.json`. Any old outer config is migrated once before
+ * writing canonical state, then removed.
+ *
+ * Physically migrated from `instance-manager.saveConfig`.
+ */
+function saveNativeConfigImpl(instanceId, config) {
+    const configPath = openclawConfigPath(instanceId);
+    if (!existsSync(framework_instanceDir(instanceId)))
+        return false;
+    migrateLegacyOuterConfigOnce(instanceId);
+    // Save x-jishushell metadata to instance.json (not openclaw.json)
+    if (config["x-jishushell"]) {
+        updateInstanceMeta(instanceId, { "x-jishushell": config["x-jishushell"] });
+    }
+    const configToWrite = prepareConfigForSave(config);
+    const temporaryHosts = readTemporaryBrowserAllowedHostnames(instanceId);
+    const configWithTemporaryHosts = applyTemporaryBrowserAllowlistToConfigObject(configToWrite, temporaryHosts);
+    // If openclaw-lark is enabled, resolve which feishu plugin to use
+    if (configWithTemporaryHosts.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)) {
+            configWithTemporaryHosts.plugins.entries.feishu = { enabled: true };
+            delete configWithTemporaryHosts.plugins.entries["openclaw-lark"];
+        }
+        else if (existsSync(stockFeishu)) {
+            configWithTemporaryHosts.plugins ??= {};
+            configWithTemporaryHosts.plugins.entries ??= {};
+            configWithTemporaryHosts.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) {
+                configWithTemporaryHosts.plugins ??= {};
+                configWithTemporaryHosts.plugins.installs = { ...existing.plugins.installs, ...configWithTemporaryHosts.plugins?.installs };
+            }
+            if (existing.plugins?.entries && configWithTemporaryHosts.plugins?.entries) {
+                for (const [key, val] of Object.entries(configWithTemporaryHosts.plugins.entries)) {
+                    const old = existing.plugins.entries[key];
+                    if (val && typeof val === "object" && !Array.isArray(val) && old && typeof old === "object") {
+                        configWithTemporaryHosts.plugins.entries[key] = { ...old, ...val };
+                    }
+                }
+            }
+            if (existing.channels && configWithTemporaryHosts.channels) {
+                for (const [key, val] of Object.entries(configWithTemporaryHosts.channels)) {
+                    const old = existing.channels[key];
+                    if (val && typeof val === "object" && !Array.isArray(val) && old && typeof old === "object") {
+                        configWithTemporaryHosts.channels[key] = { ...old, ...val };
+                    }
+                }
+            }
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    // Backup + atomic write
+    if (existsSync(configPath)) {
+        copyFileSync(configPath, configPath + ".bak");
+    }
+    const configJson = JSON.stringify(configWithTemporaryHosts, null, 2);
+    ensureDirContainer(dirname(configPath));
+    writeConfigFile(configPath + ".tmp", configJson);
+    JSON.parse(readFileSync(configPath + ".tmp", "utf-8"));
+    renameSync(configPath + ".tmp", configPath);
+    chownToServiceUser(configPath);
+    // Notify listeners (LLM proxy cache invalidation etc.)
+    notifyConfigChange(instanceId);
+    return true;
+}
+export const openclawIntegration = new OpenClawIntegration();
+registerIntegration(openclawIntegration);
+//# sourceMappingURL=integration.js.map