jishushell 0.5.22 → 0.6.18

package/dist/services/app/app-manager.js

@@ -1,2741 +0,0 @@
-import { createHash } from "crypto";
-import { existsSync, mkdtempSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, chmodSync, chownSync, lstatSync, } from "fs";
-import { homedir, tmpdir } from "os";
-import { basename, extname, join, dirname } from "path";
-import { spawn, spawnSync } from "child_process";
-import { fileURLToPath } from "url";
-import { parse, stringify } from "yaml";
-import * as config from "../../config.js";
-import { ensureDirHost } from "../../utils/fs.js";
-import { safeReadJson, safeWriteJson } from "../../utils/safe-json.js";
-import * as legacyInstanceManager from "../instance-manager.js";
-import { withInstanceLock } from "../../utils/instance-lock.js";
-import { createTask, emitTask, getRunningTasks, getTask } from "../task-registry.js";
-import { compileTaskRuntime } from "./app-compiler.js";
-import * as capabilityRegistry from "../capability-registry.js";
-import { resolveProvideEndpoint } from "./provide-resolver.js";
-import { platformTransformSpec } from "./platform-transform.js";
-const DEFAULT_LIFECYCLE_PATH_ENTRIES = [
-    "/opt/homebrew/bin",
-    "/opt/homebrew/sbin",
-    "/usr/local/bin",
-    "/usr/local/sbin",
-    "/usr/bin",
-    "/bin",
-    "/usr/sbin",
-    "/sbin",
-];
-const DEFAULT_LIFECYCLE_PATH = DEFAULT_LIFECYCLE_PATH_ENTRIES.join(":");
-const MACOS_LIFECYCLE_PATH_PROBES = [
-    "/Applications/Docker.app/Contents/Resources/bin",
-];
-const ANONYMOUS_DOWNLOAD_IMAGE_ALLOWLIST = new Set([
-    "filebrowser/filebrowser:latest",
-    "ghcr.io/browserless/chromium:latest",
-    "ghcr.io/fmaclen/hollama:latest",
-    "ghcr.io/open-webui/open-webui:main",
-    "mcr.microsoft.com/playwright:v1.55.0-noble",
-    "mintplexlabs/anythingllm:latest",
-    "paradedb/paradedb:v0.22.2-pg17",
-    "redis:7.0-alpine",
-    "searxng/searxng:latest",
-    "wechatopenai/weknora-app:latest",
-    "wechatopenai/weknora-docreader:latest",
-    "wechatopenai/weknora-ui:latest",
-]);
-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"), join(process.env.HOME ?? homedir(), ".jishushell"));
-const APPS_DIR = resolveConfigPath(getConfigValue("APPS_DIR"), join(JISHUSHELL_HOME, "apps"));
-const INSTANCES_DIR = resolveConfigPath(getConfigValue("INSTANCES_DIR"), join(JISHUSHELL_HOME, "instances"));
-const CURRENT_JISHUSHELL_VERSION = (() => {
-    try {
-        const pkg = JSON.parse(readFileSync(new URL("../../../package.json", import.meta.url), "utf-8"));
-        return String(pkg.version ?? "0.0.0");
-    }
-    catch {
-        return "0.0.0";
-    }
-})();
-const BUILTIN_SPEC_FILE_RE = /\.ya?ml$/i;
-function builtinAppsDirCandidates() {
-    return [
-        fileURLToPath(new URL("../../../apps/", import.meta.url)),
-        join(process.cwd(), "apps"),
-    ];
-}
-function resolveBuiltinAppsDir() {
-    for (const candidate of builtinAppsDirCandidates()) {
-        if (existsSync(candidate))
-            return candidate;
-    }
-    return null;
-}
-function parseBuiltinTemplate(fileName, yamlText) {
-    let parsed = {};
-    try {
-        parsed = parse(yamlText) ?? {};
-    }
-    catch {
-        return null;
-    }
-    const tasks = Array.isArray(parsed.tasks) ? parsed.tasks : [];
-    const serviceTasks = tasks.filter((task) => (task?.role ?? "service") === "service");
-    const serviceTask = serviceTasks[0] ?? tasks[0] ?? null;
-    const serviceRuntime = typeof serviceTask?.runtime === "string" && serviceTask.runtime.trim()
-        ? serviceTask.runtime.trim()
-        : null;
-    const id = typeof parsed.id === "string" && parsed.id.trim()
-        ? parsed.id.trim()
-        : basename(fileName, extname(fileName));
-    const name = typeof parsed.name === "string" && parsed.name.trim()
-        ? parsed.name.trim()
-        : id;
-    const description = typeof parsed.description === "string" ? parsed.description : "";
-    const isOllamaTemplate = /^ollama(?:[-_]|$)/i.test(basename(fileName, extname(fileName))) || /^ollama(?:[-_]|$)/i.test(id);
-    const suggestedAppType = isOllamaTemplate ? "ollama" : "custom";
-    return {
-        id,
-        fileName,
-        name,
-        description,
-        serviceRuntime,
-        instanceCompatible: serviceTasks.length === 1
-            && tasks.every((task) => {
-                const runtime = typeof task?.runtime === "string" ? task.runtime.trim() : "";
-                return runtime === "container" || runtime === "process";
-            })
-            && (serviceRuntime === "container" || serviceRuntime === "process"),
-        suggestedAppType,
-        yaml: yamlText,
-    };
-}
-export function listBuiltinAppSpecs() {
-    const dir = resolveBuiltinAppsDir();
-    if (!dir)
-        return [];
-    return readdirSync(dir)
-        .filter((entry) => BUILTIN_SPEC_FILE_RE.test(entry))
-        .sort((left, right) => left.localeCompare(right))
-        .map((fileName) => parseBuiltinTemplate(fileName, readFileSync(join(dir, fileName), "utf-8")))
-        .filter((entry) => entry != null);
-}
-function installedAppDir(instanceId) {
-    for (const rootDir of [APPS_DIR, INSTANCES_DIR]) {
-        const dir = join(rootDir, instanceId);
-        if (existsSync(join(dir, "app-spec.yaml")) && existsSync(join(dir, "manifest.json"))) {
-            return dir;
-        }
-    }
-    return null;
-}
-export function updateInstance(instanceId, name, description) {
-    const updatedMeta = legacyInstanceManager.updateInstance(instanceId, name, description);
-    const appData = getApp(instanceId);
-    const appDir = installedAppDir(instanceId);
-    if (appData && appDir) {
-        const nextSpec = {
-            ...appData.spec,
-            ...(name != null ? { name } : {}),
-            ...(description != null ? { description } : {}),
-        };
-        const yamlPath = join(appDir, "app-spec.yaml");
-        const yamlTmp = yamlPath + ".tmp";
-        writeFileSync(yamlTmp, stringify(nextSpec), { mode: 0o644 });
-        renameSync(yamlTmp, yamlPath);
-    }
-    return legacyInstanceManager.getInstance(instanceId) ?? updatedMeta;
-}
-function parseComparableVersion(version, label) {
-    const normalized = version
-        .trim()
-        .replace(/^>=\s*/, "")
-        .replace(/^v/i, "")
-        .replace(/[-+].*$/, "");
-    const match = normalized.match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/);
-    if (!match) {
-        throw new Error(`${label} '${version}' 格式无效，应为 x.y.z`);
-    }
-    return [
-        Number(match[1] ?? 0),
-        Number(match[2] ?? 0),
-        Number(match[3] ?? 0),
-    ];
-}
-function compareVersions(left, right) {
-    for (let index = 0; index < 3; index++) {
-        if (left[index] > right[index])
-            return 1;
-        if (left[index] < right[index])
-            return -1;
-    }
-    return 0;
-}
-function requiredJishuShellVersion(spec) {
-    const required = spec.jishushell?.min_version?.trim();
-    if (!required) {
-        throw new Error(`App '${spec.id}' 缺少 jishushell.min_version，请先在 YAML 中声明支持的最低 JishuShell 版本`);
-    }
-    return required;
-}
-function ensureCompatibleJishuShellVersion(spec) {
-    const required = requiredJishuShellVersion(spec);
-    const current = parseComparableVersion(CURRENT_JISHUSHELL_VERSION, "当前 JishuShell 版本");
-    const minimum = parseComparableVersion(required, "jishushell.min_version");
-    if (compareVersions(current, minimum) < 0) {
-        throw new Error(`当前 JishuShell 版本 ${CURRENT_JISHUSHELL_VERSION} 低于应用要求 ${required}，请先升级 JishuShell`);
-    }
-}
-function expandPath(p) {
-    if (/^~\/\.jishushell(?:\/|$)/.test(p)) {
-        return p.replace(/^~\/\.jishushell(?=\/|$)/, JISHUSHELL_HOME);
-    }
-    return p.replace(/^~(?=\/|$)/, process.env.HOME ?? homedir());
-}
-function buildDeterministicPath(basePath, extraPaths = []) {
-    return [basePath ?? "", DEFAULT_LIFECYCLE_PATH, dirname(process.execPath), ...extraPaths]
-        .flatMap((entry) => entry.split(":"))
-        .map((entry) => entry.trim())
-        .filter(Boolean)
-        .filter((entry, index, entries) => entries.indexOf(entry) === index)
-        .join(":");
-}
-function buildLifecycleEnv() {
-    const extraPaths = process.platform === "darwin"
-        ? MACOS_LIFECYCLE_PATH_PROBES.filter((entry) => existsSync(entry))
-        : [];
-    const mergedPath = buildDeterministicPath(process.env.PATH, extraPaths);
-    // Surface panel callback hooks to lifecycle scripts. post_start can curl
-    // ${JISHUSHELL_PANEL_URL}/api/internal/* with the internal token to read
-    // panel-managed state (default provider creds etc.) and self-configure
-    // without going through user JWT. Best-effort: if the token file or
-    // port lookup fails we just omit the vars and the script gets a clean
-    // "missing env" failure path.
-    const panelHooks = {};
-    try {
-        panelHooks.JISHUSHELL_PANEL_URL = `http://127.0.0.1:${config.getPanelPort()}`;
-        panelHooks.JISHUSHELL_INTERNAL_TOKEN = config.getInternalMcpToken();
-        // LAN host that *other* services (and the post_start script's curls into
-        // its own service) can reach. AnythingLLM binds eth0 via Nomad's
-        // `external` host_network, so the panel-host loopback (127.0.0.1) won't
-        // reach 18097 — post_start needs to hit the LAN IP to check its own
-        // health. getPanelLanHost() returns the same IP Nomad publishes ports on.
-        panelHooks.JISHUSHELL_LAN_HOST = config.getPanelLanHost();
-    }
-    catch {
-        // tolerate — only post_start cares
-    }
-    return {
-        ...process.env,
-        HOME: process.env.HOME ?? homedir(),
-        PATH: mergedPath,
-        ...panelHooks,
-    };
-}
-const SUDO_PASSTHROUGH_ENV_KEYS = ["HOME", "PATH", "TMPDIR", "TMP", "TEMP", "XDG_RUNTIME_DIR"];
-function isSudoAuthenticationError(message) {
-    return /incorrect password|try again|authentication failure|密码错误|抱歉，请重试/i.test(message);
-}
-function isSudoNoNewPrivilegesError(message) {
-    return /no new privileges/i.test(message);
-}
-function isSudoPasswordRequiredError(message) {
-    return /password is required|a password is required/i.test(message);
-}
-function buildSudoWrappedCommand(cmd, args, env, execOptions) {
-    const sudoArgs = execOptions?.sudoPassword ? ["-k", "-A"] : ["-n"];
-    const envArgs = SUDO_PASSTHROUGH_ENV_KEYS.flatMap((key) => {
-        const value = env[key];
-        return typeof value === "string" && value.length > 0 ? [`${key}=${value}`] : [];
-    });
-    return {
-        command: "sudo",
-        args: [...sudoArgs, "--", "env", ...envArgs, cmd, ...args],
-    };
-}
-function createLifecycleSudoError(stderr, fallbackDisplay, hasPassword) {
-    const message = sanitizeTaskLine(stderr).trim();
-    if (isSudoNoNewPrivilegesError(message)) {
-        return createNoNewPrivilegesSudoError();
-    }
-    if (isSudoAuthenticationError(message)) {
-        const err = new Error("sudo 密码错误，请重新输入。");
-        err.code = "INVALID_SUDO_PASSWORD";
-        return err;
-    }
-    if (!hasPassword && isSudoPasswordRequiredError(message)) {
-        return new Error("该生命周期步骤需要 sudo 密码；请在页面弹窗中输入后重试。");
-    }
-    if (message) {
-        return new Error(message);
-    }
-    return new Error(`lifecycle sudo step failed: ${fallbackDisplay}`);
-}
-function panelSystemdServicePath() {
-    const override = process.env.JISHUSHELL_PANEL_SYSTEMD_SERVICE_PATH?.trim();
-    return override || "/etc/systemd/system/jishushell.service";
-}
-function isLikelySystemdServiceProcess() {
-    return Boolean(process.env.INVOCATION_ID
-        || process.env.JOURNAL_STREAM
-        || process.env.NOTIFY_SOCKET
-        || process.env.JISHUSHELL_PANEL_SYSTEMD_SERVICE_PATH?.trim());
-}
-function maybeRepairPanelAutostartNoNewPrivileges() {
-    if (!isLikelySystemdServiceProcess())
-        return null;
-    const servicePath = panelSystemdServicePath();
-    if (!existsSync(servicePath))
-        return null;
-    let unitText = "";
-    try {
-        unitText = readFileSync(servicePath, "utf-8");
-    }
-    catch {
-        return { servicePath, detected: true, updated: false };
-    }
-    if (!/^\s*NoNewPrivileges\s*=\s*true\s*$/mi.test(unitText)) {
-        return null;
-    }
-    const nextText = unitText.replace(/^\s*NoNewPrivileges\s*=\s*true\s*\n?/gim, "");
-    if (nextText === unitText) {
-        return { servicePath, detected: true, updated: false };
-    }
-    try {
-        writeFileSync(servicePath, nextText);
-        return { servicePath, detected: true, updated: true };
-    }
-    catch {
-        return { servicePath, detected: true, updated: false };
-    }
-}
-function manualInstallCommandForSpec(spec) {
-    if (spec.id === "ollama-binary") {
-        return "jishushell app install ollama";
-    }
-    const builtin = listBuiltinAppSpecs().find((entry) => entry.id === spec.id);
-    if (!builtin)
-        return null;
-    return `jishushell app install ${spec.id}`;
-}
-function createNoNewPrivilegesSudoError(manualInstallCommand) {
-    const repair = maybeRepairPanelAutostartNoNewPrivileges();
-    const restartCommand = "sudo systemctl daemon-reload && sudo systemctl restart jishushell";
-    const parts = ["当前运行环境禁止 sudo 提权（no new privileges），面板内无法继续后续安装。"];
-    if (repair?.updated) {
-        parts.push(`已从自启文件 ${repair.servicePath} 移除 NoNewPrivileges=true。请在系统终端执行以下命令后重试：\n${restartCommand}`);
-    }
-    else if (repair?.detected) {
-        parts.push(`检测到自启文件 ${repair.servicePath} 仍包含 NoNewPrivileges=true。请在系统终端删除该行后执行：\n${restartCommand}`);
-    }
-    if (manualInstallCommand) {
-        parts.push(`当前安装已停止。你也可以在系统终端手动执行 ${manualInstallCommand}。`);
-    }
-    return new Error(parts.join("\n"));
-}
-function decorateInstallError(error, spec) {
-    const original = error instanceof Error ? error : new Error(String(error));
-    if (!isSudoNoNewPrivilegesError(original.message) && !/NoNewPrivileges=true/i.test(original.message)) {
-        return original;
-    }
-    return createNoNewPrivilegesSudoError(manualInstallCommandForSpec(spec) ?? undefined);
-}
-export async function validateSudoPassword(sudoPassword) {
-    if (!sudoPassword) {
-        throw new Error("请输入 sudo 密码");
-    }
-    if (typeof process.getuid === "function" && process.getuid() === 0) {
-        return;
-    }
-    const preparedEnv = prepareLifecycleExecEnv({ sudoPassword });
-    try {
-        await new Promise((resolve, reject) => {
-            const child = spawn("sudo", ["-k", "-A", "true"], {
-                stdio: ["ignore", "ignore", "pipe"],
-                env: preparedEnv.env,
-                timeout: 15_000,
-            });
-            let stderr = "";
-            child.stderr?.on("data", (chunk) => {
-                stderr += chunk.toString("utf-8");
-            });
-            child.on("close", (code) => {
-                if (code === 0) {
-                    resolve();
-                    return;
-                }
-                const message = sanitizeTaskLine(stderr).trim();
-                if (isSudoNoNewPrivilegesError(message)) {
-                    reject(createNoNewPrivilegesSudoError());
-                    return;
-                }
-                if (/incorrect password|try again|authentication failure|密码错误|抱歉，请重试/i.test(message)) {
-                    const err = new Error("sudo 密码错误，请重新输入。");
-                    err.code = "INVALID_SUDO_PASSWORD";
-                    reject(err);
-                    return;
-                }
-                resolve();
-            });
-            child.on("error", (_error) => {
-                resolve();
-            });
-        });
-    }
-    finally {
-        preparedEnv.cleanup();
-    }
-}
-function prepareLifecycleExecEnv(execOptions, envOverrides) {
-    const env = {
-        ...buildLifecycleEnv(),
-        ...(envOverrides ?? {}),
-    };
-    const sudoPassword = execOptions?.sudoPassword;
-    if (!sudoPassword) {
-        return { env, cleanup: () => undefined };
-    }
-    const helperDir = mkdtempSync(join(tmpdir(), "jishushell-sudo-askpass-"));
-    const passwordPath = join(helperDir, "password.txt");
-    const askpassPath = join(helperDir, "askpass.sh");
-    writeFileSync(passwordPath, sudoPassword, { mode: 0o600 });
-    // Use an absolute password-file path in the helper script so sudo env
-    // filtering cannot drop the file path and cause false password failures.
-    writeFileSync(askpassPath, `#!/bin/sh\ncat '${passwordPath}'\nprintf '\\n'\n`, { mode: 0o700 });
-    chmodSync(askpassPath, 0o700);
-    return {
-        env: {
-            ...env,
-            SUDO_ASKPASS: askpassPath,
-            JISHUSHELL_SUDO_ASKPASS: "1",
-        },
-        cleanup: () => {
-            try {
-                rmSync(helperDir, { recursive: true, force: true });
-            }
-            catch {
-                // best effort cleanup for one-shot askpass helper files
-            }
-        },
-    };
-}
-function shouldBypassDockerCredentialHelperForDownloadImage(image) {
-    return ANONYMOUS_DOWNLOAD_IMAGE_ALLOWLIST.has(image.trim());
-}
-function createAnonymousDockerConfig() {
-    const dockerConfigDir = mkdtempSync(join(tmpdir(), "jishushell-docker-config-"));
-    writeFileSync(join(dockerConfigDir, "config.json"), `${JSON.stringify({ auths: {} }, null, 2)}\n`, { mode: 0o600 });
-    return {
-        envOverrides: {
-            DOCKER_CONFIG: dockerConfigDir,
-        },
-        cleanup: () => {
-            try {
-                rmSync(dockerConfigDir, { recursive: true, force: true });
-            }
-            catch {
-                // best effort cleanup for one-shot anonymous docker config files
-            }
-        },
-    };
-}
-const ANSI_ESCAPE_RE = /\u001B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g;
-function sanitizeTaskLine(line) {
-    return line
-        .replace(ANSI_ESCAPE_RE, "")
-        .replace(/[\u0000-\u0008\u000B-\u001F\u007F]/g, "")
-        .trimEnd();
-}
-function emitInstallTaskLog(task, message) {
-    if (!task)
-        return;
-    const line = sanitizeTaskLine(message).trim();
-    if (!line)
-        return;
-    emitTask(task, { type: "log", message: line });
-}
-function emitAppTaskProgress(task, message, progress) {
-    if (!task)
-        return;
-    const line = sanitizeTaskLine(message).trim();
-    if (!line)
-        return;
-    emitTask(task, { type: "progress", message: line, ...(typeof progress === "number" ? { progress } : {}) });
-}
-function normalizePortVisibility(visibility) {
-    if (!visibility || visibility === "external" || visibility === "public") {
-        return "external";
-    }
-    if (visibility === "internal") {
-        return visibility;
-    }
-    throw new Error(`port visibility '${visibility}' 仅支持 external 或 internal`);
-}
-function normalizeAppSpec(spec) {
-    const normalizedProvides = (spec.provides ?? []).map((provide) => {
-        if (spec.id === "browserless-chromium-container"
-            && provide.capability === BROWSERLESS_DEBUGGER_CAPABILITY
-            && (provide.path === "/" || provide.path === "/debugger")) {
-            return { ...provide, path: "/debugger/" };
-        }
-        if (spec.id === "browserless-chromium-container"
-            && provide.capability === BROWSERLESS_DOCS_CAPABILITY
-            && provide.path === "/docs") {
-            return { ...provide, path: "/docs/" };
-        }
-        if (spec.id === "browserless-chromium-container"
-            && provide.capability === BROWSERLESS_API_CAPABILITY
-            && provide.path !== "/") {
-            return { ...provide, path: "/" };
-        }
-        return provide;
-    });
-    // Inject browserless-api capability for legacy installed specs that lack it.
-    if (spec.id === "browserless-chromium-container"
-        && normalizedProvides.length > 0
-        && !normalizedProvides.some((p) => p.capability === BROWSERLESS_API_CAPABILITY)) {
-        const debugger_ = normalizedProvides.find((p) => p.capability === BROWSERLESS_DEBUGGER_CAPABILITY);
-        if (debugger_) {
-            normalizedProvides.push({
-                capability: BROWSERLESS_API_CAPABILITY,
-                port: debugger_.port ?? 3000,
-                path: "/",
-                protocol: "http",
-                description: "Browserless 根 API（供调试器页面连接 ws 与 sessions 接口）",
-            });
-        }
-    }
-    const normalizedTasks = (spec.tasks ?? []).map((task) => {
-        const rawTask = { ...task };
-        if (!rawTask.role) {
-            rawTask.role = "service";
-        }
-        if (!rawTask.command && rawTask.binary) {
-            rawTask.command = rawTask.binary;
-        }
-        if (Array.isArray(rawTask.ports)) {
-            rawTask.ports = rawTask.ports.map((port) => ({
-                ...port,
-                visibility: normalizePortVisibility(port.visibility),
-            }));
-        }
-        return rawTask;
-    });
-    let normalizedLifecycle = spec.lifecycle ? { ...spec.lifecycle } : undefined;
-    if (spec.id === "browserless-chromium-container") {
-        const browserlessDataDir = `~/.jishushell/apps/${spec.app_id || spec.id}/data`;
-        const browserlessDataDirTemplate = "~/.jishushell/apps/${app_id}/data";
-        const browserlessTask = normalizedTasks.find((task) => task.name === "browserless");
-        if (browserlessTask) {
-            const dataDirTarget = "/tmp/browserless-data";
-            const existingVolumes = Array.isArray(browserlessTask.volumes) ? [...browserlessTask.volumes] : [];
-            const hasDataDirVolume = existingVolumes.some((volume) => typeof volume === "object" && volume !== null && volume.target === dataDirTarget);
-            if (!hasDataDirVolume) {
-                existingVolumes.push({ source: browserlessDataDir, target: dataDirTarget });
-            }
-            browserlessTask.volumes = existingVolumes;
-        }
-        const install = [...(normalizedLifecycle?.install ?? [])];
-        if (!install.some((step) => "mkdir" in step && (step.mkdir === browserlessDataDir || step.mkdir === browserlessDataDirTemplate))) {
-            install.push({ mkdir: browserlessDataDir });
-        }
-        const preStart = [...(normalizedLifecycle?.pre_start ?? [])];
-        if (!preStart.some((step) => "mkdir" in step && (step.mkdir === browserlessDataDir || step.mkdir === browserlessDataDirTemplate))) {
-            preStart.push({ mkdir: browserlessDataDir });
-        }
-        normalizedLifecycle = {
-            ...(normalizedLifecycle ?? {}),
-            install,
-            pre_start: preStart,
-        };
-    }
-    return {
-        ...spec,
-        ...(spec.provides ? { provides: normalizedProvides } : {}),
-        tasks: normalizedTasks,
-        ...(normalizedLifecycle ? { lifecycle: normalizedLifecycle } : {}),
-    };
-}
-function imageReferencedByOtherInstalledApps(currentAppId, imagePath) {
-    return listApps().some((app) => app.manifest.id !== currentAppId && (app.spec.tasks.some((task) => task.image === imagePath)
-        || app.manifest.artifacts?.some((artifact) => artifact.type === "image" && artifact.path === imagePath)
-        || app.spec.lifecycle?.install?.some((step) => "downloadImage" in step && step.downloadImage === imagePath)));
-}
-function shouldDeleteImageForApp(appData, imagePath) {
-    if (appData.spec.singleInstance === false)
-        return false;
-    return !imageReferencedByOtherInstalledApps(appData.manifest.id, imagePath);
-}
-function selectUninstallLifecycleSteps(appData) {
-    if (!appData?.spec.lifecycle?.uninstall?.length)
-        return undefined;
-    return appData.spec.lifecycle.uninstall.filter((step) => !("deleteImage" in step) || shouldDeleteImageForApp(appData, step.deleteImage));
-}
-function selectCleanupArtifacts(appData) {
-    if (!appData?.manifest.artifacts?.length)
-        return [];
-    const lifecycleImageDeletes = new Set((selectUninstallLifecycleSteps(appData) ?? [])
-        .flatMap((step) => ("deleteImage" in step ? [step.deleteImage] : [])));
-    return appData.manifest.artifacts.filter((artifact) => {
-        if (artifact.type !== "image")
-            return true;
-        if (lifecycleImageDeletes.has(artifact.path))
-            return false;
-        return shouldDeleteImageForApp(appData, artifact.path);
-    });
-}
-async function deleteLinkedInstances(appId) {
-    const warnings = [];
-    const instanceManager = await import("../instance-manager.js");
-    const linkedInstances = instanceManager
-        .listInstances()
-        .filter((instance) => instance?.id && instance.id !== appId && instance.app_id === appId);
-    if (linkedInstances.length === 0)
-        return warnings;
-    const { stopNomadJobInstance: stopInstance } = await import("../nomad-manager.js");
-    let processManager = null;
-    try {
-        processManager = await import("../process-manager.js");
-    }
-    catch {
-        processManager = null;
-    }
-    for (const instance of linkedInstances) {
-        const instanceId = String(instance.id);
-        let stopFailed = false;
-        try {
-            const stopped = await stopInstance(instanceId, true);
-            if (!stopped.ok) {
-                const fallback = await stopInstance(instanceId);
-                if (!fallback.ok)
-                    stopFailed = true;
-            }
-        }
-        catch {
-            stopFailed = true;
-        }
-        if (processManager) {
-            try {
-                if ((await processManager.getLegacyStatus(instanceId)).status === "running") {
-                    await processManager.stopInstance(instanceId);
-                    stopFailed = false;
-                }
-            }
-            catch {
-                // best effort
-            }
-        }
-        const result = await instanceManager.deleteInstance(instanceId);
-        if (!result.ok) {
-            warnings.push(`关联实例 '${instanceId}' 删除失败`);
-        }
-        if (result.warnings?.length) {
-            warnings.push(...result.warnings.map((warning) => `关联实例 '${instanceId}': ${warning}`));
-        }
-        if (stopFailed) {
-            warnings.push(`关联实例 '${instanceId}' 停止失败，可能残留进程`);
-        }
-    }
-    return warnings;
-}
-function getProvidePort(spec, provide) {
-    if (typeof provide.url === "string" && provide.url.trim()) {
-        return null;
-    }
-    if (typeof provide.port === "number") {
-        return provide.port;
-    }
-    const firstPort = spec.tasks.find((task) => task.role === "service")?.ports?.[0];
-    if (!firstPort)
-        return null;
-    const p = firstPort.host_port ?? firstPort.port;
-    return typeof p === "number" && p > 0 ? p : null;
-}
-function getProvideUrl(provide) {
-    const raw = typeof provide.url === "string" ? provide.url.trim() : "";
-    if (!raw)
-        return null;
-    try {
-        const parsed = new URL(raw);
-        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-            return null;
-        }
-        return parsed.toString();
-    }
-    catch {
-        return null;
-    }
-}
-function buildCapabilityAddress(port, path) {
-    const host = port > 0 ? legacyInstanceManager.getAdvertisedHostForPort(port) : "127.0.0.1";
-    if (!path) {
-        return `${host}:${port}`;
-    }
-    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
-    return `${host}:${port}${normalizedPath}`;
-}
-function normalizeProvideProtocol(protocol) {
-    const raw = typeof protocol === "string" ? protocol.trim().toLowerCase() : "";
-    return raw || "http";
-}
-function resolveProvideProtocol(provide) {
-    const url = getProvideUrl(provide);
-    if (url) {
-        try {
-            return new URL(url).protocol.replace(/:$/, "").toLowerCase();
-        }
-        catch {
-            return normalizeProvideProtocol(provide.protocol);
-        }
-    }
-    return normalizeProvideProtocol(provide.protocol);
-}
-function collectDeclaredPorts(spec) {
-    return spec.tasks.flatMap((task) => (task.ports ?? [])
-        .map((port) => port.host_port ?? port.port)
-        .filter((port) => Number.isInteger(port) && port > 0 && port <= 65535));
-}
-function buildPortShiftMap(spec, offset) {
-    const portShiftMap = new Map();
-    for (const port of collectDeclaredPorts(spec)) {
-        const shiftedPort = port + offset;
-        if (shiftedPort < 1 || shiftedPort > 65535) {
-            throw new Error(`App '${spec.id}' 没有可用端口，端口递增已超出 65535`);
-        }
-        portShiftMap.set(port, shiftedPort);
-    }
-    return portShiftMap;
-}
-function replaceAppScopedPaths(value, baseId, appId) {
-    if (baseId === appId)
-        return value;
-    const homeDir = homedir();
-    const replacements = [
-        [`~/.jishushell/apps/${baseId}`, `~/.jishushell/apps/${appId}`],
-        [`$HOME/.jishushell/apps/${baseId}`, `$HOME/.jishushell/apps/${appId}`],
-        [`${homeDir}/.jishushell/apps/${baseId}`, `${homeDir}/.jishushell/apps/${appId}`],
-        [`\${HOME}/.jishushell/apps/${baseId}`, `\${HOME}/.jishushell/apps/${appId}`],
-    ];
-    let rewritten = value;
-    for (const [from, to] of replacements) {
-        rewritten = rewritten.split(from).join(to);
-    }
-    return rewritten;
-}
-function replaceAppIdTokens(value, appId) {
-    return value
-        .replace(/\$\{app_id\}/g, appId)
-        .replace(/\$\{app\.id\}/g, appId);
-}
-function replacePortTokens(value, portShiftMap) {
-    let rewritten = value;
-    const replacements = [...portShiftMap.entries()].sort((left, right) => right[0] - left[0]);
-    for (const [fromPort, toPort] of replacements) {
-        const pattern = new RegExp(`(^|[^0-9A-Za-z])${fromPort}($|[^0-9A-Za-z])`, "g");
-        rewritten = rewritten.replace(pattern, (_match, prefix, suffix) => `${prefix}${toPort}${suffix}`);
-    }
-    return rewritten;
-}
-function rewriteInstalledSpecValue(value, baseId, appId, portShiftMap) {
-    if (typeof value === "string") {
-        const hasAppIdToken = value.includes("${app_id}") || value.includes("${app.id}");
-        return replacePortTokens(hasAppIdToken
-            ? replaceAppIdTokens(value, appId)
-            : replaceAppScopedPaths(value, baseId, appId), portShiftMap);
-    }
-    if (typeof value === "number") {
-        return portShiftMap.get(value) ?? value;
-    }
-    if (Array.isArray(value)) {
-        return value.map((entry) => rewriteInstalledSpecValue(entry, baseId, appId, portShiftMap));
-    }
-    if (value && typeof value === "object") {
-        const rewritten = {};
-        for (const [key, entry] of Object.entries(value)) {
-            rewritten[key] = rewriteInstalledSpecValue(entry, baseId, appId, portShiftMap);
-        }
-        return rewritten;
-    }
-    return value;
-}
-function materializeInstalledSpec(spec, appId, offset) {
-    const portShiftMap = buildPortShiftMap(spec, offset);
-    const rewritten = rewriteInstalledSpecValue(spec, spec.id, appId, portShiftMap);
-    const derivedName = deriveInstalledDisplayName(spec, appId);
-    const normalized = normalizeAppSpec({
-        ...rewritten,
-        id: spec.id,
-        ...(derivedName ? { name: derivedName } : {}),
-    });
-    // Final step: drop spec fields that work on the spec author's Linux
-    // baseline but break on the host platform (e.g. host_network:
-    // docker_bridge / user: "host" on darwin). Identity pass-through on
-    // Linux — see platform-transform.ts for the rule list.
-    return platformTransformSpec(normalized);
-}
-function deriveInstalledDisplayName(spec, appId) {
-    const baseName = typeof spec.name === "string" && spec.name.trim() ? spec.name.trim() : spec.id;
-    if (!baseName)
-        return appId;
-    if (appId === spec.id)
-        return baseName;
-    if (!appId.startsWith(`${spec.id}-`))
-        return baseName;
-    const suffix = appId.slice(spec.id.length + 1).trim();
-    return suffix ? `${baseName}-${suffix}` : baseName;
-}
-function formatInstalledAppId(baseId, instancePrefix, offset) {
-    if (offset === 0)
-        return baseId;
-    return `${baseId}-${instancePrefix}${offset}`;
-}
-// Delegate to the canonical multi-locus probe in instance-manager so macOS
-// loopback-only listeners (e.g. a natively-installed openclaw bound to
-// 127.0.0.1:18789) are visible to AppSpec port conflict detection as well.
-// Wrap in a thunk so the lookup happens at call time — some test suites
-// partially mock instance-manager without re-exporting this symbol.
-function isPortInUse(port) {
-    return legacyInstanceManager.isPortInUse(port);
-}
-async function resolveInstallTarget(spec, originalSpecYaml, requestedAppId) {
-    const baseId = spec.id;
-    const multiInstance = spec.singleInstance === false;
-    const explicitAppId = requestedAppId?.trim();
-    if (explicitAppId && !APP_ID_RE.test(explicitAppId)) {
-        throw new Error(`App id '${explicitAppId}' 格式无效，必须符合 /^[a-z0-9][a-z0-9-]{0,62}$/`);
-    }
-    const installedSameSpec = listApps().find((app) => app.spec.id === baseId);
-    if (!multiInstance) {
-        if (installedSameSpec) {
-            const err = new Error(`App '${baseId}' 已安装为 '${installedSameSpec.manifest.id}'，如需多实例请设置 singleInstance: false`);
-            err.code = 409;
-            throw err;
-        }
-        const appId = explicitAppId ?? baseId;
-        if (appId !== baseId && resolveAppDir(appId)) {
-            const err = new Error(`App '${appId}' 已安装`);
-            err.code = 409;
-            throw err;
-        }
-        const installedSpec = materializeInstalledSpec(spec, appId, 0);
-        return {
-            appId,
-            installedSpec,
-            installedSpecYaml: stringify(installedSpec),
-        };
-    }
-    const usedPorts = new Set();
-    for (const installedApp of listApps()) {
-        for (const port of collectDeclaredPorts(installedApp.spec)) {
-            usedPorts.add(port);
-        }
-    }
-    const instancePrefix = spec.instancePrefix ?? "";
-    const declaredPorts = collectDeclaredPorts(spec);
-    const maxBasePort = declaredPorts.length > 0 ? Math.max(...declaredPorts) : 0;
-    const maxOffset = declaredPorts.length > 0 ? 65535 - maxBasePort : 9999;
-    if (explicitAppId) {
-        if (resolveAppDir(explicitAppId)) {
-            const err = new Error(`App '${explicitAppId}' 已安装`);
-            err.code = 409;
-            throw err;
-        }
-        for (let offset = 0; offset <= maxOffset; offset++) {
-            const installedSpec = materializeInstalledSpec(spec, explicitAppId, offset);
-            const candidatePorts = collectDeclaredPorts(installedSpec);
-            let portConflict = false;
-            for (const port of candidatePorts) {
-                if (usedPorts.has(port) || await isPortInUse(port)) {
-                    portConflict = true;
-                    break;
-                }
-            }
-            if (portConflict)
-                continue;
-            return {
-                appId: explicitAppId,
-                installedSpec,
-                installedSpecYaml: stringify(installedSpec),
-            };
-        }
-        throw new Error(`App '${baseId}' 使用指定 id '${explicitAppId}' 时没有可用端口槽位`);
-    }
-    for (let offset = 0; offset <= maxOffset; offset++) {
-        const appId = formatInstalledAppId(baseId, instancePrefix, offset);
-        if (!APP_ID_RE.test(appId)) {
-            throw new Error(`自动生成的 App id '${appId}' 超出格式限制，请缩短 id 或 instancePrefix`);
-        }
-        if (existsSync(appDirForId(appId)))
-            continue;
-        const installedSpec = materializeInstalledSpec(spec, appId, offset);
-        const candidatePorts = collectDeclaredPorts(installedSpec);
-        let portConflict = false;
-        for (const port of candidatePorts) {
-            if (usedPorts.has(port) || await isPortInUse(port)) {
-                portConflict = true;
-                break;
-            }
-        }
-        if (portConflict)
-            continue;
-        return {
-            appId,
-            installedSpec,
-            // Always re-serialize from `installedSpec` so the cached yaml
-            // reflects every transform `materializeInstalledSpec` ran —
-            // including the platform pass that strips host_network/user fields
-            // on darwin. Using `originalSpecYaml` for offset=0 (the previous
-            // behavior) bypassed the transformer for multi-instance apps'
-            // first install slot and re-introduced the Linux-only fields on
-            // disk; subsequent panel restarts then re-read the raw source via
-            // `loadInstalledAppSpec` and broke macOS placement again.
-            installedSpecYaml: stringify(installedSpec),
-        };
-    }
-    throw new Error(`App '${baseId}' 没有可用安装槽位，目录名或端口已全部占用`);
-}
-function spawnStep(label, display, cmd, args, task) {
-    return spawnStepWithTimeout(label, display, display, cmd, args, 300_000, task);
-}
-const DOCKER_PULL_RETRY_ATTEMPTS = 3;
-// spawnStep's 5-min default is fine for small CLI calls but starves real-world
-// image pulls on ARM + SD-card hardware. Playwright v1.55.0-noble is ~2.3 GB
-// compressed (bundles Chromium + Firefox + WebKit), Hermes ~2.4 GB — neither
-// extracts in 5 min on a Raspberry Pi. 30 min clears both with headroom while
-// still capping runaway failures (total retry budget 90 min).
-const DOCKER_PULL_TIMEOUT_MS = 1_800_000;
-// Separate from the total timeout above: if docker pull stops producing any
-// stdout/stderr for long enough, treat it as stalled and retry rather than
-// waiting the full 30 minutes.
-//
-// Why 600s (not 180s): on slow links (especially Docker Hub from China to
-// edge devices), large single layers — AnythingLLM ~500MB, Playwright/Hermes
-// ~2.3GB — can spend 5-8 minutes between progress lines without TTY. 180s
-// idle was killing pulls that were actually making progress, then rolling
-// back the partially-completed image. Layer cache is preserved across
-// retries (docker dedupes by layer sha), so a higher idle ceiling lets each
-// big layer finish without throwing away the layers already on disk.
-const DOCKER_PULL_IDLE_TIMEOUT_MS = 600_000;
-async function pullDockerImageStep(label, image, display, task, timeoutMs = DOCKER_PULL_TIMEOUT_MS, idleTimeoutMs) {
-    if (await dockerImageExists(image)) {
-        const skipMessage = `[lifecycle:${label}] docker image '${image}' already exists locally; skipping pull`;
-        process.stdout.write(`  ${skipMessage}\n`);
-        emitInstallTaskLog(task, skipMessage);
-        return;
-    }
-    const anonymousDockerConfig = shouldBypassDockerCredentialHelperForDownloadImage(image)
-        ? createAnonymousDockerConfig()
-        : null;
-    let lastError;
-    try {
-        for (let attempt = 1; attempt <= DOCKER_PULL_RETRY_ATTEMPTS; attempt++) {
-            try {
-                await spawnStepWithTimeout(label, display, display, "docker", ["pull", image], timeoutMs, task, undefined, undefined, {
-                    idleTimeoutMs: idleTimeoutMs ?? Math.min(DOCKER_PULL_IDLE_TIMEOUT_MS, timeoutMs),
-                    envOverrides: anonymousDockerConfig?.envOverrides,
-                    stallMessageHint: "Docker credential resolution (for example docker-credential-desktop) may be involved.",
-                });
-                return;
-            }
-            catch (error) {
-                if (await dockerImageExists(image)) {
-                    const recoveredMessage = `[lifecycle:${label}] docker image '${image}' is present locally after pull failure/timeout; treating step as successful`;
-                    process.stdout.write(`  ${recoveredMessage}\n`);
-                    emitInstallTaskLog(task, recoveredMessage);
-                    return;
-                }
-                lastError = error;
-                if (attempt === DOCKER_PULL_RETRY_ATTEMPTS) {
-                    break;
-                }
-                const reason = error instanceof Error ? error.message : String(error);
-                const retryMessage = `[lifecycle:${label}] docker pull failed for ${image} (attempt ${attempt}/${DOCKER_PULL_RETRY_ATTEMPTS}): ${reason}; retrying`;
-                process.stdout.write(`  ${retryMessage}\n`);
-                emitInstallTaskLog(task, retryMessage);
-            }
-        }
-    }
-    finally {
-        anonymousDockerConfig?.cleanup();
-    }
-    throw (lastError instanceof Error ? lastError : new Error(String(lastError)));
-}
-async function dockerImageExists(image) {
-    return new Promise((resolve) => {
-        const child = spawn("docker", ["image", "inspect", image], {
-            stdio: "ignore",
-            env: buildLifecycleEnv(),
-        });
-        child.on("close", (code) => resolve(code === 0));
-        child.on("error", () => resolve(false));
-    });
-}
-function spawnStepWithTimeout(label, display, taskDisplay, cmd, args, timeoutMs, task, execOptions, sudo, runOptions) {
-    process.stdout.write(`  [lifecycle:${label}] ${display}\n`);
-    emitInstallTaskLog(task, `[lifecycle:${label}] ${taskDisplay}`);
-    return new Promise((resolve, reject) => {
-        const preparedEnv = prepareLifecycleExecEnv(sudo ? execOptions : undefined, runOptions?.envOverrides);
-        let cleaned = false;
-        let heartbeatTimer = null;
-        let idleTimer = null;
-        let stdoutPending = "";
-        let stderrPending = "";
-        let capturedStderr = "";
-        let forcedError = null;
-        const cleanupPreparedEnv = () => {
-            if (cleaned)
-                return;
-            cleaned = true;
-            if (heartbeatTimer) {
-                clearInterval(heartbeatTimer);
-                heartbeatTimer = null;
-            }
-            if (idleTimer) {
-                clearTimeout(idleTimer);
-                idleTimer = null;
-            }
-            preparedEnv.cleanup();
-        };
-        const spawnTarget = sudo
-            ? buildSudoWrappedCommand(cmd, args, preparedEnv.env, execOptions)
-            : { command: cmd, args };
-        const captureOutput = Boolean(task) || Boolean(sudo) || Boolean(runOptions?.idleTimeoutMs);
-        const child = spawn(spawnTarget.command, spawnTarget.args, {
-            stdio: captureOutput ? ["ignore", "pipe", "pipe"] : "inherit",
-            timeout: timeoutMs,
-            env: preparedEnv.env,
-        });
-        const resetIdleTimer = () => {
-            if (!runOptions?.idleTimeoutMs)
-                return;
-            if (idleTimer)
-                clearTimeout(idleTimer);
-            idleTimer = setTimeout(() => {
-                const idleSeconds = Math.max(1, Math.round(runOptions.idleTimeoutMs / 1000));
-                const stallMessageSuffix = runOptions.stallMessageHint ? ` ${runOptions.stallMessageHint}` : "";
-                const stallMessage = `[lifecycle:${label}] no output for ${idleSeconds}s; terminating stalled step: ${taskDisplay}${stallMessageSuffix}`;
-                process.stdout.write(`  ${stallMessage}\n`);
-                emitInstallTaskLog(task, stallMessage);
-                forcedError = new Error(`lifecycle '${label}' step stalled after ${idleSeconds}s with no output: ${display}${stallMessageSuffix}`);
-                child.kill("SIGTERM");
-            }, runOptions.idleTimeoutMs);
-            idleTimer.unref?.();
-        };
-        resetIdleTimer();
-        if (captureOutput) {
-            const startedAt = Date.now();
-            const flushPendingLine = (line) => {
-                if (!task)
-                    return;
-                emitInstallTaskLog(task, line);
-            };
-            const handleChunk = (chunk, stream) => {
-                resetIdleTimer();
-                const text = typeof chunk === "string" ? chunk : chunk.toString("utf-8");
-                if (stream === "stderr") {
-                    capturedStderr += text;
-                }
-                if (!task) {
-                    if (stream === "stdout")
-                        process.stdout.write(text);
-                    else
-                        process.stderr.write(text);
-                    return;
-                }
-                const normalized = `${stream === "stdout" ? stdoutPending : stderrPending}${text}`
-                    .replace(/\r\n/g, "\n")
-                    .replace(/\r/g, "\n");
-                const lines = normalized.split("\n");
-                const pending = lines.pop() ?? "";
-                if (stream === "stdout")
-                    stdoutPending = pending;
-                else
-                    stderrPending = pending;
-                for (const line of lines) {
-                    flushPendingLine(line);
-                }
-            };
-            child.stdout?.on("data", (data) => handleChunk(data, "stdout"));
-            child.stderr?.on("data", (data) => handleChunk(data, "stderr"));
-            if (task) {
-                heartbeatTimer = setInterval(() => {
-                    const elapsedSeconds = Math.max(1, Math.round((Date.now() - startedAt) / 1000));
-                    emitInstallTaskLog(task, `[lifecycle:${label}] still running (${elapsedSeconds}s): ${taskDisplay}`);
-                }, 10_000);
-                child.on("close", () => {
-                    flushPendingLine(stdoutPending);
-                    flushPendingLine(stderrPending);
-                });
-            }
-        }
-        child.on("close", (code) => {
-            cleanupPreparedEnv();
-            if (forcedError)
-                reject(forcedError);
-            else if (code === 0)
-                resolve();
-            else if (sudo)
-                reject(createLifecycleSudoError(capturedStderr, display, Boolean(execOptions?.sudoPassword)));
-            else
-                reject(new Error(`lifecycle '${label}' step failed (exit ${code ?? 1}): ${display}`));
-        });
-        child.on("error", (err) => {
-            cleanupPreparedEnv();
-            if (forcedError) {
-                reject(forcedError);
-                return;
-            }
-            if (sudo && err.code === "ENOENT") {
-                reject(new Error("当前环境未检测到 sudo，无法执行需要 sudo 的生命周期步骤。请以 root 身份重试。"));
-                return;
-            }
-            reject(new Error(`lifecycle '${label}' step error: ${err.message}`));
-        });
-    });
-}
-function lifecycleRunStepDisplay(label, index) {
-    if (label === "pre_install") {
-        return `run step ${index + 1}`;
-    }
-    return "$";
-}
-async function commandExists(command) {
-    return new Promise((resolve) => {
-        const quoted = command.replace(/'/g, "'\\''");
-        const child = spawn("sh", ["-c", `command -v '${quoted}' > /dev/null 2>&1`], {
-            stdio: "ignore",
-            env: buildLifecycleEnv(),
-        });
-        child.on("close", (code) => resolve(code === 0));
-        child.on("error", () => resolve(false));
-    });
-}
-// Recursively chown a path. Owner format is "uid:gid" (numeric only, e.g.
-// "0:0" or "1000:1000"). Used by container apps whose images run as a
-// different uid than the panel user — without this, bind-mounted data
-// dirs end up unwritable for the in-container process and fail with
-// SQLite "readonly database" or chroma init errors.
-function parseOwnerSpec(owner) {
-    const m = /^(\d+):(\d+)$/.exec(owner);
-    if (!m)
-        throw new Error(`chown owner must be "uid:gid" (numeric), got "${owner}"`);
-    return { uid: Number(m[1]), gid: Number(m[2]) };
-}
-function chownRecursive(path, uid, gid) {
-    chownSync(path, uid, gid);
-    let stat;
-    try {
-        stat = lstatSync(path);
-    }
-    catch {
-        return;
-    }
-    if (!stat.isDirectory())
-        return;
-    for (const entry of readdirSync(path)) {
-        chownRecursive(join(path, entry), uid, gid);
-    }
-}
-/**
- * Try chowning via direct fs syscall first; on EPERM (panel runs as a
- * non-root user with no CAP_CHOWN) fall back to `sudo -n chown`. The
- * fallback only succeeds where passwordless sudo is configured for the
- * panel user (the canonical Pi setup); on other hosts the original
- * EPERM bubbles up as a clear error.
- */
-function chownWithSudoFallback(path, uid, gid, recursive) {
-    try {
-        if (recursive)
-            chownRecursive(path, uid, gid);
-        else
-            chownSync(path, uid, gid);
-        return;
-    }
-    catch (e) {
-        if (e?.code !== "EPERM" && e?.code !== "EACCES")
-            throw e;
-    }
-    const args = [
-        "-n",
-        "chown",
-        ...(recursive ? ["-R"] : []),
-        `${uid}:${gid}`,
-        path,
-    ];
-    const r = spawnSync("sudo", args, { stdio: ["ignore", "ignore", "pipe"] });
-    if (r.status !== 0) {
-        const stderr = r.stderr ? r.stderr.toString().trim() : "";
-        throw new Error(`chown ${recursive ? "-R " : ""}${uid}:${gid} ${path} failed: panel user lacks CAP_CHOWN and passwordless sudo also failed${stderr ? `: ${stderr}` : ""}`);
-    }
-}
-async function downloadBinaryStep(label, url, dest, chmod, task) {
-    const expanded = expandPath(dest);
-    process.stdout.write(`  [lifecycle:${label}] downloadBinary: ${url} → ${expanded}\n`);
-    emitInstallTaskLog(task, `[lifecycle:${label}] downloadBinary: ${url} -> ${expanded}`);
-    mkdirSync(dirname(expanded), { recursive: true });
-    const tmp = expanded + ".tmp";
-    const res = await fetch(url);
-    if (!res.ok)
-        throw new Error(`downloadBinary: HTTP ${res.status} ${url}`);
-    const buf = await res.arrayBuffer();
-    writeFileSync(tmp, Buffer.from(buf), { mode: 0o644 });
-    renameSync(tmp, expanded);
-    if (chmod)
-        chmodSync(expanded, parseInt(chmod, 8));
-}
-async function runLifecycleSteps(steps, label, artifacts, task, execOptions) {
-    if (!steps || steps.length === 0)
-        return;
-    for (const [index, step] of steps.entries()) {
-        if ("run" in step) {
-            if (step.ifFileExists && !existsSync(expandPath(step.ifFileExists))) {
-                continue;
-            }
-            const timeoutMs = step.timeout_ms ?? 300_000;
-            const display = label === "pre_install"
-                ? lifecycleRunStepDisplay(label, index)
-                : `${lifecycleRunStepDisplay(label, index)} ${step.run}`;
-            const taskDisplay = `run step ${index + 1}`;
-            try {
-                await spawnStepWithTimeout(label, display, taskDisplay, "sh", ["-c", step.run], timeoutMs, task, execOptions, step.sudo === true);
-            }
-            catch (error) {
-                if (step.successIfCommandExists && await commandExists(step.successIfCommandExists)) {
-                    process.stdout.write(`  [lifecycle:${label}] command '${step.successIfCommandExists}' detected after failure/timeout; treating step as successful\n`);
-                    emitInstallTaskLog(task, `[lifecycle:${label}] command '${step.successIfCommandExists}' detected after failure/timeout; treating step as successful`);
-                    continue;
-                }
-                throw error;
-            }
-        }
-        else if ("checkNotCommand" in step) {
-            const cmd = step.checkNotCommand;
-            const found = await commandExists(cmd);
-            if (found) {
-                throw new Error(step.message ??
-                    `系统中已检测到 '${cmd}'，建议直接使用系统版本，无需重复安装。如需由 Nomad 统一管理，请先卸载系统版本`);
-            }
-        }
-        else if ("downloadImage" in step) {
-            await pullDockerImageStep(label, step.downloadImage, `downloadImage: ${step.downloadImage}`, task, step.timeout_ms, step.idle_timeout_ms);
-            artifacts?.push({ type: "image", path: step.downloadImage });
-        }
-        else if ("deleteImage" in step) {
-            await spawnStep(label, `deleteImage: ${step.deleteImage}`, "sh", [
-                "-c",
-                `docker rmi -f ${step.deleteImage} 2>/dev/null || true`,
-            ], task);
-        }
-        else if ("downloadBinary" in step) {
-            const { url, dest, chmod } = step.downloadBinary;
-            await downloadBinaryStep(label, url, dest, chmod, task);
-            artifacts?.push({ type: "binary", path: expandPath(dest) });
-        }
-        else if ("deleteBinary" in step) {
-            const p = expandPath(step.deleteBinary);
-            process.stdout.write(`  [lifecycle:${label}] deleteBinary: ${p}\n`);
-            emitInstallTaskLog(task, `[lifecycle:${label}] deleteBinary: ${p}`);
-            try {
-                unlinkSync(p);
-            }
-            catch (e) {
-                if (e.code !== "ENOENT")
-                    throw e;
-            }
-        }
-        else if ("mkdir" in step) {
-            const p = expandPath(step.mkdir);
-            process.stdout.write(`  [lifecycle:${label}] mkdir: ${p}\n`);
-            emitInstallTaskLog(task, `[lifecycle:${label}] mkdir: ${p}`);
-            mkdirSync(p, { recursive: true });
-            artifacts?.push({ type: "dir", path: p });
-        }
-        else if ("chown" in step) {
-            const p = expandPath(step.chown.path);
-            const { uid, gid } = parseOwnerSpec(step.chown.owner);
-            const recursive = step.chown.recursive !== false;
-            const tag = recursive ? "chown -R" : "chown";
-            process.stdout.write(`  [lifecycle:${label}] ${tag} ${uid}:${gid} ${p}\n`);
-            emitInstallTaskLog(task, `[lifecycle:${label}] ${tag} ${uid}:${gid} ${p}`);
-            if (!existsSync(p)) {
-                // chown only makes sense if the target exists; surface a clear
-                // error rather than letting fs throw an opaque ENOENT later.
-                throw new Error(`chown target does not exist: ${p}`);
-            }
-            try {
-                chownWithSudoFallback(p, uid, gid, recursive);
-            }
-            catch (chownErr) {
-                // In pre_start, chown failures are non-fatal: on macOS Docker/Colima
-                // the VM handles UID mapping for bind-mounts, so the container can
-                // write even without matching ownership. Failing fatally here blocks
-                // any non-root panel user from starting the app.
-                if (label === "pre_start") {
-                    const msg = `[lifecycle:${label}] ${tag} ${uid}:${gid} ${p} failed (non-fatal): ${chownErr.message}`;
-                    process.stdout.write(`  ${msg}\n`);
-                    emitInstallTaskLog(task, msg);
-                }
-                else {
-                    throw chownErr;
-                }
-            }
-        }
-        else if ("deleteDir" in step) {
-            const p = expandPath(step.deleteDir);
-            process.stdout.write(`  [lifecycle:${label}] deleteDir: ${p}\n`);
-            emitInstallTaskLog(task, `[lifecycle:${label}] deleteDir: ${p}`);
-            rmSync(p, { recursive: true, force: true });
-        }
-    }
-}
-function cleanupArtifacts(artifacts, task) {
-    for (let i = artifacts.length - 1; i >= 0; i--) {
-        const a = artifacts[i];
-        try {
-            switch (a.type) {
-                case "image":
-                    process.stdout.write(`  [cleanup] removing image: ${a.path}\n`);
-                    emitInstallTaskLog(task, `[cleanup] removing image: ${a.path}`);
-                    spawn("docker", ["rmi", "-f", a.path], { stdio: "ignore" }).unref();
-                    break;
-                case "binary":
-                    process.stdout.write(`  [cleanup] removing binary: ${a.path}\n`);
-                    emitInstallTaskLog(task, `[cleanup] removing binary: ${a.path}`);
-                    unlinkSync(a.path);
-                    break;
-                case "dir":
-                    process.stdout.write(`  [cleanup] removing dir: ${a.path}\n`);
-                    emitInstallTaskLog(task, `[cleanup] removing dir: ${a.path}`);
-                    rmSync(a.path, { recursive: true, force: true });
-                    break;
-            }
-        }
-        catch {
-            // best-effort
-        }
-    }
-}
-const DOCKER_IMAGE_RE = /^[a-zA-Z0-9][a-zA-Z0-9\-_.:/@]*$/;
-const APP_ID_RE = /^[a-z0-9][a-z0-9-]{0,62}$/;
-const _REGISTRY_PATH = join(APPS_DIR, "capability-registry.json");
-const INSTALL_LOCK_FILENAME = "install.lock";
-// ── Directory helpers ─────────────────────────────────────────────────────
-function appDirForId(appId) {
-    return join(APPS_DIR, appId);
-}
-function installLockPathForDir(appDir) {
-    return join(appDir, INSTALL_LOCK_FILENAME);
-}
-function hasInstallLock(appDir) {
-    return existsSync(installLockPathForDir(appDir));
-}
-function readInstallLockMetadata(appDir) {
-    const lockPath = installLockPathForDir(appDir);
-    if (!existsSync(lockPath))
-        return null;
-    try {
-        const parsed = JSON.parse(readFileSync(lockPath, "utf-8"));
-        return parsed && typeof parsed === "object" ? parsed : null;
-    }
-    catch {
-        return null;
-    }
-}
-function installDirLooksComplete(appDir) {
-    return (existsSync(join(appDir, "app-spec.yaml"))
-        && existsSync(join(appDir, "manifest.json"))
-        && existsSync(join(appDir, "instance.json")));
-}
-function isProcessAlive(pid) {
-    if (!Number.isInteger(pid) || pid <= 0)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function isStaleInstallLock(appDir) {
-    if (!hasInstallLock(appDir))
-        return false;
-    const metadata = readInstallLockMetadata(appDir);
-    if (!metadata)
-        return true;
-    const taskId = typeof metadata.taskId === "string" ? metadata.taskId.trim() : "";
-    if (taskId) {
-        return getTask(taskId)?.status !== "running";
-    }
-    if (typeof metadata.pid === "number") {
-        if (isProcessAlive(metadata.pid)) {
-            const specId = typeof metadata.specId === "string" ? metadata.specId.trim() : "";
-            if (installDirLooksComplete(appDir) && (!specId || getRunningTasks(`app-install-${specId}`).length === 0)) {
-                return true;
-            }
-            return false;
-        }
-        return !isProcessAlive(metadata.pid);
-    }
-    const specId = typeof metadata.specId === "string" ? metadata.specId.trim() : "";
-    return specId ? getRunningTasks(`app-install-${specId}`).length === 0 : true;
-}
-function cleanupStaleInstallDir(appDir) {
-    if (!isStaleInstallLock(appDir))
-        return false;
-    if (installDirLooksComplete(appDir)) {
-        process.stdout.write(`  [app-manager] removing stale install lock: ${appDir}\n`);
-        removeInstallLock(appDir);
-        return false;
-    }
-    process.stdout.write(`  [app-manager] removing stale install dir: ${appDir}\n`);
-    rmSync(appDir, { recursive: true, force: true });
-    return true;
-}
-function createInstallLock(appDir, appId, specId, task) {
-    writeFileSync(installLockPathForDir(appDir), JSON.stringify({ appId, specId, started_at: new Date().toISOString(), pid: process.pid, taskId: task?.id }, null, 2) + "\n", { mode: 0o644 });
-}
-function removeInstallLock(appDir) {
-    const lockPath = installLockPathForDir(appDir);
-    if (existsSync(lockPath)) {
-        unlinkSync(lockPath);
-    }
-}
-function appTaskName(kind, appId) {
-    return `app-${kind}:${appId}`;
-}
-function findRunningInstallTask(appDir) {
-    const metadata = readInstallLockMetadata(appDir);
-    const taskId = typeof metadata?.taskId === "string" ? metadata.taskId.trim() : "";
-    if (!taskId)
-        return undefined;
-    const status = getTask(taskId)?.status;
-    if (status !== "running")
-        return undefined;
-    return { id: taskId, kind: "install", status };
-}
-function findRunningNamedTask(taskName, kind) {
-    const running = getRunningTasks(taskName)[0];
-    if (!running)
-        return undefined;
-    const status = getTask(running.id)?.status;
-    if (status !== "running")
-        return undefined;
-    return { id: running.id, kind, status };
-}
-export function getRunningAppTask(appId, appDir) {
-    const resolvedAppDir = appDir ?? resolveAppLocation(appId)?.dir;
-    if (resolvedAppDir && hasInstallLock(resolvedAppDir)) {
-        const installTask = findRunningInstallTask(resolvedAppDir);
-        if (installTask)
-            return installTask;
-    }
-    for (const kind of ["uninstall", "restart", "stop", "start"]) {
-        const task = findRunningNamedTask(appTaskName(kind, appId), kind);
-        if (task)
-            return task;
-    }
-    return undefined;
-}
-function startAppLifecycleTask(appId, kind, startMessage, doneMessage, action) {
-    const currentTask = getRunningAppTask(appId);
-    if (currentTask) {
-        if (currentTask.kind === kind) {
-            return { ok: true, taskId: currentTask.id, reused: true, kind };
-        }
-        return {
-            ok: false,
-            error: `App '${appId}' 正在执行 ${currentTask.kind} 操作，请等待完成后再试`,
-            code: "TASK_BUSY",
-            kind,
-        };
-    }
-    const task = createTask(appTaskName(kind, appId));
-    emitAppTaskProgress(task, startMessage, 0);
-    void (async () => {
-        try {
-            await action();
-            task.status = "done";
-            emitTask(task, { type: "done", message: doneMessage, progress: 100 });
-        }
-        catch (e) {
-            task.status = "error";
-            emitTask(task, {
-                type: "error",
-                message: e?.message || `App '${appId}' ${kind} 失败`,
-            });
-        }
-    })();
-    return { ok: true, taskId: task.id, kind };
-}
-function instanceAppDirForId(appId) {
-    return join(INSTANCES_DIR, appId);
-}
-function resolveAppLocation(appId) {
-    const candidates = [
-        { dir: appDirForId(appId), installMode: "app-dir" },
-        { dir: instanceAppDirForId(appId), installMode: "instance-dir" },
-    ];
-    for (const candidate of candidates) {
-        cleanupStaleInstallDir(candidate.dir);
-        if (existsSync(join(candidate.dir, "app-spec.yaml"))
-            && existsSync(join(candidate.dir, "manifest.json"))) {
-            return candidate;
-        }
-    }
-    return null;
-}
-function isInstanceBackedApp(appData) {
-    return appData?.manifest.install_mode === "instance-dir";
-}
-function getSingleServiceTask(spec) {
-    const serviceTasks = spec.tasks.filter((task) => (task.role ?? "service") === "service");
-    if (spec.tasks.length !== 1 || serviceTasks.length !== 1)
-        return null;
-    return serviceTasks[0];
-}
-function inferLegacyAppType(spec) {
-    return /ollama/i.test(`${spec.id} ${spec.name ?? ""}`) ? "ollama" : "custom";
-}
-function rewriteInstanceScopedPathText(value, appId) {
-    return value
-        .split(`~/.jishushell/apps/${appId}`).join(`~/.jishushell/instances/${appId}`)
-        .split(`$HOME/.jishushell/apps/${appId}`).join(`$HOME/.jishushell/instances/${appId}`)
-        .split(`${homedir()}/.jishushell/apps/${appId}`).join(`${homedir()}/.jishushell/instances/${appId}`);
-}
-function rewriteInstanceScopedPaths(value, appId) {
-    if (typeof value === "string") {
-        return rewriteInstanceScopedPathText(value, appId);
-    }
-    if (Array.isArray(value)) {
-        return value.map((entry) => rewriteInstanceScopedPaths(entry, appId));
-    }
-    if (value && typeof value === "object") {
-        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
-            key,
-            rewriteInstanceScopedPaths(entry, appId),
-        ]));
-    }
-    return value;
-}
-function buildGenericInstanceBackedMeta(appId, spec) {
-    return {
-        id: appId,
-        name: spec.name || appId,
-        description: spec.description || "",
-        // See buildGenericAppMeta for the dual-write rationale: legacy
-        // `app_type` keeps V1 dispatch alive, `app_spec_ref` is the V2
-        // discriminator recognized by resolveAgentType.
-        app_type: inferLegacyAppType(spec),
-        app_spec_ref: spec.id,
-        ...(spec.singleInstance ? { singleInstance: true } : {}),
-        runtime: {},
-        created_at: new Date().toISOString(),
-        app_id: spec.app_id ?? appId,
-    };
-}
-function explicitAgentTypeForSpec(spec) {
-    if (typeof spec.agentType === "string" && spec.agentType.trim()) {
-        return spec.agentType.trim();
-    }
-    if (typeof spec._engine?.agentType === "string" && spec._engine.agentType.trim()) {
-        return spec._engine.agentType.trim();
-    }
-    return "";
-}
-function buildGenericAppRuntime(spec, appId) {
-    const serviceTask = spec.tasks.find((task) => (task.role ?? "service") === "service");
-    if (!serviceTask)
-        return {};
-    const runtime = compileTaskRuntime(serviceTask, appId);
-    if (Array.isArray(serviceTask.ports) && serviceTask.ports.length > 0) {
-        runtime.ports = serviceTask.ports.map((port) => ({
-            name: port.name,
-            containerPort: port.container_port ?? port.port,
-            hostPort: port.host_port ?? port.port,
-            visibility: port.visibility ?? "external",
-        }));
-    }
-    if (serviceTask.health?.http) {
-        const healthPortEntry = serviceTask.ports?.find((port) => port.port === serviceTask.health?.http?.port
-            || port.host_port === serviceTask.health?.http?.port
-            || port.container_port === serviceTask.health?.http?.port);
-        runtime.health = {
-            type: "http",
-            path: serviceTask.health.http.path,
-            port: healthPortEntry?.host_port ?? healthPortEntry?.port ?? serviceTask.health.http.port,
-            interval: serviceTask.health.interval,
-            timeout: serviceTask.health.timeout,
-            retries: serviceTask.health.retries,
-        };
-    }
-    if (Array.isArray(serviceTask.volumes)) {
-        runtime.volumes = serviceTask.volumes.map((volume) => ({
-            hostPath: expandPath(String(volume.source ?? "")),
-            containerPath: String(volume.target ?? ""),
-            mode: volume.readonly ? "ro" : "rw",
-        }));
-    }
-    return runtime;
-}
-function buildGenericAppMeta(appId, spec, createdAt) {
-    const explicitAgentType = explicitAgentTypeForSpec(spec);
-    return {
-        id: appId,
-        name: spec.name || appId,
-        description: spec.description || "",
-        runtime: buildGenericAppRuntime(spec, appId),
-        created_at: createdAt,
-        app_id: spec.app_id ?? appId,
-        ...(explicitAgentType
-            ? { agentType: explicitAgentType }
-            : {
-                // `app_type: "custom"` is the V1 legacy marker; `app_spec_ref`
-                // is the V2 discriminator that resolveAgentType (runtime/
-                // instance.ts) uses to route to the custom adapter. Writing
-                // both makes dispatch survive the eventual removal of the
-                // resolveLegacyAppType bridge without touching each instance.
-                app_type: inferLegacyAppType(spec),
-                app_spec_ref: spec.id,
-                ...(spec.singleInstance ? { singleInstance: true } : {}),
-            }),
-    };
-}
-async function bootstrapAdapterManagedApp(appId, spec, options) {
-    const agentType = explicitAgentTypeForSpec(spec);
-    if (!agentType)
-        return false;
-    const { hasAdapter, getAdapter } = await import("../runtime/index.js");
-    if (!hasAdapter(agentType))
-        return false;
-    const adapter = getAdapter(agentType);
-    if (!adapter.createInstance)
-        return false;
-    await adapter.createInstance({
-        instanceId: appId,
-        name: options.bootstrap?.name ?? spec.name ?? appId,
-        description: options.bootstrap?.description ?? spec.description ?? "",
-        cloneFrom: options.bootstrap?.cloneFrom,
-        agentHome: options.bootstrap?.agentHome,
-        cloneOptions: options.bootstrap?.cloneOptions,
-        appSpec: spec,
-    });
-    return true;
-}
-function getAdapterManagedAgentType(appData) {
-    if (!appData || appData.manifest.install_mode !== "app-dir")
-        return null;
-    const meta = legacyInstanceManager.getInstance(appData.manifest.id);
-    const agentType = typeof meta?.agentType === "string" ? meta.agentType.trim() : "";
-    const legacyAppType = typeof meta?.app_type === "string" ? meta.app_type.trim() : "";
-    if (!agentType || legacyAppType)
-        return null;
-    return agentType;
-}
-async function installIntoInstanceDir(spec, specYaml, requestedAppId, options = {}) {
-    if (options.preferInstanceDir !== true)
-        return null;
-    const serviceTask = getSingleServiceTask(spec);
-    if (!serviceTask)
-        return null;
-    const explicitAgentType = typeof spec.agentType === "string" && spec.agentType.trim()
-        ? spec.agentType.trim()
-        : typeof spec._engine?.agentType === "string" && spec._engine.agentType.trim()
-            ? spec._engine.agentType.trim()
-            : "";
-    const { hasAdapter, getAdapter } = await import("../runtime/index.js");
-    let installTarget = null;
-    if (explicitAgentType) {
-        if (hasAdapter(explicitAgentType) && getAdapter(explicitAgentType).createInstance) {
-            installTarget = { kind: "adapter", agentType: explicitAgentType };
-        }
-    }
-    else {
-        const hintText = `${spec.id} ${spec.name ?? ""}`.toLowerCase();
-        for (const hintedAgentType of ["openclaw", "hermes"]) {
-            if (hintText.includes(hintedAgentType) && hasAdapter(hintedAgentType) && getAdapter(hintedAgentType).createInstance) {
-                installTarget = { kind: "adapter", agentType: hintedAgentType };
-                break;
-            }
-        }
-        if (!installTarget && serviceTask.runtime === "container") {
-            installTarget = { kind: "legacy", appType: inferLegacyAppType(spec) };
-        }
-    }
-    if (!installTarget)
-        return null;
-    const { appId, installedSpec, } = await resolveInstallTarget(spec, specYaml, requestedAppId);
-    let instanceSpec = rewriteInstanceScopedPaths(installedSpec, appId);
-    // PR 3 sub-step 3c: switch from legacy `resolveRequires(spec)` to the new
-    // resolveConnections in preCreate mode. Legacy single-candidate fallback
-    // still materializes its env (so meta-apps stay "open the box and it
-    // works"); category-prefix requires + missing required producers fall
-    // into `pending` for UI display via the install task event (PR 4 wires
-    // task.event.affectedConsumers etc.). install never fails here — even if
-    // a required capability is unavailable; start time will surface the
-    // error. The previous `ensureRequiredCapabilitiesAvailable` block has
-    // been removed for the same reason.
-    const { resolveConnections, resolvedToLegacyEnv } = await import("../connection-resolver.js");
-    const { resolved, pending } = resolveConnections(installedSpec, { connections: {} }, "preCreate");
-    if (pending.length > 0) {
-        console.log(`[install] ${appId}: ${pending.length} pending connection(s): ` +
-            pending.map((p) => `${p.slot} (${p.capability}, ${p.reason})`).join(", "));
-    }
-    const resolvedRequires = resolvedToLegacyEnv(resolved);
-    if (Object.keys(resolvedRequires).length > 0) {
-        instanceSpec = {
-            ...installedSpec,
-            tasks: installedSpec.tasks.map((task) => (task.role ?? "service") === "service"
-                ? { ...task, env: { ...task.env, ...resolvedRequires } }
-                : task),
-        };
-        instanceSpec = rewriteInstanceScopedPaths(instanceSpec, appId);
-    }
-    const persistedSpecYaml = stringify(instanceSpec);
-    const instanceDir = instanceAppDirForId(appId);
-    const manifest = {
-        id: appId,
-        installed_at: new Date().toISOString(),
-        spec_hash: createHash("sha256").update(persistedSpecYaml).digest("hex"),
-        install_mode: "instance-dir",
-    };
-    const { getAppManager } = await import("./registry.js");
-    const instanceName = instanceSpec.name || appId;
-    const instanceDescription = instanceSpec.description || "";
-    const artifacts = [];
-    try {
-        if (installTarget?.kind === "adapter") {
-            const adapter = getAdapter(installTarget.agentType);
-            if (!adapter.createInstance)
-                return null;
-            await adapter.createInstance({
-                instanceId: appId,
-                name: instanceName,
-                description: instanceDescription,
-                appSpec: instanceSpec,
-            });
-        }
-        else if (installTarget?.kind === "legacy") {
-            await getAppManager(installTarget.appType).createInstance(appId, instanceName, instanceDescription, { appSpec: instanceSpec });
-        }
-        else {
-            ensureDirHost(instanceDir);
-            safeWriteJson(join(instanceDir, "instance.json"), buildGenericInstanceBackedMeta(appId, instanceSpec), true);
-        }
-        ensureDirHost(instanceDir);
-        const yamlPath = join(instanceDir, "app-spec.yaml");
-        const yamlTmp = yamlPath + ".tmp";
-        writeFileSync(yamlTmp, persistedSpecYaml, { mode: 0o644 });
-        renameSync(yamlTmp, yamlPath);
-        safeWriteJson(join(instanceDir, "manifest.json"), manifest, true);
-        await runLifecycleSteps(instanceSpec.lifecycle?.pre_install, "pre_install", artifacts, options.task, options.exec);
-    }
-    catch (e) {
-        cleanupArtifacts(artifacts, options.task);
-        try {
-            const instanceManager = await import("../instance-manager.js");
-            await instanceManager.deleteInstance(appId);
-        }
-        catch {
-            rmSync(instanceDir, { recursive: true, force: true });
-        }
-        throw decorateInstallError(e, instanceSpec);
-    }
-    try {
-        await runLifecycleSteps(instanceSpec.lifecycle?.install, "install", artifacts, options.task, options.exec);
-        const pulledImages = new Set(artifacts.filter((artifact) => artifact.type === "image").map((artifact) => artifact.path));
-        const imagesToPull = [...new Set(instanceSpec.tasks.filter((task) => task.image).map((task) => task.image))];
-        for (const image of imagesToPull) {
-            if (!pulledImages.has(image)) {
-                await pullDockerImageStep("install", image, `docker pull ${image}`, options.task);
-                artifacts.push({ type: "image", path: image });
-            }
-        }
-    }
-    catch (e) {
-        try {
-            await runLifecycleSteps(instanceSpec.lifecycle?.uninstall, "rollback_uninstall", undefined, options.task, options.exec);
-        }
-        catch (rollbackError) {
-            process.stdout.write(`  [app-manager] rollback uninstall failed: ${rollbackError.message}\n`);
-            emitInstallTaskLog(options.task, `[app-manager] rollback uninstall failed: ${rollbackError.message}`);
-        }
-        cleanupArtifacts(artifacts, options.task);
-        try {
-            const instanceManager = await import("../instance-manager.js");
-            await instanceManager.deleteInstance(appId);
-        }
-        catch {
-            rmSync(instanceDir, { recursive: true, force: true });
-        }
-        throw decorateInstallError(e, instanceSpec);
-    }
-    if (artifacts.length > 0) {
-        manifest.artifacts = artifacts;
-        safeWriteJson(join(instanceDir, "manifest.json"), manifest, true);
-    }
-    return { spec: instanceSpec, manifest };
-}
-/**
- * Check whether an app with this id is installed (has manifest.json + app-spec.yaml).
- * Exported so nomad-manager can use it for routing without the old prefix convention.
- */
-export function isAppInstalled(appId) {
-    const location = resolveAppLocation(appId);
-    return location != null && !hasInstallLock(location.dir);
-}
-function resolveAppDir(appId) {
-    return resolveAppLocation(appId)?.dir ?? null;
-}
-function readAppFromDir(appDir, appId, installModeHint = "app-dir") {
-    if (cleanupStaleInstallDir(appDir))
-        return null;
-    const yamlPath = join(appDir, "app-spec.yaml");
-    const manifestPath = join(appDir, "manifest.json");
-    if (!existsSync(yamlPath) || !existsSync(manifestPath))
-        return null;
-    try {
-        const spec = normalizeAppSpec(parse(readFileSync(yamlPath, "utf-8")));
-        const manifest = safeReadJson(manifestPath, `app:${appId}`);
-        if (!manifest)
-            return null;
-        return {
-            spec,
-            manifest: {
-                ...manifest,
-                install_mode: manifest.install_mode ?? installModeHint,
-            },
-            install_state: hasInstallLock(appDir) ? "installing" : "installed",
-            ...(getRunningAppTask(appId, appDir) ? { current_task: getRunningAppTask(appId, appDir) } : {}),
-        };
-    }
-    catch {
-        return null;
-    }
-}
-export function getAppInstallState(appId) {
-    const location = resolveAppLocation(appId);
-    if (!location)
-        return null;
-    return hasInstallLock(location.dir) ? "installing" : "installed";
-}
-const BROWSERLESS_DEBUGGER_CAPABILITY = "browserless-debugger";
-const BROWSERLESS_API_CAPABILITY = "browserless-api";
-const BROWSERLESS_DOCS_CAPABILITY = "browserless-docs";
-/**
- * Compat-view registry reader. Returns the legacy `{ capabilities: {} }`
- * shape that older call sites expect. The new `capability-registry.ts`
- * module migrates dual-shape entries on every read so the legacy view is
- * always populated. PR 3 sub-step 3f deletes this shim.
- */
-function readRegistry() {
-    const file = capabilityRegistry.readRegistry();
-    return { capabilities: file.capabilities ?? {}, providersByCapability: file.providersByCapability };
-}
-// `ensureRequiredCapabilitiesAvailable` was removed in PR 3 sub-step 3c.
-// install never blocks on missing required providers any more —
-// resolveConnections(..., "preCreate") collects them into the `pending`
-// list and the UI surfaces them after install completes.
-// `listProvidedCapabilities()` does a full filesystem app scan (listApps →
-// readdir + per-app spec parse) plus a registry read. `augmentInstanceMetadata`
-// calls it ~2× per instance (getProvidedCapabilitiesForApp +
-// getEmbeddedUiHintForApp), so `GET /api/instances` over N instances did ~2N
-// full disk scans per request — the dashboard warm-path cost.
-//
-// Cache the result, but key validity on a CHEAP fingerprint of the
-// underlying state, not on time alone. A time-only TTL left a staleness
-// window where a freshly installed/uninstalled app (or created/deleted
-// instance — INSTANCES_DIR also feeds listApps) was missing from / lingered
-// in the list until the TTL expired, which broke the Connections UI and the
-// embedded-UI hint. The fingerprint (sorted dir entries of APPS_DIR +
-// INSTANCES_DIR, plus the registry file mtime) changes the instant the app
-// set or registry changes — including external mutations — so the cache
-// self-busts without having to hook every mutation site. It costs two
-// readdir + one stat, still vastly cheaper than re-parsing every app spec.
-// The short TTL stays only as a safety net for in-place spec edits that
-// don't change the dir set; the explicit register/unregister/markStopped
-// invalidations remain as a precise fast-path for sub-millisecond registry
-// writes that could share an mtime tick.
-const PROVIDED_CAPS_TTL_MS = 5_000;
-let _providedCapsEntry = null;
-function providedCapabilitiesFingerprint() {
-    const dirEntries = (dir) => {
-        try {
-            return existsSync(dir) ? readdirSync(dir).sort().join(",") : "";
-        }
-        catch {
-            return "";
-        }
-    };
-    let registryMtime = 0;
-    try {
-        registryMtime = lstatSync(_REGISTRY_PATH).mtimeMs;
-    }
-    catch {
-        /* registry file not written yet → 0 */
-    }
-    return `${dirEntries(APPS_DIR)}|${dirEntries(INSTANCES_DIR)}|${registryMtime}`;
-}
-export function invalidateProvidedCapabilitiesCache() {
-    _providedCapsEntry = null;
-}
-export function listProvidedCapabilities() {
-    const fp = providedCapabilitiesFingerprint();
-    const now = Date.now();
-    if (_providedCapsEntry &&
-        _providedCapsEntry.fp === fp &&
-        now - _providedCapsEntry.ts < PROVIDED_CAPS_TTL_MS) {
-        return _providedCapsEntry.data;
-    }
-    const data = computeProvidedCapabilities();
-    _providedCapsEntry = { data, fp, ts: now };
-    return data;
-}
-function computeProvidedCapabilities() {
-    const reg = readRegistry();
-    return listApps().flatMap((app) => (app.spec.provides ?? []).map((provide) => {
-        const url = getProvideUrl(provide) ?? undefined;
-        const port = getProvidePort(app.spec, provide) ?? undefined;
-        const address = !url && typeof port === "number" ? buildCapabilityAddress(port, provide.path) : undefined;
-        const providers = reg.providersByCapability?.[provide.capability] ?? [];
-        const registered = providers.find((e) => e.instanceId === app.manifest.id)
-            ?? providers.find((e) => e.status === "running")
-            ?? providers[0];
-        const protocol = resolveProvideProtocol(provide);
-        return {
-            appId: app.manifest.id,
-            capability: provide.capability,
-            ...(typeof port === "number" ? { port } : {}),
-            ...(provide.path ? { path: provide.path } : {}),
-            ...(url ? { url } : {}),
-            protocol,
-            ...(provide.visibility ? { visibility: provide.visibility } : {}),
-            ...(provide.description ? { description: provide.description } : {}),
-            ...(provide.terminal ? { terminal: provide.terminal } : {}),
-            ...(provide.embedded ? { embedded: provide.embedded } : {}),
-            ...(address ? { address } : {}),
-            registered: Boolean(registered),
-            ...(registered?.address ? { registeredAddress: registered.address } : {}),
-            ...(registered?.instanceId ? { providerInstanceId: registered.instanceId } : {}),
-        };
-    }));
-}
-export function getProvidedCapabilitiesForApp(appId) {
-    return listProvidedCapabilities().filter((entry) => entry.appId === appId);
-}
-/**
- * Resolve the runtime endpoint (host + port) for a given app's capability.
- * Returns the runtime-resolved port when available, falling back to the
- * declared AppSpec port. This is used by the capability proxy to target the
- * correct live endpoint after potential port reallocation.
- */
-export function resolveRuntimeCapabilityPort(appId, capabilityName) {
-    const app = getApp(appId);
-    if (!app)
-        return null;
-    const provide = (app.spec.provides ?? []).find((p) => p.capability === capabilityName);
-    if (!provide)
-        return null;
-    const resolved = resolveProvideEndpoint(appId, app.spec, provide);
-    return resolved?.hostPort ?? getProvidePort(app.spec, provide);
-}
-export function getEmbeddedUiHintForApp(appId) {
-    const provides = getProvidedCapabilitiesForApp(appId);
-    if (!provides.length)
-        return null;
-    // Selection priority for which provide becomes the embedded UI:
-    //   1. browserless-debugger (special — dev console, not the API)
-    //   2. any capability whose name ends in "-ui" (the canonical Web UI slot,
-    //      by convention served at "/"). Apps like AnythingLLM provide both an
-    //      API capability (`knowledge-anythingllm`, path `/api/v1`) AND a UI
-    //      capability (`anythingllm-ui`, path `/`). Without this preference
-    //      the first-iterated provide wins and the iframe ends up pointing
-    //      at `/api/v1` → 404.
-    //   3. fall back to natural order for legacy single-capability apps.
-    const browserlessPreferred = provides.find((provide) => provide.capability === BROWSERLESS_DEBUGGER_CAPABILITY);
-    const uiPreferred = provides.find((provide) => provide.capability.endsWith("-ui"));
-    const preferred = browserlessPreferred ?? uiPreferred ?? null;
-    const orderedProvides = preferred
-        ? [preferred, ...provides.filter((provide) => provide !== preferred)]
-        : provides;
-    for (const provide of orderedProvides) {
-        const protocol = normalizeProvideProtocol(provide.protocol);
-        if (provide.visibility === "internal")
-            continue;
-        if (protocol !== "http" && protocol !== "https")
-            continue;
-        if (typeof provide.url === "string" && provide.url.trim()) {
-            const url = provide.url.trim();
-            return {
-                capability: provide.capability,
-                protocol,
-                url,
-            };
-        }
-        if (typeof provide.port !== "number" || provide.port < 1)
-            continue;
-        // Honor explicit `embedded` opt-in/out on the provide before the
-        // auto-detection logic runs. `"proxy"` short-circuits to the
-        // same-origin proxy path (needed when upstream is firewall-blocked,
-        // emits X-Frame-Options, or otherwise can't be reached by the
-        // browser directly). `"direct"` forces the direct URL even when
-        // listening only on loopback — caller asserts they know what
-        // they're doing.
-        const embeddedMode = provide.embedded ?? "auto";
-        // Prefer a direct upstream URL when the container port is published to
-        // a LAN-reachable address (Pi with host_network "external", etc.). The
-        // same-origin reverse-proxy path is necessary only when the container
-        // is bound to 127.0.0.1 (macOS+Colima, dev laptops without LAN
-        // exposure) — there it's the only way for a remote browser to reach
-        // the iframe content. Going through the proxy when the upstream is
-        // already public causes path-collision bugs for apps that fetch
-        // absolute URLs starting with `/api/...` (e.g. OpenWebUI), because
-        // those calls bypass `<base href>` and hit the panel API instead.
-        const listeningHost = legacyInstanceManager.getListeningHostForPort(provide.port);
-        const isLoopback = listeningHost === "127.0.0.1" || listeningHost === "::1";
-        const directlyReachable = embeddedMode !== "proxy"
-            && listeningHost
-            && (!isLoopback || embeddedMode === "direct");
-        if (directlyReachable) {
-            const advertised = legacyInstanceManager.getAdvertisedHostForPort(provide.port);
-            const directUrl = `${protocol}://${advertised}:${provide.port}${provide.path ?? ""}`;
-            return {
-                capability: provide.capability,
-                protocol,
-                port: provide.port,
-                url: directUrl,
-            };
-        }
-        // Use same-origin reverse-proxy path so the frontend iframe works for
-        // remote browsers and macOS+Colima environments where the container
-        // port is only published to 127.0.0.1.
-        // Root-path UIs (path omitted) still need a trailing slash so the
-        // browser treats the iframe src as a directory URL. Without it, some
-        // SPA runtimes compute relative URLs from `/.../provides/<capability>`
-        // as if `<capability>` were a file segment, which breaks boot under the
-        // proxy even when the HTML/base rewrite succeeded.
-        const normalizedProvidePath = typeof provide.path === "string" ? provide.path.trim() : "";
-        const needsTrailingSlash = !normalizedProvidePath || normalizedProvidePath.endsWith("/");
-        const proxyPath = `/api/instances/${encodeURIComponent(appId)}/provides/${encodeURIComponent(provide.capability)}${needsTrailingSlash ? "/" : ""}`;
-        return {
-            capability: provide.capability,
-            protocol,
-            port: provide.port,
-            url: proxyPath,
-        };
-    }
-    return null;
-}
-export async function installApp(specYaml, requestedAppId, options = {}) {
-    let spec;
-    try {
-        spec = normalizeAppSpec(parse(specYaml));
-    }
-    catch (e) {
-        throw new Error(`YAML 解析失败: ${e.message}`);
-    }
-    if (!spec || !spec.id || !APP_ID_RE.test(spec.id)) {
-        throw new Error(`App id '${spec?.id}' 格式无效，必须符合 /^[a-z0-9][a-z0-9-]{0,62}$/`);
-    }
-    ensureCompatibleJishuShellVersion(spec);
-    if (!Array.isArray(spec.tasks) || spec.tasks.length === 0) {
-        throw new Error("tasks 不能为空");
-    }
-    const hasService = spec.tasks.some((t) => t.role === "service");
-    if (!hasService) {
-        throw new Error("tasks 中至少需要一个 role 为 'service' 的任务");
-    }
-    for (const task of spec.tasks) {
-        if (task.runtime === "vm") {
-            throw new Error(`runtime 'vm' 暂不支持，请使用 runtime: container 或 process`);
-        }
-        if (task.runtime === "container" && !task.image) {
-            throw new Error(`container task '${task.name}' 需要指定 image 字段`);
-        }
-        if (task.runtime === "process" && !task.command) {
-            throw new Error(`process task '${task.name}' 需要指定 command 或 binary 字段`);
-        }
-        if (task.image && !DOCKER_IMAGE_RE.test(task.image)) {
-            throw new Error(`task '${task.name}' 的 image '${task.image}' 格式无效`);
-        }
-    }
-    // PR 3 sub-step 3c: removed the legacy `ensureRequiredCapabilitiesAvailable`
-    // hard-stop. install now never blocks on missing required providers —
-    // resolveConnections(..., "preCreate") records them as `pending` on the
-    // install task event so the UI can prompt the user; start time surfaces
-    // the error if still unresolved.
-    const instanceBackedInstall = await installIntoInstanceDir(spec, specYaml, requestedAppId, options);
-    if (instanceBackedInstall) {
-        return instanceBackedInstall;
-    }
-    const { appId, installedSpec, installedSpecYaml, } = await resolveInstallTarget(spec, specYaml, requestedAppId);
-    const appDir = appDirForId(appId);
-    ensureDirHost(appDir);
-    createInstallLock(appDir, appId, spec.id, options.task);
-    emitInstallTaskLog(options.task, `[app-manager] created ${INSTALL_LOCK_FILENAME} for ${appId}`);
-    const yamlPath = join(appDir, "app-spec.yaml");
-    const yamlTmp = yamlPath + ".tmp";
-    writeFileSync(yamlTmp, installedSpecYaml, { mode: 0o644 });
-    renameSync(yamlTmp, yamlPath);
-    const manifest = {
-        id: appId,
-        installed_at: new Date().toISOString(),
-        spec_hash: createHash("sha256").update(installedSpecYaml).digest("hex"),
-        install_mode: "app-dir",
-    };
-    safeWriteJson(join(appDir, "manifest.json"), manifest, true);
-    const artifacts = [];
-    try {
-        await runLifecycleSteps(installedSpec.lifecycle?.pre_install, "pre_install", artifacts, options.task, options.exec);
-    }
-    catch (e) {
-        cleanupArtifacts(artifacts, options.task);
-        rmSync(appDir, { recursive: true, force: true });
-        throw decorateInstallError(e, installedSpec);
-    }
-    try {
-        await runLifecycleSteps(installedSpec.lifecycle?.install, "install", artifacts, options.task, options.exec);
-        // Auto-pull docker images declared in tasks (deduplicated, skip already-pulled by lifecycle steps)
-        const pulledImages = new Set(artifacts.filter(a => a.type === "image").map(a => a.path));
-        const imagesToPull = [...new Set(installedSpec.tasks.filter(t => t.image).map(t => t.image))];
-        for (const image of imagesToPull) {
-            if (!pulledImages.has(image)) {
-                await pullDockerImageStep("install", image, `docker pull ${image}`, options.task);
-                artifacts.push({ type: "image", path: image });
-            }
-        }
-        const bootstrappedByAdapter = await bootstrapAdapterManagedApp(appId, installedSpec, options);
-        if (!bootstrappedByAdapter) {
-            safeWriteJson(join(appDir, "instance.json"), buildGenericAppMeta(appId, installedSpec, manifest.installed_at), true);
-        }
-    }
-    catch (e) {
-        try {
-            await runLifecycleSteps(installedSpec.lifecycle?.uninstall, "rollback_uninstall", undefined, options.task, options.exec);
-        }
-        catch (rollbackError) {
-            process.stdout.write(`  [app-manager] rollback uninstall failed: ${rollbackError.message}\n`);
-            emitInstallTaskLog(options.task, `[app-manager] rollback uninstall failed: ${rollbackError.message}`);
-        }
-        cleanupArtifacts(artifacts, options.task);
-        rmSync(appDir, { recursive: true, force: true });
-        throw decorateInstallError(e, installedSpec);
-    }
-    if (artifacts.length > 0) {
-        manifest.artifacts = artifacts;
-        safeWriteJson(join(appDir, "manifest.json"), manifest, true);
-    }
-    removeInstallLock(appDir);
-    emitInstallTaskLog(options.task, `[app-manager] removed ${INSTALL_LOCK_FILENAME} for ${appId}`);
-    return { spec: installedSpec, manifest };
-}
-export function listApps() {
-    const results = [];
-    for (const { rootDir, installMode } of [
-        { rootDir: APPS_DIR, installMode: "app-dir" },
-        { rootDir: INSTANCES_DIR, installMode: "instance-dir" },
-    ]) {
-        if (!existsSync(rootDir))
-            continue;
-        let entries;
-        try {
-            entries = readdirSync(rootDir, { withFileTypes: true });
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            if (!entry.isDirectory())
-                continue;
-            const appId = entry.name;
-            const appDir = join(rootDir, appId);
-            try {
-                const appData = readAppFromDir(appDir, appId, installMode);
-                if (!appData)
-                    continue;
-                results.push(appData);
-            }
-            catch (e) {
-                console.warn(`[app-manager] Skipping app '${appId}': ${e.message}`);
-            }
-        }
-    }
-    const deduped = new Map();
-    for (const item of results) {
-        deduped.set(item.manifest.id, item);
-    }
-    return [...deduped.values()];
-}
-export function getApp(id) {
-    if (!APP_ID_RE.test(id))
-        return null;
-    const location = resolveAppLocation(id);
-    if (!location)
-        return null;
-    return readAppFromDir(location.dir, id, location.installMode);
-}
-function writeAppManagerWarnings(warnings) {
-    for (const warning of warnings) {
-        process.stdout.write(`  [app-manager] ${warning}\n`);
-    }
-}
-export async function uninstallApp(id, options = {}) {
-    if (!APP_ID_RE.test(id))
-        return;
-    const appData = getApp(id);
-    const warnings = [];
-    if (isInstanceBackedApp(appData)) {
-        const { stopNomadJobInstance } = await import("../nomad-manager.js");
-        const stopResult = await stopNomadJobInstance(id, true);
-        if (!stopResult.ok && stopResult.error && !stopResult.error.includes("not found") && !stopResult.error.includes("not running")) {
-            warnings.push(`应用 '${id}' 停止失败: ${stopResult.error}`);
-        }
-        if (appData) {
-            // For multi-instance container apps the uninstalled app is the base
-            // template and may have spawned children via copyApp. Children carry
-            // `app_id === id`; stop + delete them here so they don't outlive the
-            // template that described their lifecycle.
-            if (appData.spec.singleInstance === false) {
-                warnings.push(...await deleteLinkedInstances(appData.manifest.id));
-            }
-            const uninstallSteps = selectUninstallLifecycleSteps(appData);
-            if (uninstallSteps?.length) {
-                try {
-                    await runLifecycleSteps(uninstallSteps, "uninstall", undefined, undefined, options.exec);
-                }
-                catch (e) {
-                    writeAppManagerWarnings(warnings);
-                    throw new Error(`卸载生命周期执行失败: ${e.message}`);
-                }
-            }
-            const cleanupList = selectCleanupArtifacts(appData);
-            if (cleanupList.length > 0) {
-                cleanupArtifacts(cleanupList);
-            }
-        }
-        unregisterCapabilities(id);
-        const instanceManager = await import("../instance-manager.js");
-        const deleteResult = await instanceManager.deleteInstance(id);
-        if (!deleteResult.ok && deleteResult.warnings?.length) {
-            warnings.push(...deleteResult.warnings);
-        }
-        writeAppManagerWarnings(warnings);
-        return;
-    }
-    const adapterManagedAgentType = getAdapterManagedAgentType(appData);
-    if (adapterManagedAgentType) {
-        const { stopNomadJobInstance } = await import("../nomad-manager.js");
-        const stopResult = await stopNomadJobInstance(id, true);
-        if (!stopResult.ok && stopResult.error && !stopResult.error.includes("not found") && !stopResult.error.includes("not running")) {
-            warnings.push(`应用 '${id}' 停止失败: ${stopResult.error}`);
-        }
-        if (appData) {
-            warnings.push(...await deleteLinkedInstances(appData.manifest.id));
-            const uninstallSteps = selectUninstallLifecycleSteps(appData);
-            if (uninstallSteps?.length) {
-                try {
-                    await runLifecycleSteps(uninstallSteps, "uninstall", undefined, undefined, options.exec);
-                }
-                catch (e) {
-                    writeAppManagerWarnings(warnings);
-                    throw new Error(`卸载生命周期执行失败: ${e.message}`);
-                }
-            }
-            const cleanupList = selectCleanupArtifacts(appData);
-            if (cleanupList.length > 0) {
-                cleanupArtifacts(cleanupList);
-            }
-        }
-        unregisterCapabilities(id);
-        const deleteResult = await legacyInstanceManager.deleteInstance(id);
-        if (!deleteResult.ok && deleteResult.warnings?.length) {
-            warnings.push(...deleteResult.warnings);
-        }
-        writeAppManagerWarnings(warnings);
-        return;
-    }
-    const stopResult = await stopApp(id, true);
-    if (stopResult.ok) {
-        process.stdout.write(`  [app-manager] Stopped running job for "${id}"\n`);
-    }
-    else if (stopResult.error && !stopResult.error.includes("not found") && !stopResult.error.includes("not running")) {
-        warnings.push(`应用 '${id}' 停止失败: ${stopResult.error}`);
-    }
-    if (appData) {
-        warnings.push(...await deleteLinkedInstances(appData.manifest.id));
-        const uninstallSteps = selectUninstallLifecycleSteps(appData);
-        if (uninstallSteps?.length) {
-            try {
-                await runLifecycleSteps(uninstallSteps, "uninstall", undefined, undefined, options.exec);
-            }
-            catch (e) {
-                writeAppManagerWarnings(warnings);
-                throw new Error(`卸载生命周期执行失败: ${e.message}`);
-            }
-        }
-        const cleanupList = selectCleanupArtifacts(appData);
-        if (cleanupList.length > 0) {
-            cleanupArtifacts(cleanupList);
-        }
-    }
-    unregisterCapabilities(id);
-    const appDir = resolveAppDir(id) ?? appDirForId(id);
-    rmSync(appDir, { recursive: true, force: true });
-    writeAppManagerWarnings(warnings);
-}
-export function uninstallAppTask(id, exec) {
-    if (!getApp(id)) {
-        return { ok: false, error: `App '${id}' not found`, kind: "uninstall" };
-    }
-    return startAppLifecycleTask(id, "uninstall", `开始卸载应用 ${id}...`, `应用 ${id} 卸载完成`, async () => {
-        await uninstallApp(id, { exec });
-    });
-}
-export async function runPostStartSteps(spec) {
-    await runLifecycleSteps(spec.lifecycle?.post_start, "post_start");
-}
-/**
- * Register all `provides` for an instance. PR 1 routes through the new
- * `capability-registry.ts` module (which dual-writes the legacy
- * `capabilities` map for compat). `portOverride` is preserved as a
- * temporary parameter for the existing server.ts startup-rebuild path
- * (`server.ts:266-282`); PR 1 step 0 of `resolveProvideEndpoint` reads
- * the actual allocated port from instance runtime when available, so
- * once PR 3 lands `portOverride` becomes redundant and gets removed.
- */
-export function registerCapabilities(instanceId, spec, portOverride) {
-    if (!spec.provides || spec.provides.length === 0)
-        return;
-    const now = new Date().toISOString();
-    const appName = spec.name ?? spec.id;
-    for (const provide of spec.provides) {
-        // url-only provide — out of capability registry scope (§5.1 boundary).
-        if (typeof provide.url === "string" && provide.url.trim())
-            continue;
-        let host = "127.0.0.1";
-        let hostPort;
-        if (typeof portOverride === "number" && portOverride > 0) {
-            // Legacy startup-rebuild path: server.ts already resolved the actual
-            // listening port via `instanceManager.getGatewayPort()`. Honor it for
-            // the gateway-port provide (typically `provides[0]`); other provides
-            // fall through to the spec-derived port.
-            hostPort = portOverride;
-            host = legacyInstanceManager.getAdvertisedHostForPort(portOverride);
-        }
-        if (typeof hostPort !== "number") {
-            const resolved = resolveProvideEndpoint(instanceId, spec, provide);
-            if (resolved) {
-                host = resolved.host;
-                hostPort = resolved.hostPort;
-            }
-            else {
-                const declared = getProvidePort(spec, provide);
-                if (declared == null)
-                    continue;
-                hostPort = declared;
-                host = legacyInstanceManager.getAdvertisedHostForPort(declared);
-            }
-        }
-        const protocol = resolveProvideProtocol(provide);
-        const entry = {
-            instanceId,
-            name: appName,
-            capability: provide.capability,
-            host,
-            hostPort,
-            ...(provide.path ? { path: provide.path } : {}),
-            address: buildCapabilityAddress(hostPort, provide.path),
-            protocol,
-            ...(provide.visibility ? { visibility: String(provide.visibility) } : {}),
-            status: "running",
-            lastSeenRunningAt: now,
-            registeredAt: now,
-            // §17 (PR 8) — carry MCP firewall canonical schema through so
-            // adapters can resolve it during applyConnectionEnv without
-            // reading the spec a second time.
-            ...(provide.tool_schema ? { toolSchema: provide.tool_schema } : {}),
-            // §6 (PR B) — carry auth config through so apply hooks can resolve
-            // tokens at apply/runtime time without re-reading the spec.
-            ...(provide.auth ? { auth: provide.auth } : {}),
-        };
-        capabilityRegistry.registerProvider(entry);
-    }
-    invalidateProvidedCapabilitiesCache();
-}
-/**
- * Mark an instance's providers as `stopped` (preferred for stop) or
- * remove them entirely (uninstall / delete). Defaults to remove for
- * back-compat with existing call sites; new code should prefer
- * `markCapabilitiesStopped` to keep entries visible in the Connections UI.
- */
-export function unregisterCapabilities(instanceId) {
-    capabilityRegistry.unregisterProviders(instanceId);
-    invalidateProvidedCapabilitiesCache();
-}
-export function markCapabilitiesStopped(instanceId) {
-    capabilityRegistry.setProviderStatus(instanceId, "stopped");
-    invalidateProvidedCapabilitiesCache();
-}
-export function resolveRequires(spec) {
-    if (!spec.requires || spec.requires.length === 0)
-        return {};
-    const result = {};
-    for (const req of spec.requires) {
-        const entry = capabilityRegistry.getCapabilityEntry(req.capability);
-        if (entry) {
-            result[req.inject_as] = entry.address;
-        }
-        else if (req.required !== false) {
-            throw new Error(`Required capability '${req.capability}' is not registered`);
-        }
-    }
-    return result;
-}
-// ── App Lifecycle (delegates to nomad-manager) ───────────────────
-/**
- * Read `instance.json` for a generic container app. Returns the parsed
- * record or `null` if missing/unreadable. Adapter-managed consumers
- * (OpenClaw, Hermes) keep their state elsewhere; this is the generic
- * app-dir layout under `~/.jishushell/apps/<appId>/`.
- */
-function readAppInstanceJson(appId) {
-    try {
-        const path = join(APPS_DIR, appId, "instance.json");
-        return safeReadJson(path, `app-instance:${appId}`) ?? null;
-    }
-    catch (e) {
-        console.warn(`[app-instance] read failed for ${appId}: ${e?.message ?? e}`);
-        return null;
-    }
-}
-/**
- * Read `instance.json["connections-env"]` for a generic container app and
- * return a copy of the persisted env vars. Adapter-managed consumers
- * (OpenClaw, Hermes) route connections through `applyConnectionEnv` and
- * don't write to this field. Best-effort — failures return empty object
- * so they never block startup.
- */
-function loadConnectionsEnv(appId) {
-    const inst = readAppInstanceJson(appId);
-    const env = inst?.["connections-env"];
-    if (env && typeof env === "object" && !Array.isArray(env)) {
-        const out = {};
-        for (const [k, v] of Object.entries(env)) {
-            if (typeof v === "string")
-                out[k] = v;
-        }
-        return out;
-    }
-    return {};
-}
-export async function startApp(appId) {
-    // Serialize against PUT /connections, stopApp and concurrent startApp on
-    // the same instance — see `utils/instance-lock.ts` and §10.3 of the
-    // app-interconnect design.
-    return withInstanceLock(appId, () => startAppImpl(appId));
-}
-async function startAppImpl(appId) {
-    const appData = getApp(appId);
-    if (!appData) {
-        return { ok: false, error: `App '${appId}' not found` };
-    }
-    if (appData.install_state === "installing") {
-        return { ok: false, error: `App '${appId}' is still installing` };
-    }
-    if (isInstanceBackedApp(appData) || getAdapterManagedAgentType(appData)) {
-        if (appData.spec.lifecycle?.pre_start?.length) {
-            await runLifecycleSteps(appData.spec.lifecycle.pre_start, "pre_start");
-        }
-        const { startNomadJobInstance } = await import("../nomad-manager.js");
-        const result = await startNomadJobInstance(appId);
-        if (!result.ok)
-            return result;
-        if (appData.spec.provides?.length) {
-            registerCapabilities(appId, appData.spec);
-        }
-        if (appData.spec.lifecycle?.post_start?.length) {
-            await runPostStartSteps(appData.spec);
-        }
-        return result;
-    }
-    // Resolve requires through the v3 connection-resolver in runtime mode so
-    // missing-required / ambiguous-prefix / invalid-binding all surface with
-    // the structured 412/409/400 codes (§6.4 Phase 4 of the app-interconnect
-    // design). The legacy `resolveRequires` path threw a bare Error which the
-    // route handler could only forward as a generic 400 — losing the bind-vs-
-    // start-vs-pick distinction the UI needs.
-    const instJson = readAppInstanceJson(appId);
-    const persistedEnv = loadConnectionsEnv(appId);
-    let extraEnv = {};
-    try {
-        const { resolveConnections, resolvedToLegacyEnv } = await import("../connection-resolver.js");
-        const { renderRuntimeConnectionsEnv } = await import("../connection-apply.js");
-        const { resolved } = resolveConnections(appData.spec, { connections: instJson?.connections ?? {} }, "runtime");
-        const runtimeEnv = await renderRuntimeConnectionsEnv(appData.spec, {
-            id: appId,
-            connections: instJson?.connections,
-        });
-        // Frozen `connections-env` is the lowest-priority fallback for legacy
-        // apps that pre-date resolveConnections. Runtime-rendered env wins so
-        // provider port/IP changes propagate without re-binding.
-        extraEnv = { ...persistedEnv, ...resolvedToLegacyEnv(resolved), ...runtimeEnv };
-    }
-    catch (e) {
-        return {
-            ok: false,
-            error: e.message,
-            ...(e.code ? { code: e.code } : {}),
-            ...(typeof e.statusCode === "number" ? { statusCode: e.statusCode } : {}),
-        };
-    }
-    const { startAppJob: nomadStart, checkDependencies, waitForRunning } = await import("../nomad-manager.js");
-    const depCheck = await checkDependencies(appData.spec);
-    if (!depCheck.ok) {
-        return { ok: false, error: depCheck.errors.join("; ") };
-    }
-    // Run pre_start steps right before submitting the Nomad job — gives
-    // apps a place to enforce per-start invariants (e.g. chown the
-    // bind-mount source so the container's runtime uid can write).
-    if (appData.spec.lifecycle?.pre_start?.length) {
-        await runLifecycleSteps(appData.spec.lifecycle.pre_start, "pre_start");
-    }
-    const result = await nomadStart(appData.spec, appId, extraEnv);
-    if (!result.ok) {
-        return result;
-    }
-    if (appData.spec.provides?.length) {
-        registerCapabilities(appId, appData.spec);
-    }
-    if (appData.spec.lifecycle?.post_start?.length) {
-        const running = await waitForRunning(appId);
-        if (running) {
-            await runPostStartSteps(appData.spec);
-        }
-    }
-    return result;
-}
-export function startAppTask(appId) {
-    if (!getApp(appId)) {
-        return { ok: false, error: `App '${appId}' not found`, kind: "start" };
-    }
-    return startAppLifecycleTask(appId, "start", `开始启动应用 ${appId}...`, `应用 ${appId} 已启动`, async () => {
-        const result = await startApp(appId);
-        if (!result.ok) {
-            throw new Error(result.error || `App '${appId}' start failed`);
-        }
-    });
-}
-export async function stopApp(appId, purge = false) {
-    return withInstanceLock(appId, () => stopAppImpl(appId, purge));
-}
-async function stopAppImpl(appId, purge) {
-    const appData = getApp(appId);
-    if (appData?.install_state === "installing") {
-        return { ok: false, error: `App '${appId}' is still installing` };
-    }
-    if (isInstanceBackedApp(appData) || getAdapterManagedAgentType(appData)) {
-        const { stopNomadJobInstance } = await import("../nomad-manager.js");
-        const result = await stopNomadJobInstance(appId, purge);
-        if (result.ok || result.error?.includes("not running") || result.error?.includes("not found")) {
-            // Stop = mark stopped (keep entry visible in Connections UI as a
-            // greyed candidate); only purge / uninstall fully unregisters.
-            if (purge)
-                unregisterCapabilities(appId);
-            else
-                markCapabilitiesStopped(appId);
-        }
-        return result;
-    }
-    const { stopAppJob } = await import("../nomad-manager.js");
-    const result = await stopAppJob(appId, purge);
-    if (result.ok || result.error?.includes("not running") || result.error?.includes("not found")) {
-        if (purge)
-            unregisterCapabilities(appId);
-        else
-            markCapabilitiesStopped(appId);
-    }
-    return result;
-}
-export function stopAppTask(appId, purge = false) {
-    if (!getApp(appId)) {
-        return { ok: false, error: `App '${appId}' not found`, kind: "stop" };
-    }
-    return startAppLifecycleTask(appId, "stop", `开始停止应用 ${appId}${purge ? "（purge）" : ""}...`, `应用 ${appId} 已停止${purge ? "（purged）" : ""}`, async () => {
-        const result = await stopApp(appId, purge);
-        if (!result.ok) {
-            throw new Error(result.error || `App '${appId}' stop failed`);
-        }
-    });
-}
-export async function restartApp(appId) {
-    // Hold the instance lock for the entire restart sequence so a concurrent
-    // PUT /connections / startApp / stopApp on the same id can't observe a
-    // half-restarted state. Inner stop/start calls reuse the same lock id;
-    // we route them through the *Impl helpers to avoid re-acquiring.
-    return withInstanceLock(appId, async () => {
-        const appData = getApp(appId);
-        if (appData?.install_state === "installing") {
-            return { ok: false, error: `App '${appId}' is still installing` };
-        }
-        if (isInstanceBackedApp(appData) || getAdapterManagedAgentType(appData)) {
-            const { restartNomadJobInstance } = await import("../nomad-manager.js");
-            const result = await restartNomadJobInstance(appId);
-            if (!result.ok)
-                return result;
-            if (appData?.spec.provides?.length) {
-                registerCapabilities(appId, appData.spec);
-            }
-            if (appData?.spec.lifecycle?.post_start?.length) {
-                await runPostStartSteps(appData.spec);
-            }
-            return result;
-        }
-        const stopResult = await stopAppImpl(appId, true);
-        if (!stopResult.ok && !stopResult.error?.includes("not found")) {
-            return stopResult;
-        }
-        return startAppImpl(appId);
-    });
-}
-export function restartAppTask(appId) {
-    if (!getApp(appId)) {
-        return { ok: false, error: `App '${appId}' not found`, kind: "restart" };
-    }
-    return startAppLifecycleTask(appId, "restart", `开始重启应用 ${appId}...`, `应用 ${appId} 已重启`, async () => {
-        const result = await restartApp(appId);
-        if (!result.ok) {
-            throw new Error(result.error || `App '${appId}' restart failed`);
-        }
-    });
-}
-export async function getAppRuntimeStatus(appId) {
-    const appData = getApp(appId);
-    if (isInstanceBackedApp(appData) || getAdapterManagedAgentType(appData)) {
-        const { getInstanceStatus } = await import("../nomad-manager.js");
-        const st = await getInstanceStatus(appId);
-        return {
-            status: st.status,
-            uptime: st.uptime ?? undefined,
-            memory_mb: st.memory_mb ?? undefined,
-        };
-    }
-    const { getAppStatus, isBinaryRunning } = await import("../nomad-manager.js");
-    const st = await getAppStatus(appId);
-    // For process-runtime apps: if Nomad can't place the job (pending/unplaced due
-    // to missing raw_exec driver) but the binary is already running on the host,
-    // report the real status as "running" so the UI doesn't show a failure.
-    if (st.status === "pending" || st.status === "stopped") {
-        const appData = getApp(appId);
-        if (appData) {
-            const processTask = appData.spec.tasks.find((t) => t.runtime === "process" && (t.role ?? "service") === "service" && t.command);
-            if (processTask) {
-                const running = await isBinaryRunning(processTask.command);
-                if (running) {
-                    return { status: "running" };
-                }
-            }
-        }
-    }
-    return {
-        status: st.status,
-        uptime: st.uptime ?? undefined,
-        memory_mb: st.memory_mb ?? undefined,
-        tasks: st.tasks,
-        error: st.error,
-    };
-}
-export async function getAppStatus(appId) {
-    const appData = getApp(appId);
-    if (appData?.install_state === "installing") {
-        return {
-            status: "installing",
-            tasks: {},
-            pid: null,
-            uptime: null,
-            memory_mb: null,
-            cpu_percent: null,
-            restarts: 0,
-            error: undefined,
-        };
-    }
-    if (isInstanceBackedApp(appData) || getAdapterManagedAgentType(appData)) {
-        const { getInstanceStatus } = await import("../nomad-manager.js");
-        const st = await getInstanceStatus(appId);
-        return {
-            status: st.status,
-            tasks: {},
-            pid: null,
-            uptime: st.uptime,
-            memory_mb: st.memory_mb,
-            cpu_percent: st.cpu_percent,
-            restarts: 0,
-            error: undefined,
-        };
-    }
-    const { getAppStatus: nomadGetAppStatus } = await import("../nomad-manager.js");
-    return nomadGetAppStatus(appId);
-}
-export async function getAppLogs(appId, taskName, lines = 200, logType = "stderr") {
-    const appData = getApp(appId);
-    if (isInstanceBackedApp(appData) || getAdapterManagedAgentType(appData)) {
-        const { getInstanceLogs } = await import("../nomad-manager.js");
-        return getInstanceLogs(appId, lines, logType);
-    }
-    const { getAppLogs: nomadGetAppLogs } = await import("../nomad-manager.js");
-    return nomadGetAppLogs(appId, taskName, lines, logType);
-}
-export async function execInApp(appId, command, timeoutMs) {
-    const appData = getApp(appId);
-    if (isInstanceBackedApp(appData) || getAdapterManagedAgentType(appData)) {
-        const { execInInstance } = await import("../nomad-manager.js");
-        return execInInstance(appId, command, timeoutMs ?? 120_000);
-    }
-    const { execInApp: nomadExecInApp } = await import("../nomad-manager.js");
-    return nomadExecInApp(appId, "", command, timeoutMs ?? 120_000);
-}
-export async function streamExecInApp(appId, command, handlers, options) {
-    const timeoutMs = options?.timeoutMs ?? 120_000;
-    const taskName = options?.taskName ?? "";
-    const appData = getApp(appId);
-    if (isInstanceBackedApp(appData) || getAdapterManagedAgentType(appData)) {
-        const { streamExecInInstance } = await import("../nomad-manager.js");
-        return streamExecInInstance(appId, command, handlers, timeoutMs, taskName);
-    }
-    const { streamExecInApp: nomadStreamExecInApp } = await import("../nomad-manager.js");
-    return nomadStreamExecInApp(appId, taskName, command, handlers, timeoutMs);
-}
-export async function copyApp(sourceId) {
-    const source = getApp(sourceId);
-    if (!source)
-        throw new Error(`App '${sourceId}' not found`);
-    if (source.spec.singleInstance)
-        throw new Error(`App '${sourceId}' is singleInstance — cannot copy`);
-    // A faithful copy requires re-materialization: ${app_id} tokens, port
-    // shifts, and app-scoped paths all need to be recomputed for the new
-    // slot. Naively swapping the `id:` line leaves lifecycle scripts and
-    // volume sources pointing at the source's settings dir, which then
-    // collides on start and leaks state across instances.
-    //
-    // The base app's on-disk yaml for offset=0 is written as the pristine
-    // originalSpecYaml (see resolveInstallTarget → installedSpecYaml), so
-    // reading from the base dir recovers the template that installApp can
-    // re-materialize. The source's own yaml is already baked to its own
-    // offset when source is itself a copy, and installApp cannot cleanly
-    // un-do that substitution from a string diff alone.
-    const baseId = source.spec.id;
-    const baseDir = resolveAppDir(baseId);
-    if (!baseDir) {
-        throw new Error(`App '${sourceId}' base '${baseId}' is not installed; cannot copy without the pristine spec. Reinstall the base app first.`);
-    }
-    const baseYaml = readFileSync(join(baseDir, "app-spec.yaml"), "utf-8");
-    // Delegate: installApp runs resolveInstallTarget (which picks the next
-    // free <baseId>-<prefix><n> slot and applies a fresh port shift) and
-    // executes the install lifecycle in the new app dir.
-    return installApp(baseYaml);
-}
-export { onConfigChange, notifyConfigChange, instanceDir, instanceMetaPath, defaultModelEnvFile, normalizePath, extractGatewayPort, isPortInUse, allocateGatewayPort, releasePendingPort, getResolvedOpenclawBin, resolveServiceUser, chownToServiceUser, parseEnvFile, updateEnvFile, inferProviderApiKeyEnvName, listInstances, getInstance, updateInstanceMeta, deleteInstance, getConfig, getStoredConfig, saveConfig, CHANNEL_PLUGIN_MAP, isChannelPluginInstalled, createInstance, getOpenclawHome, saveFeishuCredentials, saveWeixinCredentials, getWeixinAccounts, getOpenclawConfigPath, getLegacyOpenclawConfigPath, getInstanceRuntime, getRuntimeEnvFiles, getGatewayPort, getGatewayHost, getListeningHostForPort, getHostForAppPort, urlHost, findInstancesSharingOpenclawHome, reallocateGatewayPort, findInstancesSharingGatewayPort, getRuntimeEnv, defaultGatewayPort, releasePort, } from "../instance-manager.js";
-//# sourceMappingURL=app-manager.js.map