jishushell 0.4.24 → 0.5.15

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

@@ -1,17 +1,48 @@
 import { createHash } from "crypto";
-import { existsSync, mkdtempSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, chmodSync, } from "fs";
+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 } from "child_process";
+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";
-const DEFAULT_LIFECYCLE_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+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;
 }
@@ -78,7 +109,6 @@ function parseBuiltinTemplate(fileName, yamlText) {
                 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,
@@ -121,7 +151,11 @@ export function updateInstance(instanceId, name, description) {
     return legacyInstanceManager.getInstance(instanceId) ?? updatedMeta;
 }
 function parseComparableVersion(version, label) {
-    const normalized = version.trim().replace(/^>=\s*/, "").replace(/^v/i, "");
+    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`);
@@ -162,17 +196,154 @@ function expandPath(p) {
     }
     return p.replace(/^~(?=\/|$)/, process.env.HOME ?? homedir());
 }
-function buildLifecycleEnv() {
-    const mergedPath = `${process.env.PATH ?? ""}:${DEFAULT_LIFECYCLE_PATH}`
-        .split(":")
+function buildDeterministicPath(basePath, extraPaths = []) {
+    return [basePath ?? "", DEFAULT_LIFECYCLE_PATH, dirname(process.execPath), ...extraPaths]
+        .flatMap((entry) => entry.split(":"))
         .map((entry) => entry.trim())
-        .filter(Boolean);
+        .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: [...new Set(mergedPath)].join(":"),
+        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 密码");
@@ -198,13 +369,19 @@ export async function validateSudoPassword(sudoPassword) {
                     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 密码错误，请重新输入。"));
+                    const err = new Error("sudo 密码错误，请重新输入。");
+                    err.code = "INVALID_SUDO_PASSWORD";
+                    reject(err);
                     return;
                 }
                 resolve();
             });
-            child.on("error", (error) => {
+            child.on("error", (_error) => {
                 resolve();
             });
         });
@@ -213,8 +390,11 @@ export async function validateSudoPassword(sudoPassword) {
         preparedEnv.cleanup();
     }
 }
-function prepareLifecycleExecEnv(execOptions) {
-    const env = buildLifecycleEnv();
+function prepareLifecycleExecEnv(execOptions, envOverrides) {
+    const env = {
+        ...buildLifecycleEnv(),
+        ...(envOverrides ?? {}),
+    };
     const sudoPassword = execOptions?.sudoPassword;
     if (!sudoPassword) {
         return { env, cleanup: () => undefined };
@@ -243,6 +423,26 @@ function prepareLifecycleExecEnv(execOptions) {
         },
     };
 }
+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
@@ -276,24 +476,88 @@ function normalizePortVisibility(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,
-        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;
-        }),
+        ...(spec.provides ? { provides: normalizedProvides } : {}),
+        tasks: normalizedTasks,
+        ...(normalizedLifecycle ? { lifecycle: normalizedLifecycle } : {}),
     };
 }
 function imageReferencedByOtherInstalledApps(currentAppId, imagePath) {
@@ -388,7 +652,8 @@ function getProvidePort(spec, provide) {
     const firstPort = spec.tasks.find((task) => task.role === "service")?.ports?.[0];
     if (!firstPort)
         return null;
-    return firstPort.host_port ?? firstPort.port;
+    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() : "";
@@ -406,7 +671,7 @@ function getProvideUrl(provide) {
     }
 }
 function buildCapabilityAddress(port, path) {
-    const host = legacyInstanceManager.getAdvertisedHostForPort(port);
+    const host = port > 0 ? legacyInstanceManager.getAdvertisedHostForPort(port) : "127.0.0.1";
     if (!path) {
         return `${host}:${port}`;
     }
@@ -501,11 +766,16 @@ 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({
+    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;
@@ -615,7 +885,15 @@ async function resolveInstallTarget(spec, originalSpecYaml, requestedAppId) {
         return {
             appId,
             installedSpec,
-            installedSpecYaml: offset === 0 ? originalSpecYaml : stringify(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}' 没有可用安装槽位，目录名或端口已全部占用`);
@@ -630,30 +908,60 @@ const DOCKER_PULL_RETRY_ATTEMPTS = 3;
 // 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) {
+    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;
-    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);
+    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: Math.min(DOCKER_PULL_IDLE_TIMEOUT_MS, timeoutMs),
+                    envOverrides: anonymousDockerConfig?.envOverrides,
+                    stallMessageHint: "Docker credential resolution (for example docker-credential-desktop) may be involved.",
+                });
                 return;
             }
-            lastError = error;
-            if (attempt === DOCKER_PULL_RETRY_ATTEMPTS) {
-                break;
+            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);
             }
-            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) {
@@ -666,13 +974,18 @@ async function dockerImageExists(image) {
         child.on("error", () => resolve(false));
     });
 }
-function spawnStepWithTimeout(label, display, taskDisplay, cmd, args, timeoutMs, task, execOptions) {
+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(execOptions);
+        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;
@@ -681,22 +994,58 @@ function spawnStepWithTimeout(label, display, taskDisplay, cmd, args, timeoutMs,
                 clearInterval(heartbeatTimer);
                 heartbeatTimer = null;
             }
+            if (idleTimer) {
+                clearTimeout(idleTimer);
+                idleTimer = null;
+            }
             preparedEnv.cleanup();
         };
-        const child = spawn(cmd, args, {
-            stdio: task ? ["ignore", "pipe", "pipe"] : "inherit",
+        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,
         });
-        if (task) {
-            let stdoutPending = "";
-            let stderrPending = "";
+        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");
@@ -712,24 +1061,38 @@ function spawnStepWithTimeout(label, display, taskDisplay, cmd, args, timeoutMs,
             };
             child.stdout?.on("data", (data) => handleChunk(data, "stdout"));
             child.stderr?.on("data", (data) => handleChunk(data, "stderr"));
-            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);
-            });
+            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)
+            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}`));
         });
     });
@@ -742,7 +1105,8 @@ function lifecycleRunStepDisplay(label, index) {
 }
 async function commandExists(command) {
     return new Promise((resolve) => {
-        const child = spawn("sh", ["-c", `command -v '${command}' > /dev/null 2>&1`], {
+        const quoted = command.replace(/'/g, "'\\''");
+        const child = spawn("sh", ["-c", `command -v '${quoted}' > /dev/null 2>&1`], {
             stdio: "ignore",
             env: buildLifecycleEnv(),
         });
@@ -750,6 +1114,64 @@ async function commandExists(command) {
         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`);
@@ -770,13 +1192,16 @@ async function runLifecycleSteps(steps, label, artifacts, task, execOptions) {
         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);
+                await spawnStepWithTimeout(label, display, taskDisplay, "sh", ["-c", step.run], timeoutMs, task, execOptions, step.sudo === true);
             }
             catch (error) {
                 if (step.successIfCommandExists && await commandExists(step.successIfCommandExists)) {
@@ -829,6 +1254,36 @@ async function runLifecycleSteps(steps, label, artifacts, task, execOptions) {
             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`);
@@ -866,7 +1321,7 @@ function cleanupArtifacts(artifacts, task) {
 }
 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 _REGISTRY_PATH = join(APPS_DIR, "capability-registry.json");
 const INSTALL_LOCK_FILENAME = "install.lock";
 // ── Directory helpers ─────────────────────────────────────────────────────
 function appDirForId(appId) {
@@ -995,6 +1450,7 @@ function startAppLifecycleTask(appId, kind, startMessage, doneMessage, action) {
         return {
             ok: false,
             error: `App '${appId}' 正在执行 ${currentTask.kind} 操作，请等待完成后再试`,
+            code: "TASK_BUSY",
             kind,
         };
     }
@@ -1214,7 +1670,22 @@ async function installIntoInstanceDir(spec, specYaml, requestedAppId, options =
         return null;
     const { appId, installedSpec, } = await resolveInstallTarget(spec, specYaml, requestedAppId);
     let instanceSpec = rewriteInstanceScopedPaths(installedSpec, appId);
-    const resolvedRequires = resolveRequires(installedSpec);
+    // 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,
@@ -1262,6 +1733,19 @@ async function installIntoInstanceDir(spec, specYaml, requestedAppId, options =
         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))];
@@ -1288,7 +1772,7 @@ async function installIntoInstanceDir(spec, specYaml, requestedAppId, options =
         catch {
             rmSync(instanceDir, { recursive: true, force: true });
         }
-        throw e;
+        throw decorateInstallError(e, instanceSpec);
     }
     if (artifacts.length > 0) {
         manifest.artifacts = artifacts;
@@ -1339,43 +1823,33 @@ export function getAppInstallState(appId) {
         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 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 查看当前可用能力。`);
+    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.
 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 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,
@@ -1387,6 +1861,7 @@ export function listProvidedCapabilities() {
             ...(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 } : {}),
@@ -1401,7 +1876,22 @@ export function getEmbeddedUiHintForApp(appId) {
     const provides = getProvidedCapabilitiesForApp(appId);
     if (!provides.length)
         return null;
-    for (const provide of provides) {
+    // 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;
@@ -1417,14 +1907,54 @@ export function getEmbeddedUiHintForApp(appId) {
         }
         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);
+        // 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: `${protocol}://${address}`,
+            url: proxyPath,
         };
     }
     return null;
@@ -1462,7 +1992,11 @@ export async function installApp(specYaml, requestedAppId, options = {}) {
             throw new Error(`task '${task.name}' 的 image '${task.image}' 格式无效`);
         }
     }
-    ensureRequiredCapabilitiesAvailable(spec);
+    // 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;
@@ -1486,6 +2020,13 @@ export async function installApp(specYaml, requestedAppId, options = {}) {
     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));
@@ -1511,7 +2052,7 @@ export async function installApp(specYaml, requestedAppId, options = {}) {
         }
         cleanupArtifacts(artifacts, options.task);
         rmSync(appDir, { recursive: true, force: true });
-        throw e;
+        throw decorateInstallError(e, installedSpec);
     }
     if (artifacts.length > 0) {
         manifest.artifacts = artifacts;
@@ -1686,44 +2227,91 @@ export function uninstallAppTask(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 reg = readRegistry();
     const now = new Date().toISOString();
+    const appName = spec.name ?? spec.id;
     for (const provide of spec.provides) {
-        const hostPort = typeof portOverride === "number" && portOverride > 0
-            ? portOverride
-            : getProvidePort(spec, provide);
-        if (hostPort == null) {
+        // 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);
+            }
         }
-        reg.capabilities[provide.capability] = {
+        const protocol = resolveProvideProtocol(provide);
+        const entry = {
             instanceId,
+            name: appName,
+            capability: provide.capability,
+            host,
             hostPort,
+            ...(provide.path ? { path: provide.path } : {}),
             address: buildCapabilityAddress(hostPort, provide.path),
-            path: provide.path,
-            registered_at: now,
+            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);
     }
-    writeRegistry(reg);
 }
+/**
+ * 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) {
-    const reg = readRegistry();
-    for (const key of Object.keys(reg.capabilities)) {
-        if (reg.capabilities[key].instanceId === instanceId) {
-            delete reg.capabilities[key];
-        }
-    }
-    writeRegistry(reg);
+    capabilityRegistry.unregisterProviders(instanceId);
+}
+export function markCapabilitiesStopped(instanceId) {
+    capabilityRegistry.setProviderStatus(instanceId, "stopped");
 }
 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];
+        const entry = capabilityRegistry.getCapabilityEntry(req.capability);
         if (entry) {
             result[req.inject_as] = entry.address;
         }
@@ -1734,7 +2322,49 @@ export function resolveRequires(spec) {
     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` };
@@ -1743,6 +2373,9 @@ export async function startApp(appId) {
         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)
@@ -1755,18 +2388,47 @@ export async function startApp(appId) {
         }
         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 {
-        extraEnv = resolveRequires(appData.spec);
+        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 };
+        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;
@@ -1794,6 +2456,9 @@ export function startAppTask(appId) {
     });
 }
 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` };
@@ -1802,14 +2467,22 @@ export async function stopApp(appId, purge = false) {
         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);
+            // 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")) {
-        unregisterCapabilities(appId);
+        if (purge)
+            unregisterCapabilities(appId);
+        else
+            markCapabilitiesStopped(appId);
     }
     return result;
 }
@@ -1825,28 +2498,34 @@ export function stopAppTask(appId, purge = false) {
     });
 }
 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)
+    // 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;
-        if (appData?.spec.provides?.length) {
-            registerCapabilities(appId, appData.spec);
         }
-        if (appData?.spec.lifecycle?.post_start?.length) {
-            await runPostStartSteps(appData.spec);
+        const stopResult = await stopAppImpl(appId, true);
+        if (!stopResult.ok && !stopResult.error?.includes("not found")) {
+            return stopResult;
         }
-        return result;
-    }
-    const stopResult = await stopApp(appId, true);
-    if (!stopResult.ok && !stopResult.error?.includes("not found")) {
-        return stopResult;
-    }
-    return startApp(appId);
+        return startAppImpl(appId);
+    });
 }
 export function restartAppTask(appId) {
     if (!getApp(appId)) {
@@ -1984,5 +2663,5 @@ export async function copyApp(sourceId) {
     // 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";
+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