jishushell 0.4.10 → 0.4.24-beta.2

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

@@ -0,0 +1,2148 @@
+import { createHash } from "crypto";
+import { existsSync, mkdtempSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, chmodSync, } from "fs";
+import { homedir, tmpdir } from "os";
+import { basename, extname, join, dirname } from "path";
+import { spawn } 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 { createTask, emitTask, getRunningTasks, getTask } from "../task-registry.js";
+import { compileTaskRuntime } from "./app-compiler.js";
+const DEFAULT_LIFECYCLE_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+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";
+            })
+            && (tasks.length === 1 || isOllamaTemplate)
+            && (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 buildLifecycleEnv() {
+    const mergedPath = `${process.env.PATH ?? ""}:${DEFAULT_LIFECYCLE_PATH}`
+        .split(":")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    return {
+        ...process.env,
+        HOME: process.env.HOME ?? homedir(),
+        PATH: [...new Set(mergedPath)].join(":"),
+    };
+}
+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)) {
+        return new Error("sudo 密码错误，请重新输入。");
+    }
+    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 process.platform === "linux"
+        && Boolean(process.env.INVOCATION_ID || process.env.JOURNAL_STREAM || process.env.NOTIFY_SOCKET);
+}
+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)) {
+                    reject(new Error("sudo 密码错误，请重新输入。"));
+                    return;
+                }
+                resolve();
+            });
+            child.on("error", (error) => {
+                resolve();
+            });
+        });
+    }
+    finally {
+        preparedEnv.cleanup();
+    }
+}
+function prepareLifecycleExecEnv(execOptions) {
+    const env = buildLifecycleEnv();
+    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
+            }
+        },
+    };
+}
+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) {
+    return {
+        ...spec,
+        tasks: (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;
+        }),
+    };
+}
+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;
+    return firstPort.host_port ?? firstPort.port;
+}
+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 = legacyInstanceManager.getAdvertisedHostForPort(port);
+    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);
+    return normalizeAppSpec({
+        ...rewritten,
+        id: spec.id,
+        ...(derivedName ? { name: derivedName } : {}),
+    });
+}
+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,
+            installedSpecYaml: offset === 0 ? originalSpecYaml : 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;
+async function pullDockerImageStep(label, image, display, task, timeoutMs = DOCKER_PULL_TIMEOUT_MS) {
+    let lastError;
+    for (let attempt = 1; attempt <= DOCKER_PULL_RETRY_ATTEMPTS; attempt++) {
+        try {
+            await spawnStepWithTimeout(label, display, display, "docker", ["pull", image], timeoutMs, task);
+            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);
+        }
+    }
+    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) {
+    process.stdout.write(`  [lifecycle:${label}] ${display}\n`);
+    emitInstallTaskLog(task, `[lifecycle:${label}] ${taskDisplay}`);
+    return new Promise((resolve, reject) => {
+        const preparedEnv = prepareLifecycleExecEnv(sudo ? execOptions : undefined);
+        let cleaned = false;
+        let heartbeatTimer = null;
+        let stdoutPending = "";
+        let stderrPending = "";
+        let capturedStderr = "";
+        const cleanupPreparedEnv = () => {
+            if (cleaned)
+                return;
+            cleaned = true;
+            if (heartbeatTimer) {
+                clearInterval(heartbeatTimer);
+                heartbeatTimer = null;
+            }
+            preparedEnv.cleanup();
+        };
+        const spawnTarget = sudo
+            ? buildSudoWrappedCommand(cmd, args, preparedEnv.env, execOptions)
+            : { command: cmd, args };
+        const captureOutput = Boolean(task) || Boolean(sudo);
+        const child = spawn(spawnTarget.command, spawnTarget.args, {
+            stdio: captureOutput ? ["ignore", "pipe", "pipe"] : "inherit",
+            timeout: timeoutMs,
+            env: preparedEnv.env,
+        });
+        if (captureOutput) {
+            const startedAt = Date.now();
+            const flushPendingLine = (line) => {
+                if (!task)
+                    return;
+                emitInstallTaskLog(task, line);
+            };
+            const handleChunk = (chunk, stream) => {
+                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 (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 (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 child = spawn("sh", ["-c", `command -v '${command}' > /dev/null 2>&1`], {
+            stdio: "ignore",
+            env: buildLifecycleEnv(),
+        });
+        child.on("close", (code) => resolve(code === 0));
+        child.on("error", () => resolve(false));
+    });
+}
+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);
+            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 ("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} 操作，请等待完成后再试`,
+            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);
+    const resolvedRequires = resolveRequires(installedSpec);
+    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";
+}
+function readRegistry() {
+    const reg = safeReadJson(REGISTRY_PATH, "capability-registry");
+    return reg ?? { capabilities: {} };
+}
+function writeRegistry(reg) {
+    ensureDirHost(APPS_DIR);
+    safeWriteJson(REGISTRY_PATH, reg, true);
+}
+function installedProvidersForCapability(capability) {
+    return listApps()
+        .filter((app) => app.spec.provides?.some((provide) => provide.capability === capability))
+        .map((app) => app.manifest.id);
+}
+function ensureRequiredCapabilitiesAvailable(spec) {
+    if (!spec.requires?.length)
+        return;
+    const reg = readRegistry();
+    const missing = spec.requires
+        .filter((req) => req.required !== false && !reg.capabilities[req.capability])
+        .map((req) => {
+        const installedProviders = installedProvidersForCapability(req.capability);
+        const providerHint = installedProviders.length > 0
+            ? `；已安装但未注册的 provider: ${installedProviders.join(", ")}`
+            : "";
+        return `- ${req.capability} -> ${req.inject_as}${providerHint}`;
+    });
+    if (missing.length === 0)
+        return;
+    throw new Error(`App '${spec.id}' 缺少必需能力，已跳过安装:\n${missing.join("\n")}\n请先启动对应 provider，再执行 jishushell app provides 查看当前可用能力。`);
+}
+export function listProvidedCapabilities() {
+    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 registered = reg.capabilities[provide.capability];
+        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 } : {}),
+            ...(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);
+}
+export function getEmbeddedUiHintForApp(appId) {
+    const provides = getProvidedCapabilitiesForApp(appId);
+    if (!provides.length)
+        return null;
+    for (const provide of provides) {
+        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;
+        const address = typeof provide.address === "string" && provide.address.trim()
+            ? provide.address.trim()
+            : buildCapabilityAddress(provide.port, provide.path);
+        return {
+            capability: provide.capability,
+            protocol,
+            port: provide.port,
+            url: `${protocol}://${address}`,
+        };
+    }
+    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}' 格式无效`);
+        }
+    }
+    ensureRequiredCapabilitiesAvailable(spec);
+    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");
+}
+export function registerCapabilities(instanceId, spec, portOverride) {
+    if (!spec.provides || spec.provides.length === 0)
+        return;
+    const reg = readRegistry();
+    const now = new Date().toISOString();
+    for (const provide of spec.provides) {
+        const hostPort = typeof portOverride === "number" && portOverride > 0
+            ? portOverride
+            : getProvidePort(spec, provide);
+        if (hostPort == null) {
+            continue;
+        }
+        reg.capabilities[provide.capability] = {
+            instanceId,
+            hostPort,
+            address: buildCapabilityAddress(hostPort, provide.path),
+            path: provide.path,
+            registered_at: now,
+        };
+    }
+    writeRegistry(reg);
+}
+export function unregisterCapabilities(instanceId) {
+    const reg = readRegistry();
+    for (const key of Object.keys(reg.capabilities)) {
+        if (reg.capabilities[key].instanceId === instanceId) {
+            delete reg.capabilities[key];
+        }
+    }
+    writeRegistry(reg);
+}
+export function resolveRequires(spec) {
+    if (!spec.requires || spec.requires.length === 0)
+        return {};
+    const reg = readRegistry();
+    const result = {};
+    for (const req of spec.requires) {
+        const entry = reg.capabilities[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) ───────────────────
+export async function startApp(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)) {
+        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;
+    }
+    let extraEnv = {};
+    try {
+        extraEnv = resolveRequires(appData.spec);
+    }
+    catch (e) {
+        return { ok: false, error: e.message };
+    }
+    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("; ") };
+    }
+    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) {
+    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")) {
+            unregisterCapabilities(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")) {
+        unregisterCapabilities(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) {
+    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 stopApp(appId, true);
+    if (!stopResult.ok && !stopResult.error?.includes("not found")) {
+        return stopResult;
+    }
+    return startApp(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, urlHost, findInstancesSharingOpenclawHome, reallocateGatewayPort, findInstancesSharingGatewayPort, getRuntimeEnv, defaultGatewayPort, releasePort, } from "../instance-manager.js";
+//# sourceMappingURL=app-manager.js.map