jishushell 0.6.5 → 0.6.18

package/dist/routes/instances.js

@@ -1,21 +1,25 @@
 import { getServiceManagerType } from "../config.js";
-import { assertNotLocked } from "../services/backup-manager.js";
-import * as instanceManager from "../services/app/app-manager.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/instance-admin.js";
-import { getConnectionStatus, getConnectionSummary, isConnectionAdminError, replaceConnections, } from "../services/connection-admin.js";
-import { getAppConfigMeta, isAppConfigAdminError, readAppConfig, writeAppConfig, } from "../services/app-config-admin.js";
-import { augmentInstanceMetadata, getInstanceCapabilities, resolveAgentType, } from "../services/runtime/instance.js";
-import { getAdapter, hasAdapter } from "../services/runtime/index.js";
-import { invalidateRuntimeIdentity, resolveRuntimeIdentity, } from "../services/runtime-identity.js";
-import { acknowledgeRuntimeRestartAdvisory } from "../services/system-reconciler.js";
-import { assertTerminalSessionOwner, getTerminalSession, getTerminalSessionEvents, sendTerminalSessionInput, startTerminalSession, stopTerminalSession, subscribeTerminalSession, } from "../services/app/terminal-session-manager.js";
-import { TtlMap } from "../utils/ttl-cache.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",
@@ -77,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}`)
         : "/";
@@ -90,244 +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("");
-}
-const JISHU_KB_PRELOAD_SESSION_LIMIT = 50;
-const JISHU_KB_PRELOAD_MESSAGE_LIMIT = 20;
-const JISHU_KB_PRELOAD_TIMEOUT_MS = 5_000;
-const JISHU_KB_PRELOAD_GLOBAL = "__JISHU_KB_PRELOADED_SESSIONS__";
-function trimString(value) {
-    return typeof value === "string" ? value.trim() : "";
-}
-function parseJishuKbConversationId(value) {
-    if (typeof value === "number") {
-        return Number.isSafeInteger(value) && value > 0 ? value : null;
+function capabilityProxyCleanupToken(parts) {
+    const hash = createHash("sha256");
+    for (const part of parts) {
+        hash.update(part ?? "");
+        hash.update("\0");
     }
-    const raw = trimString(value);
-    if (!/^\d+$/.test(raw))
-        return null;
-    const parsed = Number(raw);
-    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
-}
-function parseJishuKbTimestamp(value) {
-    const numeric = typeof value === "number" ? value : Number(value);
-    return Number.isFinite(numeric) ? numeric : 0;
+    return hash.digest("hex").slice(0, 32);
 }
-function parseJishuKbRole(value) {
-    const normalized = trimString(value);
-    return normalized === "user" || normalized === "assistant" || normalized === "system"
-        ? normalized
-        : null;
-}
-function parseJishuKbCitations(value) {
-    if (Array.isArray(value))
-        return value;
-    if (typeof value !== "string" || !value.trim())
-        return undefined;
-    try {
-        const parsed = JSON.parse(value);
-        return Array.isArray(parsed) ? parsed : undefined;
-    }
-    catch {
-        return undefined;
-    }
+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;
+    });
 }
-function relayAbort(parentSignal, controller) {
-    if (parentSignal.aborted) {
-        controller.abort(parentSignal.reason);
-        return () => { };
+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`);
     }
-    const abort = () => controller.abort(parentSignal.reason);
-    parentSignal.addEventListener("abort", abort, { once: true });
-    return () => parentSignal.removeEventListener("abort", abort);
-}
-async function fetchJsonWithTimeout(upstreamOrigin, relativePath, parentSignal) {
-    const controller = new AbortController();
-    const cleanupAbort = relayAbort(parentSignal, controller);
-    const timer = setTimeout(() => controller.abort(new Error("timeout")), JISHU_KB_PRELOAD_TIMEOUT_MS);
-    try {
-        const response = await fetch(new URL(relativePath, `${upstreamOrigin}/`).toString(), {
-            headers: { accept: "application/json" },
-            signal: controller.signal,
-        });
-        if (!response.ok) {
-            const detail = (await response.text()).slice(0, 200);
-            throw new Error(`${relativePath} -> ${response.status}${detail ? `: ${detail}` : ""}`);
-        }
-        return await response.json();
+    if (capability.protocol !== "http" && capability.protocol !== "https") {
+        throw new Error(`Capability '${capabilityName}' does not use HTTP(S)`);
     }
-    finally {
-        clearTimeout(timer);
-        cleanupAbort();
+    const runtimePort = appService.resolveRuntimeCapabilityPort(instanceId, capabilityName);
+    if (typeof runtimePort !== "number" || runtimePort < 1) {
+        throw new Error(`Capability '${capabilityName}' has no resolved port`);
     }
-}
-async function loadJishuKbPreloadedSessions(upstreamOrigin, parentSignal) {
-    const kbList = await fetchJsonWithTimeout(upstreamOrigin, "/api/kb", parentSignal);
-    const kbIds = Array.from(new Set((Array.isArray(kbList) ? kbList : [])
-        .map((kb) => trimString(kb?.id))
-        .filter(Boolean)));
-    if (!kbIds.length)
-        kbIds.push("default");
-    const conversationLists = await Promise.all(kbIds.map(async (kbId) => {
-        const query = new URLSearchParams({ kb_id: kbId }).toString();
-        const rows = await fetchJsonWithTimeout(upstreamOrigin, `/api/conversations?${query}`, parentSignal);
-        return Array.isArray(rows)
-            ? rows.map((row) => ({
-                ...row,
-                kb_id: trimString(row?.kb_id) || kbId,
-            }))
-            : [];
-    }));
-    const selected = conversationLists
-        .flat()
-        .sort((left, right) => parseJishuKbTimestamp(right.updated_at) - parseJishuKbTimestamp(left.updated_at))
-        .slice(0, JISHU_KB_PRELOAD_SESSION_LIMIT);
-    const hydrated = await Promise.all(selected.map(async (conversation) => {
-        const conversationId = parseJishuKbConversationId(conversation.id);
-        const kbId = trimString(conversation.kb_id);
-        if (!conversationId || !kbId) {
-            console.warn("[cap-proxy] skipping jishukb conversation preload with unsupported id/kb", {
-                id: conversation.id,
-                kbId,
-            });
-            return null;
-        }
-        const messages = await fetchJsonWithTimeout(upstreamOrigin, `/api/conversations/${encodeURIComponent(String(conversationId))}/messages`, parentSignal);
-        const normalizedMessages = (Array.isArray(messages) ? messages : [])
-            .map((message) => {
-            const role = parseJishuKbRole(message?.role);
-            const content = typeof message?.content === "string" ? message.content : "";
-            if (!role || !content)
-                return null;
-            const cites = parseJishuKbCitations(message?.citations);
-            return cites?.length
-                ? { role, content, cites }
-                : { role, content };
-        })
-            .filter((message) => message !== null)
-            .slice(-JISHU_KB_PRELOAD_MESSAGE_LIMIT);
-        return {
-            id: conversationId,
-            kb: kbId,
-            title: trimString(conversation.title) || "Untitled",
-            msgs: normalizedMessages,
-            _syncedMsgIdx: normalizedMessages.length,
-        };
-    }));
-    return hydrated
-        .filter((session) => session !== null)
-        .sort((left, right) => left.id - right.id);
-}
-function jishuKbConversationBootstrap(preloadedSessions) {
-    const serialized = JSON.stringify(preloadedSessions);
-    const globalName = JSON.stringify(JISHU_KB_PRELOAD_GLOBAL);
-    return [
-        "<script>(function(){",
-        "try{",
-        `var incoming=${serialized};`,
-        `window[${globalName}]=incoming;`,
-        "var current=[];",
-        "try{var raw=window.localStorage.getItem('jkb_sess');current=raw?JSON.parse(raw):[];}catch(_e){current=[];}",
-        "if(!Array.isArray(current))current=[];",
-        "var seen=Object.create(null);",
-        "var merged=[];",
-        "function key(entry){return String(entry&&entry.kb||'')+'::'+String(entry&&entry.id||'');}",
-        "function push(entry){if(!entry||typeof entry!=='object')return;var k=key(entry);if(seen[k])return;seen[k]=1;merged.push(entry);}",
-        "incoming.forEach(push);",
-        "current.forEach(push);",
-        "merged.sort(function(a,b){return Number(a&&a.id||0)-Number(b&&b.id||0);});",
-        `if(merged.length>${JISHU_KB_PRELOAD_SESSION_LIMIT})merged=merged.slice(-${JISHU_KB_PRELOAD_SESSION_LIMIT});`,
-        "window.localStorage.setItem('jkb_sess',JSON.stringify(merged));",
-        "}catch(_e){}",
-        "})();</script>",
-    ].join("");
+    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`,
@@ -697,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)
@@ -727,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` });
@@ -743,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("?")) : "";
@@ -914,18 +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);
-            }
-            if (willInjectHtml && req.params.capability === "web-jishukb") {
-                try {
-                    const preloadedSessions = await loadJishuKbPreloadedSessions(upstreamOrigin, upstreamAbort.signal);
-                    extraHeadHtml += jishuKbConversationBootstrap(preloadedSessions);
-                }
-                catch (error) {
-                    console.warn("[cap-proxy] jishukb conversation preload skipped:", error);
-                }
-            }
+            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.
@@ -934,24 +748,37 @@ 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();
             reply.raw.off("close", onClientClose);
             const rewritten = rewriteProxyTextBody(rawBody, upstreamContentType, proxyBasePath, extraHeadHtml);
             return reply.send(rewritten);
@@ -970,25 +797,6 @@ async function proxyProvidedCapability(req, reply) {
         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 = "";
@@ -996,80 +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;
 }
-function getInstanceBackedInstalledApp(instanceId) {
-    return instanceManager.getApp(instanceId);
-}
-function shouldUseAppManager(identity) {
-    if (!identity)
-        return false;
-    if (identity.driver === "app-job")
-        return true;
-    return identity.driver === "local-model" && !!getInstanceBackedInstalledApp(identity.id);
-}
-function shouldUseAppManagerForId(instanceId, identity) {
-    return shouldUseAppManager(identity) || (!identity && !!getInstanceBackedInstalledApp(instanceId));
-}
-function hasRuntimeIdentity(instanceId) {
-    return resolveRuntimeIdentity(instanceId) != null
-        || !!instanceManager.getInstance(instanceId)
-        || !!getInstanceBackedInstalledApp(instanceId);
+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";
 }
-// 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 identity = resolveRuntimeIdentity(instanceId);
-    const statusPromise = shouldUseAppManagerForId(instanceId, identity)
-        ? 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;
-    });
-}
-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],
@@ -1097,16 +861,51 @@ export async function instanceRoutes(app) {
             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,
@@ -1130,11 +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" });
-        invalidateRuntimeIdentity(req.params.id);
-        return inst;
+        invalidateExecutionOwner(req.params.id);
+        return augmentInstanceMetadata(req.params.id, inst);
     });
     // Delete
     app.delete("/api/instances/:id", async (req, reply) => {
@@ -1147,61 +946,35 @@ 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);
-            invalidateRuntimeIdentity(req.params.id);
-            cleanupProxyInstance(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;
-        try {
-            await svc.stopInstance(req.params.id, true);
-        }
-        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 { /* ignore */ }
-        statusCache.delete(req.params.id);
-        invalidateRuntimeIdentity(req.params.id);
-        cleanupProxyInstance(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 };
+        return { ok: true, warnings: result.warnings?.length ? result.warnings : undefined };
     });
     // Config
     app.get("/api/instances/:id/config-meta", async (req, reply) => {
@@ -1245,15 +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();
-        const identity = resolveRuntimeIdentity(req.params.id);
-        if (!identity && !hasRuntimeIdentity(req.params.id)) {
-            return reply.status(404).send({ detail: "Instance not found" });
+        let status;
+        try {
+            status = await appLifecycle.getManagedStatus(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 (shouldUseAppManagerForId(req.params.id, identity)) {
-            return instanceManager.getAppStatus(req.params.id);
+        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);
@@ -1265,21 +1043,18 @@ export async function instanceRoutes(app) {
         catch (e) {
             return reply.status(e.statusCode || 409).send({ detail: e.message });
         }
-        const svc = await getSvc();
-        const identity = resolveRuntimeIdentity(req.params.id);
-        if (!identity && !hasRuntimeIdentity(req.params.id)) {
-            return reply.status(404).send({ detail: "Instance not found" });
-        }
-        const result = shouldUseAppManagerForId(req.params.id, identity)
-            ? await instanceManager.startApp(req.params.id)
-            : await svc.startInstance(req.params.id);
-        statusCache.delete(req.params.id);
-        invalidateRuntimeIdentity(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)
@@ -1290,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.
@@ -1298,7 +1076,7 @@ export async function instanceRoutes(app) {
                 : 400;
             return reply.status(statusCode).send(payload);
         }
-        await acknowledgeRuntimeRestartAdvisory(req.params.id);
+        markRuntimeRepairRestartApplied(req.params.id);
         return result;
     });
     app.post("/api/instances/:id/service/stop", async (req, reply) => {
@@ -1311,18 +1089,14 @@ export async function instanceRoutes(app) {
         catch (e) {
             return reply.status(e.statusCode || 409).send({ detail: e.message });
         }
-        const svc = await getSvc();
-        const identity = resolveRuntimeIdentity(req.params.id);
-        if (!identity && !hasRuntimeIdentity(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 = shouldUseAppManagerForId(req.params.id, identity)
-            ? await instanceManager.stopApp(req.params.id)
-            : await svc.stopInstance(req.params.id);
-        statusCache.delete(req.params.id);
-        invalidateRuntimeIdentity(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) => {
@@ -1335,19 +1109,21 @@ export async function instanceRoutes(app) {
         catch (e) {
             return reply.status(e.statusCode || 409).send({ detail: e.message });
         }
-        const svc = await getSvc();
-        const identity = resolveRuntimeIdentity(req.params.id);
-        if (!identity && !hasRuntimeIdentity(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 = shouldUseAppManagerForId(req.params.id, identity)
-            ? await instanceManager.restartApp(req.params.id)
-            : await svc.restartInstance(req.params.id);
-        statusCache.delete(req.params.id);
-        invalidateRuntimeIdentity(req.params.id);
-        if (!result.ok)
-            return reply.status(400).send({ detail: result.error || "Unknown error" });
-        await acknowledgeRuntimeRestartAdvisory(req.params.id);
+        markRuntimeRepairRestartApplied(req.params.id);
         return result;
     });
     // ── Pairing ──────────────────────────────────────────────────────────────
@@ -1359,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" });
         }
@@ -1367,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 };
     });
@@ -1378,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" });
         }
@@ -1393,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,
@@ -1406,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.
     //
@@ -1431,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);
+        }
+        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 adapter-managed secretEnv file. Adapter
+        // 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({
@@ -1481,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;
@@ -1490,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();
@@ -1557,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 {
@@ -1657,20 +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();
-        const identity = resolveRuntimeIdentity(req.params.id);
-        if (!identity && !hasRuntimeIdentity(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 = shouldUseAppManagerForId(req.params.id, identity)
-            ? 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
@@ -1678,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" });
@@ -1750,7 +1538,7 @@ export async function instanceRoutes(app) {
     });
     // ── 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;
@@ -1795,7 +1583,7 @@ 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) => {
         try {
@@ -1846,11 +1634,11 @@ export async function instanceRoutes(app) {
     });
     // ── 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) {
@@ -1859,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 ?? {}),
@@ -1888,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}`) ?? {});
@@ -1904,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({
@@ -1923,7 +1712,7 @@ export async function instanceRoutes(app) {
                 newConnections,
                 saveInstanceJson,
                 readInstanceJson,
-                adapter,
+                integration,
             });
             return { ok: true, applied: target.id, resolved: result.resolved.length };
         }
@@ -1935,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 };
@@ -1944,12 +1733,5 @@ export async function instanceRoutes(app) {
             return reply.status(400).send({ detail: e?.message ?? "Invalid suggestion id" });
         }
     });
-    try {
-        const { registerOpenclawRoutes } = await import("./openclaw-routes.js");
-        registerOpenclawRoutes(app);
-    }
-    catch (err) {
-        console.error("[instances] openclaw route registration failed:", err);
-    }
 }
 //# sourceMappingURL=instances.js.map