jishushell 0.5.22 → 0.6.18

package/dist/services/instance-manager.js

@@ -1,1296 +0,0 @@
-import { execFileSync } from "child_process";
-import { chownSync, closeSync, existsSync, openSync, readFileSync, readdirSync, renameSync, statSync, } from "fs";
-import { rm as rmAsync } from "fs/promises";
-import { createServer as netCreateServer } from "net";
-import { networkInterfaces, userInfo } from "os";
-import { dirname, join, resolve } from "path";
-import * as config from "../config.js";
-import { safeReadJson, safeWriteJson } from "../utils/safe-json.js";
-import { ensureDirContainer, writeSecretFile } from "../utils/fs.js";
-// runtime/index.ts gets imported only for framework-level adapter lookups
-// (defaultGatewayPort fallback). Adapters statically import BACK into this
-// file for primitives; that static cycle is safe because no top-level code
-// in adapters references instance-manager exports.
-import { getAdapter, resolveAgentType } from "./runtime/index.js";
-import { backfillInstanceMeta } from "./runtime/migrations.js";
-function getConfigValue(name) {
-    return name in config ? config[name] : undefined;
-}
-function resolveConfigPath(value, fallback) {
-    return typeof value === "string" && value.trim() ? value : fallback;
-}
-const JISHUSHELL_HOME = resolveConfigPath(getConfigValue("JISHUSHELL_HOME"), resolve(process.env.HOME ?? userInfo().homedir, ".jishushell"));
-const APPS_DIR = resolveConfigPath(getConfigValue("APPS_DIR"), join(JISHUSHELL_HOME, "apps"));
-const BACKUPS_DIR = resolveConfigPath(getConfigValue("BACKUPS_DIR"), join(JISHUSHELL_HOME, "backups"));
-const INSTANCES_DIR = resolveConfigPath(getConfigValue("INSTANCES_DIR"), join(JISHUSHELL_HOME, "instances"));
-const getPanelConfigValue = getConfigValue("getPanelConfig");
-const _getPanelConfig = typeof getPanelConfigValue === "function"
-    ? getPanelConfigValue
-    : () => ({});
-const _configChangeListeners = [];
-export function onConfigChange(listener) {
-    _configChangeListeners.push(listener);
-    return () => {
-        const idx = _configChangeListeners.indexOf(listener);
-        if (idx >= 0)
-            _configChangeListeners.splice(idx, 1);
-    };
-}
-/**
- * Fire the config-change listener fan-out. Adapters call this after
- * `saveNativeConfig()` so LLM proxy / config editors pick up the change.
- */
-export function notifyConfigChange(instanceId) {
-    for (const listener of _configChangeListeners) {
-        try {
-            listener(instanceId);
-        }
-        catch { /* ignore listener errors */ }
-    }
-}
-const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
-// ── Path helpers (framework-level) ──
-//
-// Physical definitions live in config.ts alongside INSTANCES_DIR so
-// tests that mock instance-manager.js don't lose path resolution. The
-// re-exports below preserve the existing import surface.
-function appInstanceDir(instanceId) {
-    return join(APPS_DIR, instanceId);
-}
-function hasAppInstallMarkers(dir) {
-    return existsSync(join(dir, "manifest.json")) && existsSync(join(dir, "app-spec.yaml"));
-}
-function hasIncompleteAppInstallShadow(dir) {
-    const hasManifest = existsSync(join(dir, "manifest.json"));
-    const hasSpec = existsSync(join(dir, "app-spec.yaml"));
-    return (hasManifest || hasSpec) && !(hasManifest && hasSpec);
-}
-function resolveInstanceRoot(instanceId) {
-    const appDir = appInstanceDir(instanceId);
-    if (hasAppInstallMarkers(appDir) || (existsSync(join(appDir, "instance.json")) && !hasIncompleteAppInstallShadow(appDir))) {
-        return appDir;
-    }
-    // V1 legacy grandfathered path: fall through to `instances/<id>/` only when
-    // the legacy dir has real content. New instances (neither dir exists) get
-    // the V2 `apps/<id>/` default so they land in the new layout from day one.
-    const legacyDir = join(INSTANCES_DIR, instanceId);
-    if (existsSync(join(legacyDir, "instance.json"))) {
-        return legacyDir;
-    }
-    return appDir;
-}
-export function instanceDir(instanceId) {
-    return resolveInstanceRoot(instanceId);
-}
-export function instanceMetaPath(instanceId) {
-    return join(instanceDir(instanceId), "instance.json");
-}
-// §32.2 / §32.8: `defaultOpenclawHome` / `openclawStateDir` /
-// `openclawConfigPathInternal` / `legacyOpenclawConfigPath` /
-// `getOpenclawHomeInternal` / `defaultModelEnvFile` physically migrated
-// into `src/services/runtime/adapters/openclaw.ts`. Callers reach them
-// through `getAdapter("openclaw").resolve*()` methods.
-// Re-export `defaultModelEnvFile` as a dispatch wrapper for any
-// remaining framework callers that need an env file path.
-export function defaultModelEnvFile(instanceId) {
-    return join(instanceDir(instanceId), "model.env");
-}
-export function normalizePath(p) {
-    return resolve(p.replace(/^~/, userInfo().homedir));
-}
-// ── Gateway port helpers ──
-// Track in-flight port allocations to prevent race conditions
-// between concurrent createInstance() calls.
-const _pendingPorts = new Set();
-/**
- * Read the gateway port out of a persisted runtime record. Tries
- * `runtime.ports[]` first (generic framework contract); on miss,
- * asks the runtime adapter for its legacy fallback (e.g. OpenClaw's
- * `env.OPENCLAW_GATEWAY_PORT` / `args --port N`).
- */
-export function extractGatewayPort(runtime, agentType) {
-    if (!runtime)
-        return null;
-    // Primary: RuntimeSpec.ports[] declaration. Prefer a port literally named
-    // "gateway" (the convention OpenClaw / Hermes templates use); otherwise
-    // fall back to the first declared port. This makes the helper work for
-    // generic V2 apps (SearXNG = "http", Open WebUI = "http", Ollama =
-    // "ollama", etc.) without forcing every template to rename its port.
-    const ports = Array.isArray(runtime.ports) ? runtime.ports : [];
-    for (const port of ports) {
-        if (port?.name === "gateway" && Number.isInteger(port.hostPort) && port.hostPort > 0) {
-            return port.hostPort;
-        }
-    }
-    for (const port of ports) {
-        if (Number.isInteger(port?.hostPort) && port.hostPort > 0) {
-            return port.hostPort;
-        }
-    }
-    // Fall back to the adapter's legacy reader. Default agentType "openclaw".
-    try {
-        const adapter = getAdapter(agentType || "openclaw");
-        if (typeof adapter.readLegacyGatewayPort === "function") {
-            return adapter.readLegacyGatewayPort(runtime);
-        }
-    }
-    catch {
-        /* adapter not registered — no fallback */
-    }
-    return null;
-}
-function usedGatewayPorts(excludeId) {
-    const ports = new Set();
-    for (const inst of listInstances()) {
-        if (inst.id === excludeId)
-            continue;
-        const port = extractGatewayPort(inst.runtime);
-        if (port)
-            ports.add(port);
-    }
-    return ports;
-}
-function safePort(port) {
-    if (!Number.isInteger(port) || port < 1 || port > 65535)
-        throw new Error(`Invalid port: ${port}`);
-    return String(port);
-}
-/**
- * Probes whether a port is currently held by any process on the host.
- *
- * Binds four addresses concurrently — `0.0.0.0`, `127.0.0.1`, `::` (v6-only),
- * and `::1` — and treats the port as busy if any probe returns EADDRINUSE.
- * The single-`0.0.0.0` probe used by the earlier revision was sufficient on
- * Linux (where binding `0.0.0.0` conflicts with any pre-existing loopback
- * listener on the same port) but silently passed on macOS, where BSD socket
- * semantics let a wildcard v4 bind coexist with a `127.0.0.1` listener. A
- * user running a natively-installed openclaw bound to `127.0.0.1:18789`
- * would then be invisible to jishushell, so port allocation would assign
- * 18789 to a new instance and the gateway would silently fail to bind at
- * start time. Probing the loopback addresses directly closes that gap.
- */
-export function isPortInUse(port) {
-    if (!Number.isInteger(port) || port < 1 || port > 65535)
-        return Promise.resolve(false);
-    const probeAt = (host, opts = {}) => new Promise((resolve) => {
-        const server = netCreateServer();
-        server.once("error", (err) => {
-            if (err?.code === "EADDRINUSE")
-                return resolve(true);
-            // EACCES / EADDRNOTAVAIL / ENOTSUP / EINVAL mean we could not even
-            // attempt the bind (restricted port, address family unsupported on
-            // this host, etc). Report "not busy" from this probe so one bad
-            // locus doesn't falsely block the whole port — the other probes
-            // still cover their respective loci.
-            if (err?.code && err.code !== "EACCES" && err.code !== "EADDRNOTAVAIL"
-                && err.code !== "ENOTSUP" && err.code !== "EINVAL" && err.code !== "EAFNOSUPPORT") {
-                console.warn(`[port-probe] bind ${host}:${port} failed with ${err.code}: ${err.message}; treating locus as free`);
-            }
-            resolve(false);
-        });
-        server.once("listening", () => {
-            server.close(() => resolve(false));
-        });
-        server.listen({ port, host, ...opts });
-    });
-    // Run probes sequentially, not in parallel: two probes on the same port
-    // collide with each other (the first bind on 0.0.0.0 makes the second
-    // bind on 127.0.0.1 hit EADDRINUSE), which would make every port look
-    // busy. Short-circuit on the first busy locus to keep the common case
-    // (port free) close to single-probe latency.
-    return (async () => {
-        const loci = [
-            ["0.0.0.0", {}],
-            ["127.0.0.1", {}],
-            ["::", { ipv6Only: true }],
-            ["::1", {}],
-        ];
-        for (const [host, opts] of loci) {
-            if (await probeAt(host, opts))
-                return true;
-        }
-        return false;
-    })();
-}
-/**
- * Kind-agnostic gateway port allocator. Callers (adapters) pass their own
- * `defaultPort` — the framework no longer hardcodes OpenClaw / Hermes base
- * ports here. Walks upward from `defaultPort` until a free port is found
- * that is neither held by an existing instance nor by any process on the
- * host. Concurrent callers coordinate via `_pendingPorts`.
- *
- * Caller must release the allocated port via {@link releasePendingPort}
- * after persisting it into instance metadata (or on failure).
- */
-export async function allocateGatewayPort(instanceId, defaultPort) {
-    const used = usedGatewayPorts(instanceId);
-    const skipped = [];
-    let port = defaultPort;
-    while (true) {
-        if (port > 65535) {
-            throw new Error(`No available gateway port found (all ports ${defaultPort}-65535 in use)`);
-        }
-        if (used.has(port) || _pendingPorts.has(port)) {
-            skipped.push(port);
-            port++;
-            continue;
-        }
-        // Reserve BEFORE the async isPortInUse check to prevent concurrent callers
-        // from selecting the same port during the await gap.
-        _pendingPorts.add(port);
-        try {
-            if (await isPortInUse(port)) {
-                _pendingPorts.delete(port);
-                skipped.push(port);
-                port++;
-                continue;
-            }
-            return { port, skipped };
-        }
-        catch {
-            _pendingPorts.delete(port);
-            // Skip this port on a transient OS error rather than failing the entire
-            // allocation — a single bad port check should not prevent instance creation.
-            console.warn(`[instance] Port ${port} availability check failed, trying next port`);
-            skipped.push(port);
-            port++;
-            continue;
-        }
-    }
-}
-/** Release a port previously reserved by {@link allocateGatewayPort}. */
-export function releasePendingPort(port) {
-    _pendingPorts.delete(port);
-}
-// ── Runtime / config builders ──
-export function getResolvedOpenclawBin() {
-    try {
-        const a = getAdapter("openclaw");
-        return typeof a.resolveBin === "function"
-            ? a.resolveBin()
-            : "/usr/local/bin/openclaw";
-    }
-    catch {
-        return "/usr/local/bin/openclaw";
-    }
-}
-/**
- * When jishushell runs as root (e.g. systemd service), returns the actual
- * non-root user that should own instance files and run openclaw processes.
- * Returns null when not running as root or when no suitable non-root user is found.
- */
-export function resolveServiceUser() {
-    if (typeof process.getuid !== "function" || process.getuid() !== 0)
-        return null;
-    // SUDO_USER is set when launched via `sudo`
-    const sudoUser = process.env.SUDO_USER;
-    if (sudoUser && sudoUser !== "root") {
-        try {
-            const uid = parseInt(execFileSync("id", ["-u", sudoUser], { encoding: "utf-8" }).trim(), 10);
-            const gid = parseInt(execFileSync("id", ["-g", sudoUser], { encoding: "utf-8" }).trim(), 10);
-            if (!isNaN(uid) && !isNaN(gid))
-                return { username: sudoUser, uid, gid };
-        }
-        catch { /* fall through */ }
-    }
-    // Fall back to owner of INSTANCES_DIR or JISHUSHELL_HOME
-    try {
-        const target = existsSync(INSTANCES_DIR) ? INSTANCES_DIR : JISHUSHELL_HOME;
-        const uid = statSync(target).uid;
-        if (uid !== 0) {
-            const username = execFileSync("id", ["-un", String(uid)], { encoding: "utf-8" }).trim();
-            const gid = parseInt(execFileSync("id", ["-g", username], { encoding: "utf-8" }).trim(), 10);
-            if (!isNaN(gid))
-                return { username, uid, gid };
-        }
-    }
-    catch { /* fall through */ }
-    return null;
-}
-/**
- * When running as root, chown a file (and its .bak) to the service user so the
- * openclaw process (running as that user) can read/write its own data files.
- * No-op when not running as root.
- */
-export function chownToServiceUser(...paths) {
-    const svc = resolveServiceUser();
-    if (!svc)
-        return;
-    for (const p of paths) {
-        for (const f of [p, p + ".bak"]) {
-            try {
-                if (existsSync(f))
-                    chownSync(f, svc.uid, svc.gid);
-            }
-            catch { /* best effort */ }
-        }
-    }
-}
-// §32.2 / §32.8: buildDefaultRuntime + starterConfig physically migrated
-// into src/services/runtime/adapters/openclaw.ts. Framework layer no
-// longer owns OpenClaw runtime templates or default config shape.
-// ── Env file helpers ──
-export function parseEnvFile(path) {
-    const env = {};
-    if (!existsSync(path))
-        return env;
-    for (let line of readFileSync(path, "utf-8").split("\n")) {
-        line = line.trim();
-        if (!line || line.startsWith("#"))
-            continue;
-        if (line.startsWith("export "))
-            line = line.slice(7).trimStart();
-        if (!line.includes("="))
-            continue;
-        const eqIdx = line.indexOf("=");
-        const key = line.slice(0, eqIdx).trim();
-        let value = line.slice(eqIdx + 1).trim();
-        if (!ENV_KEY_RE.test(key))
-            continue;
-        if (value.length >= 2 && value[0] === value[value.length - 1] && (value[0] === "'" || value[0] === '"')) {
-            value = value.slice(1, -1);
-        }
-        env[key] = value;
-    }
-    return env;
-}
-function quoteEnvValue(value) {
-    if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value))
-        return value;
-    return JSON.stringify(value);
-}
-export function updateEnvFile(path, updates) {
-    ensureDirContainer(dirname(path));
-    const existing = existsSync(path) ? readFileSync(path, "utf-8").split("\n") : [];
-    const remaining = { ...updates };
-    const newLines = [];
-    for (const rawLine of existing) {
-        const stripped = rawLine.trim();
-        const candidate = stripped.startsWith("export ") ? stripped.slice(7).trimStart() : stripped;
-        if (!candidate || candidate.startsWith("#") || !candidate.includes("=")) {
-            newLines.push(rawLine);
-            continue;
-        }
-        const key = candidate.slice(0, candidate.indexOf("=")).trim();
-        if (!ENV_KEY_RE.test(key) || !(key in remaining)) {
-            newLines.push(rawLine);
-            continue;
-        }
-        const value = remaining[key];
-        delete remaining[key];
-        if (value === "")
-            continue;
-        const prefix = stripped.startsWith("export ") ? "export " : "";
-        newLines.push(`${prefix}${key}=${quoteEnvValue(value)}`);
-    }
-    for (const [key, value] of Object.entries(remaining)) {
-        if (!ENV_KEY_RE.test(key) || value === "")
-            continue;
-        newLines.push(`${key}=${quoteEnvValue(value)}`);
-    }
-    const output = newLines.join("\n").trimEnd();
-    const content = output ? output + "\n" : "";
-    // Atomic write: tmp then rename to protect against RPi power loss
-    const tmp = path + ".tmp";
-    writeSecretFile(tmp, content);
-    renameSync(tmp, path);
-}
-// ── Provider key helpers ──
-export function inferProviderApiKeyEnvName(providerId) {
-    let normalized = providerId.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_|_$/g, "").toUpperCase();
-    if (!normalized)
-        normalized = "OPENCLAW_PROVIDER";
-    return `${normalized}_API_KEY`;
-}
-// §32.2 / §32.8: hasConfiguredValue / injectProviderApiKeys /
-// applyFeishuDebugAccessDefaults / prepareConfigForSave physically
-// migrated into `src/services/runtime/adapters/openclaw.ts`.
-// §32.2 / §32.8: Channel plugin helpers (CHANNEL_PLUGIN_MAP,
-// installChannelPlugin, stripImBindings, etc.) physically migrated
-// into `src/services/runtime/adapters/openclaw.ts`.
-// ── Public API ──
-/**
- * Probe whether a file is readable by the current process. Used to
- * distinguish "primary missing / corrupted" (recoverable via safeReadJson's
- * .bak chain) from "primary exists but permission denied" (EACCES — the
- * common sudo-script footgun that leaves root-owned files). safeReadJson
- * swallows every read error internally and returns null, so without this
- * probe an unreadable primary looks identical to a truly-gone instance.
- */
-function probeReadable(path) {
-    if (!existsSync(path))
-        return null;
-    try {
-        const fd = openSync(path, "r");
-        closeSync(fd);
-        return null;
-    }
-    catch (e) {
-        return e;
-    }
-}
-export function listInstances() {
-    const deduped = new Map();
-    for (const rootDir of [APPS_DIR, INSTANCES_DIR]) {
-        if (!existsSync(rootDir))
-            continue;
-        const entries = readdirSync(rootDir).sort();
-        for (const name of entries) {
-            if (deduped.has(name))
-                continue;
-            const metaPath = join(rootDir, name, "instance.json");
-            const dirPath = join(rootDir, name);
-            try {
-                if (!statSync(dirPath).isDirectory())
-                    continue;
-                if (rootDir === APPS_DIR && hasIncompleteAppInstallShadow(dirPath))
-                    continue;
-                if (!existsSync(metaPath))
-                    continue;
-                // Use safeReadJson so primary instance.json that was corrupted or
-                // deleted mid-rename falls back to the .bak chain maintained by
-                // safeWriteJson. Without this, an interrupted safeWriteJson call
-                // would silently drop the instance from every list/get hot path
-                // even though the backup chain still holds valid content on disk.
-                const meta = safeReadJson(metaPath, `instance:${name}`);
-                if (meta) {
-                    const normalised = backfillInstanceMeta(meta);
-                    deduped.set(name, normalised);
-                    continue;
-                }
-                // safeReadJson → null can mean any of (a) primary missing + no
-                // backups, (b) all candidates unparseable, (c) permission denied.
-                // (a) and (b) are legitimate "drop from list" cases; (c) is the
-                // sudo-script footgun and must be logged loudly so the operator
-                // doesn't just see an empty instance list with no hint why.
-                const readErr = probeReadable(metaPath);
-                if (readErr && readErr.code === "EACCES") {
-                    console.error(`[instance-manager] cannot read instance '${name}': ${readErr.message}. ` +
-                        `Check file ownership with: ls -la ${metaPath}`);
-                }
-            }
-            catch (e) {
-                // Fallback for failures before the safeReadJson call (e.g. statSync
-                // on a directory we can't enter). Still log instead of silently
-                // dropping the entry.
-                console.error(`[instance-manager] cannot read instance '${name}': ${e.message}`);
-            }
-        }
-    }
-    return [...deduped.values()];
-}
-export function getInstance(instanceId) {
-    const metaPath = instanceMetaPath(instanceId);
-    // Go through safeReadJson so primary missing/corrupted instance.json
-    // is still served from the .bak chain. Returning null on "truly gone"
-    // (no primary, no backups) keeps the existing 404 behavior intact.
-    const meta = safeReadJson(metaPath, `instance:${instanceId}`);
-    if (meta) {
-        const normalised = backfillInstanceMeta(meta);
-        return normalised;
-    }
-    // safeReadJson swallows every read error internally, which is exactly
-    // wrong for the EACCES case — a root-owned primary would silently
-    // return null and callers would report "Instance not found" instead
-    // of the actionable "check file ownership" message. Re-probe to
-    // distinguish and throw on permission denial. Missing/corrupted with
-    // no backup still returns null (→ 404 upstream).
-    const readErr = probeReadable(metaPath);
-    if (readErr && readErr.code === "EACCES") {
-        throw new Error(`Cannot read instance '${instanceId}' metadata: ${readErr.message}. ` +
-            `Check file ownership with: ls -la ${metaPath}`);
-    }
-    return null;
-}
-// §32.2 / §32.8: `createInstance` physically migrated into
-// `src/services/runtime/adapters/openclaw.ts:OpenClawAdapter.createInstance`.
-// Framework callers now dispatch via `getAdapter(agentType).createInstance(args)`.
-export function updateInstance(instanceId, name, description) {
-    const meta = getInstance(instanceId);
-    if (!meta)
-        return null;
-    if (name != null)
-        meta.name = name;
-    if (description != null)
-        meta.description = description;
-    safeWriteJson(instanceMetaPath(instanceId), meta);
-    chownToServiceUser(instanceMetaPath(instanceId));
-    return meta;
-}
-// §32.2 / §32.8: `createHermesInstance` + `InstanceCreationRejected`
-// physically migrated into `src/services/runtime/adapters/hermes.ts`
-// and `src/services/runtime/errors.ts`. Framework callers dispatch via
-// `getAdapter(agentType).createInstance(args)` uniformly.
-export function updateInstanceMeta(instanceId, patch) {
-    const metaPath = instanceMetaPath(instanceId);
-    const meta = safeReadJson(metaPath, "instance-meta") || {};
-    Object.assign(meta, patch);
-    safeWriteJson(metaPath, meta);
-}
-export async function deleteInstance(instanceId, purgeBackups = false) {
-    const d = instanceDir(instanceId);
-    if (!existsSync(d))
-        return { ok: false, warnings: ["Instance directory not found"] };
-    const warnings = [];
-    // Cancel auto-backup timer and any queued jobs for this instance
-    import("./backup-manager.js").then(({ cancelAutoBackup, getQueueStatus, cancelJob }) => {
-        cancelAutoBackup(instanceId);
-        // Cancel queued (not yet running) jobs for this instance
-        const q = getQueueStatus();
-        for (const job of q.queued) {
-            if (job.instanceId === instanceId)
-                cancelJob(job.id);
-        }
-    }).catch(() => { });
-    // Cache metadata BEFORE deletion so adapters can inspect it after rm.
-    const meta = getInstance(instanceId);
-    const agentType = resolveAgentType(meta);
-    // Adapter-owned pre-delete hook. Adapters use this to emit advisories
-    // for resources that live outside the instance dir (legacy
-    // `openclaw_home`, named docker volumes, etc). Errors are collected
-    // into the response so one adapter misbehaving can't block removal.
-    try {
-        const legacyAppType = typeof meta?.app_type === "string" ? meta.app_type.trim() : "";
-        if ((legacyAppType === "custom" || legacyAppType === "ollama") && meta) {
-            const { getAppManager } = await import("./app/registry.js");
-            const manager = getAppManager(legacyAppType);
-            if (manager.onDelete) {
-                await manager.onDelete(instanceId);
-            }
-        }
-        else {
-            const adapter = getAdapter(agentType);
-            if (adapter.hooks?.onDelete && meta) {
-                const hookResult = await adapter.hooks.onDelete({ instanceId, meta });
-                if (hookResult && Array.isArray(hookResult.warnings)) {
-                    warnings.push(...hookResult.warnings);
-                }
-            }
-        }
-    }
-    catch (e) {
-        warnings.push(`adapter onDelete hook failed: ${e.message}`);
-    }
-    // Clean up Nomad Variables (async, best-effort)
-    import("./nomad-manager.js").then((nm) => {
-        nm.purgeInstanceVariables(instanceId).catch((e) => {
-            console.warn(`[instance] Failed to purge Nomad variables for ${instanceId}:`, e.message);
-        });
-    }).catch((e) => {
-        console.warn(`[instance] Could not load nomad-manager for cleanup:`, e.message);
-    });
-    // Async rm so the Node event loop stays responsive during large deletes:
-    // a fresh instance with a just-installed openclaw package can be 1+ GB
-    // with hundreds of nested dirs, which takes 30-60s to unlink on SD storage.
-    // rmSync would block every other HTTP request for that whole window.
-    let dirDeleted = false;
-    try {
-        await rmAsync(d, { recursive: true, force: true });
-        dirDeleted = true;
-    }
-    catch {
-        try {
-            execFileSync("sudo", ["rm", "-rf", d], { timeout: 300000 });
-            dirDeleted = true;
-        }
-        catch (e) {
-            warnings.push(`Failed to delete instance directory: ${e.message}`);
-        }
-    }
-    // (Custom openclaw_home orphan warning emitted by OpenClawAdapter.hooks.onDelete.)
-    // Handle backups (stored in separate directory, not affected by the
-    // instance rm above). Backups can be hundreds of MB each and accumulate
-    // across retention windows, so use the same async rm path to keep the
-    // event loop responsive.
-    const backupDir = join(BACKUPS_DIR, instanceId);
-    if (purgeBackups && existsSync(backupDir)) {
-        try {
-            await rmAsync(backupDir, { recursive: true, force: true });
-        }
-        catch (e) {
-            warnings.push(`Failed to delete backups: ${e.message}`);
-        }
-    }
-    else if (existsSync(backupDir)) {
-        warnings.push(`Backups preserved at ${backupDir}`);
-    }
-    return { ok: dirDeleted, warnings: warnings.length ? warnings : undefined };
-}
-// §32.2 / §32.8: getConfig / getStoredConfig / saveConfig
-// physically migrated into OpenClawAdapter. Framework callers now
-// dispatch via `getAdapter(agentType).saveNativeConfig / .getNativeConfig`.
-// Back-compat wrappers below preserve the legacy sync API shape for
-// existing call sites (llm-proxy, routes, backup-manager).
-export function getConfig(instanceId) {
-    const meta = getInstance(instanceId);
-    const agentType = resolveAgentType(meta);
-    try {
-        const adapter = getAdapter(agentType);
-        return typeof adapter.getNativeConfig === "function"
-            ? adapter.getNativeConfig(instanceId)
-            : null;
-    }
-    catch {
-        return null;
-    }
-}
-export function getStoredConfig(instanceId) {
-    const meta = getInstance(instanceId);
-    const agentType = resolveAgentType(meta);
-    try {
-        const adapter = getAdapter(agentType);
-        return typeof adapter.getStoredNativeConfig === "function"
-            ? adapter.getStoredNativeConfig(instanceId)
-            : null;
-    }
-    catch {
-        return null;
-    }
-}
-export async function saveConfig(instanceId, config) {
-    const meta = getInstance(instanceId);
-    const agentType = resolveAgentType(meta);
-    try {
-        const adapter = getAdapter(agentType);
-        if (typeof adapter.saveNativeConfig !== "function")
-            return false;
-        // Adapters may return boolean or Promise<boolean>. Awaiting a plain
-        // boolean is a no-op, so this handles both. Previously we stripped the
-        // Promise and always reported success for async adapters — that masked
-        // failures and left callers unable to detect dirty state.
-        const result = await adapter.saveNativeConfig(instanceId, config);
-        return typeof result === "boolean" ? result : true;
-    }
-    catch (e) {
-        console.warn(`[instance-manager] saveConfig dispatch failed for ${instanceId}: ${e.message}`);
-        return false;
-    }
-}
-// ── Deprecated back-compat dispatch wrappers ──────────────────────────
-//
-// The real implementations live in `OpenClawAdapter`. New code should
-// use `getAdapter(agentType).X(...)` directly. These wrappers exist so
-// existing unit tests and any stragglers in external-facing scripts
-// keep working without churn. They will be removed once the test suite
-// migrates to adapter-scoped imports.
-/**
- * @deprecated Use `getAdapter("openclaw").channelPluginMap` instead.
- * Provides the OpenClaw channel-plugin map via a Proxy so old direct-
- * property reads (e.g. `CHANNEL_PLUGIN_MAP.feishu`) keep working.
- */
-export const CHANNEL_PLUGIN_MAP = new Proxy({}, {
-    get(_target, key) {
-        if (typeof key !== "string")
-            return undefined;
-        try {
-            return getAdapter("openclaw").channelPluginMap?.[key];
-        }
-        catch {
-            return undefined;
-        }
-    },
-    ownKeys() {
-        try {
-            return Reflect.ownKeys(getAdapter("openclaw").channelPluginMap ?? {});
-        }
-        catch {
-            return [];
-        }
-    },
-    has(_target, key) {
-        if (typeof key !== "string")
-            return false;
-        try {
-            return key in (getAdapter("openclaw").channelPluginMap ?? {});
-        }
-        catch {
-            return false;
-        }
-    },
-    getOwnPropertyDescriptor(_target, key) {
-        if (typeof key !== "string")
-            return undefined;
-        let value;
-        try {
-            value = getAdapter("openclaw").channelPluginMap?.[key];
-        }
-        catch {
-            return undefined;
-        }
-        return value !== undefined
-            ? { configurable: true, enumerable: true, writable: false, value }
-            : undefined;
-    },
-});
-/**
- * @deprecated Use `getAdapter(agentType).isChannelPluginInstalled(id, channelId)` instead.
- */
-export function isChannelPluginInstalled(instanceId, channelId) {
-    try {
-        const meta = getInstance(instanceId);
-        const agentType = resolveAgentType(meta);
-        const adapter = getAdapter(agentType);
-        return typeof adapter.isChannelPluginInstalled === "function"
-            ? adapter.isChannelPluginInstalled(instanceId, channelId)
-            : false;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * @deprecated Use `getAdapter(agentType).createInstance({ instanceId, name, description, ... })` instead.
- * Retained for unit tests and legacy scripts; forwards to the
- * OpenClawAdapter's `createInstance` method.
- */
-export async function createInstance(instanceId, name, description, cloneFrom, agentHome, cloneOptions) {
-    const adapter = getAdapter("openclaw");
-    if (typeof adapter.createInstance !== "function") {
-        throw new Error("OpenClawAdapter.createInstance is not available");
-    }
-    return adapter.createInstance({
-        instanceId,
-        name,
-        description,
-        cloneFrom,
-        agentHome,
-        cloneOptions,
-    });
-}
-// §32.2 / §32.8: saveFeishuCredentials / saveWeixinCredentials /
-// getWeixinAccounts / getOpenclawHome physically migrated into
-// `src/services/runtime/adapters/openclaw.ts`. Back-compat dispatch
-// wrappers below keep existing callers working.
-export function getOpenclawHome(instanceId) {
-    const meta = getInstance(instanceId);
-    const agentType = resolveAgentType(meta);
-    try {
-        const a = getAdapter(agentType);
-        return typeof a.resolveAgentHome === "function"
-            ? a.resolveAgentHome(instanceId)
-            : meta?.openclaw_home || join(INSTANCES_DIR, instanceId, "openclaw-home");
-    }
-    catch {
-        return meta?.openclaw_home || join(INSTANCES_DIR, instanceId, "openclaw-home");
-    }
-}
-export function saveFeishuCredentials(instanceId, creds) {
-    const meta = getInstance(instanceId);
-    const agentType = resolveAgentType(meta);
-    const a = getAdapter(agentType);
-    if (typeof a.saveFeishuCredentials !== "function") {
-        throw new Error(`Runtime "${agentType}" does not support Feishu credentials`);
-    }
-    a.saveFeishuCredentials(instanceId, creds);
-}
-export function saveWeixinCredentials(instanceId, creds) {
-    const meta = getInstance(instanceId);
-    const agentType = resolveAgentType(meta);
-    const a = getAdapter(agentType);
-    if (typeof a.saveWeixinCredentials !== "function") {
-        throw new Error(`Runtime "${agentType}" does not support WeChat credentials`);
-    }
-    a.saveWeixinCredentials(instanceId, creds);
-}
-export function getWeixinAccounts(instanceId) {
-    const meta = getInstance(instanceId);
-    const agentType = resolveAgentType(meta);
-    try {
-        const a = getAdapter(agentType);
-        return typeof a.getWeixinAccounts === "function"
-            ? a.getWeixinAccounts(instanceId)
-            : [];
-    }
-    catch {
-        return [];
-    }
-}
-export function getOpenclawConfigPath(instanceId) {
-    const meta = getInstance(instanceId);
-    const agentType = resolveAgentType(meta);
-    const a = getAdapter(agentType);
-    if (typeof a.resolveConfigPath === "function")
-        return a.resolveConfigPath(instanceId);
-    return join(getOpenclawHome(instanceId), ".openclaw", "openclaw.json");
-}
-export function getLegacyOpenclawConfigPath(instanceId) {
-    const meta = getInstance(instanceId);
-    const agentType = resolveAgentType(meta);
-    const a = getAdapter(agentType);
-    if (typeof a.resolveLegacyConfigPath === "function")
-        return a.resolveLegacyConfigPath(instanceId);
-    return join(getOpenclawHome(instanceId), "openclaw.json");
-}
-export function getInstanceRuntime(instanceId) {
-    const meta = getInstance(instanceId);
-    if (!meta)
-        return {};
-    return structuredClone(meta.runtime || {});
-}
-export function getRuntimeEnvFiles(instanceId) {
-    const runtime = getInstanceRuntime(instanceId);
-    const rawEnvFiles = Array.isArray(runtime.env_files)
-        ? runtime.env_files
-        : Array.isArray(runtime.envFiles)
-            ? runtime.envFiles
-            : [];
-    const envFiles = rawEnvFiles.map((p) => normalizePath(p)).filter(Boolean);
-    return envFiles.length ? envFiles : [defaultModelEnvFile(instanceId)];
-}
-export function getGatewayPort(instanceId) {
-    const recorded = extractGatewayPort(getInstanceRuntime(instanceId));
-    if (recorded)
-        return recorded;
-    // Fallback: look up the adapter's canonical base port. Framework does
-    // not hardcode per-kind defaults.
-    const meta = getInstance(instanceId);
-    const agentType = resolveAgentType(meta);
-    try {
-        return getAdapter(agentType).defaultGatewayPort ?? 18789;
-    }
-    catch {
-        return 18789;
-    }
-}
-/**
- * Detect the host address where the gateway port is actually listening.
- *
- * Strategy by driver:
- *  - raw_exec (Linux/Pi): use `ss` to read the listening address directly.
- *  - docker (macOS/bridge): Nomad publishes the port on the Nomad client's
- *    interface IP (e.g. 10.x.x.x), NOT 127.0.0.1. Query the Nomad allocation
- *    for `AllocatedResources.Shared.Ports[label=gateway].HostIP`.
- *
- * Result is cached for 30 s to avoid an API call on every proxy request.
- */
-const _gwHostCache = new Map();
-const GW_HOST_CACHE_TTL = 30000;
-export function getListeningHostForPort(port) {
-    // Linux: ss is universal and parses cleanly. macOS/BSD ships lsof but
-    // not ss, so without this fallback execFileSync throws ENOENT, the
-    // catch block silently returns 127.0.0.1, and any caller that fans
-    // out to the wrong host fails (the capability HTTP proxy in
-    // `proxyProvidedCapability`, the gateway-host fallback for raw_exec
-    // instances, etc.). On macOS docker driver mode the actual published
-    // host can be e.g. 10.188.0.21 via `host_network = "external"`, never
-    // loopback — so silently picking 127.0.0.1 leaves the panel fetching
-    // a host nothing is listening on.
-    const safe = safePort(port);
-    const fromSs = () => {
-        const hosts = [];
-        try {
-            const out = execFileSync("ss", ["-tlnH", "sport", "=", ":" + safe], {
-                encoding: "utf-8",
-                timeout: 3000,
-                stdio: ["pipe", "pipe", "pipe"],
-            });
-            for (const line of out.split("\n")) {
-                let match = line.match(/\s([\d.]+):(\d+)\s/);
-                if (!match)
-                    match = line.match(/\s\[([0-9a-fA-F:]+)\]:(\d+)\s/);
-                if (match && match[2] === String(port))
-                    hosts.push(match[1]);
-            }
-        }
-        catch { /* ss not available or no match */ }
-        return hosts;
-    };
-    const fromLsof = () => {
-        const hosts = [];
-        try {
-            // `-FnP` keeps numeric output (no name resolution, no /etc/services).
-            // Lines beginning with `n` carry the bind address: e.g. `n10.188.0.21:8080`,
-            // `n127.0.0.1:8080`, `n[::1]:8080`, or `n*:8080` for wildcard binds.
-            const out = execFileSync("lsof", ["-nP", "-iTCP:" + safe, "-sTCP:LISTEN", "-FnP"], {
-                encoding: "utf-8",
-                timeout: 3000,
-                stdio: ["pipe", "pipe", "pipe"],
-            });
-            for (const line of out.split("\n")) {
-                if (!line.startsWith("n"))
-                    continue;
-                const body = line.slice(1);
-                // IPv6 form: [::1]:8080 → strip brackets
-                const v6 = body.match(/^\[([0-9a-fA-F:]+)\]:(\d+)$/);
-                if (v6 && v6[2] === String(port)) {
-                    hosts.push(v6[1]);
-                    continue;
-                }
-                const idx = body.lastIndexOf(":");
-                if (idx <= 0)
-                    continue;
-                const addr = body.slice(0, idx);
-                const portPart = body.slice(idx + 1);
-                if (portPart === String(port))
-                    hosts.push(addr === "*" ? "0.0.0.0" : addr);
-            }
-        }
-        catch { /* lsof unavailable or no match */ }
-        return hosts;
-    };
-    const detected = process.platform === "linux"
-        ? [...fromSs(), ...fromLsof()]
-        : [...fromLsof(), ...fromSs()];
-    const unique = [...new Set(detected)];
-    if (unique.length === 0)
-        return "127.0.0.1";
-    return unique[0] === "0.0.0.0" ? "127.0.0.1" : unique[0];
-}
-function getExclusiveLoopbackListenerForPort(port) {
-    const safe = safePort(port);
-    const hosts = new Set();
-    try {
-        const out = execFileSync("lsof", ["-nP", "-iTCP:" + safe, "-sTCP:LISTEN", "-FnP"], {
-            encoding: "utf-8",
-            timeout: 3000,
-            stdio: ["pipe", "pipe", "pipe"],
-        });
-        for (const line of out.split("\n")) {
-            if (!line.startsWith("n"))
-                continue;
-            const body = line.slice(1);
-            if (body === `127.0.0.1:${safe}`) {
-                hosts.add("127.0.0.1");
-                continue;
-            }
-            if (body === `[::1]:${safe}`) {
-                hosts.add("::1");
-                continue;
-            }
-            if (!body.endsWith(`:${safe}`))
-                continue;
-            const addr = body.startsWith("[")
-                ? body.slice(1, body.lastIndexOf("]"))
-                : body.slice(0, body.lastIndexOf(":"));
-            hosts.add(addr === "*" ? "0.0.0.0" : addr);
-        }
-    }
-    catch { /* lsof unavailable or no match */ }
-    try {
-        const out = execFileSync("ss", ["-tlnH", "sport", "=", ":" + safe], {
-            encoding: "utf-8",
-            timeout: 3000,
-            stdio: ["pipe", "pipe", "pipe"],
-        });
-        for (const line of out.split("\n")) {
-            const ipv4 = line.match(/\s([\d.]+):(\d+)\s/);
-            if (ipv4 && ipv4[2] === String(safe))
-                hosts.add(ipv4[1]);
-            const ipv6 = line.match(/\s\[([0-9a-fA-F:]+)\]:(\d+)\s/);
-            if (ipv6 && ipv6[2] === String(safe))
-                hosts.add(ipv6[1]);
-        }
-    }
-    catch { /* ss unavailable or no match */ }
-    if (hosts.size === 0)
-        return null;
-    let hasIpv4Loopback = false;
-    let hasIpv6Loopback = false;
-    for (const host of hosts) {
-        if (host === "127.0.0.1") {
-            hasIpv4Loopback = true;
-            continue;
-        }
-        if (host === "::1") {
-            hasIpv6Loopback = true;
-            continue;
-        }
-        if (host === "0.0.0.0" || host === "::")
-            return null;
-        return null;
-    }
-    if (hasIpv4Loopback)
-        return "127.0.0.1";
-    if (hasIpv6Loopback)
-        return "::1";
-    return null;
-}
-function getPrimaryIpv4Address() {
-    try {
-        for (const list of Object.values(networkInterfaces())) {
-            for (const iface of list ?? []) {
-                if (!iface.internal && iface.family === "IPv4")
-                    return iface.address;
-            }
-        }
-    }
-    catch { /* fall through */ }
-    return "127.0.0.1";
-}
-export function getAdvertisedHostForPort(port) {
-    const host = getListeningHostForPort(port);
-    if (host && host !== "127.0.0.1" && host !== "0.0.0.0" && host !== "::1" && host !== "::") {
-        return host;
-    }
-    return getPrimaryIpv4Address();
-}
-export async function getGatewayHost(instanceId) {
-    const cached = _gwHostCache.get(instanceId);
-    if (cached && Date.now() - cached.ts < GW_HOST_CACHE_TTL)
-        return cached.host;
-    const port = getGatewayPort(instanceId);
-    let result = "127.0.0.1";
-    try {
-        const { getNomadDriver } = await import("../config.js");
-        if (getNomadDriver() === "docker") {
-            const { getNomadAddr, getNomadToken } = await import("../config.js");
-            // Dispatch job-id construction through the adapter so every runtime
-            // owns its own Nomad job namespace (hermes-<id>, openclaw-<id>, …).
-            // Falls back to a generic `jishushell-` prefix only when the adapter
-            // lookup fails — that branch should never fire for a registered
-            // agent type.
-            const meta = getInstance(instanceId);
-            const agentType = resolveAgentType(meta);
-            let prefix = "jishushell-";
-            try {
-                const a = getAdapter(agentType);
-                if (typeof a.nomadJobPrefix === "string" && a.nomadJobPrefix.length) {
-                    prefix = a.nomadJobPrefix;
-                }
-            }
-            catch { /* use fallback prefix */ }
-            // Avoid double-prefix when the instance ID already carries the
-            // adapter prefix (e.g. apps stored as `openclaw-c1` whose Nomad
-            // job name is also `openclaw-c1`). Without this guard we'd ask
-            // Nomad for `openclaw-openclaw-c1`, get 0 allocs, and fall back
-            // to the 127.0.0.1 default — which silently breaks the gateway
-            // proxy on docker driver where the real HostIP differs.
-            const jid = instanceId.startsWith(prefix) ? instanceId : `${prefix}${instanceId}`;
-            const headers = { "Content-Type": "application/json" };
-            const token = getNomadToken();
-            if (token)
-                headers["X-Nomad-Token"] = token;
-            const resp = await fetch(`${getNomadAddr()}/v1/job/${encodeURIComponent(jid)}/allocations`, {
-                headers,
-                signal: AbortSignal.timeout(5000),
-            });
-            if (resp.ok) {
-                const allocs = await resp.json();
-                const alloc = allocs.find((a) => a.ClientStatus === "running")
-                    ?? allocs.find((a) => a.ClientStatus === "pending");
-                if (alloc) {
-                    const detail = await fetch(`${getNomadAddr()}/v1/allocation/${encodeURIComponent(alloc.ID)}`, { headers, signal: AbortSignal.timeout(5000) });
-                    if (detail.ok) {
-                        const d = await detail.json();
-                        // Preferred source: AllocatedResources.Shared.Ports (bridge mode).
-                        const sharedPorts = d?.AllocatedResources?.Shared?.Ports ?? [];
-                        const gwPort = sharedPorts.find((p) => p.Label === "gateway");
-                        if (gwPort?.HostIP && gwPort.HostIP !== "0.0.0.0") {
-                            result = gwPort.HostIP;
-                        }
-                        else {
-                            // Host mode / task-level reservation: address lives under
-                            // AllocatedResources.Tasks.<task>.Networks[*].IP. On Nomad
-                            // 1.6.5 with `network_interface = "lo"`, the IP is whichever
-                            // address the OS enumerates first — which can be IPv6 `::1`
-                            // on systems where lo has both `127.0.0.1/8` and `::1/128`
-                            // (the default on most modern Linux distros). Reading it from
-                            // here is the authoritative source and matches what nomad
-                            // configures the docker-proxy bind to use.
-                            //
-                            // Scan every task instead of indexing a hardcoded "gateway"
-                            // task — adapters are free to name the task whatever they
-                            // like, we only require the reserved port carry the
-                            // framework-level `gateway` label.
-                            const tasksMap = d?.AllocatedResources?.Tasks ?? {};
-                            for (const taskName of Object.keys(tasksMap)) {
-                                const taskNets = tasksMap[taskName]?.Networks ?? [];
-                                const net = taskNets.find((n) => {
-                                    const rps = n?.ReservedPorts ?? [];
-                                    return rps.some((p) => p.Label === "gateway");
-                                });
-                                if (net?.IP && net.IP !== "0.0.0.0") {
-                                    result = net.IP;
-                                    break;
-                                }
-                            }
-                        }
-                    }
-                }
-            }
-            // If Nomad API resolved a non-default host, cache and return it
-            if (result !== "127.0.0.1") {
-                const localLoopbackHost = getExclusiveLoopbackListenerForPort(port);
-                if (localLoopbackHost) {
-                    result = localLoopbackHost;
-                }
-                _gwHostCache.set(instanceId, { host: result, ts: Date.now() });
-                return result;
-            }
-            // Otherwise fall through to ss-based detection
-        }
-    }
-    catch { /* fall through */ }
-    result = getListeningHostForPort(port);
-    _gwHostCache.set(instanceId, { host: result, ts: Date.now() });
-    return result;
-}
-const _appPortHostCache = new Map();
-const APP_PORT_HOST_CACHE_TTL = 30000;
-/**
- * Resolve the host IP for a specific port belonging to an app's Nomad job.
- *
- * On macOS with Colima + docker driver the container port is bound *inside*
- * the VM, not on the host.  `ss` (or `netstat`) run on the macOS host see
- * nothing on that port, so `getListeningHostForPort` returns 127.0.0.1 and
- * the panel proxy gets a 502.
- *
- * This function mirrors the logic of `getGatewayHost` but matches by port
- * *value* rather than by the "gateway" label, making it suitable for
- * arbitrary capability ports exposed by app tasks.
- */
-export async function getHostForAppPort(appId, port) {
-    const cacheKey = `${appId}:${port}`;
-    const cached = _appPortHostCache.get(cacheKey);
-    if (cached && Date.now() - cached.ts < APP_PORT_HOST_CACHE_TTL)
-        return cached.host;
-    let result = "127.0.0.1";
-    try {
-        const { getNomadDriver, getNomadAddr, getNomadToken } = await import("../config.js");
-        if (getNomadDriver() === "docker") {
-            const headers = { "Content-Type": "application/json" };
-            const token = getNomadToken();
-            if (token)
-                headers["X-Nomad-Token"] = token;
-            const resp = await fetch(`${getNomadAddr()}/v1/job/${encodeURIComponent(appId)}/allocations`, { headers, signal: AbortSignal.timeout(5000) });
-            if (resp.ok) {
-                const allocs = await resp.json();
-                const alloc = allocs.find((a) => a.ClientStatus === "running")
-                    ?? allocs.find((a) => a.ClientStatus === "pending");
-                if (alloc) {
-                    const detail = await fetch(`${getNomadAddr()}/v1/allocation/${encodeURIComponent(alloc.ID)}`, { headers, signal: AbortSignal.timeout(5000) });
-                    if (detail.ok) {
-                        const d = await detail.json();
-                        // Bridge / host-network mode: ports listed under Shared.Ports
-                        const sharedPorts = d?.AllocatedResources?.Shared?.Ports ?? [];
-                        const matched = sharedPorts.find((p) => p.Value === port || p.To === port);
-                        if (matched?.HostIP && matched.HostIP !== "0.0.0.0") {
-                            result = matched.HostIP;
-                        }
-                    }
-                }
-            }
-        }
-    }
-    catch { /* fall through to ss-based detection */ }
-    if (result === "127.0.0.1") {
-        result = getListeningHostForPort(port);
-    }
-    _appPortHostCache.set(cacheKey, { host: result, ts: Date.now() });
-    return result;
-}
-/**
- * Wrap an IPv6 literal in brackets for safe URL host-component / Host-header
- * use. Bare names ("gateway.local") and IPv4 ("127.0.0.1") contain no colon
- * and pass through unchanged; anything with a colon is an IPv6 literal and
- * MUST be bracketed before being concatenated with a port, otherwise
- * `http://::1:18789/` is unparseable.
- */
-export function urlHost(host) {
-    return host.includes(":") ? `[${host}]` : host;
-}
-export function findInstancesSharingOpenclawHome(instanceId) {
-    const meta = getInstance(instanceId);
-    const agentType = resolveAgentType(meta);
-    try {
-        const a = getAdapter(agentType);
-        return typeof a.findInstancesSharingHome === "function"
-            ? a.findInstancesSharingHome(instanceId)
-            : [];
-    }
-    catch {
-        return [];
-    }
-}
-/**
- * Re-pick a gateway port for an existing instance and rewrite its persisted
- * runtime metadata (`runtime.args` and `runtime.env.OPENCLAW_GATEWAY_PORT`).
- *
- * Used when {@link isPortInUse} reports that the previously-assigned port has
- * been taken by something else between create-time and start-time (e.g. a
- * host-side openclaw started by the user, an unrelated service that grabbed
- * the port at boot, or a Docker race on the next allocation). The Nomad job
- * spec is rebuilt from instance metadata on every submit, so updating
- * `instance.json` here is sufficient — no other files need patching.
- */
-export async function reallocateGatewayPort(instanceId) {
-    const meta = safeReadJson(instanceMetaPath(instanceId), "instance-meta");
-    if (!meta)
-        throw new Error(`Cannot reallocate port for unknown instance '${instanceId}'`);
-    const agentType = resolveAgentType(meta);
-    let adapter;
-    try {
-        adapter = getAdapter(agentType);
-    }
-    catch {
-        throw new Error(`Unknown runtime agentType "${agentType}" for instance ${instanceId}`);
-    }
-    const defaultPort = adapter.defaultGatewayPort ?? 18789;
-    const fromPort = extractGatewayPort(meta.runtime, agentType) ?? defaultPort;
-    const alloc = await allocateGatewayPort(instanceId, defaultPort);
-    try {
-        const runtime = (meta.runtime ?? {});
-        // Delegate the kind-specific runtime rewrite to the adapter.
-        if (typeof adapter.reallocateRuntimePort === "function") {
-            adapter.reallocateRuntimePort(runtime, alloc.port);
-        }
-        meta.runtime = runtime;
-        safeWriteJson(instanceMetaPath(instanceId), meta);
-        chownToServiceUser(instanceMetaPath(instanceId));
-        console.log(`[instance] ${instanceId}: gateway port reallocated ${fromPort} -> ${alloc.port}`);
-        return { from: fromPort, to: alloc.port, skipped: alloc.skipped };
-    }
-    finally {
-        _pendingPorts.delete(alloc.port);
-    }
-}
-export function findInstancesSharingGatewayPort(instanceId) {
-    const targetPort = getGatewayPort(instanceId);
-    return listInstances()
-        .filter((inst) => inst.id !== instanceId)
-        .filter((inst) => extractGatewayPort(inst.runtime) === targetPort)
-        .map((inst) => inst.id);
-}
-export function getRuntimeEnv(instanceId) {
-    const runtime = getInstanceRuntime(instanceId);
-    const env = {};
-    for (const envFile of getRuntimeEnvFiles(instanceId)) {
-        Object.assign(env, parseEnvFile(envFile));
-    }
-    for (const [key, value] of Object.entries(runtime.env || {})) {
-        if (value != null)
-            env[key] = String(value);
-    }
-    return env;
-}
-// Re-export instanceDir for nomad-manager under its getInstanceDir alias.
-export { instanceDir as getInstanceDir };
-// ── Compatibility exports for app-type managers (src/services/app/) ──────────
-// `instanceMetaPath`, `chownToServiceUser`, `notifyConfigChange` already
-// exported above; §32.2/§32.8 migration kept the originals in place so the
-// app-manager layer can still depend on them. The shims below add the
-// naming aliases the cli branch's app managers import.
-/**
- * Compatibility shim: allocate a gateway port for a new instance and return
- * just the port number. Wraps `allocateGatewayPort`, which takes a seed port
- * and returns `{ port, skipped }`. Non-OpenClaw app managers don't have an
- * agentType-specific default port yet, so we seed with 18789 (OpenClaw's
- * default) — the allocator walks upward until it finds a free slot so the
- * actual port chosen is independent of the seed.
- */
-export async function defaultGatewayPort(instanceId) {
-    const result = await allocateGatewayPort(instanceId, 18789);
-    return result.port;
-}
-/**
- * Compatibility shim: release a pending port reservation.
- * Mirrors the cli-branch `releasePort(port)` helper on top of the framework's
- * existing `releasePendingPort`.
- */
-export function releasePort(port) {
-    releasePendingPort(port);
-}
-// `resolveExistingConfigPath` is owned by the OpenClaw adapter after §32.2 —
-// callers that still need it live inside `src/services/runtime/adapters/` or
-// `src/services/app/openclaw-manager.ts` (which defines its own copy).
-//# sourceMappingURL=instance-manager.js.map