jishushell 0.5.22 → 0.6.18

package/dist/routes/instances.js

@@ -1,17 +1,25 @@
 import { getServiceManagerType } from "../config.js";
-import { assertNotLocked } from "../services/backup-manager.js";
-import * as instanceManager from "../services/app/app-manager.js";
-import * as llmProxy from "../services/llm-proxy/index.js";
-import { loadRemoteAppSpecYaml } from "../services/app/remote-spec.js";
-import { augmentInstanceMetadata, getInstanceCapabilities, getInstanceConfigMeta, resolveAgentType, } from "../services/runtime/instance.js";
-import { getAdapter, hasAdapter, listRegisteredAdapters } from "../services/runtime/index.js";
-import { normalizeInstanceId } from "../services/app/id-normalizer.js";
-import { assertTerminalSessionOwner, getTerminalSession, getTerminalSessionEvents, sendTerminalSessionInput, startTerminalSession, stopTerminalSession, subscribeTerminalSession, } from "../services/app/terminal-session-manager.js";
-import { TtlMap } from "../utils/ttl-cache.js";
+import { assertNotLocked } from "../services/backup/backup-manager.js";
+import * as appService from "../services/app-common/service.js";
+import * as appLifecycle from "../services/app-common/lifecycle-service.js";
+import { cleanupInstance as cleanupProxyInstance, getLastProxyError, invalidateConfigCache, } from "../services/llm-proxy/instance-proxy.js";
+import { createInstance, isInstanceAdminError, validateId, } from "../services/instances/admin.js";
+import { cloneInstance, isInstanceCloneError } from "../services/instances/clone.js";
+import { getConnectionStatus, getConnectionSummary, isConnectionAdminError, replaceConnections, } from "../services/connections/admin.js";
+import { getAppConfigMeta, isAppConfigAdminError, readAppConfig, writeAppConfig, } from "../services/instances/config-admin.js";
+import { augmentInstanceMetadata, getInstanceCapabilities, resolvePrimaryIntegrationKind, } from "../services/runtime/instance.js";
+import { getIntegration, hasIntegration } from "../services/integrations/index.js";
+import { invalidateExecutionOwner } from "../services/app-common/execution-owner.js";
+import { markRuntimeRepairRestartApplied } from "../services/repair/runtime-repair.js";
+import { getCapabilityHtmlRewriter } from "../services/capability-proxy/html-rewriters/index.js";
+import { createHash } from "node:crypto";
+import { assertTerminalSessionOwner, getTerminalSession, getTerminalSessionEvents, sendTerminalSessionInput, startTerminalSession, stopTerminalSession, subscribeTerminalSession, } from "../services/app-common/terminal-session-manager.js";
+import { refreshInstanceStatus } from "../services/app-common/status-refresh.js";
 import { writeSecretFile } from "../utils/fs.js";
 import { Readable } from "node:stream";
+export { validateId };
 // Hop-by-hop headers that must not be forwarded by a proxy (RFC 2616 §13.5.1).
-// Exported for adapter-owned route modules that implement their own HTTP proxies.
+// Exported for integration-owned route modules that implement their own HTTP proxies.
 export const HOP_BY_HOP = new Set([
     "connection", "keep-alive", "proxy-authenticate", "proxy-authorization",
     "te", "trailer", "transfer-encoding", "upgrade",
@@ -73,7 +81,7 @@ function rewriteCapabilityLocation(basePath, canonicalBasePath, pathname, search
         : joinProxyPath(basePath, pathname);
     return `${rewrittenPath}${search}${hash}`;
 }
-function joinUpstreamPath(basePath, suffix) {
+export function joinUpstreamPath(basePath, suffix) {
     const normalizedBase = typeof basePath === "string" && basePath.trim()
         ? (basePath.startsWith("/") ? basePath : `/${basePath}`)
         : "/";
@@ -86,94 +94,49 @@ function shouldRewriteProxyResponse(contentType) {
     const value = (contentType ?? "").toLowerCase();
     return value.includes("text/html") || value.includes("text/css");
 }
-function browserlessDebuggerBootstrap(instanceId) {
-    const apiProxyPath = `${capabilityProxyPath(instanceId, "browserless-api")}`;
-    const escapedPath = JSON.stringify(apiProxyPath + "/");
-    const escapedProxyBase = JSON.stringify(apiProxyPath);
-    const escapedWorkerPrelude = JSON.stringify([
-        "(function(){",
-        `var P=${escapedProxyBase};`,
-        "var _WS=self.WebSocket;",
-        "if(typeof _WS!=='function')return;",
-        "self.WebSocket=function(url,protocols){",
-        "try{var p=new URL(url,self.location.origin);",
-        "if(p.host===self.location.host&&!p.pathname.startsWith('/api/')){",
-        "var s=self.location.protocol==='https:'?'wss:':'ws:';",
-        "url=s+'//'+self.location.host+P+p.pathname+p.search;",
-        "}}catch(_e){}",
-        "return protocols!==undefined?new _WS(url,protocols):new _WS(url);",
-        "};",
-        "self.WebSocket.prototype=_WS.prototype;",
-        "self.WebSocket.CONNECTING=_WS.CONNECTING;",
-        "self.WebSocket.OPEN=_WS.OPEN;",
-        "self.WebSocket.CLOSING=_WS.CLOSING;",
-        "self.WebSocket.CLOSED=_WS.CLOSED;",
-        "})();",
-    ].join(""));
-    // 1) Set baseURL in localStorage so the debugger's HTTP API calls go through
-    //    the capability proxy.
-    // 2) Monkey-patch WebSocket in the page and any same-origin workers so that
-    //    Browserless connections targeting the panel origin (e.g.
-    //    ws://panel:8090/?launch=...) are rewritten through the capability proxy.
-    return [
-        "<script>(function(){",
-        // --- localStorage apiSettings.baseURL ---
-        // Browserless reads `state.apiSettings.baseURL` (a NESTED object); writing
-        // a flat `state.baseURL` is silently ignored, and the SPA falls back to
-        // `window.location.origin` (no proxy prefix) — producing connect URLs like
-        // `ws://panel:8090/?launch=...` that bypass the capability proxy.
-        "try{var key='browserless-debugger:'+window.location.origin+window.location.pathname;",
-        "var raw=window.localStorage.getItem(key)||'{}';",
-        "var state={};try{state=JSON.parse(raw)||{}}catch(_e){}",
-        `var base=new URL(${escapedPath},window.location.origin);`,
-        "var token=new URL(window.location.href).searchParams.get('token');",
-        "if(token)base.searchParams.set('token',token);",
-        "var settings=(state&&typeof state.apiSettings==='object'&&state.apiSettings)?state.apiSettings:{};",
-        "settings.baseURL=base.href;",
-        "state.apiSettings=settings;",
-        "window.localStorage.setItem(key,JSON.stringify(state));",
-        "}catch(_e){}",
-        // --- WebSocket monkey-patch ---
-        "var _WS=window.WebSocket;",
-        `var _base=${escapedProxyBase};`,
-        "window.WebSocket=function(url,protocols){",
-        "try{var p=new URL(url,window.location.origin);",
-        "if(p.host===window.location.host&&!p.pathname.startsWith('/api/')){",
-        "var s=window.location.protocol==='https:'?'wss:':'ws:';",
-        "url=s+'//'+window.location.host+_base+p.pathname+p.search;",
-        "}}catch(_e){}",
-        "return protocols!==undefined?new _WS(url,protocols):new _WS(url);",
-        "};",
-        "window.WebSocket.prototype=_WS.prototype;",
-        "window.WebSocket.CONNECTING=_WS.CONNECTING;",
-        "window.WebSocket.OPEN=_WS.OPEN;",
-        "window.WebSocket.CLOSING=_WS.CLOSING;",
-        "window.WebSocket.CLOSED=_WS.CLOSED;",
-        // --- Worker monkey-patch ---
-        "var _Worker=window.Worker;",
-        `var _workerPrelude=${escapedWorkerPrelude};`,
-        "function shouldWrapWorker(url){",
-        "try{var p=new URL(String(url),window.location.href);",
-        "return p.protocol==='blob:'||p.protocol==='data:'||p.origin===window.location.origin;",
-        "}catch(_e){return false;}",
-        "}",
-        "function wrapWorker(url,options){",
-        "if(typeof _Worker!=='function'||!shouldWrapWorker(url))return url;",
-        "try{var resolved=new URL(String(url),window.location.href).href;",
-        "var isModule=!!(options&&options.type==='module');",
-        "var source=isModule?_workerPrelude+'\\nimport '+JSON.stringify(resolved)+';':_workerPrelude+'\\nimportScripts('+JSON.stringify(resolved)+');';",
-        "return URL.createObjectURL(new Blob([source],{type:'text/javascript'}));",
-        "}catch(_e){return url;}",
-        "}",
-        "if(typeof _Worker==='function'){",
-        "window.Worker=function(url,options){",
-        "var wrapped=wrapWorker(url,options);",
-        "return options!==undefined?new _Worker(wrapped,options):new _Worker(wrapped);",
-        "};",
-        "window.Worker.prototype=_Worker.prototype;",
-        "}",
-        "})();</script>",
-    ].join("");
+function capabilityProxyCleanupToken(parts) {
+    const hash = createHash("sha256");
+    for (const part of parts) {
+        hash.update(part ?? "");
+        hash.update("\0");
+    }
+    return hash.digest("hex").slice(0, 32);
+}
+function hasCookieValue(cookieHeader, name, expectedValue) {
+    return cookieHeader
+        .split(";")
+        .map((part) => part.trim())
+        .some((part) => {
+        const eq = part.indexOf("=");
+        if (eq < 0)
+            return false;
+        return part.slice(0, eq) === name && part.slice(eq + 1) === expectedValue;
+    });
+}
+export async function resolveHttpCapability(instanceId, capabilityName) {
+    const capability = appService
+        .getProvidedCapabilitiesForApp(instanceId)
+        .find((entry) => entry.capability === capabilityName);
+    if (!capability)
+        throw new Error(`Capability '${capabilityName}' not found`);
+    if (capability.visibility === "internal") {
+        throw new Error(`Capability '${capabilityName}' is not externally accessible`);
+    }
+    if (capability.protocol !== "http" && capability.protocol !== "https") {
+        throw new Error(`Capability '${capabilityName}' does not use HTTP(S)`);
+    }
+    const runtimePort = appService.resolveRuntimeCapabilityPort(instanceId, capabilityName);
+    if (typeof runtimePort !== "number" || runtimePort < 1) {
+        throw new Error(`Capability '${capabilityName}' has no resolved port`);
+    }
+    const upstreamHost = await appService.getHostForAppPort(instanceId, runtimePort);
+    const proxyBase = capabilityProxyPath(instanceId, capabilityName);
+    const canonicalProxyBase = canonicalCapabilityProxyBase(proxyBase, capability.path);
+    return {
+        capability,
+        targetBaseUrl: `${capability.protocol}://${appService.urlHost(upstreamHost)}:${runtimePort}`,
+        proxyUrl: canonicalProxyBase,
+    };
 }
 /**
  * Inject a tiny <script> that monkey-patches `fetch`, `XMLHttpRequest.open`,
@@ -416,23 +379,77 @@ function rewriteProxyTextBody(body, contentType, proxyBasePath, extraHeadHtml =
     }
     return rewritten;
 }
-function buildProxyRequestBody(req) {
+function isReadableBody(value) {
+    if (value instanceof Readable)
+        return true;
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return (typeof candidate.pipe === "function" &&
+        typeof candidate.on === "function" &&
+        typeof candidate[Symbol.asyncIterator] === "function");
+}
+async function readProxyBodyStream(stream) {
+    const chunks = [];
+    for await (const chunk of stream) {
+        if (typeof chunk === "string") {
+            chunks.push(Buffer.from(chunk));
+        }
+        else if (chunk instanceof Uint8Array) {
+            chunks.push(Buffer.from(chunk));
+        }
+        else {
+            chunks.push(Buffer.from(String(chunk)));
+        }
+    }
+    return Buffer.concat(chunks);
+}
+function bytesToArrayBuffer(bytes) {
+    const out = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(out).set(bytes);
+    return out;
+}
+function isPlainRecord(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function encodeFormRecord(body) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(body)) {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                params.append(key, String(item));
+        }
+        else {
+            params.append(key, String(value));
+        }
+    }
+    return params.toString();
+}
+async function buildProxyRequestBody(req) {
     if (req.method === "GET" || req.method === "HEAD")
         return undefined;
     const body = req.body;
     if (body == null)
         return undefined;
-    if (typeof body === "string" || body instanceof Uint8Array || Buffer.isBuffer(body)) {
+    if (typeof body === "string") {
         return body;
     }
+    if (body instanceof Uint8Array || Buffer.isBuffer(body))
+        return bytesToArrayBuffer(body);
+    if (isReadableBody(body)) {
+        return bytesToArrayBuffer(await readProxyBodyStream(body));
+    }
     const contentType = String(req.headers["content-type"] ?? "").toLowerCase();
-    if (contentType.includes("application/x-www-form-urlencoded") && typeof body === "object") {
-        return new URLSearchParams(body).toString();
+    if (contentType.includes("application/x-www-form-urlencoded") && isPlainRecord(body)) {
+        return encodeFormRecord(body);
     }
-    if (contentType.includes("application/json")) {
+    if (contentType.includes("application/json") && isPlainRecord(body)) {
         return JSON.stringify(body);
     }
-    if (typeof body === "object") {
+    if (isPlainRecord(body)) {
         return JSON.stringify(body);
     }
     return undefined;
@@ -489,7 +506,7 @@ function isTerminalProvide(provide) {
     return !!provide && String(provide.protocol).toLowerCase() === "terminal" && !!provide.terminal;
 }
 function resolveTerminalProvide(instanceId, capability) {
-    const provide = instanceManager
+    const provide = appService
         .getProvidedCapabilitiesForApp(instanceId)
         .find((entry) => entry.capability === capability);
     if (!provide)
@@ -519,12 +536,12 @@ async function proxyProvidedCapability(req, reply) {
     const idErr = validateId(req.params.id);
     if (idErr)
         return reply.status(400).send({ detail: idErr });
-    const rawInst = instanceManager.getInstance(req.params.id);
+    const rawInst = appService.getInstance(req.params.id);
     if (!rawInst)
         return reply.status(404).send({ detail: "Instance not found" });
-    if (!instanceManager.getApp(req.params.id))
+    if (!appService.getInstanceInstallRecord(req.params.id))
         return reply.status(404).send({ detail: "App not found" });
-    const capabilities = instanceManager.getProvidedCapabilitiesForApp(req.params.id);
+    const capabilities = appService.getProvidedCapabilitiesForApp(req.params.id);
     const capability = capabilities.find((entry) => entry.capability === req.params.capability);
     if (!capability) {
         return reply.status(404).send({ detail: `Capability '${req.params.capability}' not found` });
@@ -535,15 +552,24 @@ async function proxyProvidedCapability(req, reply) {
     if (capability.protocol !== "http" && capability.protocol !== "https") {
         return reply.status(400).send({ detail: `Capability '${req.params.capability}' does not use HTTP(S)` });
     }
-    // Resolve the runtime port (handles port reallocation) instead of using
-    // the declared AppSpec port which may be stale.
-    const runtimePort = instanceManager.resolveRuntimeCapabilityPort(req.params.id, req.params.capability)
-        ?? capability.port;
+    // Resolve only the canonical runtime hostPort. AppSpec declared ports are
+    // template metadata; using them here would route users to the wrong
+    // instance after reallocation or migration drift.
+    let runtimePort;
+    try {
+        runtimePort = appService.resolveRuntimeCapabilityPort(req.params.id, req.params.capability) ?? undefined;
+    }
+    catch (error) {
+        if (appService.isCanonicalRuntimePortRequiredError(error)) {
+            return reply.status(error.statusCode || 409).send({ detail: error.message, code: error.code });
+        }
+        throw error;
+    }
     if (typeof runtimePort !== "number" || runtimePort < 1) {
         return reply.status(500).send({ detail: `Capability '${req.params.capability}' has no resolved port` });
     }
-    const upstreamHost = await instanceManager.getHostForAppPort(req.params.id, runtimePort);
-    const upstreamOrigin = `${capability.protocol}://${instanceManager.urlHost(upstreamHost)}:${runtimePort}`;
+    const upstreamHost = await appService.getHostForAppPort(req.params.id, runtimePort);
+    const upstreamOrigin = `${capability.protocol}://${appService.urlHost(upstreamHost)}:${runtimePort}`;
     const wildcardSuffix = typeof req.params["*"] === "string" ? req.params["*"] : "";
     const proxyBasePath = capabilityProxyPath(req.params.id, req.params.capability);
     const querySuffix = req.raw.url?.includes("?") ? req.raw.url.slice(req.raw.url.indexOf("?")) : "";
@@ -591,6 +617,16 @@ async function proxyProvidedCapability(req, reply) {
     if (req.headers.host)
         headers.set("x-forwarded-host", String(req.headers.host));
     headers.set("x-forwarded-proto", req.protocol);
+    const clientIp = typeof req.ip === "string" && req.ip
+        ? req.ip
+        : typeof req.raw?.socket?.remoteAddress === "string"
+            ? req.raw.socket.remoteAddress
+            : "";
+    if (clientIp) {
+        const forwardedFor = headers.get("x-forwarded-for");
+        headers.set("x-forwarded-for", forwardedFor ? `${forwardedFor}, ${clientIp}` : clientIp);
+        headers.set("x-real-ip", clientIp);
+    }
     // Intercept service worker scripts BEFORE talking to upstream.  SPAs like
     // OpenWebUI register a SvelteKit service worker that aggressively caches
     // HTML/JS at the proxy origin; once installed, the SW serves stale bodies
@@ -621,16 +657,23 @@ async function proxyProvidedCapability(req, reply) {
     // promise indefinitely and starve the event loop.
     const upstreamAbort = new AbortController();
     const connectTimer = setTimeout(() => upstreamAbort.abort(new Error("upstream connect timeout")), 30_000);
-    const onClientClose = () => upstreamAbort.abort();
-    req.raw.once("close", onClientClose);
+    const onClientClose = () => {
+        if (!reply.raw.writableEnded)
+            upstreamAbort.abort(new Error("client disconnected"));
+    };
+    reply.raw.once("close", onClientClose);
     try {
+        console.error("[cap-proxy] PRE buildBody method=", req.method, "bodyType=", typeof req.body, req.body?.constructor?.name, "signalAborted=", upstreamAbort.signal.aborted);
+        const requestBody = await buildProxyRequestBody(req);
+        console.error("[cap-proxy] POST buildBody size=", requestBody instanceof ArrayBuffer ? requestBody.byteLength : typeof requestBody === "string" ? requestBody.length : "undef", "signalAborted=", upstreamAbort.signal.aborted, "reason=", upstreamAbort.signal.reason?.message);
         const upstream = await fetch(targetUrl, {
             method: req.method,
             headers,
-            body: buildProxyRequestBody(req),
+            body: requestBody,
             redirect: "manual",
             signal: upstreamAbort.signal,
         }).finally(() => clearTimeout(connectTimer));
+        console.error("[cap-proxy] POST fetch status=", upstream.status);
         const upstreamContentType = upstream.headers.get("content-type");
         const willRewriteBody = shouldRewriteProxyResponse(upstreamContentType);
         const willInjectHtml = (upstreamContentType ?? "").toLowerCase().includes("text/html");
@@ -646,7 +689,7 @@ async function proxyProvidedCapability(req, reply) {
             // hard-coded redirect targets, etc.). Honoring the upstream cache hints
             // lets the browser pin a stale rewrite indefinitely: e.g. an early
             // visit that pre-dated the JS rewrite gets cached and survives across
-            // panel restarts, breaking the auth redirect logic until a hard refresh.
+            // app restarts, breaking the auth redirect logic until a hard refresh.
             // Strip cache validators and force revalidation on every load.
             if (willRewriteBody && (normalizedKey === "cache-control" ||
                 normalizedKey === "etag" ||
@@ -680,7 +723,7 @@ async function proxyProvidedCapability(req, reply) {
             reply.header(key, value);
         });
         if (req.method === "HEAD") {
-            req.raw.off("close", onClientClose);
+            reply.raw.off("close", onClientClose);
             return reply.send();
         }
         if (willRewriteBody) {
@@ -689,9 +732,14 @@ async function proxyProvidedCapability(req, reply) {
             reply.header("pragma", "no-cache");
             reply.header("expires", "0");
             let extraHeadHtml = "";
-            if (req.params.capability === "browserless-debugger") {
-                extraHeadHtml = browserlessDebuggerBootstrap(req.params.id);
-            }
+            const htmlRewriter = getCapabilityHtmlRewriter(capability);
+            extraHeadHtml += (await htmlRewriter?.buildHeadHtml({
+                instanceId: req.params.id,
+                capability,
+                upstreamOrigin,
+                signal: upstreamAbort.signal,
+                willInjectHtml,
+            })) ?? "";
             // Inject a generic fetch/XHR monkey-patch for all capability-proxied
             // HTML pages.  SPA frameworks like SvelteKit compile absolute API paths
             // (e.g. `/api/v1/...`, `/ollama/...`) into JS bundles at build time.
@@ -700,60 +748,55 @@ async function proxyProvidedCapability(req, reply) {
             // intercepts fetch() and XMLHttpRequest.open() and rewrites same-origin
             // absolute paths that do NOT already start with the proxy prefix.
             extraHeadHtml += capabilityProxyBootstrap(proxyBasePath);
-            // First-visit cleanup: if the browser still has a stale ServiceWorker
-            // registered from an earlier panel build (which would intercept this
-            // navigation and serve cached HTML *without* the bootstrap patches),
-            // emit Clear-Site-Data so the browser drops the SW + its cache and
-            // reloads through the proxy. We mark the success with a long-lived
-            // cookie scoped to the proxy path to avoid a reload loop.
+            const rawBody = await upstream.text();
+            // First-visit/content-change cleanup: if the browser still has a stale
+            // ServiceWorker registered from an earlier panel build (which would
+            // intercept this navigation and serve cached HTML *without* the
+            // bootstrap patches), emit Clear-Site-Data so the browser drops the SW
+            // + its cache and reloads through the proxy. We mark the success with a
+            // long-lived cookie scoped to the proxy path to avoid a reload loop.
+            // The cookie value is tied to the upstream HTML bytes and validators,
+            // not a fixed boolean, so same-tag image rebuilds such as jishu-kb:0.1.1
+            // can still trigger one fresh cleanup after the embedded UI changes.
             // Gate to HTML only — JS/CSS sub-resources also flow through this branch
             // now that we rewrite JS bundles, and emitting Clear-Site-Data on a JS
             // response would clear storage mid-page-load.
             if (willInjectHtml) {
+                const cleanupToken = capabilityProxyCleanupToken([
+                    req.params.id,
+                    req.params.capability,
+                    upstreamOrigin,
+                    upstreamContentType,
+                    upstream.headers.get("etag"),
+                    upstream.headers.get("last-modified"),
+                    upstream.headers.get("content-length"),
+                    rawBody,
+                ]);
                 const cookieHeader = (req.headers.cookie || "").toString();
-                const swCleaned = /(?:^|;\s*)cap_proxy_sw_clean=1(?:;|$)/.test(cookieHeader);
+                const swCleaned = hasCookieValue(cookieHeader, "cap_proxy_sw_clean", cleanupToken);
                 if (!swCleaned) {
                     reply.header("Clear-Site-Data", '"cache", "storage"');
-                    reply.header("Set-Cookie", `cap_proxy_sw_clean=1; Path=${proxyBasePath}; Max-Age=2592000; SameSite=Lax`);
+                    reply.header("Set-Cookie", `cap_proxy_sw_clean=${cleanupToken}; Path=${proxyBasePath}; Max-Age=2592000; SameSite=Lax`);
                 }
             }
-            const rawBody = await upstream.text();
-            req.raw.off("close", onClientClose);
+            reply.raw.off("close", onClientClose);
             const rewritten = rewriteProxyTextBody(rawBody, upstreamContentType, proxyBasePath, extraHeadHtml);
             return reply.send(rewritten);
         }
         if (!upstream.body) {
-            req.raw.off("close", onClientClose);
+            reply.raw.off("close", onClientClose);
             return reply.send();
         }
         const readable = Readable.fromWeb(upstream.body);
-        readable.once("close", () => req.raw.off("close", onClientClose));
+        readable.once("close", () => reply.raw.off("close", onClientClose));
         return reply.send(readable);
     }
     catch (error) {
-        req.raw.off("close", onClientClose);
+        console.error("[cap-proxy] CATCH", error?.constructor?.name, error?.name, error?.message, "signalAborted=", upstreamAbort.signal.aborted, "reason=", upstreamAbort.signal.reason?.message, "stack=", error?.stack?.split("\n").slice(0, 4).join(" | "));
+        reply.raw.off("close", onClientClose);
         return reply.status(502).send({ detail: error?.message || `Failed to proxy capability '${req.params.capability}'` });
     }
 }
-export async function ensureControlUiAllowedOrigin(instanceId, origin) {
-    const normalizedOrigin = origin.trim();
-    if (!normalizedOrigin)
-        return false;
-    const config = instanceManager.getStoredConfig(instanceId);
-    if (!config)
-        return false;
-    const gateway = config.gateway ??= {};
-    const controlUi = gateway.controlUi ??= {};
-    const existing = Array.isArray(controlUi.allowedOrigins)
-        ? controlUi.allowedOrigins.map((value) => String(value))
-        : [];
-    const normalized = new Set(existing.map((value) => value.trim().toLowerCase()).filter(Boolean));
-    if (normalized.has("*") || normalized.has(normalizedOrigin.toLowerCase()))
-        return false;
-    controlUi.allowedOrigins = [...existing.filter((value) => value.trim()), normalizedOrigin];
-    await instanceManager.saveConfig(instanceId, config);
-    return true;
-}
 // Resolve service manager once at route registration, re-resolve on config change
 let _svc = null;
 let _svcType = "";
@@ -761,124 +804,36 @@ export async function getSvc() {
     const currentType = getServiceManagerType();
     if (_svc && _svcType === currentType)
         return _svc;
-    _svc = currentType === "nomad"
-        ? await import("../services/nomad-manager.js")
-        : await import("../services/process-manager.js");
+    if (currentType !== "nomad") {
+        // Step 13: process-manager / host-mode legacy runtime is unsupported.
+        throw new Error(`service_manager='${currentType}' is no longer supported. ` +
+            "Only 'nomad' runtimes are accepted on the runtime path. " +
+            "Run `jishushell migrate legacy` to convert legacy instances.");
+    }
+    _svc = await import("../services/runtime/drivers/nomad.js");
     _svcType = currentType;
     return _svc;
 }
-export function validateId(id) {
-    if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(id)) {
-        return "ID must be lowercase alphanumeric with hyphens, 1-63 chars";
-    }
-    return null;
-}
-function normalizeInstanceName(name) {
-    return name.trim().toLowerCase();
-}
-function isLegacyInstanceAppType(value) {
-    return value === "custom" || value === "ollama";
-}
-function getInstanceBackedInstalledApp(instanceId) {
-    return instanceManager.getApp(instanceId);
-}
-/**
- * Resolve the spec used to drive the Connections feature.
- *
- * For V2 app-installed instances (`meta.app_id` set), pull the persisted
- * `app-spec.yaml` via app-manager. For legacy hermes/openclaw instances
- * created via the old "新建实例" flow (no `app_id`, no spec on disk),
- * synthesize an in-memory capability-only spec from the bundled
- * `apps/<agentType>-container.yaml` template.
- *
- * Returning `legacy: true` lets the PUT handler skip the adapter-driven
- * env injection that V2 expects — for legacy instances the apply hooks
- * fall back to writing `instance.json["connections-env"]`, which the
- * legacy start path is responsible for merging into runtime.env.
- */
-async function loadConnectionsSpec(meta) {
-    const { app_id } = meta;
-    if (app_id) {
-        const appData = instanceManager.getApp(app_id);
-        if (!appData)
-            return null;
-        return { spec: appData.spec, legacy: false, appId: app_id };
-    }
-    const { loadCapabilitySpecForLegacyInstance } = await import("../services/runtime/migrations.js");
-    const synthetic = loadCapabilitySpecForLegacyInstance(meta);
-    if (!synthetic)
-        return null;
-    return { spec: synthetic, legacy: true, appId: meta.id };
-}
-const DEFAULT_INSTANCE_TEMPLATE_BY_KIND = {
-    ollama: "ollama-with-hollama-binary.yaml",
-};
-const HIDDEN_CONNECTION_STATUS_CAPABILITIES = new Set(["mcp"]);
-function loadBuiltinAppSpecYaml(fileName) {
-    const template = instanceManager.listBuiltinAppSpecs().find((entry) => entry.fileName === fileName);
-    if (!template?.yaml) {
-        throw new Error(`Builtin app spec '${fileName}' not found`);
-    }
-    return template.yaml;
-}
-async function loadRemoteAppSpecYamlForInstance(urlText) {
-    return loadRemoteAppSpecYaml(urlText, { fieldName: "app_spec_url" });
-}
-function isConfigDocument(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return false;
-    const format = value.format;
-    return format === "json" || format === "yaml+env";
-}
-// TTL 15s: outlives the frontend 10s polling interval so most requests hit cache
-const statusCache = new TtlMap(15_000);
-const controlUiRestartInFlight = new Map();
-function getCachedStatus(svc, instanceId) {
-    const cached = statusCache.get(instanceId);
-    if (cached !== undefined)
-        return Promise.resolve(cached);
-    const statusPromise = getInstanceBackedInstalledApp(instanceId)
-        ? instanceManager.getAppStatus(instanceId).then((data) => ({
-            status: data.status,
-            pid: data.pid,
-            uptime: data.uptime,
-            memory_mb: data.memory_mb,
-            cpu_percent: data.cpu_percent,
-        }))
-        : Promise.resolve(svc.getStatus(instanceId));
-    return statusPromise.then((data) => {
-        statusCache.set(instanceId, data);
-        return data;
-    });
+function getLifecycleActionSource(req) {
+    const raw = req.headers["x-jishushell-action-source"];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    const source = typeof value === "string" ? value.trim() : "";
+    return /^[a-z0-9._:-]{1,80}$/i.test(source) ? source : "unknown";
 }
-export async function restartRunningInstanceForControlUiOrigin(instanceId, origin) {
-    const inFlight = controlUiRestartInFlight.get(instanceId);
-    if (inFlight)
-        return inFlight;
-    const task = (async () => {
-        const svc = await getSvc();
-        const status = await svc.getStatus(instanceId);
-        if (status.status !== "running")
-            return;
-        const result = await svc.restartInstance(instanceId);
-        statusCache.delete(instanceId);
-        if (!result.ok) {
-            console.warn(`[gateway-launch] failed to auto-restart ${instanceId} after allowing origin ${origin}:`, result.error || "unknown error");
-            return;
-        }
-        console.log(`[gateway-launch] auto-restarted ${instanceId} after allowing origin ${origin}`);
-    })().finally(() => {
-        controlUiRestartInFlight.delete(instanceId);
+export async function getCachedStatus(_svc, instanceId, reason) {
+    const snapshot = await refreshInstanceStatus(instanceId, {
+        reason,
+        force: true,
+        minIntervalMs: 0,
     });
-    controlUiRestartInFlight.set(instanceId, task);
-    return task;
+    return snapshot?.service ?? { status: "unknown", pid: null, uptime: null, memory_mb: null, cpu_percent: null };
 }
 export async function instanceRoutes(app) {
     // List
     app.get("/api/instances", async () => {
         const svc = await getSvc();
-        const instances = instanceManager.listInstances();
-        const statuses = await Promise.all(instances.map(inst => getCachedStatus(svc, inst.id).catch(() => ({ status: "unknown" }))));
+        const instances = appService.listInstances();
+        const statuses = await Promise.all(instances.map(inst => getCachedStatus(svc, inst.id, "api-list").catch(() => ({ status: "unknown", pid: null, uptime: null, memory_mb: null, cpu_percent: null }))));
         return Promise.all(instances.map(async (inst, i) => ({
             ...(await augmentInstanceMetadata(inst.id, inst)),
             service: statuses[i],
@@ -886,192 +841,8 @@ export async function instanceRoutes(app) {
     });
     // Create
     app.post("/api/instances", async (req, reply) => {
-        const err = validateId(req.body.id);
-        if (err)
-            return reply.status(400).send({ detail: err });
-        const requestedName = typeof req.body.name === "string" ? req.body.name.trim() : "";
-        // Validate name/description length
-        if (!requestedName || requestedName.length > 256) {
-            return reply.status(400).send({ detail: "Name must be 1-256 characters" });
-        }
-        if (req.body.description && req.body.description.length > 2048) {
-            return reply.status(400).send({ detail: "Description must be at most 2048 characters" });
-        }
-        // §32.2 / §32.8: pure adapter dispatch. The route layer has no
-        // knowledge of specific runtimes beyond trusting what the caller sent;
-        // `getAdapter(agentType)` throws cleanly if the type is unregistered.
-        // `app_type` is accepted as a legacy alias that predates the adapter
-        // contract (pre-§32.2) — both resolve to the same dispatch key.
-        const requestedKind = typeof req.body.agentType === "string" && req.body.agentType.trim()
-            ? req.body.agentType.trim()
-            : typeof req.body.app_type === "string" && req.body.app_type.trim()
-                ? req.body.app_type.trim()
-                : "openclaw";
-        const { getAdapter, hasAdapter } = await import("../services/runtime/index.js");
-        const legacyAppType = isLegacyInstanceAppType(requestedKind) ? requestedKind : null;
-        if (!hasAdapter(requestedKind) && !legacyAppType) {
-            return reply.status(400).send({
-                detail: `Unsupported agentType="${requestedKind}". Install the matching runtime first.`,
-            });
-        }
-        // Parse app_spec_yaml if provided (for YAML-backed install flows).
-        let appSpec;
-        let appSpecYaml = typeof req.body.app_spec_yaml === "string" ? req.body.app_spec_yaml.trim() : "";
-        if (!appSpecYaml && typeof req.body.app_spec_url === "string" && req.body.app_spec_url.trim()) {
-            try {
-                appSpecYaml = await loadRemoteAppSpecYamlForInstance(req.body.app_spec_url.trim());
-            }
-            catch (e) {
-                return reply.status(400).send({ detail: e.message });
-            }
-        }
-        // When a legacy dispatch key (e.g. app_type="ollama") is sent without
-        // an explicit AppSpec, auto-load the shipped default template so the
-        // caller doesn't have to know the YAML lives in apps/.
-        const defaultTemplateFile = DEFAULT_INSTANCE_TEMPLATE_BY_KIND[requestedKind];
-        if (!appSpecYaml && defaultTemplateFile) {
-            try {
-                appSpecYaml = loadBuiltinAppSpecYaml(defaultTemplateFile);
-            }
-            catch (e) {
-                return reply.status(500).send({ detail: e.message });
-            }
-        }
-        if (appSpecYaml) {
-            try {
-                const { parse: parseYaml } = await import("yaml");
-                const parsed = parseYaml(appSpecYaml);
-                if (!parsed || !parsed.tasks || !Array.isArray(parsed.tasks)) {
-                    return reply.status(400).send({ detail: "Invalid app-spec YAML: must contain a 'tasks' array" });
-                }
-                if (!parsed.id)
-                    parsed.id = req.body.id;
-                appSpec = parsed;
-            }
-            catch (e) {
-                return reply.status(400).send({ detail: `Invalid YAML: ${e.message}` });
-            }
-        }
-        // Normalize instance id: Tier-1 agents get "<agentType>-" prefix;
-        // custom apps get "<app_spec_ref>-" prefix (or the spec id verbatim
-        // for singleInstance). Idempotent when the user already types the
-        // expected prefix. See docs/app-dir-v2-plan.md §2.4.
-        //
-        // Gate: only apply normalization when the caller explicitly opted in
-        // by sending `agentType` (or the legacy `app_type` alias), or when an
-        // AppSpec is being installed. Requests without an explicit runtime
-        // hint keep the V1 contract (id preserved verbatim) so older API
-        // consumers and existing test fixtures continue working. Panel UI
-        // sends `agentType` explicitly (`frontend/src/pages/NewInstance.tsx`).
-        const explicitRuntime = (typeof req.body.agentType === "string" && req.body.agentType.trim().length > 0) ||
-            (typeof req.body.app_type === "string" && req.body.app_type.trim().length > 0);
-        // Skip normalization for legacy app types (ollama / custom old marker):
-        // these follow the V1 legacy short-circuit path (see
-        // docs/app-dir-v2-plan.md §2.1 "Legacy Ollama semantics"), so we keep their
-        // ids verbatim rather than retroactively prefixing them.
-        const shouldNormalize = (explicitRuntime || appSpecYaml.length > 0) && !legacyAppType;
-        const kind = requestedKind === "hermes" ? "hermes"
-            : requestedKind === "custom" ? "custom"
-                : requestedKind === "openclaw" ? "openclaw"
-                    : "openclaw";
-        let instanceId = req.body.id;
-        if (shouldNormalize) {
-            try {
-                instanceId = normalizeInstanceId(req.body.id, kind, appSpec ? { id: appSpec.id, singleInstance: appSpec.singleInstance } : undefined);
-            }
-            catch (e) {
-                return reply.status(400).send({ detail: e.message });
-            }
-        }
-        const existingById = instanceManager.getInstance(instanceId);
-        if (existingById) {
-            return reply.status(409).send({ detail: `Application '${instanceId}' already exists` });
-        }
-        const requestedNormalizedName = normalizeInstanceName(requestedName);
-        const existingByName = instanceManager.listInstances().find((instance) => {
-            if (!instance || typeof instance.name !== "string")
-                return false;
-            return normalizeInstanceName(instance.name) === requestedNormalizedName;
-        });
-        if (existingByName) {
-            return reply.status(409).send({
-                detail: `Application name '${requestedName}' already exists`,
-                existingId: existingByName.id,
-            });
-        }
-        // Validate clone_from if provided — adapter will reject it if the
-        // runtime does not support cloning, but we do the existence check
-        // here so the error message points at the wrong source, not at the
-        // wrong-runtime rejection.
-        if (req.body.clone_from) {
-            const cloneErr = validateId(req.body.clone_from);
-            if (cloneErr)
-                return reply.status(400).send({ detail: `Invalid clone_from: ${cloneErr}` });
-            const sourceInstance = instanceManager.getInstance(req.body.clone_from);
-            if (!sourceInstance)
-                return reply.status(400).send({ detail: `Source instance '${req.body.clone_from}' not found` });
-        }
         try {
-            let meta;
-            const createFromAppSpec = appSpecYaml.length > 0;
-            if (!createFromAppSpec) {
-                if (!hasAdapter(requestedKind)) {
-                    return reply.status(400).send({ detail: `Creating ${requestedKind} requires an app spec` });
-                }
-                const adapter = getAdapter(requestedKind);
-                if (typeof adapter.createInstance !== "function") {
-                    return reply.status(400).send({ detail: `Creating ${requestedKind} requires an app spec` });
-                }
-                meta = await adapter.createInstance({
-                    instanceId,
-                    name: requestedName,
-                    description: req.body.description || "",
-                    cloneFrom: req.body.clone_from,
-                    agentHome: req.body.agent_home ?? req.body.openclaw_home,
-                    cloneOptions: req.body.clone_options,
-                });
-            }
-            else {
-                await instanceManager.installApp(appSpecYaml, instanceId, {
-                    bootstrap: {
-                        name: requestedName,
-                        description: req.body.description || "",
-                        cloneFrom: req.body.clone_from,
-                        agentHome: req.body.agent_home ?? req.body.openclaw_home,
-                        cloneOptions: req.body.clone_options,
-                    },
-                });
-                meta = instanceManager.updateInstance(instanceId, requestedName, req.body.description || "") ?? instanceManager.getInstance(instanceId) ?? {
-                    id: instanceId,
-                    name: requestedName,
-                    description: req.body.description || "",
-                    created_at: new Date().toISOString(),
-                    ...(legacyAppType ? { app_type: legacyAppType } : {}),
-                    ...(appSpec ? { app_id: appSpec.app_id ?? instanceId } : {}),
-                };
-            }
-            // Auto-start if default provider is configured (model ready to use).
-            // Non-openclaw runtimes always auto-start — Hermes/Ollama/custom manage
-            // their own provider plumbing (or don't need one), so skipping the
-            // auto-start would make the first run feel broken.
-            const { getPanelConfig } = await import("../config.js");
-            const dp = getPanelConfig().default_provider;
-            const shouldAutoStart = requestedKind !== "openclaw" || (dp && dp.providerId && !dp.skipped);
-            if (shouldAutoStart) {
-                void (async () => {
-                    const result = createFromAppSpec
-                        ? await instanceManager.startApp(instanceId)
-                        : await (await getSvc()).startInstance(instanceId);
-                    if (!result.ok) {
-                        console.warn(`[instances] Auto-start ${instanceId} failed: ${result.error ?? "unknown error"}`);
-                    }
-                })();
-                meta.autoStarted = true;
-            }
-            const decorated = await augmentInstanceMetadata(instanceId, meta);
-            if (meta.autoStarted)
-                decorated.autoStarted = true;
-            return decorated;
+            return await createInstance(req.body);
         }
         catch (e) {
             // Structured rejection from createHermesInstance — return 409 with code
@@ -1084,23 +855,61 @@ export async function instanceRoutes(app) {
                     currentNomadDriver: e.currentNomadDriver,
                 });
             }
+            if (isInstanceAdminError(e)) {
+                return reply.status(e.statusCode).send(e.payload);
+            }
             return reply.status(409).send({ detail: e.message });
         }
     });
+    app.post("/api/instances/:id/clone", async (req, reply) => {
+        const sourceIdError = validateId(req.params.id);
+        if (sourceIdError)
+            return reply.status(400).send({ detail: sourceIdError });
+        const targetId = typeof req.body?.id === "string" ? req.body.id : "";
+        const targetIdError = validateId(targetId);
+        if (targetIdError)
+            return reply.status(400).send({ detail: targetIdError });
+        const name = typeof req.body?.name === "string" ? req.body.name.trim() : "";
+        if (!name || name.length > 256) {
+            return reply.status(400).send({ detail: "Name must be 1-256 characters" });
+        }
+        if (typeof req.body?.description === "string" && req.body.description.length > 2048) {
+            return reply.status(400).send({ detail: "Description must be at most 2048 characters" });
+        }
+        try {
+            const result = await cloneInstance({
+                sourceInstanceId: req.params.id,
+                targetId,
+                name,
+                description: req.body?.description,
+                cloneOptions: req.body?.clone_options,
+            });
+            return reply.status(201).send(result);
+        }
+        catch (error) {
+            if (isInstanceCloneError(error)) {
+                return reply.status(error.statusCode).send({
+                    detail: error.message,
+                    ...(error.code ? { code: error.code } : {}),
+                });
+            }
+            throw error;
+        }
+    });
     // Get
     app.get("/api/instances/:id", async (req, reply) => {
         const idErr = validateId(req.params.id);
         if (idErr)
             return reply.status(400).send({ detail: idErr });
         const svc = await getSvc();
-        const inst = instanceManager.getInstance(req.params.id);
+        const inst = appService.getInstance(req.params.id);
         if (!inst)
             return reply.status(404).send({ detail: "Instance not found" });
-        const status = await getCachedStatus(svc, req.params.id);
+        const status = await getCachedStatus(svc, req.params.id, "api-detail");
         return {
             ...(await augmentInstanceMetadata(req.params.id, inst)),
             service: status,
-            llmError: llmProxy.getLastProxyError(req.params.id) ?? null,
+            llmError: getLastProxyError(req.params.id) ?? null,
         };
     });
     // Update
@@ -1120,10 +929,11 @@ export async function instanceRoutes(app) {
         catch (e) {
             return reply.status(e.statusCode || 409).send({ detail: e.message });
         }
-        const inst = instanceManager.updateInstance(req.params.id, req.body.name, req.body.description);
+        const inst = appService.updateInstance(req.params.id, req.body.name, req.body.description);
         if (!inst)
             return reply.status(404).send({ detail: "Instance not found" });
-        return inst;
+        invalidateExecutionOwner(req.params.id);
+        return augmentInstanceMetadata(req.params.id, inst);
     });
     // Delete
     app.delete("/api/instances/:id", async (req, reply) => {
@@ -1136,144 +946,71 @@ export async function instanceRoutes(app) {
         catch (e) {
             return reply.status(e.statusCode || 409).send({ detail: e.message });
         }
-        if (getInstanceBackedInstalledApp(req.params.id)) {
-            const sudoPassword = typeof req.body?.sudoPassword === "string" && req.body.sudoPassword.trim()
-                ? req.body.sudoPassword
-                : undefined;
-            const result = instanceManager.uninstallAppTask(req.params.id, sudoPassword ? { sudoPassword } : undefined);
-            if (!result.ok) {
-                const code = result.code;
-                const status = code === "TASK_BUSY" ? 409 : code === "APP_NOT_FOUND" ? 404 : 400;
-                return reply.status(status).send({ detail: result.error, code });
-            }
-            statusCache.delete(req.params.id);
-            llmProxy.cleanupInstance(req.params.id);
+        const purgeBackups = req.query.purge_backups === "true";
+        const sudoPassword = typeof req.body?.sudoPassword === "string" && req.body.sudoPassword.trim()
+            ? req.body.sudoPassword
+            : undefined;
+        const result = await appLifecycle.deleteManagedInstance(req.params.id, {
+            purgeBackups,
+            ...(sudoPassword ? { exec: { sudoPassword } } : {}),
+        });
+        if (!result.ok) {
+            const status = result.code === "TASK_BUSY"
+                ? 409
+                : result.code === "APP_NOT_FOUND" || result.code === "INSTANCE_NOT_FOUND"
+                    ? 404
+                    : 400;
+            return reply.status(status).send({
+                detail: result.error,
+                ...(result.code ? { code: result.code } : {}),
+            });
+        }
+        invalidateExecutionOwner(req.params.id);
+        cleanupProxyInstance(req.params.id);
+        if (result.taskId) {
             return reply.status(202).send({
                 ok: true,
                 taskId: result.taskId,
-                ...result.reused ? { reused: true } : {},
+                ...(result.reused ? { reused: true } : {}),
             });
         }
-        const svc = await getSvc();
-        let stopFailed = false;
+        return { ok: true, warnings: result.warnings?.length ? result.warnings : undefined };
+    });
+    // Config
+    app.get("/api/instances/:id/config-meta", async (req, reply) => {
         try {
-            await svc.stopInstance(req.params.id, true);
+            return getAppConfigMeta(req.params.id);
         }
-        catch {
-            try {
-                await svc.stopInstance(req.params.id);
-            }
-            catch {
-                stopFailed = true;
-            }
-        }
-        // Also stop any legacy process-manager process that might be lingering
-        try {
-            const { getLegacyStatus, stopInstance: stopLegacy } = await import("../services/process-manager.js");
-            if ((await getLegacyStatus(req.params.id)).status === "running") {
-                await stopLegacy(req.params.id);
-                stopFailed = false;
+        catch (e) {
+            if (isAppConfigAdminError(e)) {
+                const detail = e.code === "APP_NOT_FOUND" ? "Instance not found" : e.message;
+                return reply.status(e.statusCode).send({ detail, code: e.code });
             }
+            throw e;
         }
-        catch { /* ignore */ }
-        statusCache.delete(req.params.id);
-        llmProxy.cleanupInstance(req.params.id);
-        const purgeBackups = req.query.purge_backups === "true";
-        const result = await instanceManager.deleteInstance(req.params.id, purgeBackups);
-        if (!result.ok && result.warnings?.some(w => w.includes("not found"))) {
-            return reply.status(404).send({ detail: "Instance not found" });
-        }
-        const warnings = result.warnings ? [...result.warnings] : [];
-        if (stopFailed) {
-            console.warn(`[instances] Delete ${req.params.id}: service stop failed, orphaned processes may remain`);
-            warnings.push("Service stop did not complete; verify no orphaned processes remain.");
-        }
-        return { ok: result.ok, warnings: warnings.length ? warnings : undefined };
-    });
-    // Config
-    app.get("/api/instances/:id/config-meta", async (req, reply) => {
-        const idErr = validateId(req.params.id);
-        if (idErr)
-            return reply.status(400).send({ detail: idErr });
-        const inst = instanceManager.getInstance(req.params.id);
-        if (!inst)
-            return reply.status(404).send({ detail: "Instance not found" });
-        return getInstanceConfigMeta(req.params.id, inst);
     });
     app.get("/api/instances/:id/config", async (req, reply) => {
-        const idErr = validateId(req.params.id);
-        if (idErr)
-            return reply.status(400).send({ detail: idErr });
-        const inst = instanceManager.getInstance(req.params.id);
-        if (!inst)
-            return reply.status(404).send({ detail: "Instance not found" });
-        const agentType = resolveAgentType(inst);
-        if (hasAdapter(agentType)) {
-            try {
-                const doc = await getAdapter(agentType).readConfig(req.params.id);
-                // Back-compat: frontend ConfigForm treats JSON-format responses as
-                // the raw config object (no {format, content} wrapper). Unwrap here
-                // so the existing OpenClaw editor keeps working without touching
-                // every consumer.
-                return doc.format === "json" ? doc.content : doc;
-            }
-            catch (e) {
-                if (/not found/i.test(e?.message || "")) {
-                    return reply.status(404).send({ detail: e.message });
-                }
-                throw e;
+        try {
+            return await readAppConfig(req.params.id);
+        }
+        catch (e) {
+            if (isAppConfigAdminError(e)) {
+                const detail = e.code === "APP_NOT_FOUND" ? "Instance not found" : e.message;
+                return reply.status(e.statusCode).send({ detail, code: e.code });
             }
+            throw e;
         }
-        const config = llmProxy.getInstanceConfig(req.params.id);
-        if (!config)
-            return reply.status(404).send({ detail: "Instance or config not found" });
-        return config;
     });
     app.put("/api/instances/:id/config", async (req, reply) => {
-        const idErr = validateId(req.params.id);
-        if (idErr)
-            return reply.status(400).send({ detail: idErr });
-        const inst = instanceManager.getInstance(req.params.id);
-        if (!inst)
-            return reply.status(404).send({ detail: "Instance not found" });
-        const agentType = resolveAgentType(inst);
-        // Basic payload validation
-        const body = req.body;
-        const bodyStr = JSON.stringify(body);
-        if (bodyStr.length > 512 * 1024) {
-            return reply.status(400).send({ detail: "Config too large (max 512KB)" });
-        }
         try {
-            assertNotLocked(req.params.id);
-            if (hasAdapter(agentType)) {
-                // Accept either a typed ConfigDocument (`{format, content|yaml+env}`)
-                // or a raw JSON object (legacy OpenClaw shape) — the route wraps
-                // the raw shape so adapter.writeConfig always sees the typed
-                // contract. Response is unwrapped symmetrically with GET.
-                let doc;
-                if (isConfigDocument(body)) {
-                    doc = body;
-                }
-                else if (body && typeof body === "object" && !Array.isArray(body)) {
-                    doc = { format: "json", content: body };
-                }
-                else {
-                    return reply.status(400).send({ detail: "Config must be a JSON object" });
-                }
-                const saved = await getAdapter(agentType).writeConfig(req.params.id, doc);
-                return { ok: true, config: saved.format === "json" ? saved.content : saved };
-            }
-            if (!body || typeof body !== "object" || Array.isArray(body)) {
-                return reply.status(400).send({ detail: "Config must be a JSON object" });
-            }
-            const saved = await llmProxy.saveInstanceConfig(req.params.id, body);
-            return { ok: true, config: saved };
+            return await writeAppConfig(req.params.id, req.body);
         }
         catch (e) {
-            const msg = e.message || "";
-            if (msg.includes("not found"))
-                return reply.status(404).send({ detail: msg });
-            return reply.status(400).send({ detail: msg });
+            if (isAppConfigAdminError(e)) {
+                const detail = e.code === "APP_NOT_FOUND" ? "Instance not found" : e.message;
+                return reply.status(e.statusCode).send({ detail, code: e.code });
+            }
+            throw e;
         }
     });
     // Service control
@@ -1281,14 +1018,20 @@ export async function instanceRoutes(app) {
         const idErr = validateId(req.params.id);
         if (idErr)
             return reply.status(400).send({ detail: idErr });
-        const svc = await getSvc();
-        if (!instanceManager.getInstance(req.params.id) && !getInstanceBackedInstalledApp(req.params.id)) {
-            return reply.status(404).send({ detail: "Instance not found" });
+        let status;
+        try {
+            status = await appLifecycle.getManagedStatus(req.params.id);
         }
-        if (getInstanceBackedInstalledApp(req.params.id)) {
-            return instanceManager.getAppStatus(req.params.id);
+        catch (error) {
+            if (appService.isCanonicalRuntimePortRequiredError(error)) {
+                return reply.status(error.statusCode || 409).send({ detail: error.message, code: error.code });
+            }
+            throw error;
+        }
+        if (!status) {
+            return reply.status(404).send({ detail: "Instance not found" });
         }
-        return svc.getStatus(req.params.id);
+        return status;
     });
     app.post("/api/instances/:id/service/start", async (req, reply) => {
         const idErr = validateId(req.params.id);
@@ -1300,19 +1043,18 @@ export async function instanceRoutes(app) {
         catch (e) {
             return reply.status(e.statusCode || 409).send({ detail: e.message });
         }
-        const svc = await getSvc();
-        if (!instanceManager.getInstance(req.params.id) && !getInstanceBackedInstalledApp(req.params.id)) {
-            return reply.status(404).send({ detail: "Instance not found" });
-        }
-        const result = getInstanceBackedInstalledApp(req.params.id)
-            ? await instanceManager.startApp(req.params.id)
-            : await svc.startInstance(req.params.id);
-        statusCache.delete(req.params.id);
+        const actionSource = getLifecycleActionSource(req);
+        console.log(`[lifecycle] start requested for ${req.params.id} source=${actionSource}`);
+        const controlUiOrigin = inferRequestOrigin(req);
+        const result = controlUiOrigin
+            ? await appLifecycle.startInstance(req.params.id, { controlUiOrigin })
+            : await appLifecycle.startInstance(req.params.id);
+        invalidateExecutionOwner(req.params.id);
         if (!result.ok) {
             const resultRecord = result;
             // Surface the phase tag so the UI can highlight where the start
             // pipeline failed (running_check / home_conflict / port_alloc /
-            // pre_start_hook / submit). Legacy clients that only read `detail`
+            // port allocation / submit). Legacy clients that only read `detail`
             // keep working.
             const payload = { detail: result.error };
             if (resultRecord.phase)
@@ -1323,6 +1065,9 @@ export async function instanceRoutes(app) {
                 payload.taskId = resultRecord.taskId;
             if (resultRecord.code)
                 payload.code = resultRecord.code;
+            if (resultRecord.code === "INSTANCE_NOT_FOUND") {
+                return reply.status(404).send(payload);
+            }
             // Honor the structured ConnectionError statusCode (412 / 409 / 400)
             // when present so the UI can distinguish missing-required from
             // ambiguous-prefix from invalid-binding without parsing the message.
@@ -1331,6 +1076,7 @@ export async function instanceRoutes(app) {
                 : 400;
             return reply.status(statusCode).send(payload);
         }
+        markRuntimeRepairRestartApplied(req.params.id);
         return result;
     });
     app.post("/api/instances/:id/service/stop", async (req, reply) => {
@@ -1343,16 +1089,14 @@ export async function instanceRoutes(app) {
         catch (e) {
             return reply.status(e.statusCode || 409).send({ detail: e.message });
         }
-        const svc = await getSvc();
-        if (!instanceManager.getInstance(req.params.id) && !getInstanceBackedInstalledApp(req.params.id)) {
-            return reply.status(404).send({ detail: "Instance not found" });
+        const actionSource = getLifecycleActionSource(req);
+        console.log(`[lifecycle] stop requested for ${req.params.id} source=${actionSource}`);
+        const result = await appLifecycle.stopInstance(req.params.id);
+        invalidateExecutionOwner(req.params.id);
+        if (!result.ok) {
+            const statusCode = result.code === "INSTANCE_NOT_FOUND" ? 404 : 400;
+            return reply.status(statusCode).send({ detail: result.error, ...(result.code ? { code: result.code } : {}) });
         }
-        const result = getInstanceBackedInstalledApp(req.params.id)
-            ? await instanceManager.stopApp(req.params.id)
-            : await svc.stopInstance(req.params.id);
-        statusCache.delete(req.params.id);
-        if (!result.ok)
-            return reply.status(400).send({ detail: result.error });
         return result;
     });
     app.post("/api/instances/:id/service/restart", async (req, reply) => {
@@ -1365,16 +1109,21 @@ export async function instanceRoutes(app) {
         catch (e) {
             return reply.status(e.statusCode || 409).send({ detail: e.message });
         }
-        const svc = await getSvc();
-        if (!instanceManager.getInstance(req.params.id) && !getInstanceBackedInstalledApp(req.params.id)) {
-            return reply.status(404).send({ detail: "Instance not found" });
+        const actionSource = getLifecycleActionSource(req);
+        console.log(`[lifecycle] restart requested for ${req.params.id} source=${actionSource}`);
+        const controlUiOrigin = inferRequestOrigin(req);
+        const result = controlUiOrigin
+            ? await appLifecycle.restartInstance(req.params.id, { controlUiOrigin })
+            : await appLifecycle.restartInstance(req.params.id);
+        invalidateExecutionOwner(req.params.id);
+        if (!result.ok) {
+            const statusCode = result.code === "INSTANCE_NOT_FOUND" ? 404 : 400;
+            return reply.status(statusCode).send({
+                detail: result.error || "Unknown error",
+                ...(result.code ? { code: result.code } : {}),
+            });
         }
-        const result = getInstanceBackedInstalledApp(req.params.id)
-            ? await instanceManager.restartApp(req.params.id)
-            : await svc.restartInstance(req.params.id);
-        statusCache.delete(req.params.id);
-        if (!result.ok)
-            return reply.status(400).send({ detail: result.error || "Unknown error" });
+        markRuntimeRepairRestartApplied(req.params.id);
         return result;
     });
     // ── Pairing ──────────────────────────────────────────────────────────────
@@ -1386,7 +1135,7 @@ export async function instanceRoutes(app) {
         const idErr = validateId(req.params.id);
         if (idErr)
             return reply.status(400).send({ detail: idErr });
-        const inst = instanceManager.getInstance(req.params.id);
+        const inst = appService.getInstance(req.params.id);
         if (!inst) {
             return reply.status(404).send({ detail: "Instance not found" });
         }
@@ -1394,10 +1143,13 @@ export async function instanceRoutes(app) {
         if (!capabilities.pairing.list) {
             return reply.status(501).send({ detail: "Pairing list is not supported for this runtime" });
         }
-        const agentType = resolveAgentType(inst);
+        const integrationKind = resolvePrimaryIntegrationKind(inst);
+        if (!integrationKind) {
+            return reply.status(501).send({ detail: "Pairing list is not supported for this runtime" });
+        }
         const svc = await getSvc();
-        // Pure adapter dispatch — no hardcoded kind fallback.
-        const cmd = await getAdapter(agentType).buildPairingListCommand(req.params.id);
+        // Pure integration dispatch — no hardcoded kind fallback.
+        const cmd = await getIntegration(integrationKind).buildPairingListCommand(req.params.id);
         const result = await svc.exec(req.params.id, cmd, 15_000);
         return { output: result.stdout + result.stderr, exitCode: result.exitCode };
     });
@@ -1405,7 +1157,7 @@ export async function instanceRoutes(app) {
         const idErr = validateId(req.params.id);
         if (idErr)
             return reply.status(400).send({ detail: idErr });
-        const inst = instanceManager.getInstance(req.params.id);
+        const inst = appService.getInstance(req.params.id);
         if (!inst) {
             return reply.status(404).send({ detail: "Instance not found" });
         }
@@ -1420,8 +1172,11 @@ export async function instanceRoutes(app) {
         if (!code || !PAIRING_CODE_RE.test(code)) {
             return reply.status(400).send({ detail: "Invalid pairing code: must be 4-16 uppercase alphanumeric characters" });
         }
-        const agentType = resolveAgentType(inst);
-        const cmd = await getAdapter(agentType).buildPairingApproveCommand(req.params.id, {
+        const integrationKind = resolvePrimaryIntegrationKind(inst);
+        if (!integrationKind) {
+            return reply.status(501).send({ detail: "Pairing approve is not supported for this runtime" });
+        }
+        const cmd = await getIntegration(integrationKind).buildPairingApproveCommand(req.params.id, {
             channel,
             code,
             notify,
@@ -1433,11 +1188,11 @@ export async function instanceRoutes(app) {
         }
         return { ok: true, output: (result.stdout + result.stderr).trim() };
     });
-    // Agent chat (inline chat panel for runtimes that expose an OpenAI-compat
+    // Integration chat (inline chat panel for runtimes that expose an OpenAI-compat
     // HTTP chat completion endpoint and declare chatPanel="inline" in their
     // capability profile — currently only Hermes).
     //
-    // Flow: panel JWT auth → read per-instance API_SERVER_KEY from agent-home/.env →
+    // Flow: panel JWT auth → read per-instance API_SERVER_KEY from integration-home/.env →
     // read allocated host port from runtime.ports → POST forward to
     // http://127.0.0.1:<port>/v1/chat/completions.
     //
@@ -1458,46 +1213,57 @@ export async function instanceRoutes(app) {
         const idErr = validateId(req.params.id);
         if (idErr)
             return reply.status(400).send({ detail: idErr });
-        const rawInst = instanceManager.getInstance(req.params.id);
+        const rawInst = appService.getInstance(req.params.id);
         if (!rawInst)
             return reply.status(404).send({ detail: "Instance not found" });
-        // getInstance returns raw instance.json without `capabilities` (that's
-        // runtime-synthesized per §32.4). Use augmentInstanceMetadata so we
-        // read the adapter's live defaultCapabilities.
+        // getInstance returns raw instance.json without `capabilities` (those are
+        // synthesized by the integration layer). Use augmentInstanceMetadata so we
+        // read the integration's live defaultCapabilities.
         const inst = await augmentInstanceMetadata(req.params.id, rawInst);
+        const integrationKind = resolvePrimaryIntegrationKind(inst);
         // Only runtimes declaring chatPanel="inline" are supported here
-        const chatPanel = inst?.capabilities?.gateway?.chatPanel;
+        const chatPanel = inst?.capabilities?.ui?.chatPanel;
         if (chatPanel !== "inline") {
             return reply.status(400).send({
-                detail: `Runtime "${inst.agentType}" does not support inline chat (chatPanel=${chatPanel})`,
+                detail: `Runtime "${integrationKind ?? "generic"}" does not support inline chat (chatPanel=${chatPanel})`,
             });
         }
-        // Adapter-owned dispatch: the route no longer hardcodes Hermes's env
-        // var name or endpoint path. Any adapter that declares chatPanel
+        // Integration-owned dispatch: the route no longer hardcodes Hermes's env
+        // var name or endpoint path. Any integration that declares chatPanel
         // "inline" MUST also supply `inlineChatDescriptor` (api key env var +
         // optional path/header/timeout) so this forwarder can reach its agent.
-        const agentType = resolveAgentType(inst);
-        const adapter = getAdapter(agentType);
-        const desc = adapter.inlineChatDescriptor;
+        if (!integrationKind) {
+            return reply.status(500).send({
+                detail: `Instance "${req.params.id}" has no integration identity but declared chatPanel=inline`,
+            });
+        }
+        const integration = getIntegration(integrationKind);
+        const desc = integration.inlineChatDescriptor;
         if (!desc) {
             return reply.status(500).send({
-                detail: `Runtime "${agentType}" declares chatPanel=inline but no inlineChatDescriptor`,
+                detail: `Runtime "${integrationKind}" declares chatPanel=inline but no inlineChatDescriptor`,
             });
         }
         // Resolve host port from the persisted RuntimeSpec.ports[] allocation.
-        const ports = Array.isArray(inst?.runtime?.ports) ? inst.runtime.ports : [];
-        const gw = ports.find((p) => p?.name === "gateway") || ports[0];
-        const hostPort = Number(gw?.hostPort) || 0;
-        if (!hostPort) {
-            return reply.status(500).send({ detail: "Gateway host port not allocated" });
+        let hostPort = 0;
+        let gwHost = "127.0.0.1";
+        try {
+            hostPort = appService.getPrimaryHostPort(req.params.id);
+            gwHost = await appService.getPrimaryHostForInstance(req.params.id);
         }
-        // Agent API key lives in the adapter-managed secretEnv file. Adapter
+        catch (error) {
+            if (appService.isCanonicalRuntimePortRequiredError(error)) {
+                return reply.status(error.statusCode || 409).send({ detail: error.message, code: error.code });
+            }
+            throw error;
+        }
+        // Agent API key lives in the integration-managed secretEnv file. Integration
         // declares which env var holds it (Hermes → API_SERVER_KEY).
         const secretEnv = inst?.paths?.secretEnv;
         if (!secretEnv) {
             return reply.status(500).send({ detail: "Instance has no secretEnv path" });
         }
-        const envVars = instanceManager.parseEnvFile(secretEnv);
+        const envVars = appService.parseEnvFile(secretEnv);
         const apiKey = envVars[desc.apiKeyEnvVar] || "";
         if (!apiKey) {
             return reply.status(500).send({
@@ -1508,7 +1274,7 @@ export async function instanceRoutes(app) {
         const authHeader = desc.authHeader ?? "Authorization";
         const authScheme = desc.authScheme ?? "Bearer ";
         // Upstream budget: the Hermes call itself still gets a hard ceiling so
-        // a wedged container can't hold the connection forever. Adapter can
+        // a wedged container can't hold the connection forever. Integration can
         // extend this via inlineChatDescriptor.timeoutMs; default is 30 min
         // which comfortably covers multi-step tool loops.
         const upstreamTimeoutMs = desc.timeoutMs ?? 30 * 60_000;
@@ -1517,8 +1283,7 @@ export async function instanceRoutes(app) {
         // on modern Linux (Debian 12, Ubuntu 22.04+) that's frequently `::1`
         // rather than `127.0.0.1` — so a hardcoded IPv4 fetch() returns
         // ECONNREFUSED and the user sees "Failed to reach agent".
-        const gwHost = await instanceManager.getGatewayHost(req.params.id);
-        const target = `http://${instanceManager.urlHost(gwHost)}:${hostPort}${endpointPath}`;
+        const target = `http://${appService.urlHost(gwHost)}:${hostPort}${endpointPath}`;
         // Hijack the response so we own the raw socket — lets us flush SSE
         // headers + heartbeats before the upstream fetch resolves.
         reply.hijack();
@@ -1584,7 +1349,7 @@ export async function instanceRoutes(app) {
         const idErr = validateId(req.params.id);
         if (idErr)
             return reply.status(400).send({ detail: idErr });
-        if (!instanceManager.getInstance(req.params.id) && !getInstanceBackedInstalledApp(req.params.id)) {
+        if (!appService.getInstance(req.params.id)) {
             return reply.status(404).send({ detail: "Instance not found" });
         }
         try {
@@ -1684,19 +1449,16 @@ export async function instanceRoutes(app) {
         const idErr = validateId(req.params.id);
         if (idErr)
             return reply.status(400).send({ detail: idErr });
-        const svc = await getSvc();
-        if (!instanceManager.getInstance(req.params.id) && !getInstanceBackedInstalledApp(req.params.id)) {
-            return reply.status(404).send({ detail: "Instance not found" });
-        }
         const logType = req.query.log_type || "stderr";
         if (logType !== "stdout" && logType !== "stderr") {
             return reply.status(400).send({ detail: "log_type must be stdout or stderr" });
         }
         const MAX_LOG_LINES = 5000;
         const lines = Math.min(parseInt(req.query.lines || "100", 10) || 100, MAX_LOG_LINES);
-        const logLines = getInstanceBackedInstalledApp(req.params.id)
-            ? await instanceManager.getAppLogs(req.params.id, "", lines, logType)
-            : await svc.getLogs(req.params.id, lines, logType);
+        const logLines = await appLifecycle.getManagedLogs(req.params.id, lines, logType);
+        if (!logLines) {
+            return reply.status(404).send({ detail: "Instance not found" });
+        }
         return { lines: logLines };
     });
     // Admin: re-encrypt all instance secrets with current AES key
@@ -1704,12 +1466,12 @@ export async function instanceRoutes(app) {
         const { getAesKey, getJwtSecret } = await import("../config.js");
         const { scryptSync, createDecipheriv, createCipheriv, randomBytes } = await import("crypto");
         const { readFileSync, existsSync: fsExistsSync } = await import("fs");
-        const instances = instanceManager.listInstances();
+        const instances = appService.listInstances();
         const results = [];
         const currentKey = getAesKey();
         const legacyKey = scryptSync(getJwtSecret(), "jishushell-apikey-v1", 32);
         for (const inst of instances) {
-            const envFiles = instanceManager.getRuntimeEnvFiles(inst.id);
+            const envFiles = appService.getRuntimeEnvFiles(inst.id);
             const providerEnvFile = envFiles[0]?.replace(/model\.env$/, "provider.env");
             if (!providerEnvFile || !fsExistsSync(providerEnvFile)) {
                 results.push({ id: inst.id, status: "skipped", error: "no provider.env" });
@@ -1770,13 +1532,13 @@ export async function instanceRoutes(app) {
         // Invalidate proxy config cache for migrated instances
         for (const r of results) {
             if (r.status === "migrated")
-                llmProxy.invalidateConfigCache(r.id);
+                invalidateConfigCache(r.id);
         }
         return { ok: true, results };
     });
     // ── Docker image check & pull ───────────────────────────────────────────
     // Generic Docker operations used by NewInstance UI to verify / pull runtime
-    // images before creating an instance. Framework-level (not adapter-scoped)
+    // images before creating an instance. Framework-level (not integration-scoped)
     // because every container runtime shares the same docker CLI here.
     app.get("/api/docker/image-check", async (req, reply) => {
         const image = req.query.image;
@@ -1787,14 +1549,20 @@ export async function instanceRoutes(app) {
         if (!/^[a-zA-Z0-9][a-zA-Z0-9\-_.:/@]*$/.test(image) || image.length > 256) {
             return reply.status(400).send({ detail: "Invalid Docker image name" });
         }
-        try {
-            const { execFileSync } = await import("child_process");
-            execFileSync("docker", ["image", "inspect", image], { timeout: 10000, stdio: "ignore" });
+        const { inspectDockerImage, toDockerInspectUserError } = await import("../utils/docker-inspect.js");
+        const result = inspectDockerImage(image, { timeout: 10000 });
+        if (result.ok) {
             return { exists: true, image };
         }
-        catch {
+        if (result.reason === "not_found")
             return { exists: false, image };
-        }
+        const inspectError = toDockerInspectUserError(image, result);
+        return reply.status(inspectError.statusCode).send({
+            detail: inspectError.message,
+            code: inspectError.code,
+            exists: false,
+            image,
+        });
     });
     app.post("/api/docker/image-pull", async (req, reply) => {
         const image = req.body?.image;
@@ -1815,163 +1583,34 @@ export async function instanceRoutes(app) {
             return reply.status(500).send({ detail: `Failed to pull image: ${e.message}` });
         }
     });
-    // ── Connections REST API (PR 4 of app-interconnect-design) ──────────────
+    // ── Connections REST API ────────────────────────────────────────────────
     /** GET /api/instances/:id/connections — view spec.requires + bindings. */
     app.get("/api/instances/:id/connections", async (req, reply) => {
-        const idErr = validateId(req.params.id);
-        if (idErr)
-            return reply.status(400).send({ detail: idErr });
-        const meta = instanceManager.getInstance(req.params.id);
-        if (!meta)
-            return reply.status(404).send({ detail: "Instance not found" });
-        const specInfo = await loadConnectionsSpec(meta);
-        if (!specInfo) {
-            // Truly unknown agent type or missing spec — empty Connections view.
-            return { requires: [], connections: {}, pending: [] };
-        }
-        const { resolveConnections } = await import("../services/connection-resolver.js");
-        const capabilityRegistry = await import("../services/capability-registry.js");
-        const persistedConnections = (meta.connections ?? {});
-        const { resolved, pending } = resolveConnections(specInfo.spec, { connections: persistedConnections }, "preCreate");
-        // For UI display: each require slot, candidates pulled from registry.
-        // Two filters keep nonsensical bindings out of the dropdown:
-        //   1. Self-binding — an instance must never appear in its own slot's
-        //      candidates. Without this, e.g. hermes-h shows up as a candidate
-        //      for hermes-h's own `llm` slot, which would create an infinite
-        //      self-call loop at apply time.
-        //   2. Agent-on-agent — agent runtimes (hermes / openclaw) consume
-        //      `llm` for their internal reasoning. Letting them bind another
-        //      agent's `llm-agent` capability would chain agent → agent →
-        //      llm provider, which is structurally wrong (the inner agent is
-        //      not a model). Only true LLM model providers (capability
-        //      `llm-<vendor>` like `llm-ollama`, `llm-openai`) are valid.
-        //      The `llm-agent` capability stays available to non-agent
-        //      consumers (OpenWebUI etc.) where agent-as-LLM makes sense.
-        const consumerAgentType = String(meta?.agentType ?? "");
-        const consumerIsAgent = consumerAgentType === "hermes" || consumerAgentType === "openclaw";
-        const requires = (specInfo.spec.requires ?? []).map((r) => {
-            const isCategoryToken = ["llm", "search", "browser", "mcp", "files", "knowledge"].includes(r.capability);
-            const candidates = isCategoryToken
-                ? Object.entries(capabilityRegistry.snapshot().providersByCapability ?? {})
-                    .filter(([cap]) => cap.startsWith(r.capability + "-") || cap === r.capability)
-                    .flatMap(([_, list]) => list)
-                : capabilityRegistry.listProviders(r.capability);
-            const filtered = candidates.filter((c) => {
-                if (c.instanceId === req.params.id)
-                    return false;
-                if (consumerIsAgent && r.capability === "llm" && c.capability === "llm-agent")
-                    return false;
-                return true;
-            });
-            return {
-                capability: r.capability,
-                inject_as: r.inject_as,
-                required: r.required !== false,
-                cardinality: r.cardinality ?? "one",
-                apply: r.apply,
-                category: isCategoryToken ? r.capability : "default",
-                candidates: filtered.map((c) => ({
-                    providerId: c.instanceId,
-                    capability: c.capability,
-                    name: c.name,
-                    protocol: c.protocol,
-                    status: c.status,
-                    hostPort: c.hostPort,
-                    path: c.path,
-                })),
-            };
-        });
-        return {
-            requires,
-            connections: persistedConnections,
-            pending: pending.map((p) => ({
-                slot: p.slot,
-                capability: p.capability,
-                reason: p.reason,
-                required: p.required,
-            })),
-            // resolved is internal — surface as debug to help UI understand state.
-            _resolved: resolved.map((r) => ({
-                slot: r.slot,
-                capability: r.capability,
-                category: r.category,
-                source: r.source,
-                providerCount: r.entries.length,
-            })),
-        };
-    });
-    /** PUT /api/instances/:id/connections — save bindings via transactor. */
-    app.put("/api/instances/:id/connections", async (req, reply) => {
-        const idErr = validateId(req.params.id);
-        if (idErr)
-            return reply.status(400).send({ detail: idErr });
-        const meta = instanceManager.getInstance(req.params.id);
-        if (!meta)
-            return reply.status(404).send({ detail: "Instance not found" });
-        const specInfo = await loadConnectionsSpec(meta);
-        if (!specInfo) {
-            return reply.status(400).send({
-                detail: "Connections only available for app-installed instances",
-                code: "NOT_APP_INSTANCE",
-            });
-        }
-        const newConnections = (req.body?.connections ?? {});
-        const { applyConnections } = await import("../services/connection-transactor.js");
-        const safeJson = await import("../utils/safe-json.js");
-        const fs = await import("fs");
-        const path = await import("path");
-        const instancePath = instanceManager.instanceMetaPath(req.params.id);
-        const readInstanceJson = async (_id) => {
-            const cur = safeJson.safeReadJson(instancePath, `instance:${req.params.id}`);
-            return (cur ?? {});
-        };
-        const saveInstanceJson = async (_id, mutator) => {
-            const cur = safeJson.safeReadJson(instancePath, `instance:${req.params.id}`) ?? {};
-            const updated = mutator(cur);
-            // Ensure parent dir exists (instance dir is always there for app instances).
-            try {
-                fs.mkdirSync(path.dirname(instancePath), { recursive: true });
-            }
-            catch {
-                /* noop */
-            }
-            safeJson.safeWriteJson(instancePath, updated);
-        };
-        // Adapter resolution — adapter-managed consumers route writeConnectionEnv
-        // through adapter.applyConnectionEnv; generic apps go through
-        // instance.json["connections-env"].
-        let adapter = null;
         try {
-            const agentType = resolveAgentType(meta);
-            if (hasAdapter(agentType)) {
-                adapter = getAdapter(agentType);
-                // Only expose the optional methods if the adapter implements them.
-                if (typeof adapter.applyConnectionEnv !== "function")
-                    adapter = null;
-            }
+            return await getConnectionSummary(req.params.id);
         }
-        catch {
-            adapter = null;
+        catch (e) {
+            if (isConnectionAdminError(e)) {
+                const detail = e.code === "APP_NOT_FOUND" ? "Instance not found" : e.message;
+                return reply.status(e.statusCode).send({ detail, code: e.code });
+            }
+            throw e;
         }
+    });
+    /** PUT /api/instances/:id/connections — save bindings via transactor. */
+    app.put("/api/instances/:id/connections", async (req, reply) => {
         try {
-            const result = await applyConnections({
-                instance: meta,
-                spec: specInfo.spec,
-                newConnections,
-                saveInstanceJson,
-                readInstanceJson,
-                adapter,
-            });
-            return {
-                ok: true,
-                resolved: result.resolved.map((r) => ({
-                    slot: r.slot,
-                    capability: r.capability,
-                    category: r.category,
-                })),
-            };
+            return await replaceConnections(req.params.id, (req.body?.connections ?? {}));
         }
         catch (e) {
+            if (isConnectionAdminError(e)) {
+                const detail = e.code === "APP_NOT_FOUND" ? "Instance not found" : e.message;
+                return reply.status(e.statusCode).send({
+                    detail,
+                    code: e.code,
+                    ...(e.details ? { details: e.details } : {}),
+                });
+            }
             const status = e?.statusCode ?? 500;
             return reply.status(status).send({
                 detail: e?.message ?? "Connection apply failed",
@@ -1982,91 +1621,24 @@ export async function instanceRoutes(app) {
     });
     /** GET /api/instances/:id/connection-status — UI badge state. */
     app.get("/api/instances/:id/connection-status", async (req, reply) => {
-        const idErr = validateId(req.params.id);
-        if (idErr)
-            return reply.status(400).send({ detail: idErr });
-        const meta = instanceManager.getInstance(req.params.id);
-        if (!meta)
-            return reply.status(404).send({ detail: "Instance not found" });
-        const specInfo = await loadConnectionsSpec(meta);
-        if (!specInfo)
-            return { state: "empty", unboundRequired: [], unboundOptional: [] };
-        // An instance with no `requires` slots (pure provider — e.g. SearXNG,
-        // Ollama, Browserless) has nothing to bind. Returning `ok` would
-        // surface a misleading "Connected" badge in the UI; treat it as
-        // empty so the badge / Connect-Apps menu entry hide entirely
-        // (ConnectionsBadge already returns null on `empty`).
-        if (!Array.isArray(specInfo.spec.requires) || specInfo.spec.requires.length === 0) {
-            return { state: "empty", unboundRequired: [], unboundOptional: [] };
-        }
-        const { resolveConnections } = await import("../services/connection-resolver.js");
         try {
-            const { pending, resolved } = resolveConnections(specInfo.spec, { connections: (meta.connections ?? {}) }, "preCreate");
-            const hiddenSlots = new Set((specInfo.spec.requires ?? [])
-                .filter((req) => HIDDEN_CONNECTION_STATUS_CAPABILITIES.has(req.capability))
-                .map((req) => req.inject_as));
-            const visibleRequires = (specInfo.spec.requires ?? []).filter((req) => !hiddenSlots.has(req.inject_as));
-            if (visibleRequires.length === 0) {
-                return { state: "empty", unboundRequired: [], unboundOptional: [], bindable: 0 };
-            }
-            // Stale bindings — slot is bound (in `resolved`) but at least one
-            // bound provider entry is no longer running. preCreate mode skips
-            // the runtime status check so these otherwise stay invisible to
-            // the badge; surface them as synthetic pending so the badge drops
-            // out of `ok`.
-            const stalePending = resolved
-                .filter((r) => r.entries.some((e) => e.status !== "running"))
-                .map((r) => ({ slot: r.slot, capability: r.capability, required: r.required }));
-            const staleSlots = new Set(stalePending.map((p) => p.slot));
-            const allPending = [...pending, ...stalePending];
-            const visiblePending = allPending.filter((p) => !hiddenSlots.has(p.slot));
-            const unboundRequired = visiblePending.filter((p) => p.required).map((p) => p.slot);
-            const unboundOptional = visiblePending.filter((p) => !p.required).map((p) => p.slot);
-            // Count slots that the user can act on right now — i.e. unbound
-            // visible slots whose capability has at least one running candidate
-            // in the registry. Hidden categories like MCP should neither show
-            // cards in the UI nor inflate the badge count. Stale slots are
-            // always actionable (re-bind or start the bound provider) so they
-            // count even when no other candidate is running.
-            const capabilityRegistry = await import("../services/capability-registry.js");
-            const consumerAgentType = String(meta?.agentType ?? "");
-            const consumerIsAgent = consumerAgentType === "hermes" || consumerAgentType === "openclaw";
-            const isCategoryToken = (cap) => ["llm", "search", "browser", "mcp"].includes(cap);
-            const enumerateRunning = (cap) => {
-                const list = isCategoryToken(cap)
-                    ? Object.entries(capabilityRegistry.snapshot().providersByCapability ?? {})
-                        .filter(([k]) => k.startsWith(cap + "-") || k === cap)
-                        .flatMap(([_, v]) => v)
-                    : capabilityRegistry.listProviders(cap);
-                return list.filter((c) => {
-                    if (c.status !== "running")
-                        return false;
-                    if (c.instanceId === req.params.id)
-                        return false;
-                    if (consumerIsAgent && cap === "llm" && c.capability === "llm-agent")
-                        return false;
-                    return true;
-                });
-            };
-            const bindable = visiblePending.filter((p) => staleSlots.has(p.slot) || enumerateRunning(p.capability).length > 0).length;
-            let state = "ok";
-            if (unboundRequired.length > 0)
-                state = "error";
-            else if (bindable > 0)
-                state = "warn";
-            return { state, unboundRequired, unboundOptional, bindable };
+            return await getConnectionStatus(req.params.id);
         }
         catch (e) {
+            if (isConnectionAdminError(e)) {
+                const detail = e.code === "APP_NOT_FOUND" ? "Instance not found" : e.message;
+                return reply.status(e.statusCode).send({ detail, code: e.code });
+            }
             return { state: "error", unboundRequired: [], unboundOptional: [], bindable: 0, error: e.message };
         }
     });
     // ── Suggestions API (PR 6) ─────────────────────────────────────────────
     app.get("/api/suggestions", async () => {
-        const { computeSuggestions } = await import("../services/suggestions.js");
+        const { computeSuggestions } = await import("../services/connections/suggestions.js");
         return { suggestions: computeSuggestions() };
     });
     app.post("/api/suggestions/:id/apply", async (req, reply) => {
-        const { computeSuggestions } = await import("../services/suggestions.js");
+        const { computeSuggestions } = await import("../services/connections/suggestions.js");
         const all = computeSuggestions();
         const target = all.find((s) => s.id === req.params.id);
         if (!target) {
@@ -2075,26 +1647,22 @@ export async function instanceRoutes(app) {
         // Apply by issuing the equivalent PUT /connections — read current
         // bindings, splice in the new one for `slot`, persist via the
         // transactor.
-        const meta = instanceManager.getInstance(target.consumerInstanceId);
+        const meta = appService.getInstance(target.consumerInstanceId);
         if (!meta)
             return reply.status(404).send({ detail: "Consumer instance not found" });
-        // Resolve consumer spec — app-installed instances have it in the app
-        // registry; legacy instances (no app_id) fall back to the
-        // yaml-template synthesizer used everywhere else for legacy
-        // capability work.
-        let consumerSpec = null;
-        if (target.appId) {
-            const appData = instanceManager.getApp(target.appId);
-            if (!appData)
-                return reply.status(404).send({ detail: "App spec not found" });
-            consumerSpec = appData.spec;
-        }
-        else {
-            const { loadCapabilitySpecForLegacyInstance } = await import("../services/runtime/migrations.js");
-            consumerSpec = loadCapabilitySpecForLegacyInstance(meta);
-            if (!consumerSpec) {
-                return reply.status(404).send({ detail: "No capability spec for legacy instance" });
-            }
+        // Resolve consumer spec from canonical sources only. The suggestion
+        // target is an instance id; AppSpec id is only the template identity.
+        const appData = appService.getInstanceInstallRecord(target.consumerInstanceId);
+        let consumerSpec = appData?.spec ?? null;
+        if (!consumerSpec) {
+            const { readCanonicalSpecForInstance } = await import("../services/app-common/instance-store.js");
+            consumerSpec = readCanonicalSpecForInstance(target.consumerInstanceId);
+        }
+        if (!consumerSpec) {
+            return reply.status(409).send({
+                detail: "Instance has no canonical AppSpec; run `jishushell migrate legacy --yes` first",
+                code: "INSTANCE_NEEDS_MIGRATION",
+            });
         }
         const newConnections = {
             ...(meta.connections ?? {}),
@@ -2104,11 +1672,11 @@ export async function instanceRoutes(app) {
                 capability: target.candidate.capability,
             },
         };
-        const { applyConnections } = await import("../services/connection-transactor.js");
+        const { applyConnections } = await import("../services/connections/transactor.js");
         const safeJson = await import("../utils/safe-json.js");
         const fs = await import("fs");
         const path = await import("path");
-        const instancePath = instanceManager.instanceMetaPath(target.consumerInstanceId);
+        const instancePath = appService.instanceMetaPath(target.consumerInstanceId);
         const readInstanceJson = async () => (safeJson.safeReadJson(instancePath, `instance:${target.consumerInstanceId}`) ?? {});
         const saveInstanceJson = async (_id, mutator) => {
             const cur = (safeJson.safeReadJson(instancePath, `instance:${target.consumerInstanceId}`) ?? {});
@@ -2120,17 +1688,22 @@ export async function instanceRoutes(app) {
             }
             safeJson.safeWriteJson(instancePath, mutator(cur));
         };
-        let adapter = null;
-        try {
-            const agentType = resolveAgentType(meta);
-            if (hasAdapter(agentType)) {
-                adapter = getAdapter(agentType);
-                if (typeof adapter.applyConnectionEnv !== "function")
-                    adapter = null;
+        let integration = null;
+        const hasIntegrationMetadata = Array.isArray(meta.integrations)
+            && meta.integrations.length > 0;
+        if (hasIntegrationMetadata) {
+            const integrationKind = resolvePrimaryIntegrationKind(meta);
+            if (!integrationKind || !hasIntegration(integrationKind)) {
+                return reply.status(409).send({
+                    detail: "Instance is missing canonical integration identity; run migration or repair first",
+                    code: "INSTANCE_NEEDS_MIGRATION",
+                });
             }
-        }
-        catch {
-            adapter = null;
+            const resolvedIntegration = getIntegration(integrationKind);
+            integration =
+                typeof resolvedIntegration.applyConnectionEnv === "function"
+                    ? resolvedIntegration
+                    : null;
         }
         try {
             const result = await applyConnections({
@@ -2139,7 +1712,7 @@ export async function instanceRoutes(app) {
                 newConnections,
                 saveInstanceJson,
                 readInstanceJson,
-                adapter,
+                integration,
             });
             return { ok: true, applied: target.id, resolved: result.resolved.length };
         }
@@ -2151,7 +1724,7 @@ export async function instanceRoutes(app) {
         }
     });
     app.post("/api/suggestions/:id/dismiss", async (req, reply) => {
-        const { dismissSuggestion } = await import("../services/suggestions.js");
+        const { dismissSuggestion } = await import("../services/connections/suggestions.js");
         try {
             await dismissSuggestion(req.params.id);
             return { ok: true };
@@ -2160,19 +1733,5 @@ export async function instanceRoutes(app) {
             return reply.status(400).send({ detail: e?.message ?? "Invalid suggestion id" });
         }
     });
-    // ── Adapter-owned routes (§32.2.5) ─────────────────────────────────────
-    // Each registered runtime adapter may contribute its own HTTP endpoints.
-    // OpenClaw owns plugins/mcporter/skills/feishu/weixin/usage/gateway-launch/
-    // gateway proxy; Hermes currently owns none. Adding a new agent that
-    // needs custom routes is a matter of implementing registerRoutes() in
-    // the adapter — the framework layer never hard-codes kind-specific paths.
-    for (const adapter of listRegisteredAdapters()) {
-        try {
-            await adapter.registerRoutes?.(app);
-        }
-        catch (err) {
-            console.error(`[instances] adapter ${adapter.agentType} registerRoutes failed:`, err);
-        }
-    }
 }
 //# sourceMappingURL=instances.js.map