jishushell 0.6.5 → 0.6.18

package/dist/server.js

@@ -2,40 +2,50 @@ import Fastify from "fastify";
 import multipart from "@fastify/multipart";
 import { request as httpRequest } from "http";
 import { request as httpsRequest } from "https";
-import { ensureDirs, ensureCoreConfig, getCoreConfig, migrateCatalogSchemaIfNeeded, migrateHermesShimOutIfNeeded, migrateOpenclawImageTagIfNeeded, removeFlatOpenclawImageIfNeeded, getInternalMcpToken, } from "./config.js";
+import { ensureDirs, ensureCoreConfig, getCoreConfig, migrateIntegrationRuntimeSchemaIfNeeded, migrateHermesShimOutIfNeeded, removeFlatOpenclawImageIfNeeded, getInternalMcpToken, } from "./config.js";
 import { timingSafeEqual } from "node:crypto";
-import { runStartupMigrations } from "./services/runtime/index.js";
+import { listRegisteredIntegrations, normalizeIntegrationCoreConfigOnStartup } from "./services/integrations/index.js";
 import { verifyToken } from "./auth.js";
 import { authRoutes } from "./routes/auth.js";
 import { instanceRoutes } from "./routes/instances.js";
 import { systemRoutes } from "./routes/system.js";
 import { setupRoutes } from "./routes/setup.js";
-import { runtimeCatalogRoutes } from "./routes/runtime.js";
+import { integrationsRoutes } from "./routes/integrations.js";
 import { appRoutes } from "./routes/apps.js";
-import { agentAppRoutes } from "./routes/agent-apps.js";
+import { integrationAppRoutes } from "./routes/integration-apps.js";
 import { llmRoutes } from "./routes/llm.js";
 import { filesRoutes } from "./routes/files.js";
-import { internalRoutes } from "./routes/internal.js";
 import { organizeRoutes } from "./routes/files-organize.js";
 import { fileMountsRoutes } from "./routes/file-mounts.js";
 import { registerProxyRoutes } from "./routes/llm-proxy.js";
 import { webdavRoutes } from "./routes/webdav.js";
 import { externalMountsRoutes } from "./routes/external-mounts.js";
-import { FilesManager } from "./services/files-manager.js";
-import * as appManager from "./services/app/app-manager.js";
-import * as capabilityRegistry from "./services/capability-registry.js";
-import { getConnectHostForPort, getStoredConfig as getNativeStoredConfig, } from "./services/instance-manager.js";
+import { FilesManager } from "./services/files/files-manager.js";
+import { registerAppModuleRoutes } from "./services/app-modules/routes.js";
+import { registerIntegrationOwnedRoutes } from "./services/integrations/routes.js";
+import * as appService from "./services/app-common/service.js";
+import * as appLifecycle from "./services/app-common/lifecycle-service.js";
+import * as capabilityRegistry from "./services/capabilities/registry.js";
+import { getConnectHostForPort } from "./services/instances/manager.js";
 import backupRoutes from "./routes/backup.js";
 import * as llmProxy from "./services/llm-proxy/index.js";
-import * as nomadManager from "./services/nomad-manager.js";
-import * as instanceManager from "./services/app/app-manager.js";
-import * as setupManager from "./services/setup-manager.js";
-import { startTmpCleanupScheduler, initAutoBackup } from "./services/backup-manager.js";
-import { checkUpdate, getUpdateStatus, scheduleRestart } from "./services/update-manager.js";
-import { inspectSystemDrift, reconcileSystem } from "./services/system-reconciler.js";
+import * as nomadDriver from "./services/runtime/drivers/nomad.js";
+import * as setupManager from "./services/setup/setup-manager.js";
+import { shutdownTaskRegistry } from "./services/tasks/registry.js";
+import { startTmpCleanupScheduler, stopTmpCleanupScheduler, initAutoBackup, shutdownAutoBackup, } from "./services/backup/backup-manager.js";
+import { checkUpdate, getUpdateStatus } from "./services/system/update-manager.js";
+import { inspectSystemDrift } from "./services/system/system-reconciler.js";
 import { PROXY_IDENTITY_HEADERS } from "./constants.js";
-import { supportsGatewayWebsocket } from "./services/runtime/instance.js";
-const PUBLIC_PATHS = new Set(["/api/auth/status", "/api/auth/init", "/api/auth/login", "/api/setup/status", "/api/apps/validate-sudo-password"]);
+const PUBLIC_PATHS = new Set([
+    "/api/auth/status",
+    "/api/auth/init",
+    "/api/auth/login",
+    "/api/setup/status",
+    // Public by product decision: this only validates a one-shot sudo password
+    // before install/upgrade flows. The actual privileged operation must still
+    // receive the password in its own request or run through a sudo CLI command.
+    "/api/apps/validate-sudo-password",
+]);
 /** Slug charset for /apps/:slug — same as instance ids. */
 const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,62}$/;
 /** Regex for top-level app WebSocket upgrades (AI-FS v1 W2.5 PR-8). */
@@ -119,6 +129,45 @@ export function buildCapabilityWebSocketHeaders(headers, upstreamOrigin) {
     }
     return upstreamHeaders;
 }
+function matchIntegrationPublicProxy(path, options = {}) {
+    for (const integration of listRegisteredIntegrations()) {
+        const descriptor = integration.publicProxy;
+        if (!descriptor)
+            continue;
+        if (options.authBypass === true && descriptor.authBypass !== true)
+            continue;
+        if (options.websocket === true && descriptor.websocket !== true)
+            continue;
+        descriptor.basePathPattern.lastIndex = 0;
+        const matched = descriptor.basePathPattern.exec(path);
+        if (!matched)
+            continue;
+        return {
+            integration,
+            match: {
+                instanceId: matched[1] ?? "",
+                suffix: matched[2] ?? "",
+            },
+        };
+    }
+    return null;
+}
+function buildPublicProxyWebSocketHeaders(headers, descriptorHeaders) {
+    const upstreamHeaders = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (value === undefined)
+            continue;
+        const lower = key.toLowerCase();
+        if (lower === "host" ||
+            lower === "cookie" ||
+            lower === "authorization" ||
+            PROXY_IDENTITY_HEADERS.has(lower)) {
+            continue;
+        }
+        upstreamHeaders[key] = value;
+    }
+    return { ...upstreamHeaders, ...descriptorHeaders };
+}
 function forwardWebSocketRejection(socket, res) {
     const statusCode = res.statusCode || 502;
     const statusMessage = res.statusMessage || "Bad Gateway";
@@ -140,9 +189,54 @@ export function selectRefererWebSocketCapability(capabilities, refererCapability
         ?? matches.find((capability) => capability.capability === refererCapability)
         ?? null;
 }
+async function convergeInstanceDesiredStateOnBoot() {
+    for (const inst of appService.listInstances()) {
+        const instanceId = typeof inst?.id === "string" ? inst.id : "";
+        if (!instanceId)
+            continue;
+        const desiredState = inst.desiredState;
+        if (desiredState !== "running" && desiredState !== "stopped") {
+            console.warn(`[startup] Skipping ${instanceId}: invalid desiredState '${String(desiredState)}'`);
+            continue;
+        }
+        try {
+            const status = await appService.getInstanceInstallRecordStatus(instanceId);
+            const actualStatus = String(status?.status ?? "unknown");
+            if (desiredState === "running") {
+                if (actualStatus === "running" || actualStatus === "pending" || actualStatus === "installing") {
+                    continue;
+                }
+                if (actualStatus === "unknown") {
+                    console.warn(`[startup] Skipping start convergence for ${instanceId}: runtime status unknown`);
+                    continue;
+                }
+                console.log(`[startup] Starting ${instanceId} from Core desiredState=running (actual=${actualStatus})...`);
+                const result = await appLifecycle.startInstance(instanceId);
+                if (!result.ok) {
+                    console.warn(`[startup] Start convergence failed for ${instanceId}: ${result.error ?? "unknown error"}`);
+                }
+                continue;
+            }
+            if (actualStatus === "running" || actualStatus === "pending") {
+                console.log(`[startup] Stopping ${instanceId} from Core desiredState=stopped (actual=${actualStatus})...`);
+                const result = await appLifecycle.stopInstance(instanceId);
+                if (!result.ok) {
+                    console.warn(`[startup] Stop convergence failed for ${instanceId}: ${result.error ?? "unknown error"}`);
+                }
+            }
+        }
+        catch (error) {
+            console.warn(`[startup] Desired-state convergence skipped for ${instanceId}: ${error?.message ?? error}`);
+        }
+    }
+}
 export async function createServer(options = {}) {
     const port = options.port ?? 8091;
     const host = options.host || "0.0.0.0";
+    let startupTimer = null;
+    let delayedSystemDriftTimer = null;
+    let backgroundUpdateInitial = null;
+    let backgroundUpdateInterval = null;
     ensureDirs();
     startTmpCleanupScheduler();
     initAutoBackup().catch((e) => console.error("[auto-backup] Init error:", e.message));
@@ -152,6 +246,19 @@ export async function createServer(options = {}) {
         logger: true,
         bodyLimit: 1048576,
     });
+    app.addHook("onClose", async () => {
+        if (startupTimer)
+            clearTimeout(startupTimer);
+        if (delayedSystemDriftTimer)
+            clearTimeout(delayedSystemDriftTimer);
+        if (backgroundUpdateInitial)
+            clearTimeout(backgroundUpdateInitial);
+        if (backgroundUpdateInterval)
+            clearInterval(backgroundUpdateInterval);
+        shutdownTaskRegistry();
+        stopTmpCleanupScheduler();
+        shutdownAutoBackup();
+    });
     // Allow empty JSON body for POST requests
     app.addContentTypeParser("application/json", { parseAs: "string" }, (_req, body, done) => {
         if (!body || body.length === 0) {
@@ -182,7 +289,7 @@ export async function createServer(options = {}) {
     // any agent container starts and tries to read it via env injection.
     // Lazy-init would only fire on the first request that carries an
     // X-Jishushell-Internal-Token header, which is too late for the
-    // adapter onBeforeStart that mounts the value into the container.
+    // integration onBeforeStart hook that mounts the value into the container.
     try {
         getInternalMcpToken();
     }
@@ -190,7 +297,7 @@ export async function createServer(options = {}) {
         console.warn(`[server] internal MCP token init skipped: ${e?.message ?? e}`);
     }
     // ── Auth middleware for /apps/* (AI-FS v1 W2.5 PR-8) ──────────────────
-    // Top-level reverse proxy for installed apps. Added in AI-FS v1 W2.5 PR-8.
+    // Top-level reverse proxy for instance UI capabilities.
     // Pairs with `/api/instances/:id/provides/:cap/*` which is instance-scoped.
     // This hook is scoped to /apps/* only so it does not double-fire with the
     // existing /api/* hook below.
@@ -215,41 +322,32 @@ export async function createServer(options = {}) {
         const path = request.url.split("?")[0];
         if (!path.startsWith("/api/") || PUBLIC_PATHS.has(path))
             return;
-        // Allow gateway proxy without panel auth (gateway has its own auth),
-        // but verify the instance actually exists to prevent probing.
-        if (/^\/api\/instances\/[^/]+\/gateway(\/|$)/.test(path)) {
-            const id = path.match(/^\/api\/instances\/([^/]+)\/gateway/)?.[1];
-            if (!id || !instanceManager.getInstance(id)) {
+        // Allow integration-owned public proxies without panel auth when the
+        // integration declares its own upstream auth, but verify the instance
+        // actually exists to prevent probing.
+        const publicProxy = matchIntegrationPublicProxy(path, { authBypass: true });
+        if (publicProxy) {
+            const id = publicProxy.match.instanceId;
+            if (!id || !appService.getInstance(id)) {
                 return reply.status(404).send({ detail: "Instance not found" });
             }
             return;
         }
-        // Internal token path — used by:
-        //   (a) MCP shims spawned inside agent containers
-        //       (need BOTH X-Jishushell-Internal-Token + X-Jishushell-Instance)
-        //   (b) Panel app lifecycle scripts (post_start, etc.) calling back into
-        //       /api/internal/* on the same host
-        //       (need ONLY X-Jishushell-Internal-Token; no instance binding —
-        //        apps aren't instances)
-        // Combined with the standard JWT path below; we never require both.
+        // Internal token path — used by MCP/runtime shims spawned inside managed
+        // instances. These callers must present BOTH
+        // X-Jishushell-Internal-Token + X-Jishushell-Instance so Core can bind
+        // the request to a canonical instance. Combined with the standard JWT
+        // path below; we never require both.
         const internalToken = request.headers["x-jishushell-internal-token"];
         if (typeof internalToken === "string" && internalToken.length >= 32) {
             const expected = getInternalMcpToken();
             if (internalToken.length === expected.length &&
                 timingSafeEqual(Buffer.from(internalToken), Buffer.from(expected))) {
                 const instanceId = request.headers["x-jishushell-instance"];
-                if (typeof instanceId === "string" && instanceManager.getInstance(instanceId)) {
+                if (typeof instanceId === "string" && appService.getInstance(instanceId)) {
                     request.internalCallerInstance = instanceId;
                     return;
                 }
-                // Path (b): app-lifecycle / internal-only routes. Allowed without
-                // an instance header. The route is responsible for asserting the
-                // (request as any).internalCallerScope === "panel" tag before
-                // returning sensitive data.
-                if (path.startsWith("/api/internal/")) {
-                    request.internalCallerScope = "panel";
-                    return;
-                }
             }
             return reply.status(401).send({ detail: "Unauthorized" });
         }
@@ -290,12 +388,13 @@ export async function createServer(options = {}) {
     await app.register(instanceRoutes);
     await app.register(systemRoutes);
     await app.register(setupRoutes);
-    await app.register(runtimeCatalogRoutes);
+    await app.register(integrationsRoutes);
     await app.register(appRoutes);
-    await app.register(agentAppRoutes);
+    await app.register(integrationAppRoutes);
+    registerAppModuleRoutes(app);
+    await registerIntegrationOwnedRoutes(app);
     await app.register(llmRoutes);
     await app.register(backupRoutes);
-    await app.register(internalRoutes);
     // Single FilesManager instance shared across /api/files, /webdav, and
     // /api/files/external-mounts so a mutation on the mount list (PUT
     // /external-mounts) is visible to every layer immediately.
@@ -322,7 +421,7 @@ export async function createServer(options = {}) {
         await webdavRoutes(scope, { filesManager: sharedFilesManager });
     });
     // ── Top-level /apps/:slug/* reverse proxy (AI-FS v1 W2.5 PR-8) ───────────
-    // Reverse-proxies HTTP requests for installed apps to their capability
+    // Reverse-proxies HTTP requests for instance UI capabilities to their
     // upstream. Auth is handled by the onRequest hook above. The /apps/:slug
     // prefix is NOT stripped — apps like Filebrowser are configured with
     // --baseURL=/apps/filebrowser and expect the full path.
@@ -344,7 +443,7 @@ export async function createServer(options = {}) {
         // Pass the full original path unchanged (including /apps/<slug> prefix).
         const rawUrl = req.raw.url ?? "/";
         const targetPath = rawUrl;
-        const hostHeader = `${instanceManager.urlHost(upstreamHost)}:${upstreamPort}`;
+        const hostHeader = `${appService.urlHost(upstreamHost)}:${upstreamPort}`;
         // Build forwarded headers: strip cookie and authorization to avoid
         // leaking panel session credentials to third-party apps.
         const forwardHeaders = {};
@@ -413,62 +512,79 @@ export async function createServer(options = {}) {
     app.all("/apps/:slug/*", appsProxyHandler);
     // Auto-start Nomad-managed instances on startup
     app.addHook("onReady", async () => {
-        setTimeout(async () => {
+        startupTimer = setTimeout(async () => {
+            startupTimer = null;
             try {
+                if (process.env.JISHUSHELL_SKIP_STARTUP_MAINTENANCE === "1") {
+                    console.log("[startup] Maintenance tasks skipped by JISHUSHELL_SKIP_STARTUP_MAINTENANCE");
+                    return;
+                }
                 ensureCoreConfig();
                 removeFlatOpenclawImageIfNeeded();
                 // One-shot: drop runtime_catalog.hermes.shimPath and delete the
                 // orphaned ~/.jishushell/runtimes/hermes/ dir. The Hermes shim is
-                // now baked into the image (PR3c) and the adapter verifies the
+                // now baked into the image (PR3c) and the integration verifies the
                 // official image RepoDigest before launch, so the host shim is dead weight.
                 migrateHermesShimOutIfNeeded();
-                // Stamp the runtime_catalog schema version so core.json carries a
-                // provenance marker. Warns (but doesn't crash) on detected core
-                // downgrade where the stored version exceeds what we support.
-                migrateCatalogSchemaIfNeeded();
-                // One-shot: if core.json still stores a mutable image tag (:latest
-                // or :slim) from an older release, rewrite it to the pinned
-                // :${version} form so Nomad stops re-pulling on each restart.
-                migrateOpenclawImageTagIfNeeded();
-                // Same one-shot for per-adapter migrations (Hermes rewrites
-                // runtime_catalog.hermes.defaultImage from `:latest` to the pinned
-                // :${LABEL org.opencontainers.image.version} form). Runs every
-                // registered adapter's migrateStartup() hook so server.ts never
-                // imports a specific adapter (check-adapter-isolation §32.2.1).
-                runStartupMigrations();
+                // Stamp the historical runtime_catalog schema version so core.json
+                // carries a provenance marker. Warns (but doesn't crash) on detected
+                // core downgrade where the stored version exceeds what we support.
+                migrateIntegrationRuntimeSchemaIfNeeded();
+                // Step 13: startup no longer runs implicit instance-schema
+                // migrations. The dedicated `jishushell migrate legacy` command
+                // owns all legacy normalisation; reconcile / doctor only touch
+                // system/runtime state.
+                // Let Integrations normalize only their Core-owned global config. For
+                // example, OpenClaw pins runtime_catalog.openclaw.defaultImage and
+                // Hermes pins runtime_catalog.hermes.defaultImage. This hook
+                // must never migrate instance directories, facts, config, or jobs.
+                if (process.env.JISHUSHELL_SKIP_STARTUP_MIGRATIONS === "1") {
+                    console.log("[startup] Integration Core config normalization skipped by JISHUSHELL_SKIP_STARTUP_MIGRATIONS");
+                }
+                else {
+                    normalizeIntegrationCoreConfigOnStartup();
+                }
                 getUpdateStatus();
-                // Reconcile system-level components (systemd units, Docker images,
-                // Nomad config) against the currently installed code. Non-blocking:
-                // failures are logged but do not prevent server startup.
-                try {
-                    const reconcileResult = await reconcileSystem();
-                    const updated = reconcileResult.items.filter(i => i.status === "updated");
-                    const errors = reconcileResult.items.filter(i => i.status === "error");
-                    const needsSudo = reconcileResult.items.filter(i => i.requiresSudo && i.status !== "ok" && i.status !== "updated");
-                    if (updated.length > 0) {
-                        console.log(`[startup] Reconciled ${updated.length} system component(s): ${updated.map(i => i.component).join(", ")}`);
-                    }
-                    if (errors.length > 0) {
-                        console.warn(`[startup] Reconciliation errors: ${errors.map(i => `${i.component}: ${i.message}`).join("; ")}`);
-                    }
-                    if (needsSudo.length > 0) {
-                        console.warn(`[startup] ${needsSudo.length} item(s) need sudo to fix. Run: ${reconcileResult.command}`);
-                    }
-                    else if (reconcileResult.reloadRequired) {
-                        console.warn(`[startup] System files changed and services should be reloaded. Run: ${reconcileResult.command}`);
-                        scheduleRestart(2000);
+                // Inspect system-level drift (systemd units, Docker images, Nomad
+                // config) against the currently installed code. Startup is an
+                // observation point only: applying host-level fixes, sudo, reload, or
+                // service restarts must happen through explicit Panel/CLI reconcile
+                // actions after user confirmation.
+                if (process.env.JISHUSHELL_SKIP_STARTUP_RECONCILE === "1") {
+                    console.log("[startup] System drift inspection skipped by JISHUSHELL_SKIP_STARTUP_RECONCILE");
+                }
+                else {
+                    try {
+                        const reconcileResult = await inspectSystemDrift();
+                        const updated = reconcileResult.items.filter(i => i.status === "updated");
+                        const errors = reconcileResult.items.filter(i => i.status === "error");
+                        const needsSudo = reconcileResult.items.filter(i => i.requiresSudo && i.status !== "ok" && i.status !== "updated");
+                        if (updated.length > 0) {
+                            console.warn(`[startup] Unexpected system drift inspection update(s): ${updated.map(i => i.component).join(", ")}`);
+                        }
+                        if (errors.length > 0) {
+                            console.warn(`[startup] System drift inspection errors: ${errors.map(i => `${i.component}: ${i.message}`).join("; ")}`);
+                        }
+                        if (needsSudo.length > 0) {
+                            console.warn(`[startup] ${needsSudo.length} item(s) need sudo to fix. Run: ${reconcileResult.command}`);
+                        }
+                        else if (reconcileResult.reloadRequired) {
+                            console.warn(`[startup] System files changed and services should be reloaded. Run: ${reconcileResult.command}`);
+                        }
+                        if (errors.length > 0 || reconcileResult.reloadRequired) {
+                            delayedSystemDriftTimer = setTimeout(() => {
+                                delayedSystemDriftTimer = null;
+                                inspectSystemDrift().catch((e) => {
+                                    console.warn(`[startup] Delayed system reconciliation check skipped: ${e.message}`);
+                                });
+                            }, 15_000);
+                            delayedSystemDriftTimer.unref();
+                        }
                     }
-                    if (errors.length > 0 || reconcileResult.reloadRequired) {
-                        setTimeout(() => {
-                            inspectSystemDrift().catch((e) => {
-                                console.warn(`[startup] Delayed system reconciliation check skipped: ${e.message}`);
-                            });
-                        }, 15_000).unref();
+                    catch (e) {
+                        console.warn(`[startup] System drift inspection skipped: ${e.message}`);
                     }
                 }
-                catch (e) {
-                    console.warn(`[startup] System reconciliation skipped: ${e.message}`);
-                }
                 const config = getCoreConfig();
                 if (config.service_manager === "nomad") {
                     const nomadResult = await setupManager.startNomad();
@@ -477,51 +593,30 @@ export async function createServer(options = {}) {
                     }
                     else {
                         console.log(`[startup] Nomad: ${nomadResult.message}`);
-                    }
-                    // Auto-start stopped instances that were running before jishushell was restarted.
-                    // Running instances are left alone — no forced restart to avoid unnecessary disruption.
-                    try {
-                        for (const inst of instanceManager.listInstances()) {
-                            if (!inst.id)
-                                continue;
-                            const status = await nomadManager.getStatus(inst.id);
-                            if (status.status === "running") {
-                                continue;
-                            }
-                            else if (status.status === "pending" || status.status === "stopped") {
-                                const shouldStart = await nomadManager.shouldAutoStart(inst.id);
-                                if (shouldStart) {
-                                    console.log(`[startup] Auto-starting Nomad instance ${inst.id} (was running before restart)...`);
-                                    await nomadManager.startInstance(inst.id);
-                                }
-                            }
+                        try {
+                            await convergeInstanceDesiredStateOnBoot();
+                            console.log("[startup] Desired-state convergence completed.");
+                        }
+                        catch (e) {
+                            console.error("[startup] Desired-state convergence failed:", e);
                         }
-                        console.log("[startup] Nomad instances started/restarted.");
                     }
-                    catch (e) {
-                        console.error("[startup] Nomad restart failed:", e);
+                    // Retry Core config normalization after workload convergence because
+                    // a newly available local image may now provide a pinnable version.
+                    // This still must not mutate any instance-owned state.
+                    if (process.env.JISHUSHELL_SKIP_STARTUP_MIGRATIONS === "1") {
+                        console.log("[startup] Integration Core config normalization skipped by JISHUSHELL_SKIP_STARTUP_MIGRATIONS");
                     }
-                    // Second migration attempt: the first call above runs before Nomad
-                    // auto-starts instances, so for 0.4.2-beta2 upgrades the image is
-                    // not yet locally present then. After auto-start (which may have
-                    // triggered the one-time pull), retry the pin so core.json moves
-                    // from :latest → :${version} within the same startup cycle.
-                    try {
-                        migrateOpenclawImageTagIfNeeded();
-                    }
-                    catch (e) {
-                        console.warn("[startup] openclaw image tag migration skipped:", e);
+                    else {
+                        normalizeIntegrationCoreConfigOnStartup();
                     }
-                    // Second adapter-migration sweep — after Nomad auto-start the
-                    // runtime images may finally be locally present so `:latest` →
-                    // pinned digest tag rewrite can now succeed.
-                    runStartupMigrations();
                 }
-                // Rebuild capability registry from app instances. For instances whose
-                // underlying job is currently not running, entries stay visible in the
-                // Connections UI as greyed candidates (§5.4 of the design).
+                // Authoritative boot-time capability-registry rebuild. This
+                // populates reverse-proxy and connection routes immediately after
+                // Core restart. After boot, registry updates are event-driven through
+                // lifecycle/API status observations and uninstall cleanup.
                 try {
-                    await appManager.refreshCapabilityRegistry({ force: true });
+                    await appService.refreshCapabilityRegistry({ force: true });
                 }
                 catch (e) {
                     console.error("[startup] Capability registry rebuild failed:", e);
@@ -533,12 +628,15 @@ export async function createServer(options = {}) {
         }, 0);
     });
     await app.listen({ port, host });
+    const address = app.server.address();
+    const actualPort = typeof address === "object" && address !== null
+        ? address.port
+        : port;
     // Track active WebSocket proxy sockets for graceful shutdown
     const activeWsSockets = new Set();
     // Handle WebSocket upgrades directly on the HTTP server, bypassing Fastify's
     // request lifecycle. Fastify's internal headersTimeout (73s) kills hijacked
     // sockets, so we intercept upgrades before Fastify sees them.
-    const GATEWAY_WS_RE = /^\/api\/instances\/([a-z0-9][a-z0-9-]{0,62})\/gateway(?:\/(.*))?$/;
     const CAPABILITY_WS_RE = /^\/api\/instances\/([a-z0-9][a-z0-9-]{0,62})\/provides\/([^/?]+)(?:\/(.*))?$/;
     // Match Referer pointing at a capability proxy page (used to resolve
     // root-level WS upgrades initiated by embedded pages like Browserless debugger
@@ -547,12 +645,12 @@ export async function createServer(options = {}) {
     app.server.on("upgrade", async (req, socket, head) => {
         const url = req.url || "";
         const path = url.split("?")[0];
-        const gatewayMatch = path.match(GATEWAY_WS_RE);
+        const publicProxyMatch = matchIntegrationPublicProxy(path, { websocket: true });
         const capabilityMatch = path.match(CAPABILITY_WS_RE);
         // ── /apps/:slug/* WebSocket upgrade (AI-FS v1 W2.5 PR-8) ──────────────
-        // Proxy WS upgrades for top-level installed apps. Same auth gate as HTTP.
+        // Proxy WS upgrades for top-level instance UI capabilities. Same auth gate as HTTP.
         const appSlugWsMatch = path.match(APP_SLUG_WS_RE);
-        if (appSlugWsMatch && !gatewayMatch && !capabilityMatch) {
+        if (appSlugWsMatch && !publicProxyMatch && !capabilityMatch) {
             const slug = appSlugWsMatch[1];
             // Auth gate: same JWT cookie/bearer check as the HTTP handler above.
             if (!hasValidPanelUpgradeToken(req)) {
@@ -567,7 +665,7 @@ export async function createServer(options = {}) {
                 return;
             }
             const { host: upstreamHost, port: upstreamPort } = upstream;
-            const hostHeader = `${instanceManager.urlHost(upstreamHost)}:${upstreamPort}`;
+            const hostHeader = `${appService.urlHost(upstreamHost)}:${upstreamPort}`;
             const upstreamOrigin = `http://${hostHeader}`;
             const qs = url.includes("?") ? url.slice(url.indexOf("?")) : "";
             const targetPath = `${path}${qs}`;
@@ -677,7 +775,7 @@ export async function createServer(options = {}) {
         // resolve the target instance via the Referer header pointing at the
         // capability proxy page that served the embedded UI.
         let refererCapabilityMatch = null;
-        if (!gatewayMatch && !capabilityMatch) {
+        if (!publicProxyMatch && !capabilityMatch) {
             const referer = req.headers.referer || "";
             try {
                 const refUrl = new URL(referer, "http://localhost");
@@ -688,8 +786,8 @@ export async function createServer(options = {}) {
             }
             catch { /* ignore malformed referer */ }
         }
-        if (!gatewayMatch && !capabilityMatch && !refererCapabilityMatch) {
-            // Not a gateway WebSocket — let it drop (Fastify doesn't handle WS natively)
+        if (!publicProxyMatch && !capabilityMatch && !refererCapabilityMatch) {
+            // Not a handled WebSocket — let it drop (Fastify doesn't handle WS natively)
             socket.destroy();
             return;
         }
@@ -729,17 +827,17 @@ export async function createServer(options = {}) {
         // instance that serves the request path (e.g. path "/" with http protocol).
         if (refererCapabilityMatch) {
             const id = refererCapabilityMatch.instanceId;
-            const appData = instanceManager.getApp(id);
+            const appData = appService.getInstanceInstallRecord(id);
             if (!appData) {
                 socket.destroy();
                 return;
             }
-            const capabilities = instanceManager.getProvidedCapabilitiesForApp(id);
+            const capabilities = appService.getProvidedCapabilitiesForApp(id);
             // Find a capability whose path prefix matches the WS request path.
             // Prefer capabilities with path "/" (root API) that aren't the debugger UI itself.
             const wsPath = path || "/";
             const capability = selectRefererWebSocketCapability(capabilities, refererCapabilityMatch.capability, wsPath);
-            if (!capability || typeof capability.port !== "number" || capability.port < 1) {
+            if (!capability) {
                 try {
                     socket.write("HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n");
                 }
@@ -754,9 +852,24 @@ export async function createServer(options = {}) {
             // port (e.g. 18789) when the static port is taken at start-time. The
             // HTTP capability proxy already does this; the WS proxy must mirror it
             // or every WS upgrade for reallocated apps lands on a dead host port.
-            const runtimePort = instanceManager.resolveRuntimeCapabilityPort(id, capability.capability) ?? capability.port;
-            const targetHost = await instanceManager.getHostForAppPort(id, runtimePort);
-            const hostHeader = `${instanceManager.urlHost(targetHost)}:${runtimePort}`;
+            let runtimePort = null;
+            try {
+                runtimePort = appService.resolveRuntimeCapabilityPort(id, capability.capability);
+            }
+            catch (error) {
+                if (!appService.isCanonicalRuntimePortRequiredError(error))
+                    throw error;
+                socket.write("HTTP/1.1 409 Conflict\r\nConnection: close\r\n\r\n");
+                socket.destroy();
+                return;
+            }
+            if (typeof runtimePort !== "number" || runtimePort < 1) {
+                socket.write("HTTP/1.1 409 Conflict\r\nConnection: close\r\n\r\n");
+                socket.destroy();
+                return;
+            }
+            const targetHost = await appService.getHostForAppPort(id, runtimePort);
+            const hostHeader = `${appService.urlHost(targetHost)}:${runtimePort}`;
             const upstreamOrigin = `${protocol === "https" || protocol === "wss" ? "https" : "http"}://${hostHeader}`;
             const qs = url.includes("?") ? url.slice(url.indexOf("?")) : "";
             const targetPath = `${joinCapabilityUpstreamPath(capability.path, path.replace(/^\/+/, ""))}${qs}`;
@@ -862,12 +975,12 @@ export async function createServer(options = {}) {
         if (capabilityMatch) {
             const id = capabilityMatch[1];
             const capabilityName = decodeURIComponent(capabilityMatch[2] || "");
-            const appData = instanceManager.getApp(id);
+            const appData = appService.getInstanceInstallRecord(id);
             if (!appData) {
                 socket.destroy();
                 return;
             }
-            const capability = instanceManager.getProvidedCapabilitiesForApp(id).find((entry) => entry.capability === capabilityName);
+            const capability = appService.getProvidedCapabilitiesForApp(id).find((entry) => entry.capability === capabilityName);
             if (!capability || capability.visibility === "internal") {
                 try {
                     socket.write("HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n");
@@ -876,19 +989,26 @@ export async function createServer(options = {}) {
                 socket.destroy();
                 return;
             }
-            if (typeof capability.port !== "number" || capability.port < 1) {
-                try {
-                    socket.write("HTTP/1.1 500 Internal Server Error\r\nConnection: close\r\n\r\n");
-                }
-                catch { }
+            const protocol = String(capability.protocol || "http").toLowerCase();
+            const upstreamRequest = protocol === "https" || protocol === "wss" ? httpsRequest : httpRequest;
+            let runtimePort = null;
+            try {
+                runtimePort = appService.resolveRuntimeCapabilityPort(id, capabilityName);
+            }
+            catch (error) {
+                if (!appService.isCanonicalRuntimePortRequiredError(error))
+                    throw error;
+                socket.write("HTTP/1.1 409 Conflict\r\nConnection: close\r\n\r\n");
                 socket.destroy();
                 return;
             }
-            const protocol = String(capability.protocol || "http").toLowerCase();
-            const upstreamRequest = protocol === "https" || protocol === "wss" ? httpsRequest : httpRequest;
-            const runtimePort = instanceManager.resolveRuntimeCapabilityPort(id, capabilityName) ?? capability.port;
-            const targetHost = await instanceManager.getHostForAppPort(id, runtimePort);
-            const hostHeader = `${instanceManager.urlHost(targetHost)}:${runtimePort}`;
+            if (typeof runtimePort !== "number" || runtimePort < 1) {
+                socket.write("HTTP/1.1 409 Conflict\r\nConnection: close\r\n\r\n");
+                socket.destroy();
+                return;
+            }
+            const targetHost = await appService.getHostForAppPort(id, runtimePort);
+            const hostHeader = `${appService.urlHost(targetHost)}:${runtimePort}`;
             const upstreamOrigin = `${protocol === "https" || protocol === "wss" ? "https" : "http"}://${hostHeader}`;
             const suffix = capabilityMatch[3] || "";
             const qs = url.includes("?") ? url.slice(url.indexOf("?")) : "";
@@ -994,67 +1114,47 @@ export async function createServer(options = {}) {
             proxyReq.end();
             return;
         }
-        const match = gatewayMatch;
-        const id = match[1];
-        const inst = instanceManager.getInstance(id);
+        const publicProxy = publicProxyMatch;
+        const id = publicProxy.match.instanceId;
+        const inst = appService.getInstance(id);
         if (!inst) {
             socket.destroy();
             return;
         }
-        if (!(await supportsGatewayWebsocket(id, inst))) {
-            try {
-                socket.write("HTTP/1.1 501 Not Implemented\r\nConnection: close\r\n\r\n");
+        const qs = url.includes("?") ? url.slice(url.indexOf("?")) : "";
+        const descriptor = publicProxy.integration.publicProxy;
+        let target;
+        try {
+            target = await descriptor.resolveTarget({ match: publicProxy.match, query: qs });
+        }
+        catch (error) {
+            if (appService.isCanonicalRuntimePortRequiredError(error)) {
+                socket.write("HTTP/1.1 409 Conflict\r\nConnection: close\r\n\r\n");
+                socket.destroy();
+                return;
             }
-            catch { }
-            socket.destroy();
-            return;
+            throw error;
         }
-        const gwPort = instanceManager.getGatewayPort(id);
-        const gwHost = await instanceManager.getGatewayHost(id);
         // Bracket IPv6 literals for Host-header use. Node's http.request accepts
         // a bare `::1` in `hostname`, but the `host` header field is a URL-style
         // `<host>:<port>` where v6 must be bracketed.
-        const hostHeader = `${instanceManager.urlHost(gwHost)}:${gwPort}`;
-        const suffix = match[2] || "";
-        const qs = url.includes("?") ? url.slice(url.indexOf("?")) : "";
-        const targetPath = `/${suffix}${qs}`;
-        const upstreamHeaders = {};
-        for (const [key, value] of Object.entries(req.headers)) {
-            if (value === undefined)
-                continue;
-            const lower = key.toLowerCase();
-            if (lower === "host" ||
-                PROXY_IDENTITY_HEADERS.has(lower) ||
-                // Strip panel auth credentials — do not leak to downstream OpenClaw gateway
-                lower === "cookie" ||
-                lower === "authorization")
-                continue;
-            upstreamHeaders[key] = value;
-        }
-        try {
-            const cfg = getNativeStoredConfig(id);
-            const token = cfg?.gateway?.auth?.token;
-            if (typeof token === "string" && token.trim()) {
-                upstreamHeaders["authorization"] = `Bearer ${token.trim()}`;
-            }
-        }
-        catch {
-            // Best effort: if the config is unavailable, OpenClaw will reject the
-            // upgrade with its normal auth error.
-        }
-        // Forward the browser's Origin unchanged. The panel auto-adds it to
-        // `gateway.controlUi.allowedOrigins` via ensureControlUiAllowedOrigin
-        // + restart; rewriting to the upstream host (as cli 94163bc did)
-        // breaks that allowlist match.
+        const hostHeader = `${appService.urlHost(target.host)}:${target.port}`;
+        const targetPath = target.path;
+        const descriptorHeaders = descriptor.buildHeaders?.({
+            match: publicProxy.match,
+            incomingHeaders: req.headers,
+        }) ?? {};
+        const upstreamHeaders = buildPublicProxyWebSocketHeaders(req.headers, descriptorHeaders);
+        const upstreamRequest = target.protocol === "https" ? httpsRequest : httpRequest;
         // Prevent any HTTP-level timeouts from killing this long-lived connection
         socket.setTimeout?.(0);
         socket.setNoDelay?.(true);
         socket.setKeepAlive?.(true, 30000);
         let proxyReq;
         try {
-            proxyReq = httpRequest({
-                hostname: gwHost,
-                port: gwPort,
+            proxyReq = upstreamRequest({
+                hostname: target.host,
+                port: target.port,
                 path: targetPath,
                 method: "GET",
                 timeout: 10000, // 10s timeout for upstream upgrade handshake
@@ -1096,7 +1196,7 @@ export async function createServer(options = {}) {
             if (proxyHead.length > 0)
                 socket.write(proxyHead);
             // Bidirectional pipe: forward all WebSocket frames without interception.
-            // OpenClaw manages its own upgrades inside the container.
+            // The upstream integration manages its own WebSocket protocol.
             proxySocket.pipe(socket);
             socket.pipe(proxySocket);
             proxySocket.resume();
@@ -1149,23 +1249,25 @@ export async function createServer(options = {}) {
         });
         proxyReq.end();
     });
-    llmProxy.setCorePort(port);
-    setupManager.setServerPort(port);
-    nomadManager.setCorePort(port);
-    console.log(`JishuShell listening on http://${host}:${port}`);
+    llmProxy.setCorePort(actualPort);
+    setupManager.setServerPort(actualPort);
+    nomadDriver.setCorePort(actualPort);
+    console.log(`JishuShell listening on http://${host}:${actualPort}`);
     // Background update check — runs the update probe (which probes the npm registry
     // for new versions) so headless deployments can detect available updates.
     // Safe by design: checkUpdate swallows all errors and has a 30s in-memory cache.
     const bgUpdateCheck = () => { checkUpdate().catch(() => { }); };
-    const bgInitial = setTimeout(bgUpdateCheck, 30_000);
-    const bgInterval = setInterval(bgUpdateCheck, 4 * 60 * 60 * 1000);
-    bgInitial.unref();
-    bgInterval.unref();
+    backgroundUpdateInitial = setTimeout(bgUpdateCheck, 30_000);
+    backgroundUpdateInterval = setInterval(bgUpdateCheck, 4 * 60 * 60 * 1000);
+    backgroundUpdateInitial.unref();
+    backgroundUpdateInterval.unref();
     // Graceful shutdown — let in-flight requests finish before exiting
     const shutdown = async () => {
         console.log("[server] Shutting down gracefully...");
-        clearTimeout(bgInitial);
-        clearInterval(bgInterval);
+        if (backgroundUpdateInitial)
+            clearTimeout(backgroundUpdateInitial);
+        if (backgroundUpdateInterval)
+            clearInterval(backgroundUpdateInterval);
         llmProxy.flushUsage();
         // Destroy all active WebSocket proxy connections
         for (const s of activeWsSockets) {