jishushell 0.5.15 → 0.6.5

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

@@ -8,13 +8,15 @@ 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 * as instanceServices from "../instance-manager.js";
+import { invalidateRuntimeIdentity, resolveRuntimeIdentity } from "../runtime-identity.js";
 import { withInstanceLock } from "../../utils/instance-lock.js";
 import { createTask, emitTask, getRunningTasks, getTask } from "../task-registry.js";
 import { compileTaskRuntime } from "./app-compiler.js";
 import * as capabilityRegistry from "../capability-registry.js";
 import { resolveProvideEndpoint } from "./provide-resolver.js";
 import { platformTransformSpec } from "./platform-transform.js";
+import { createInvalidSudoPasswordError, isSudoAuthenticationError, isSudoNoNewPrivilegesError, isSudoPasswordRequiredError, prepareSudoAskpassEnv, SUDO_PASSTHROUGH_ENV_KEYS, } from "../../utils/sudo-askpass.js";
 const DEFAULT_LIFECYCLE_PATH_ENTRIES = [
     "/opt/homebrew/bin",
     "/opt/homebrew/sbin",
@@ -43,6 +45,9 @@ const ANONYMOUS_DOWNLOAD_IMAGE_ALLOWLIST = new Set([
     "wechatopenai/weknora-docreader:latest",
     "wechatopenai/weknora-ui:latest",
 ]);
+const ANONYMOUS_DOWNLOAD_IMAGE_REPOSITORY_ALLOWLIST = new Set([
+    "ghcr.io/x-aijishu/jishu-kb",
+]);
 function getConfigValue(name) {
     return name in config ? config[name] : undefined;
 }
@@ -125,7 +130,7 @@ export function listBuiltinAppSpecs() {
         .filter((entry) => entry != null);
 }
 function installedAppDir(instanceId) {
-    for (const rootDir of [APPS_DIR, INSTANCES_DIR]) {
+    for (const rootDir of [APPS_DIR]) {
         const dir = join(rootDir, instanceId);
         if (existsSync(join(dir, "app-spec.yaml")) && existsSync(join(dir, "manifest.json"))) {
             return dir;
@@ -134,7 +139,7 @@ function installedAppDir(instanceId) {
     return null;
 }
 export function updateInstance(instanceId, name, description) {
-    const updatedMeta = legacyInstanceManager.updateInstance(instanceId, name, description);
+    const updatedMeta = instanceServices.updateInstance(instanceId, name, description);
     const appData = getApp(instanceId);
     const appDir = installedAppDir(instanceId);
     if (appData && appDir) {
@@ -148,7 +153,8 @@ export function updateInstance(instanceId, name, description) {
         writeFileSync(yamlTmp, stringify(nextSpec), { mode: 0o644 });
         renameSync(yamlTmp, yamlPath);
     }
-    return legacyInstanceManager.getInstance(instanceId) ?? updatedMeta;
+    invalidateRuntimeIdentity(instanceId);
+    return instanceServices.getInstance(instanceId) ?? updatedMeta;
 }
 function parseComparableVersion(version, label) {
     const normalized = version
@@ -209,22 +215,22 @@ function buildLifecycleEnv() {
         ? 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
+    // Surface core callback hooks to lifecycle scripts. post_start can curl
+    // ${JISHUSHELL_CORE_URL}/api/internal/* with the internal token to read
+    // core-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 = {};
+    const coreHooks = {};
     try {
-        panelHooks.JISHUSHELL_PANEL_URL = `http://127.0.0.1:${config.getPanelPort()}`;
-        panelHooks.JISHUSHELL_INTERNAL_TOKEN = config.getInternalMcpToken();
+        coreHooks.JISHUSHELL_CORE_URL = `http://127.0.0.1:${config.getCorePort()}`;
+        coreHooks.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();
+        // health. getCoreLanHost() returns the same IP Nomad publishes ports on.
+        coreHooks.JISHUSHELL_LAN_HOST = config.getCoreLanHost();
     }
     catch {
         // tolerate — only post_start cares
@@ -233,19 +239,9 @@ function buildLifecycleEnv() {
         ...process.env,
         HOME: process.env.HOME ?? homedir(),
         PATH: mergedPath,
-        ...panelHooks,
+        ...coreHooks,
     };
 }
-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) => {
@@ -263,9 +259,7 @@ function createLifecycleSudoError(stderr, fallbackDisplay, hasPassword) {
         return createNoNewPrivilegesSudoError();
     }
     if (isSudoAuthenticationError(message)) {
-        const err = new Error("sudo 密码错误，请重新输入。");
-        err.code = "INVALID_SUDO_PASSWORD";
-        return err;
+        return createInvalidSudoPasswordError();
     }
     if (!hasPassword && isSudoPasswordRequiredError(message)) {
         return new Error("该生命周期步骤需要 sudo 密码；请在页面弹窗中输入后重试。");
@@ -275,20 +269,20 @@ function createLifecycleSudoError(stderr, fallbackDisplay, hasPassword) {
     }
     return new Error(`lifecycle sudo step failed: ${fallbackDisplay}`);
 }
-function panelSystemdServicePath() {
-    const override = process.env.JISHUSHELL_PANEL_SYSTEMD_SERVICE_PATH?.trim();
+function coreSystemdServicePath() {
+    const override = process.env.JISHUSHELL_CORE_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());
+        || process.env.JISHUSHELL_CORE_SYSTEMD_SERVICE_PATH?.trim());
 }
-function maybeRepairPanelAutostartNoNewPrivileges() {
+function maybeRepairCoreAutostartNoNewPrivileges() {
     if (!isLikelySystemdServiceProcess())
         return null;
-    const servicePath = panelSystemdServicePath();
+    const servicePath = coreSystemdServicePath();
     if (!existsSync(servicePath))
         return null;
     let unitText = "";
@@ -323,7 +317,7 @@ function manualInstallCommandForSpec(spec) {
     return `jishushell app install ${spec.id}`;
 }
 function createNoNewPrivilegesSudoError(manualInstallCommand) {
-    const repair = maybeRepairPanelAutostartNoNewPrivileges();
+    const repair = maybeRepairCoreAutostartNoNewPrivileges();
     const restartCommand = "sudo systemctl daemon-reload && sudo systemctl restart jishushell";
     const parts = ["当前运行环境禁止 sudo 提权（no new privileges），面板内无法继续后续安装。"];
     if (repair?.updated) {
@@ -373,10 +367,8 @@ export async function validateSudoPassword(sudoPassword) {
                     reject(createNoNewPrivilegesSudoError());
                     return;
                 }
-                if (/incorrect password|try again|authentication failure|密码错误|抱歉，请重试/i.test(message)) {
-                    const err = new Error("sudo 密码错误，请重新输入。");
-                    err.code = "INVALID_SUDO_PASSWORD";
-                    reject(err);
+                if (isSudoAuthenticationError(message)) {
+                    reject(createInvalidSudoPasswordError());
                     return;
                 }
                 resolve();
@@ -399,32 +391,21 @@ function prepareLifecycleExecEnv(execOptions, envOverrides) {
     if (!sudoPassword) {
         return { env, cleanup: () => undefined };
     }
-    const helperDir = mkdtempSync(join(tmpdir(), "jishushell-sudo-askpass-"));
-    const passwordPath = join(helperDir, "password.txt");
-    const askpassPath = join(helperDir, "askpass.sh");
-    writeFileSync(passwordPath, sudoPassword, { mode: 0o600 });
-    // Use an absolute password-file path in the helper script so sudo env
-    // filtering cannot drop the file path and cause false password failures.
-    writeFileSync(askpassPath, `#!/bin/sh\ncat '${passwordPath}'\nprintf '\\n'\n`, { mode: 0o700 });
-    chmodSync(askpassPath, 0o700);
-    return {
-        env: {
-            ...env,
-            SUDO_ASKPASS: askpassPath,
-            JISHUSHELL_SUDO_ASKPASS: "1",
-        },
-        cleanup: () => {
-            try {
-                rmSync(helperDir, { recursive: true, force: true });
-            }
-            catch {
-                // best effort cleanup for one-shot askpass helper files
-            }
-        },
-    };
+    return prepareSudoAskpassEnv(sudoPassword, env);
 }
 function shouldBypassDockerCredentialHelperForDownloadImage(image) {
-    return ANONYMOUS_DOWNLOAD_IMAGE_ALLOWLIST.has(image.trim());
+    const trimmedImage = image.trim();
+    return ANONYMOUS_DOWNLOAD_IMAGE_ALLOWLIST.has(trimmedImage)
+        || ANONYMOUS_DOWNLOAD_IMAGE_REPOSITORY_ALLOWLIST.has(normalizeDockerImageRepository(trimmedImage));
+}
+function normalizeDockerImageRepository(image) {
+    const digestIndex = image.indexOf("@");
+    const imageWithoutDigest = digestIndex >= 0 ? image.slice(0, digestIndex) : image;
+    const lastSlashIndex = imageWithoutDigest.lastIndexOf("/");
+    const lastColonIndex = imageWithoutDigest.lastIndexOf(":");
+    return lastColonIndex > lastSlashIndex
+        ? imageWithoutDigest.slice(0, lastColonIndex)
+        : imageWithoutDigest;
 }
 function createAnonymousDockerConfig() {
     const dockerConfigDir = mkdtempSync(join(tmpdir(), "jishushell-docker-config-"));
@@ -492,6 +473,11 @@ function normalizeAppSpec(spec) {
             && provide.path !== "/") {
             return { ...provide, path: "/" };
         }
+        if (spec.id === "jishu-kb-container"
+            && provide.capability === "web-jishukb"
+            && provide.embedded !== "proxy") {
+            return { ...provide, embedded: "proxy" };
+        }
         return provide;
     });
     // Inject browserless-api capability for legacy installed specs that lack it.
@@ -523,9 +509,41 @@ function normalizeAppSpec(spec) {
                 visibility: normalizePortVisibility(port.visibility),
             }));
         }
+        if (spec.id === "jishu-kb-container" && rawTask.name === "jishukb") {
+            const env = rawTask.env && typeof rawTask.env === "object"
+                ? { ...rawTask.env }
+                : {};
+            const frameAncestors = typeof env.JISHU_KB_FRAME_ANCESTORS === "string"
+                ? env.JISHU_KB_FRAME_ANCESTORS.trim()
+                : "";
+            // Keep legacy KB specs iframe-safe even though the embedded UI now runs
+            // through the capability proxy. Users can still open the direct port
+            // manually, and older installs may still rely on permissive upstream
+            // framing until they restart onto the proxied path.
+            // Repair legacy installed specs here (not via Nomad extraEnv) because
+            // task.env wins over extraEnv during job materialization.
+            if (!frameAncestors || frameAncestors === "'self'") {
+                env.JISHU_KB_FRAME_ANCESTORS = JISHU_KB_FRAME_ANCESTORS_ALLOW_ALL;
+            }
+            rawTask.env = env;
+        }
         return rawTask;
     });
     let normalizedLifecycle = spec.lifecycle ? { ...spec.lifecycle } : undefined;
+    if (spec.id === "jishu-kb-container" && normalizedLifecycle?.post_start?.length) {
+        const postStart = normalizedLifecycle.post_start.map((step) => {
+            if (typeof step?.run !== "string")
+                return step;
+            const run = normalizeJishuKbPostStartRun(step.run);
+            return run === step.run
+                ? step
+                : { ...step, run };
+        });
+        normalizedLifecycle = {
+            ...(normalizedLifecycle ?? {}),
+            post_start: postStart,
+        };
+    }
     if (spec.id === "browserless-chromium-container") {
         const browserlessDataDir = `~/.jishushell/apps/${spec.app_id || spec.id}/data`;
         const browserlessDataDirTemplate = "~/.jishushell/apps/${app_id}/data";
@@ -553,6 +571,22 @@ function normalizeAppSpec(spec) {
             pre_start: preStart,
         };
     }
+    function normalizeJishuKbPostStartRun(run) {
+        if (run.includes("fetch_default_provider_json()"))
+            return run;
+        const marker = 'echo "[post_start] fetching core default provider ..."';
+        const readyLine = `READY=$(printf '%s' "$DP_JSON" | jget ready)`;
+        if (!run.includes(marker)
+            || !run.includes('"$JISHUSHELL_CORE_URL/api/internal/default-provider"')
+            || !run.includes(`|| echo '{"ready":false,"reason":"core_unreachable"}'`)) {
+            return run;
+        }
+        const start = run.indexOf(marker);
+        const end = run.indexOf(readyLine, start);
+        if (start < 0 || end < 0)
+            return run;
+        return `${run.slice(0, start)}${JISHU_KB_DEFAULT_PROVIDER_RETRY_BLOCK}${run.slice(end + readyLine.length)}`;
+    }
     return {
         ...spec,
         ...(spec.provides ? { provides: normalizedProvides } : {}),
@@ -671,13 +705,19 @@ function getProvideUrl(provide) {
     }
 }
 function buildCapabilityAddress(port, path) {
-    const host = port > 0 ? legacyInstanceManager.getAdvertisedHostForPort(port) : "127.0.0.1";
+    const host = port > 0 ? instanceServices.getAdvertisedHostForPort(port) : "127.0.0.1";
     if (!path) {
         return `${host}:${port}`;
     }
     const normalizedPath = path.startsWith("/") ? path : `/${path}`;
     return `${host}:${port}${normalizedPath}`;
 }
+// docker0 bridge gateway (host.docker.internal target). A port published only
+// on this address is reachable by peer containers but NOT by a remote browser,
+// so it must never be advertised as the host for an embedded UI iframe.
+function isDockerBridgeHost(host) {
+    return host === "172.17.0.1";
+}
 function normalizeProvideProtocol(protocol) {
     const raw = typeof protocol === "string" ? protocol.trim().toLowerCase() : "";
     return raw || "http";
@@ -799,7 +839,7 @@ function formatInstalledAppId(baseId, instancePrefix, offset) {
 // Wrap in a thunk so the lookup happens at call time — some test suites
 // partially mock instance-manager without re-exporting this symbol.
 function isPortInUse(port) {
-    return legacyInstanceManager.isPortInUse(port);
+    return instanceServices.isPortInUse(port);
 }
 async function resolveInstallTarget(spec, originalSpecYaml, requestedAppId) {
     const baseId = spec.id;
@@ -891,7 +931,7 @@ async function resolveInstallTarget(spec, originalSpecYaml, requestedAppId) {
             // 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
+            // disk; subsequent core restarts then re-read the raw source via
             // `loadInstalledAppSpec` and broke macOS placement again.
             installedSpecYaml: stringify(installedSpec),
         };
@@ -920,7 +960,7 @@ const DOCKER_PULL_TIMEOUT_MS = 1_800_000;
 // 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) {
+async function pullDockerImageStep(label, image, display, task, timeoutMs = DOCKER_PULL_TIMEOUT_MS, idleTimeoutMs) {
     if (await dockerImageExists(image)) {
         const skipMessage = `[lifecycle:${label}] docker image '${image}' already exists locally; skipping pull`;
         process.stdout.write(`  ${skipMessage}\n`);
@@ -935,7 +975,7 @@ async function pullDockerImageStep(label, image, display, task, timeoutMs = DOCK
         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),
+                    idleTimeoutMs: idleTimeoutMs ?? Math.min(DOCKER_PULL_IDLE_TIMEOUT_MS, timeoutMs),
                     envOverrides: anonymousDockerConfig?.envOverrides,
                     stallMessageHint: "Docker credential resolution (for example docker-credential-desktop) may be involved.",
                 });
@@ -964,16 +1004,137 @@ async function pullDockerImageStep(label, image, display, task, timeoutMs = DOCK
     }
     throw (lastError instanceof Error ? lastError : new Error(String(lastError)));
 }
+/**
+ * In-flight background pulls keyed by image tag. Used by
+ * `pullDockerImageInBackground` to dedup concurrent requests so repeated
+ * UI clicks for the same not-yet-local image don't queue duplicate pulls.
+ */
+const inFlightBackgroundPulls = new Map();
+/**
+ * Fire-and-forget background docker pull. Used by `*-manager.ts`
+ * (custom / hermes / ollama) when an instance is requested with an image
+ * that's not yet local: kicks off a pull in the background and the caller
+ * asks the user to retry later (HTTP 202).
+ *
+ * Wraps the same `pullDockerImageStep` used by full installs, so it
+ * inherits the same protections — total timeout (30 min), idle timeout
+ * (10 min of silence on the pull's stdout/stderr terminates it), 3
+ * retries, and a post-failure `dockerImageExists` recovery check — that
+ * a bare `exec("docker pull ...", { timeout: 0 })` lacks. Docker Desktop
+ * on macOS can hang the CLI for tens of minutes after the image has been
+ * fully downloaded (the final manifest/tag write step occasionally
+ * deadlocks); the idle timer kills the hung CLI and the recovery check
+ * picks up the image if the tag did make it through.
+ *
+ * Concurrent calls for the same image dedup onto a single in-flight pull
+ * so repeated UI clicks don't waste retries.
+ *
+ * Always resolves — errors are logged via console.warn so the
+ * fire-and-forget caller doesn't have to attach a `.catch` handler.
+ */
+export function pullDockerImageInBackground(label, image) {
+    const existing = inFlightBackgroundPulls.get(image);
+    if (existing)
+        return existing;
+    const promise = (async () => {
+        try {
+            await pullDockerImageStep(`${label}-background`, image, `docker pull ${image} (background)`);
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            console.warn(`[${label}] Background pull of ${image} failed: ${reason}`);
+        }
+        finally {
+            inFlightBackgroundPulls.delete(image);
+        }
+    })();
+    inFlightBackgroundPulls.set(image, promise);
+    return promise;
+}
 async function dockerImageExists(image) {
     return new Promise((resolve) => {
         const child = spawn("docker", ["image", "inspect", image], {
             stdio: "ignore",
             env: buildLifecycleEnv(),
         });
-        child.on("close", (code) => resolve(code === 0));
-        child.on("error", () => resolve(false));
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        };
+        // `docker image inspect` is a local-only daemon API call that should
+        // return in milliseconds. In practice, when dockerd itself wedges
+        // (the same failure mode that causes `docker pull` to hang), `docker
+        // image inspect` hangs too. Without this timeout the inspect call
+        // ties up the install lifecycle's post-failure recovery check, which
+        // in turn keeps the install lock held indefinitely. 10s is generous
+        // for a healthy daemon and short enough that a wedged daemon doesn't
+        // block install retry/recovery.
+        const watchdog = setTimeout(() => {
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                /* already exited */
+            }
+            finish(false);
+        }, 10_000);
+        watchdog.unref?.();
+        child.on("close", (code) => {
+            clearTimeout(watchdog);
+            finish(code === 0);
+        });
+        child.on("error", () => {
+            clearTimeout(watchdog);
+            finish(false);
+        });
     });
 }
+/**
+ * Force-terminate a spawned child: send `SIGTERM`, then escalate to
+ * `SIGKILL` after a grace period if the process is still alive.
+ *
+ * Needed because some CLIs (notably `docker` on macOS when its daemon
+ * has wedged) block on a daemon round-trip and ignore `SIGTERM` until
+ * the daemon responds. Without `SIGKILL` escalation the parent
+ * `child.on("close")` handler never fires, the lifecycle promise never
+ * resolves, and the install task hangs forever holding its lock.
+ *
+ * The grace period must be long enough for well-behaved children to
+ * flush buffers and exit cleanly on SIGTERM (avoid corrupt artifacts in
+ * the common case) but short enough that a hung child doesn't waste a
+ * meaningful slice of the parent's overall budget. 30s is the sweet
+ * spot in practice for docker-class tooling.
+ */
+function forceTerminateChild(child, label) {
+    try {
+        child.kill("SIGTERM");
+    }
+    catch {
+        /* already exited */
+    }
+    // Unref'd so it doesn't keep the event loop alive. If the child
+    // exited cleanly under SIGTERM before this fires, `kill("SIGKILL")`
+    // on a dead process is a harmless no-op (and we try/catch around it
+    // anyway). We deliberately do NOT register an extra `on("close")`
+    // listener to cancel this timer — some lifecycle paths use bare
+    // mock children whose `on` is single-slot and a second listener
+    // would clobber the parent's reject handler.
+    const killTimer = setTimeout(() => {
+        if (child.exitCode !== null || child.signalCode !== null)
+            return;
+        process.stdout.write(`  [lifecycle:${label}] child ignored SIGTERM after 30s; escalating to SIGKILL\n`);
+        try {
+            child.kill("SIGKILL");
+        }
+        catch {
+            /* already exited */
+        }
+    }, 30_000);
+    killTimer.unref?.();
+}
 function spawnStepWithTimeout(label, display, taskDisplay, cmd, args, timeoutMs, task, execOptions, sudo, runOptions) {
     process.stdout.write(`  [lifecycle:${label}] ${display}\n`);
     emitInstallTaskLog(task, `[lifecycle:${label}] ${taskDisplay}`);
@@ -986,6 +1147,7 @@ function spawnStepWithTimeout(label, display, taskDisplay, cmd, args, timeoutMs,
         let stderrPending = "";
         let capturedStderr = "";
         let forcedError = null;
+        let totalTimeoutTimer = null;
         const cleanupPreparedEnv = () => {
             if (cleaned)
                 return;
@@ -998,6 +1160,10 @@ function spawnStepWithTimeout(label, display, taskDisplay, cmd, args, timeoutMs,
                 clearTimeout(idleTimer);
                 idleTimer = null;
             }
+            if (totalTimeoutTimer) {
+                clearTimeout(totalTimeoutTimer);
+                totalTimeoutTimer = null;
+            }
             preparedEnv.cleanup();
         };
         const spawnTarget = sudo
@@ -1006,9 +1172,39 @@ function spawnStepWithTimeout(label, display, taskDisplay, cmd, args, timeoutMs,
         const captureOutput = Boolean(task) || Boolean(sudo) || Boolean(runOptions?.idleTimeoutMs);
         const child = spawn(spawnTarget.command, spawnTarget.args, {
             stdio: captureOutput ? ["ignore", "pipe", "pipe"] : "inherit",
+            // Node's spawn `timeout` sends SIGTERM at the deadline but has no
+            // SIGKILL escalation, so a child that ignores SIGTERM (docker CLI
+            // on macOS when its daemon is wedged) still blocks the parent's
+            // `child.on("close")`. We keep this here so callers / tests can
+            // observe the configured budget on the spawn options, and add the
+            // `totalKillEscalationTimer` below to SIGKILL after a grace.
             timeout: timeoutMs,
             env: preparedEnv.env,
         });
+        // SIGKILL escalation for the total-timeout case. Node's `timeout`
+        // option above will have sent SIGTERM at `timeoutMs`; if the child
+        // hasn't exited within `timeoutMs + 30s` we force it. Independent
+        // of the idle timer's escalation (which `forceTerminateChild`
+        // handles inline) — covers the path where output keeps flowing but
+        // the total budget is blown.
+        totalTimeoutTimer = setTimeout(() => {
+            if (child.exitCode !== null || child.signalCode !== null)
+                return;
+            const totalSeconds = Math.max(1, Math.round(timeoutMs / 1000));
+            const timeoutMessage = `[lifecycle:${label}] child ignored spawn-timeout SIGTERM ${totalSeconds}s+30s ago; escalating to SIGKILL`;
+            process.stdout.write(`  ${timeoutMessage}\n`);
+            emitInstallTaskLog(task, timeoutMessage);
+            if (!forcedError) {
+                forcedError = new Error(`lifecycle '${label}' step exceeded ${totalSeconds}s total budget: ${display}`);
+            }
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                /* already exited */
+            }
+        }, timeoutMs + 30_000);
+        totalTimeoutTimer.unref?.();
         const resetIdleTimer = () => {
             if (!runOptions?.idleTimeoutMs)
                 return;
@@ -1021,7 +1217,7 @@ function spawnStepWithTimeout(label, display, taskDisplay, cmd, args, timeoutMs,
                 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");
+                forceTerminateChild(child, label);
             }, runOptions.idleTimeoutMs);
             idleTimer.unref?.();
         };
@@ -1116,7 +1312,7 @@ async function commandExists(command) {
 }
 // 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
+// different uid than the service 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) {
@@ -1141,10 +1337,10 @@ function chownRecursive(path, uid, gid) {
     }
 }
 /**
- * Try chowning via direct fs syscall first; on EPERM (panel runs as a
+ * Try chowning via direct fs syscall first; on EPERM (core 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
+ * service user (the canonical Pi setup); on other hosts the original
  * EPERM bubbles up as a clear error.
  */
 function chownWithSudoFallback(path, uid, gid, recursive) {
@@ -1169,7 +1365,7 @@ function chownWithSudoFallback(path, uid, gid, recursive) {
     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}` : ""}`);
+        throw new Error(`chown ${recursive ? "-R " : ""}${uid}:${gid} ${path} failed: service user lacks CAP_CHOWN and passwordless sudo also failed${stderr ? `: ${stderr}` : ""}`);
     }
 }
 async function downloadBinaryStep(label, url, dest, chmod, task) {
@@ -1221,7 +1417,7 @@ async function runLifecycleSteps(steps, label, artifacts, task, execOptions) {
             }
         }
         else if ("downloadImage" in step) {
-            await pullDockerImageStep(label, step.downloadImage, `downloadImage: ${step.downloadImage}`, task, step.timeout_ms);
+            await pullDockerImageStep(label, step.downloadImage, `downloadImage: ${step.downloadImage}`, task, step.timeout_ms, step.idle_timeout_ms);
             artifacts?.push({ type: "image", path: step.downloadImage });
         }
         else if ("deleteImage" in step) {
@@ -1273,7 +1469,7 @@ async function runLifecycleSteps(steps, label, artifacts, task, execOptions) {
                 // 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.
+                // any non-root service 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`);
@@ -1552,13 +1748,26 @@ function buildGenericAppRuntime(spec, appId) {
     if (!serviceTask)
         return {};
     const runtime = compileTaskRuntime(serviceTask, appId);
-    if (Array.isArray(serviceTask.ports) && serviceTask.ports.length > 0) {
-        runtime.ports = serviceTask.ports.map((port) => ({
-            name: port.name,
-            containerPort: port.container_port ?? port.port,
-            hostPort: port.host_port ?? port.port,
-            visibility: port.visibility ?? "external",
-        }));
+    // Record EVERY external port across ALL tasks, each tagged with its owning
+    // taskName. Multi-service-task apps (e.g. WeKnora's `app` + `ui`, both with a
+    // port named "http") otherwise lose the secondary task's ports downstream,
+    // letting name-only matching collapse two distinct host ports into one.
+    // Ordering matters: the primary service task's ports come first so
+    // extractGatewayPort / single-service `runtime.ports[0]` semantics are
+    // byte-for-byte preserved.
+    const orderedTasks = [serviceTask, ...spec.tasks.filter((task) => task !== serviceTask)];
+    const allPorts = orderedTasks.flatMap((task) => (task.ports ?? [])
+        .filter((port) => (port.visibility ?? "external") !== "internal")
+        .map((port) => ({
+        taskName: task.name,
+        name: port.name,
+        containerPort: port.container_port ?? port.port,
+        hostPort: port.host_port ?? port.port,
+        visibility: port.visibility ?? "external",
+        ...(port.host_network ? { host_network: port.host_network } : {}),
+    })));
+    if (allPorts.length > 0) {
+        runtime.ports = allPorts;
     }
     if (serviceTask.health?.http) {
         const healthPortEntry = serviceTask.ports?.find((port) => port.port === serviceTask.health?.http?.port
@@ -1629,12 +1838,8 @@ async function bootstrapAdapterManagedApp(appId, spec, options) {
 function getAdapterManagedAgentType(appData) {
     if (!appData || appData.manifest.install_mode !== "app-dir")
         return null;
-    const meta = legacyInstanceManager.getInstance(appData.manifest.id);
-    const agentType = typeof meta?.agentType === "string" ? meta.agentType.trim() : "";
-    const legacyAppType = typeof meta?.app_type === "string" ? meta.app_type.trim() : "";
-    if (!agentType || legacyAppType)
-        return null;
-    return agentType;
+    const identity = resolveRuntimeIdentity(appData.manifest.id);
+    return identity?.driver === "runtime-adapter" ? identity.agentType ?? null : null;
 }
 async function installIntoInstanceDir(spec, specYaml, requestedAppId, options = {}) {
     if (options.preferInstanceDir !== true)
@@ -1778,6 +1983,7 @@ async function installIntoInstanceDir(spec, specYaml, requestedAppId, options =
         manifest.artifacts = artifacts;
         safeWriteJson(join(instanceDir, "manifest.json"), manifest, true);
     }
+    invalidateRuntimeIdentity(appId);
     return { spec: instanceSpec, manifest };
 }
 /**
@@ -1826,25 +2032,105 @@ export function getAppInstallState(appId) {
 const BROWSERLESS_DEBUGGER_CAPABILITY = "browserless-debugger";
 const BROWSERLESS_API_CAPABILITY = "browserless-api";
 const BROWSERLESS_DOCS_CAPABILITY = "browserless-docs";
-/**
- * Compat-view registry reader. Returns the legacy `{ capabilities: {} }`
- * shape that older call sites expect. The new `capability-registry.ts`
- * module migrates dual-shape entries on every read so the legacy view is
- * always populated. PR 3 sub-step 3f deletes this shim.
- */
-function readRegistry() {
-    const file = capabilityRegistry.readRegistry();
-    return { capabilities: file.capabilities ?? {}, providersByCapability: file.providersByCapability };
-}
+const JISHU_KB_FRAME_ANCESTORS_ALLOW_ALL = "*";
+const JISHU_KB_DEFAULT_PROVIDER_RETRY_BLOCK = `echo "[post_start] fetching core default provider ..."
+fetch_default_provider_json() {
+  curl -sf --max-time 8 \
+    -H "X-Jishushell-Internal-Token: $JISHUSHELL_INTERNAL_TOKEN" \
+    "$JISHUSHELL_CORE_URL/api/internal/default-provider"
+}
+DP_JSON=""
+for i in $(seq 1 30); do
+  DP_JSON=$(fetch_default_provider_json || true)
+  READY=$(printf '%s' "$DP_JSON" | jget ready)
+  REASON=$(printf '%s' "$DP_JSON" | jget reason)
+  if [ "$READY" = "true" ]; then
+    if [ "$i" -gt 1 ]; then
+      echo "[post_start] core default provider became ready after $i attempts"
+    fi
+    break
+  fi
+  case "$REASON" in
+    no_provider|no_key)
+      break
+      ;;
+  esac
+  DP_JSON='{"ready":false,"reason":"core_unreachable"}'
+  if [ "$i" -lt 30 ]; then
+    echo "[post_start] core default provider not ready yet (attempt $i/30); retrying in 2s"
+    sleep 2
+  fi
+done
+READY=$(printf '%s' "$DP_JSON" | jget ready)`;
 // `ensureRequiredCapabilitiesAvailable` was removed in PR 3 sub-step 3c.
 // install never blocks on missing required providers any more —
 // resolveConnections(..., "preCreate") collects them into the `pending`
 // list and the UI surfaces them after install completes.
+// `listProvidedCapabilities()` does a full filesystem app scan (listApps →
+// readdir + per-app spec parse) plus a registry read. `augmentInstanceMetadata`
+// calls it ~2× per instance (getProvidedCapabilitiesForApp +
+// getEmbeddedUiHintForApp), so `GET /api/instances` over N instances did ~2N
+// full disk scans per request — the dashboard warm-path cost.
+//
+// Cache the result, but key validity on a CHEAP fingerprint of the
+// underlying state, not on time alone. A time-only TTL left a staleness
+// window where a freshly installed/uninstalled app (or created/deleted
+// instance — INSTANCES_DIR also feeds listApps) was missing from / lingered
+// in the list until the TTL expired, which broke the Connections UI and the
+// embedded-UI hint. The fingerprint (sorted dir entries of APPS_DIR +
+// INSTANCES_DIR, plus the registry file mtime) changes the instant the app
+// set or registry changes — including external mutations — so the cache
+// self-busts without having to hook every mutation site. It costs two
+// readdir + one stat, still vastly cheaper than re-parsing every app spec.
+// The short TTL stays only as a safety net for in-place spec edits that
+// don't change the dir set; the explicit register/unregister/markStopped
+// invalidations remain as a precise fast-path for sub-millisecond registry
+// writes that could share an mtime tick.
+const PROVIDED_CAPS_TTL_MS = 5_000;
+let _providedCapsEntry = null;
+function providedCapabilitiesFingerprint() {
+    const dirEntries = (dir) => {
+        try {
+            return existsSync(dir) ? readdirSync(dir).sort().join(",") : "";
+        }
+        catch {
+            return "";
+        }
+    };
+    let registryMtime = 0;
+    try {
+        registryMtime = lstatSync(_REGISTRY_PATH).mtimeMs;
+    }
+    catch {
+        /* registry file not written yet → 0 */
+    }
+    return `${dirEntries(APPS_DIR)}|${registryMtime}`;
+}
+export function invalidateProvidedCapabilitiesCache() {
+    _providedCapsEntry = null;
+}
 export function listProvidedCapabilities() {
-    const reg = readRegistry();
+    const fp = providedCapabilitiesFingerprint();
+    const now = Date.now();
+    if (_providedCapsEntry &&
+        _providedCapsEntry.fp === fp &&
+        now - _providedCapsEntry.ts < PROVIDED_CAPS_TTL_MS) {
+        return _providedCapsEntry.data;
+    }
+    const data = computeProvidedCapabilities();
+    _providedCapsEntry = { data, fp, ts: now };
+    return data;
+}
+function computeProvidedCapabilities() {
+    const reg = capabilityRegistry.snapshot();
     return listApps().flatMap((app) => (app.spec.provides ?? []).map((provide) => {
         const url = getProvideUrl(provide) ?? undefined;
-        const port = getProvidePort(app.spec, provide) ?? undefined;
+        // Report the RUNTIME port the capability actually listens on (the
+        // resolver consults the instance's recorded port allocation and only
+        // falls back to the declared spec port when no runtime exists yet).
+        // Declared spec ports go stale once a sibling task is remapped onto a
+        // different host port (multi-service-task apps like WeKnora).
+        const port = resolveRuntimeCapabilityPort(app.manifest.id, provide.capability) ?? undefined;
         const address = !url && typeof port === "number" ? buildCapabilityAddress(port, provide.path) : undefined;
         const providers = reg.providersByCapability?.[provide.capability] ?? [];
         const registered = providers.find((e) => e.instanceId === app.manifest.id)
@@ -1872,21 +2158,51 @@ export function listProvidedCapabilities() {
 export function getProvidedCapabilitiesForApp(appId) {
     return listProvidedCapabilities().filter((entry) => entry.appId === appId);
 }
+/**
+ * Resolve the runtime endpoint (host + port) for a given app's capability.
+ * Returns the runtime-resolved port when available, falling back to the
+ * declared AppSpec port. This is used by the capability proxy to target the
+ * correct live endpoint after potential port reallocation.
+ */
+export function resolveRuntimeCapabilityPort(appId, capabilityName) {
+    const app = getApp(appId);
+    if (!app)
+        return null;
+    const provide = (app.spec.provides ?? []).find((p) => p.capability === capabilityName);
+    if (!provide)
+        return null;
+    const resolved = resolveProvideEndpoint(appId, app.spec, provide);
+    return resolved?.hostPort ?? getProvidePort(app.spec, provide);
+}
 export function getEmbeddedUiHintForApp(appId) {
+    const app = getApp(appId);
+    if (!app)
+        return null;
+    // OpenClaw should always render through its dedicated gateway-launch iframe
+    // path, not through the generic app-provides embedded UI chooser. App-dir
+    // OpenClaw specs expose `openclaw-dashboard`, which would otherwise be
+    // advertised as a direct LAN URL (e.g. http://10.x.x.x:18793) and hijack the
+    // panel into a browser-direct iframe that bypasses gateway auth/proxy logic.
+    // Returning null here lets InstanceDetail fall back to
+    // `capabilities.gateway.chatPanel === "iframe"` → `/gateway-launch`.
+    if (app.spec?.agentType === "openclaw")
+        return null;
     const provides = getProvidedCapabilitiesForApp(appId);
     if (!provides.length)
         return null;
+    const isUiCapability = (capability) => capability.endsWith("-ui") || capability.startsWith("web-") || capability.endsWith("-web");
     // 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
+    //   2. any capability whose name looks like a Web UI slot:
+    //      `*-ui`, `web-*`, or `*-web`. 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.
+    //      capability (`anythingllm-ui`, path `/`). Jishu KB uses `web-jishukb`
+    //      while OpenWebUI/Hollama use `*-web`. Without this preference the
+    //      first-iterated API provide can win and the iframe lands on JSON / a
+    //      direct upstream URL instead of the intended Web UI.
     //   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 uiPreferred = provides.find((provide) => isUiCapability(provide.capability));
     const preferred = browserlessPreferred ?? uiPreferred ?? null;
     const orderedProvides = preferred
         ? [preferred, ...provides.filter((provide) => provide !== preferred)]
@@ -1905,7 +2221,13 @@ export function getEmbeddedUiHintForApp(appId) {
                 url,
             };
         }
-        if (typeof provide.port !== "number" || provide.port < 1)
+        // Resolve the RUNTIME port for this capability, not the declared spec
+        // port. For multi-service-task apps the declared port can be a dead value
+        // once another task has been remapped onto a different host port; the
+        // runtime resolver returns the port the capability actually listens on
+        // (falling back to the declared port when no runtime is recorded yet).
+        const resolvedPort = resolveRuntimeCapabilityPort(appId, provide.capability) ?? provide.port;
+        if (typeof resolvedPort !== "number" || resolvedPort < 1)
             continue;
         // Honor explicit `embedded` opt-in/out on the provide before the
         // auto-detection logic runs. `"proxy"` short-circuits to the
@@ -1923,19 +2245,28 @@ export function getEmbeddedUiHintForApp(appId) {
         // 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);
+        // those calls bypass `<base href>` and hit the core API instead.
+        const listeningHost = instanceServices.getListeningHostForPort(resolvedPort);
         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 ?? ""}`;
+            // Advertise a browser-reachable host. getAdvertisedHostForPort already
+            // prefers the external/LAN address and only ever falls back to the
+            // primary IPv4 — but when the port is published on the docker_bridge
+            // (docker0 IP 172.17.0.1) it is internal-only and unreachable from a
+            // remote browser, so override it with the LAN address for the embedded
+            // UI slot.
+            const rawAdvertised = instanceServices.getAdvertisedHostForPort(resolvedPort);
+            const advertised = isDockerBridgeHost(rawAdvertised)
+                ? instanceServices.getPrimaryIpv4Address()
+                : rawAdvertised;
+            const directUrl = `${protocol}://${advertised}:${resolvedPort}${provide.path ?? ""}`;
             return {
                 capability: provide.capability,
                 protocol,
-                port: provide.port,
+                port: resolvedPort,
                 url: directUrl,
             };
         }
@@ -1953,7 +2284,7 @@ export function getEmbeddedUiHintForApp(appId) {
         return {
             capability: provide.capability,
             protocol,
-            port: provide.port,
+            port: resolvedPort,
             url: proxyPath,
         };
     }
@@ -1999,6 +2330,7 @@ export async function installApp(specYaml, requestedAppId, options = {}) {
     // the error if still unresolved.
     const instanceBackedInstall = await installIntoInstanceDir(spec, specYaml, requestedAppId, options);
     if (instanceBackedInstall) {
+        invalidateRuntimeIdentity(instanceBackedInstall.manifest.id);
         return instanceBackedInstall;
     }
     const { appId, installedSpec, installedSpecYaml, } = await resolveInstallTarget(spec, specYaml, requestedAppId);
@@ -2060,13 +2392,13 @@ export async function installApp(specYaml, requestedAppId, options = {}) {
     }
     removeInstallLock(appDir);
     emitInstallTaskLog(options.task, `[app-manager] removed ${INSTALL_LOCK_FILENAME} for ${appId}`);
+    invalidateRuntimeIdentity(appId);
     return { spec: installedSpec, manifest };
 }
 export function listApps() {
     const results = [];
     for (const { rootDir, installMode } of [
         { rootDir: APPS_DIR, installMode: "app-dir" },
-        { rootDir: INSTANCES_DIR, installMode: "instance-dir" },
     ]) {
         if (!existsSync(rootDir))
             continue;
@@ -2146,12 +2478,13 @@ export async function uninstallApp(id, options = {}) {
                 cleanupArtifacts(cleanupList);
             }
         }
-        unregisterCapabilities(id);
         const instanceManager = await import("../instance-manager.js");
         const deleteResult = await instanceManager.deleteInstance(id);
         if (!deleteResult.ok && deleteResult.warnings?.length) {
             warnings.push(...deleteResult.warnings);
         }
+        await syncCapabilitiesForApp(id);
+        invalidateRuntimeIdentity(id);
         writeAppManagerWarnings(warnings);
         return;
     }
@@ -2179,11 +2512,12 @@ export async function uninstallApp(id, options = {}) {
                 cleanupArtifacts(cleanupList);
             }
         }
-        unregisterCapabilities(id);
-        const deleteResult = await legacyInstanceManager.deleteInstance(id);
+        const deleteResult = await instanceServices.deleteInstance(id);
         if (!deleteResult.ok && deleteResult.warnings?.length) {
             warnings.push(...deleteResult.warnings);
         }
+        await syncCapabilitiesForApp(id);
+        invalidateRuntimeIdentity(id);
         writeAppManagerWarnings(warnings);
         return;
     }
@@ -2211,9 +2545,10 @@ export async function uninstallApp(id, options = {}) {
             cleanupArtifacts(cleanupList);
         }
     }
-    unregisterCapabilities(id);
     const appDir = resolveAppDir(id) ?? appDirForId(id);
     rmSync(appDir, { recursive: true, force: true });
+    await syncCapabilitiesForApp(id);
+    invalidateRuntimeIdentity(id);
     writeAppManagerWarnings(warnings);
 }
 export function uninstallAppTask(id, exec) {
@@ -2227,91 +2562,42 @@ 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)
+async function runPostStartStepsAfterStart(appId, spec) {
+    if (!spec.lifecycle?.post_start?.length)
         return;
-    const now = new Date().toISOString();
-    const appName = spec.name ?? spec.id;
-    for (const provide of spec.provides) {
-        // url-only provide — out of capability registry scope (§5.1 boundary).
-        if (typeof provide.url === "string" && provide.url.trim())
-            continue;
-        let host = "127.0.0.1";
-        let hostPort;
-        if (typeof portOverride === "number" && portOverride > 0) {
-            // Legacy startup-rebuild path: server.ts already resolved the actual
-            // listening port via `instanceManager.getGatewayPort()`. Honor it for
-            // the gateway-port provide (typically `provides[0]`); other provides
-            // fall through to the spec-derived port.
-            hostPort = portOverride;
-            host = legacyInstanceManager.getAdvertisedHostForPort(portOverride);
-        }
-        if (typeof hostPort !== "number") {
-            const resolved = resolveProvideEndpoint(instanceId, spec, provide);
-            if (resolved) {
-                host = resolved.host;
-                hostPort = resolved.hostPort;
-            }
-            else {
-                const declared = getProvidePort(spec, provide);
-                if (declared == null)
-                    continue;
-                hostPort = declared;
-                host = legacyInstanceManager.getAdvertisedHostForPort(declared);
-            }
-        }
-        const protocol = resolveProvideProtocol(provide);
-        const entry = {
-            instanceId,
-            name: appName,
-            capability: provide.capability,
-            host,
-            hostPort,
-            ...(provide.path ? { path: provide.path } : {}),
-            address: buildCapabilityAddress(hostPort, provide.path),
-            protocol,
-            ...(provide.visibility ? { visibility: String(provide.visibility) } : {}),
-            status: "running",
-            lastSeenRunningAt: now,
-            registeredAt: now,
-            // §17 (PR 8) — carry MCP firewall canonical schema through so
-            // adapters can resolve it during applyConnectionEnv without
-            // reading the spec a second time.
-            ...(provide.tool_schema ? { toolSchema: provide.tool_schema } : {}),
-            // §6 (PR B) — carry auth config through so apply hooks can resolve
-            // tokens at apply/runtime time without re-reading the spec.
-            ...(provide.auth ? { auth: provide.auth } : {}),
-        };
-        capabilityRegistry.registerProvider(entry);
+    if (spec.provides?.length || spec.lifecycle.post_start.length) {
+        await waitForAppRuntimeRunning(appId, spec.lifecycle.post_start.length ? 120_000 : 30_000);
     }
+    await runPostStartSteps(spec);
 }
-/**
- * Mark an instance's providers as `stopped` (preferred for stop) or
- * remove them entirely (uninstall / delete). Defaults to remove for
- * back-compat with existing call sites; new code should prefer
- * `markCapabilitiesStopped` to keep entries visible in the Connections UI.
- */
-export function unregisterCapabilities(instanceId) {
-    capabilityRegistry.unregisterProviders(instanceId);
+export async function waitForAppRuntimeRunning(appId, timeoutMs = 30_000, pollIntervalMs = 1_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const status = await getAppRuntimeStatus(appId);
+        if (status.status === "running")
+            return true;
+        if (status.status === "dead" || status.status === "failed")
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+    return false;
 }
-export function markCapabilitiesStopped(instanceId) {
-    capabilityRegistry.setProviderStatus(instanceId, "stopped");
+export async function syncCapabilitiesForApp(appId) {
+    const { syncCapabilitiesForApp: sync } = await import("../capability-sync.js");
+    await sync(appId);
+}
+export async function refreshCapabilityRegistry(options = {}) {
+    const { refreshCapabilityRegistry: refresh } = await import("../capability-sync.js");
+    await refresh(options);
 }
 export function resolveRequires(spec) {
     if (!spec.requires || spec.requires.length === 0)
         return {};
     const result = {};
     for (const req of spec.requires) {
-        const entry = capabilityRegistry.getCapabilityEntry(req.capability);
+        const entry = capabilityRegistry
+            .listProviders(req.capability)
+            .find((provider) => provider.status === "running");
         if (entry) {
             result[req.inject_as] = entry.address;
         }
@@ -2380,12 +2666,8 @@ async function startAppImpl(appId) {
         const result = await startNomadJobInstance(appId);
         if (!result.ok)
             return result;
-        if (appData.spec.provides?.length) {
-            registerCapabilities(appId, appData.spec);
-        }
-        if (appData.spec.lifecycle?.post_start?.length) {
-            await runPostStartSteps(appData.spec);
-        }
+        await runPostStartStepsAfterStart(appId, appData.spec);
+        await syncCapabilitiesForApp(appId);
         return result;
     }
     // Resolve requires through the v3 connection-resolver in runtime mode so
@@ -2398,6 +2680,7 @@ async function startAppImpl(appId) {
     const persistedEnv = loadConnectionsEnv(appId);
     let extraEnv = {};
     try {
+        await refreshCapabilityRegistry();
         const { resolveConnections, resolvedToLegacyEnv } = await import("../connection-resolver.js");
         const { renderRuntimeConnectionsEnv } = await import("../connection-apply.js");
         const { resolved } = resolveConnections(appData.spec, { connections: instJson?.connections ?? {} }, "runtime");
@@ -2418,7 +2701,7 @@ async function startAppImpl(appId) {
             ...(typeof e.statusCode === "number" ? { statusCode: e.statusCode } : {}),
         };
     }
-    const { startAppJob: nomadStart, checkDependencies, waitForRunning } = await import("../nomad-manager.js");
+    const { startAppJob: nomadStart, checkDependencies } = await import("../nomad-manager.js");
     const depCheck = await checkDependencies(appData.spec);
     if (!depCheck.ok) {
         return { ok: false, error: depCheck.errors.join("; ") };
@@ -2433,15 +2716,8 @@ async function startAppImpl(appId) {
     if (!result.ok) {
         return result;
     }
-    if (appData.spec.provides?.length) {
-        registerCapabilities(appId, appData.spec);
-    }
-    if (appData.spec.lifecycle?.post_start?.length) {
-        const running = await waitForRunning(appId);
-        if (running) {
-            await runPostStartSteps(appData.spec);
-        }
-    }
+    await runPostStartStepsAfterStart(appId, appData.spec);
+    await syncCapabilitiesForApp(appId);
     return result;
 }
 export function startAppTask(appId) {
@@ -2467,22 +2743,14 @@ async function stopAppImpl(appId, purge) {
         const { stopNomadJobInstance } = await import("../nomad-manager.js");
         const result = await stopNomadJobInstance(appId, purge);
         if (result.ok || result.error?.includes("not running") || result.error?.includes("not found")) {
-            // Stop = mark stopped (keep entry visible in Connections UI as a
-            // greyed candidate); only purge / uninstall fully unregisters.
-            if (purge)
-                unregisterCapabilities(appId);
-            else
-                markCapabilitiesStopped(appId);
+            await syncCapabilitiesForApp(appId);
         }
         return result;
     }
     const { stopAppJob } = await import("../nomad-manager.js");
     const result = await stopAppJob(appId, purge);
     if (result.ok || result.error?.includes("not running") || result.error?.includes("not found")) {
-        if (purge)
-            unregisterCapabilities(appId);
-        else
-            markCapabilitiesStopped(appId);
+        await syncCapabilitiesForApp(appId);
     }
     return result;
 }
@@ -2512,12 +2780,10 @@ export async function restartApp(appId) {
             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);
+            if (appData) {
+                await runPostStartStepsAfterStart(appId, appData.spec);
             }
+            await syncCapabilitiesForApp(appId);
             return result;
         }
         const stopResult = await stopAppImpl(appId, true);