jishushell 0.4.24-beta.2 → 0.4.30

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

@@ -1,16 +1,19 @@
 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";
+import * as capabilityRegistry from "../capability-registry.js";
+import { resolveProvideEndpoint } from "./provide-resolver.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;
@@ -204,7 +207,9 @@ function createLifecycleSudoError(stderr, fallbackDisplay, hasPassword) {
         return createNoNewPrivilegesSudoError();
     }
     if (isSudoAuthenticationError(message)) {
-        return new Error("sudo 密码错误，请重新输入。");
+        const err = new Error("sudo 密码错误，请重新输入。");
+        err.code = "INVALID_SUDO_PASSWORD";
+        return err;
     }
     if (!hasPassword && isSudoPasswordRequiredError(message)) {
         return new Error("该生命周期步骤需要 sudo 密码；请在页面弹窗中输入后重试。");
@@ -219,8 +224,10 @@ function panelSystemdServicePath() {
     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);
+    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())
@@ -311,7 +318,9 @@ export async function validateSudoPassword(sudoPassword) {
                     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();
@@ -388,24 +397,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) {
@@ -500,7 +573,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() : "";
@@ -518,7 +592,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}`;
     }
@@ -742,11 +816,21 @@ 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.
+const DOCKER_PULL_IDLE_TIMEOUT_MS = 180_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;
+    }
     let lastError;
     for (let attempt = 1; attempt <= DOCKER_PULL_RETRY_ATTEMPTS; attempt++) {
         try {
-            await spawnStepWithTimeout(label, display, display, "docker", ["pull", image], timeoutMs, task);
+            await spawnStepWithTimeout(label, display, display, "docker", ["pull", image], timeoutMs, task, undefined, undefined, { idleTimeoutMs: Math.min(DOCKER_PULL_IDLE_TIMEOUT_MS, timeoutMs) });
             return;
         }
         catch (error) {
@@ -778,16 +862,18 @@ async function dockerImageExists(image) {
         child.on("error", () => resolve(false));
     });
 }
-function spawnStepWithTimeout(label, display, taskDisplay, cmd, args, timeoutMs, task, execOptions, sudo) {
+function spawnStepWithTimeout(label, display, taskDisplay, cmd, args, timeoutMs, task, execOptions, sudo, runOptions) {
     process.stdout.write(`  [lifecycle:${label}] ${display}\n`);
     emitInstallTaskLog(task, `[lifecycle:${label}] ${taskDisplay}`);
     return new Promise((resolve, reject) => {
         const preparedEnv = prepareLifecycleExecEnv(sudo ? execOptions : undefined);
         let cleaned = false;
         let heartbeatTimer = null;
+        let idleTimer = null;
         let stdoutPending = "";
         let stderrPending = "";
         let capturedStderr = "";
+        let forcedError = null;
         const cleanupPreparedEnv = () => {
             if (cleaned)
                 return;
@@ -796,17 +882,37 @@ function spawnStepWithTimeout(label, display, taskDisplay, cmd, args, timeoutMs,
                 clearInterval(heartbeatTimer);
                 heartbeatTimer = null;
             }
+            if (idleTimer) {
+                clearTimeout(idleTimer);
+                idleTimer = null;
+            }
             preparedEnv.cleanup();
         };
         const spawnTarget = sudo
             ? buildSudoWrappedCommand(cmd, args, preparedEnv.env, execOptions)
             : { command: cmd, args };
-        const captureOutput = Boolean(task) || Boolean(sudo);
+        const captureOutput = Boolean(task) || Boolean(sudo) || Boolean(runOptions?.idleTimeoutMs);
         const child = spawn(spawnTarget.command, spawnTarget.args, {
             stdio: captureOutput ? ["ignore", "pipe", "pipe"] : "inherit",
             timeout: timeoutMs,
             env: preparedEnv.env,
         });
+        const resetIdleTimer = () => {
+            if (!runOptions?.idleTimeoutMs)
+                return;
+            if (idleTimer)
+                clearTimeout(idleTimer);
+            idleTimer = setTimeout(() => {
+                const idleSeconds = Math.max(1, Math.round(runOptions.idleTimeoutMs / 1000));
+                const stallMessage = `[lifecycle:${label}] no output for ${idleSeconds}s; terminating stalled step: ${taskDisplay}`;
+                process.stdout.write(`  ${stallMessage}\n`);
+                emitInstallTaskLog(task, stallMessage);
+                forcedError = new Error(`lifecycle '${label}' step stalled after ${idleSeconds}s with no output: ${display}`);
+                child.kill("SIGTERM");
+            }, runOptions.idleTimeoutMs);
+            idleTimer.unref?.();
+        };
+        resetIdleTimer();
         if (captureOutput) {
             const startedAt = Date.now();
             const flushPendingLine = (line) => {
@@ -815,6 +921,7 @@ function spawnStepWithTimeout(label, display, taskDisplay, cmd, args, timeoutMs,
                 emitInstallTaskLog(task, line);
             };
             const handleChunk = (chunk, stream) => {
+                resetIdleTimer();
                 const text = typeof chunk === "string" ? chunk : chunk.toString("utf-8");
                 if (stream === "stderr") {
                     capturedStderr += text;
@@ -854,7 +961,9 @@ function spawnStepWithTimeout(label, display, taskDisplay, cmd, args, timeoutMs,
         }
         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)));
@@ -863,6 +972,10 @@ function spawnStepWithTimeout(label, display, taskDisplay, cmd, args, timeoutMs,
         });
         child.on("error", (err) => {
             cleanupPreparedEnv();
+            if (forcedError) {
+                reject(forcedError);
+                return;
+            }
             if (sudo && err.code === "ENOENT") {
                 reject(new Error("当前环境未检测到 sudo，无法执行需要 sudo 的生命周期步骤。请以 root 身份重试。"));
                 return;
@@ -879,7 +992,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(),
         });
@@ -887,6 +1001,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`);
@@ -969,6 +1141,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`);
@@ -1135,6 +1337,7 @@ function startAppLifecycleTask(appId, kind, startMessage, doneMessage, action) {
         return {
             ok: false,
             error: `App '${appId}' 正在执行 ${currentTask.kind} 操作，请等待完成后再试`,
+            code: "TASK_BUSY",
             kind,
         };
     }
@@ -1354,7 +1557,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,
@@ -1492,43 +1710,38 @@ 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);
+    const file = capabilityRegistry.readRegistry();
+    return { capabilities: file.capabilities ?? {}, providersByCapability: file.providersByCapability };
 }
 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 查看当前可用能力。`);
-}
+// `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,
@@ -1554,7 +1767,11 @@ export function getEmbeddedUiHintForApp(appId) {
     const provides = getProvidedCapabilitiesForApp(appId);
     if (!provides.length)
         return null;
-    for (const provide of provides) {
+    const preferred = provides.find((provide) => provide.capability === BROWSERLESS_DEBUGGER_CAPABILITY);
+    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;
@@ -1570,14 +1787,43 @@ 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);
+        // 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 directlyReachable = listeningHost && listeningHost !== "127.0.0.1" && listeningHost !== "::1";
+        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;
@@ -1615,7 +1861,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;
@@ -1846,44 +2096,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;
         }
@@ -1894,7 +2191,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` };
@@ -1903,6 +2242,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)
@@ -1915,18 +2257,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;
@@ -1954,6 +2325,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` };
@@ -1962,14 +2336,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;
 }
@@ -1985,28 +2367,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)) {
@@ -2144,5 +2532,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