@jack200714/mafw 4.8.0 → 4.10.2

package/gateway/dist/index.js

@@ -63,6 +63,8 @@ const stale_verify_1 = require("./recall/stale-verify");
 const session_worker_pool_1 = require("./recall/session-worker-pool");
 const reflect_cursor_1 = require("./recall/reflect-cursor");
 const index_scan_1 = require("./recall/index-scan");
+const redact_1 = require("./recall/redact");
+const waitwhat_command_1 = require("./routes/waitwhat-command");
 const consolidation_service_1 = require("./memory/consolidation-service");
 const auth_2 = require("./runtime/auth");
 const harmonic_file_store_2 = require("./memory/harmonic-file-store");
@@ -72,6 +74,7 @@ const media_service_1 = require("./media/media-service");
 const media_agent_1 = require("./media/media-agent");
 const pi_adapter_1 = require("./media/pi-adapter");
 const media_runtime_executor_1 = require("./media/media-runtime-executor");
+const resolve_prompt_1 = require("./media/resolve-prompt");
 const media_plugin_loader_1 = require("./media/media-plugin-loader");
 const tts_service_1 = require("./media/tts-service");
 const eval_endpoint_1 = require("./eval-endpoint");
@@ -94,7 +97,6 @@ const push_gateway_1 = require("./mobile/push-gateway");
 const device_store_1 = require("./mobile/device-store");
 const pairing_1 = require("./mobile/pairing");
 const tray_1 = require("./tray");
-const serve_sidecar_1 = require("./runtime/serve-sidecar");
 const self_update_1 = require("./self-update");
 const step_inject_1 = require("./recall/step-inject");
 const inject_format_1 = require("./recall/inject-format");
@@ -103,24 +105,19 @@ const event_broadcast_1 = require("./runtime/event-broadcast");
 const budget_guard_1 = require("./core/budget-guard");
 const goal_budget_1 = require("./core/goal-budget");
 const contract_1 = require("./runtime/contract");
+const validate_1 = require("./runtime/validate");
 const loader_1 = require("./runtime/loader");
 const pi_runtime_1 = require("./runtime/plugins/pi-runtime");
 const permission_1 = require("./routes/permission");
-const runtime_switch_1 = require("./routes/runtime-switch");
-const plugins_1 = require("./routes/plugins");
-const hub_1 = require("./plugins/hub");
-const restart_agent_1 = require("./routes/restart-agent");
-const session_mutations_1 = require("./routes/session-mutations");
+const package_host_1 = require("./plugins/package-host");
+const package_context_1 = require("./plugins/package-context");
 const serve_supervisor_1 = require("./runtime/serve-supervisor");
 const serve_for_runtime_1 = require("./runtime/serve-for-runtime");
-const media_switch_1 = require("./routes/media-switch");
-const usage_plugins_1 = require("./routes/usage-plugins");
 const model_stats_1 = require("./usage/model-stats");
-const model_config_1 = require("./routes/model-config");
-const session_branch_1 = require("./routes/session-branch");
-const session_summarize_1 = require("./routes/session-summarize");
-const goal_sessions_1 = require("./routes/goal-sessions");
-const embedding_config_1 = require("./routes/embedding-config");
+const registry_1 = require("./routes/registry");
+const route_catalog_1 = require("./routes/route-catalog");
+const wave1_handlers_1 = require("./routes/wave1-handlers");
+const wave2_handlers_1 = require("./routes/wave2-handlers");
 const manager_rotate_1 = require("./routes/manager-rotate");
 function readBody(req) {
     return new Promise((resolve, reject) => {
@@ -146,6 +143,8 @@ async function isPortHealthy(port) {
         return false;
     }
 }
+const manager_session_runtime_1 = require("./core/manager/manager-session-runtime");
+const INTERNAL_SESSION_TTL_DAYS = 7;
 class MafwScheduler {
     serveInstance;
     serveUrl;
@@ -175,6 +174,8 @@ class MafwScheduler {
     lastActiveBySession = new Map();
     lastWriteBySession = new Map();
     tokenWriterSession = null;
+    /** 畸形事件 warn 限频（每 runtime 30s 一次） */
+    malformedEventWarnAt = new Map();
     stopTokenWatcher = null;
     // Path 1 step-injection state (mark-before-async + dedup + queue). All
     // per-session entries expire via TtlMap.
@@ -217,6 +218,12 @@ class MafwScheduler {
     mcpEndpoint;
     mcpStreamableEndpoint;
     opencodeClient = null;
+    /**
+     * P4 shadow registry + P5 Wave 1 dispatch：catalog 全量登记（130 条，贡献 spec），
+     * Wave 1 已 attach 的 22 条在请求链顶端优先 dispatch（见 startApiServer），
+     * 未 attach 的 shadow 条目自然落回 legacy 内联链。
+     */
+    routeRegistry = new registry_1.RouteRegistry().register(...(0, route_catalog_1.buildRouteCatalog)());
     runtimeCaps = (0, contract_1.minimalCapabilities)();
     runtimeName = 'opencode';
     runtimeLoader;
@@ -236,6 +243,8 @@ class MafwScheduler {
     mediaPluginLoader;
     mediaRuntimeExecutor;
     mediaRuntimeExecutorRt;
+    pluginHost;
+    usageStatsProvider;
     ttsService;
     kernels;
     automationEngine;
@@ -259,51 +268,34 @@ class MafwScheduler {
         this.registryPath = config_1.config.paths.registryFile;
         this.chatSessions = new chat_sessions_1.ChatSessionManager();
         this.serveSupervisor = (0, serve_supervisor_1.createServeSupervisor)({
-            port: config_1.config.server.servePort,
-            external: !!process.env.MAFW_SERVER_SERVE_URL,
-            killPort: (port) => (0, serve_sidecar_1.killServePort)(port),
-            // Spawn 原语来自活跃 runtime 的契约（agentProcess.spawnServe）——
-            // gateway 核心不硬编码任何具体 agent 的 server 拉起细节。
+            // 全部经 runtime 契约且 late-bound（runtime 可热切换）：
+            // managed = runtime 是否持有启停原语；health = 契约 healthCheck；
+            // baseUrl/killServe = runtime 自报地址与清场原语；spawn 不传 host/port。
+            managed: () => !!this.opencodeClient?.agentProcess?.spawnServe,
+            health: async () => {
+                try {
+                    return (await this.opencodeClient?.healthCheck?.()) ?? false;
+                }
+                catch {
+                    return false;
+                }
+            },
+            baseUrl: () => this.opencodeClient?.getBaseUrl?.() ?? this.serveUrl,
+            killServe: () => this.opencodeClient?.agentProcess?.killServe?.(),
             spawn: async (opts) => {
                 const spawnServe = this.opencodeClient?.agentProcess?.spawnServe;
                 if (!spawnServe) {
                     throw new Error('active runtime does not own a server process (agentProcess.spawnServe missing)');
                 }
-                const sidecar = await spawnServe({
-                    host: opts.host,
-                    port: opts.port,
-                    timeoutMs: opts.timeoutMs,
-                });
+                const sidecar = await spawnServe({ timeoutMs: opts.timeoutMs });
                 return { url: sidecar.url, close: () => sidecar.close() };
             },
-            probe: async (url) => {
-                try {
-                    const res = await fetch(`${url}/global/health`, { signal: AbortSignal.timeout(3000) });
-                    return res.ok;
-                }
-                catch {
-                    return false;
-                }
-            },
         });
     }
     get serveRunning() {
         return !!this.serveInstance;
     }
     /** Check actual serve health via TCP connection, not just object existence. */
-    async checkServeActualHealth() {
-        try {
-            const url = `${this.serveUrl}/global/health`;
-            const res = await fetch(url, {
-                signal: AbortSignal.timeout(2000),
-                headers: { 'User-Agent': 'MAFW-Gateway-HealthCheck' }
-            });
-            return res.ok;
-        }
-        catch {
-            return false;
-        }
-    }
     async start() {
         logger_1.log.info('MAFW Scheduler v5.0 starting...');
         // Single-instance guard: if a healthy gateway already owns apiPort, this
@@ -360,6 +352,16 @@ class MafwScheduler {
         await this.runtimeLoader.init();
         // 内置插件注册：pi-coding-agent runtime（进程内 SDK 嵌入）
         this.runtimeLoader.registerBuiltin('pi', pi_runtime_1.createPiRuntime, pi_runtime_1.PI_CAPABILITIES, true);
+        // 2b. 统一插件包宿主（必须在 createRuntime 之前 init——包 runtime 贡献要先注册）
+        this.pluginHost = new package_host_1.PluginHost(process.env.MAFW_PLUGINS_DIR || config_1.config.resolvePath('plugins'), (name) => (0, package_context_1.createPluginPackageContext)(name, {
+            getCredentials: () => this.opencodeClient?.credentials ?? undefined,
+            usageStats: () => this.usageStatsProvider,
+            projectDir: this.projectDir,
+            gatewayPort: config_1.config.server.apiPort,
+            emit: (event) => this.broadcast(event),
+        }));
+        this.pluginHost.bindRuntime((entries) => this.runtimeLoader?.setPackageEntries(entries));
+        await this.pluginHost.init();
         // 3. 创建 SDK 客户端（auth），用于健康检查和后续通信
         const sdkConfig = {
             baseUrl: this.serveUrl,
@@ -370,6 +372,12 @@ class MafwScheduler {
         if (opencodePassword) {
             sdkConfig.headers = { Authorization: 'Basic ' + Buffer.from(`opencode:${opencodePassword}`).toString('base64') };
         }
+        // opencode 注册为正式内置插件（与用户插件同一接口；同名文件/包可覆盖）
+        const sdkSnapshot = { ...sdkConfig, headers: { ...sdkConfig.headers } };
+        this.runtimeLoader.registerBuiltin('opencode', async () => (await import('./runtime/opencode-runtime.js')).createOpencodeRuntime({
+            ...sdkSnapshot,
+            headers: { ...sdkSnapshot.headers },
+        }), (0, contract_1.fullCapabilities)(), !!process.env.MAFW_SERVER_SERVE_URL);
         const runtime = await this.createRuntime(sdkConfig);
         this.opencodeClient = runtime;
         this.runtimeCaps = runtime.capabilities;
@@ -404,7 +412,8 @@ class MafwScheduler {
             }
             else {
                 logger_1.log.info('OpenCode Serve not reachable, checking for stale process...');
-                (0, serve_sidecar_1.killServePort)(config_1.config.server.servePort);
+                // 清场原语归 runtime（serve 端口是实现细节；无原语的 runtime 无从清场）
+                this.opencodeClient?.agentProcess?.killServe?.();
                 try {
                     await this.startServe();
                     serveReady = !!this.serveInstance;
@@ -600,7 +609,7 @@ class MafwScheduler {
         }
         else {
             try {
-                const ms = this.getGatewayDb().kvGet('manager-session', this.projectDir);
+                const ms = this.readManagerSessionEntry(this.projectDir);
                 if (ms?.sessionId)
                     targets.add(ms.sessionId);
             }
@@ -644,8 +653,10 @@ class MafwScheduler {
                 if (changed.includes('runtime')) {
                     const newPlugin = config_1.config.runtime?.plugin;
                     if (newPlugin !== prevPlugin && !this.switchingRuntime && !this.serveRecovering) {
-                        logger_1.log.info(`[Scheduler] Runtime plugin changed: '${prevPlugin ?? 'builtin'}' → '${newPlugin ?? 'builtin'}'; hot-switching...`);
+                        this.switchingRuntime = true;
+                        const prev = this.opencodeClient;
                         try {
+                            logger_1.log.info(`[Scheduler] Runtime plugin changed: '${prevPlugin ?? 'builtin'}' → '${newPlugin ?? 'builtin'}'; hot-switching...`);
                             const sdkConfig = {
                                 baseUrl: this.serveUrl,
                                 directory: this.projectDir,
@@ -670,11 +681,28 @@ class MafwScheduler {
                             if (this.automationEngine)
                                 this.automationEngine.setRuntimeClient(runtime);
                             await this.resubscribeEvents(`config hot-reload runtime plugin changed to '${newPlugin ?? 'builtin'}'`);
+                            // Same desktop hint as the route path: hand-edited config.yaml
+                            // switches must also refresh the renderer (menus/tabs/manager kv).
+                            this.broadcast({ type: 'runtime_switched', runtime: runtime.name, previous: prevPlugin ?? null });
+                            // Dispose the previous runtime AFTER the new one is fully wired
+                            // (mirror of the route path) — without this, switching away from
+                            // pi leaks its AgentSessions/ApprovalBridges/event stream.
+                            if (prev && prev.dispose) {
+                                try {
+                                    await prev.dispose();
+                                }
+                                catch (err) {
+                                    logger_1.log.warn(`[Scheduler] dispose previous runtime failed: ${err.message}`);
+                                }
+                            }
                             logger_1.log.info(`[Scheduler] Runtime hot-switched to '${runtime.name}'`);
                         }
                         catch (err) {
                             logger_1.log.warn(`[Scheduler] Runtime hot-switch failed (non-fatal): ${err.message}`);
                         }
+                        finally {
+                            this.switchingRuntime = false;
+                        }
                     }
                 }
             }, 300);
@@ -849,6 +877,23 @@ class MafwScheduler {
     }
     handleOpencodeEvent(evt) {
         const f = (0, normalize_1.normalizeOpencodeEvent)(evt);
+        // 畸形事件诊断（限频）：runtime 插件发来的事件 type/properties 全空时
+        // 静默穿过会污染 trajectory 与桌面 SSE——这里给可定位诊断。
+        if ((0, normalize_1.isMalformedEvent)(evt)) {
+            const now = Date.now();
+            const last = this.malformedEventWarnAt.get(this.runtimeName) ?? 0;
+            if (now - last > 30_000) {
+                this.malformedEventWarnAt.set(this.runtimeName, now);
+                let summary;
+                try {
+                    summary = JSON.stringify(evt)?.slice(0, 200) ?? '(unserializable)';
+                }
+                catch {
+                    summary = '(unserializable)';
+                }
+                logger_1.log.warn(`[SSE] malformed event from runtime '${this.runtimeName}' (no type/properties) — dropped consumers may misbehave; payload: ${summary}`);
+            }
+        }
         const { type, properties: props, sessionID } = f;
         // Only memory-system sessions (index-scan / extract / reflect workers) are
         // internal: their token-level deltas flooded the desktop renderer (per-delta
@@ -993,7 +1038,18 @@ class MafwScheduler {
             if (plugin) {
                 try {
                     const creds = await this.runtimeCredentialsForPlugin();
-                    const rt = await plugin.createRuntime((0, loader_1.createRuntimePluginContext)(creds));
+                    const rt = await plugin.createRuntime((0, loader_1.createRuntimePluginContext)(creds, {
+                        projectDir: this.projectDir,
+                        gatewayPort: config_1.config.server.apiPort,
+                    }));
+                    // 声明 vs 实现一致性校验：错位插件在切换/启动期给出字段级诊断并回退，
+                    // 而不是运行时深处才炸。
+                    const issues = (0, validate_1.validateRuntimeShape)(rt, pluginName);
+                    if (issues.length > 0) {
+                        for (const issue of issues)
+                            logger_1.log.error(`[Runtime] shape violation: ${issue}`);
+                        throw new Error(`runtime '${rt.name}' failed shape validation (${issues.length} issue(s)) — see logs`);
+                    }
                     logger_1.log.info(`[Runtime] using plugin runtime '${rt.name}' (capabilities: ${JSON.stringify(rt.capabilities)})`);
                     return rt;
                 }
@@ -1005,6 +1061,11 @@ class MafwScheduler {
                 logger_1.log.warn(`[Runtime] plugin '${pluginName}' not found — falling back to opencode`);
             }
         }
+        const builtin = this.runtimeLoader?.get('opencode');
+        if (builtin) {
+            return builtin.createRuntime((0, loader_1.createRuntimePluginContext)(undefined));
+        }
+        // 最终安全网：loader 未注册时直连（不应发生）
         const { createOpencodeRuntime } = await import('./runtime/opencode-runtime.js');
         return createOpencodeRuntime({
             ...sdkConfig,
@@ -1198,6 +1259,120 @@ class MafwScheduler {
         const result = await rt.indexer.backfill(ids);
         return { ...result, vectors: rt.vectors.size(), indexEntries: entries.length };
     }
+    /** P5 Wave 2：/api/runtime 路由 deps（自内联块上移，行为逐字节等价）。 */
+    runtimeDeps() {
+        return {
+            loader: this.runtimeLoader,
+            persist: (o) => config_1.config.persistOverrides(o),
+            getCurrent: () => this.opencodeClient,
+            runtimeName: () => this.runtimeName,
+            runtimeCaps: () => this.runtimeCaps,
+            envOverride: () => !!process.env.MAFW_RUNTIME_PLUGIN,
+            createRuntime: async () => {
+                const sdkConfig = {
+                    baseUrl: this.serveUrl,
+                    directory: this.projectDir,
+                    headers: {},
+                };
+                const opencodePassword = process.env.MAFW_OPENCODE_PASSWORD;
+                if (opencodePassword) {
+                    sdkConfig.headers = { Authorization: 'Basic ' + Buffer.from(`opencode:${opencodePassword}`).toString('base64') };
+                }
+                return this.createRuntime(sdkConfig);
+            },
+            onSwitched: async (rt, prev) => {
+                this.opencodeClient = rt;
+                this.runtimeCaps = rt.capabilities;
+                this.runtimeName = rt.name;
+                // Switching onto a runtime that owns serve (builtin opencode) must
+                // ensure the sidecar exists — the gateway may have started under an
+                // external runtime (pi) that never spawned one. Must run AFTER the
+                // assignment above: the supervisor's spawn closure reads
+                // this.opencodeClient to find agentProcess.spawnServe.
+                if (rt.agentProcess?.spawnServe) {
+                    await (0, serve_for_runtime_1.ensureServeForBuiltinRuntime)(this.serveSupervisor, { startWatchdog: () => this.startServeWatchdog() }, logger_1.log);
+                }
+                this.sdkSession.setClient(this.opencodeClient);
+                if (this.trajectoryCollector)
+                    this.trajectoryCollector.setOpencodeClient(this.opencodeClient);
+                if (this.automationEngine)
+                    this.automationEngine.setRuntimeClient(rt);
+                await this.resubscribeEvents(`runtime switched to '${rt.name}'`);
+                // Desktop hint: a runtime switch swaps the session storage backend
+                // (opencode SQLite vs pi), so cached session lists are stale.
+                this.broadcast({ type: 'runtime_switched', runtime: rt.name, previous: prev?.name ?? null });
+                if (prev && prev.dispose) {
+                    try {
+                        await prev.dispose();
+                    }
+                    catch (err) {
+                        logger_1.log.warn(`[Runtime] dispose old runtime failed: ${err.message}`);
+                    }
+                }
+            },
+        };
+    }
+    /** P5 Wave 2：/api/runtime/restart-agent deps。 */
+    restartAgentDeps() {
+        return {
+            capabilities: () => this.runtimeCaps,
+            isRecovering: () => this.serveRecovering,
+            isSwitching: () => this.switchingRuntime,
+            begin: () => { this.serveRecovering = true; },
+            end: () => { this.serveRecovering = false; },
+            restartAgent: () => this.restartAgentOrchestrated(),
+        };
+    }
+    /** P5 Wave 2：/api/plugins* deps（Plugin Hub 四类型统一面）。 */
+    pluginHubDeps() {
+        return {
+            hub: {
+                dirs: {
+                    runtime: config_1.config.resolvePath('runtime-plugins'),
+                    media: config_1.config.resolvePath('media-plugins'),
+                    usage: config_1.config.resolvePath('usage-plugins'),
+                    ui: process.env.MAFW_UI_PLUGINS_DIR || path.join(os.homedir(), '.mafw', 'ui-plugins'),
+                },
+                builtinEntries: () => {
+                    const entries = [];
+                    const rt = (name) => ({ type: 'runtime', name, file: '(builtin)', status: 'enabled', size: 0, mtime: '' });
+                    for (const name of this.runtimeLoader?.getBuiltinNames?.() ?? [])
+                        entries.push(rt(name));
+                    for (const name of this.mediaPluginLoader?.getBuiltinEngineNames?.() ?? []) {
+                        entries.push({ type: 'media', name, file: '(builtin)', status: 'enabled', size: 0, mtime: '' });
+                    }
+                    const usageState = this.pluginLoader?.getState?.() ?? [];
+                    for (const s of usageState) {
+                        if (s.builtin && s.status === 'ok' && s.name) {
+                            entries.push({ type: 'usage', name: s.name, file: s.file, status: 'enabled', size: 0, mtime: '', pluginType: s.pluginType });
+                        }
+                    }
+                    return entries;
+                },
+                getErrors: (type) => {
+                    const stateOf = (loader) => (loader && typeof loader.getState === 'function' ? loader.getState() : []);
+                    const source = type === 'runtime' ? this.runtimeLoader : type === 'media' ? this.mediaPluginLoader : type === 'usage' ? this.pluginLoader : null;
+                    const out = {};
+                    for (const p of stateOf(source)) {
+                        if (p && p.error)
+                            out[p.name || p.file] = p.error;
+                    }
+                    return out;
+                },
+                configDisabledUsage: () => new Set(Array.isArray(config_1.config.usage?.disabledPlugins) ? config_1.config.usage.disabledPlugins : []),
+                reload: async (type) => {
+                    if (type === 'runtime')
+                        await this.runtimeLoader?.scan();
+                    else if (type === 'media')
+                        await this.mediaPluginLoader?.reload();
+                    else if (type === 'usage')
+                        await this.pluginLoader?.reload();
+                    // ui: desktop main fs.watch picks it up automatically
+                },
+                getPackages: () => this.pluginHost?.getState() ?? [],
+            },
+        };
+    }
     embeddingConfigDeps() {
         return {
             currentConfig: () => {
@@ -1711,6 +1886,7 @@ class MafwScheduler {
         }
         this.pluginLoader?.stop();
         this.mediaPluginLoader?.stop();
+        this.pluginHost?.stop();
         if (this.opencodeClient && typeof this.opencodeClient.dispose === 'function') {
             void this.opencodeClient.dispose().catch((err) => {
                 logger_1.log.warn(`[Scheduler] runtime dispose error: ${err?.message ?? String(err)}`);
@@ -1724,32 +1900,6 @@ class MafwScheduler {
         // }
         logger_1.log.info('[Scheduler] Stopping...');
     }
-    // Proxy a native opencode request by trying every registered workspace.
-    // Native reply/reject routes are workspace-scoped (WorkspaceRoutingMiddleware),
-    // but the gateway's own projectDir is its cwd — the request may belong to any
-    // registered project. GET list endpoints are cross-workspace and unaffected.
-    async proxyNativeWorkspaces(path, method, body) {
-        const dirs = new Set([this.projectDir || '.']);
-        for (const key of this.registeredProjects.keys())
-            dirs.add(key);
-        let lastStatus = 502;
-        for (const dir of dirs) {
-            try {
-                const r = await fetch(`${this.serveUrl}${path}?directory=${encodeURIComponent(dir)}`, {
-                    method,
-                    headers: { 'content-type': 'application/json', 'x-opencode-directory': encodeURIComponent(dir) },
-                    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
-                });
-                if (r.ok)
-                    return { ok: true, status: r.status };
-                lastStatus = r.status;
-            }
-            catch (e) {
-                logger_1.log.error(`[Native proxy] ${path} failed for ${dir}: ${e.message}`);
-            }
-        }
-        return { ok: false, status: lastStatus };
-    }
     // 鈹€鈹€ Services & Event Bus 鈹€鈹€
     async initServices() {
         const projectDir = this.projectDir;
@@ -1774,6 +1924,9 @@ class MafwScheduler {
             getCredentials: () => this.opencodeClient?.credentials ?? undefined,
         });
         await this.mediaPluginLoader.init();
+        this.pluginHost?.bindMedia((entries) => this.mediaPluginLoader?.setPackageEntries(entries));
+        // 内置 pi 引擎登记（可被用户同名包/文件覆盖——resolveMediaPrompt 语义）
+        this.mediaPluginLoader.registerBuiltinEngine('pi', ['image', 'video', 'audio']);
         this.mediaService = new media_service_1.MediaService({
             prompt: (0, pi_adapter_1.createPiPromptAdapter)({
                 getApiKey: (provider) => {
@@ -1783,31 +1936,24 @@ class MafwScheduler {
             config: () => config_1.config.raw.media,
             resolvePrompt: (kind, cfg) => {
                 const engineName = cfg[kind]?.engine ?? cfg.engine ?? 'pi';
-                // pi runtime 激活时：图片走 AgentRuntime 会话（MediaRuntimeExecutor），
-                // video/audio 由 executor 内部回退到 complete 路径
-                if (engineName === 'pi' && this.opencodeClient?.name === 'pi') {
-                    // runtime 热切换后 opencodeClient 实例更换——旧 executor 持有 stale
-                    // runtime 引用，必须重建（dispose 尽力而为，不阻塞 prompt）。
-                    if (!this.mediaRuntimeExecutor || this.mediaRuntimeExecutorRt !== this.opencodeClient) {
-                        void this.mediaRuntimeExecutor?.dispose().catch(() => { });
-                        this.mediaRuntimeExecutor = (0, media_runtime_executor_1.createMediaRuntimeExecutor)(this.opencodeClient);
-                        this.mediaRuntimeExecutorRt = this.opencodeClient;
-                    }
-                    return this.mediaRuntimeExecutor.prompt;
-                }
-                if (engineName === 'pi')
-                    return undefined;
-                const engines = this.mediaPluginLoader?.getEngines();
-                const engine = engines?.get(engineName);
-                if (!engine) {
-                    logger_1.log.warn(`[MediaService] engine '${engineName}' not found, falling back to pi`);
-                    return undefined;
-                }
-                if (!engine.modalities.includes(kind)) {
-                    logger_1.log.warn(`[MediaService] engine '${engineName}' does not support modality '${kind}', falling back to pi`);
-                    return undefined;
-                }
-                return engine.prompt;
+                return (0, resolve_prompt_1.resolveMediaPrompt)(engineName, kind, {
+                    engines: this.mediaPluginLoader?.getEngines() ?? new Map(),
+                    builtinPi: () => {
+                        // pi runtime 激活时：图片走 AgentRuntime 会话（MediaRuntimeExecutor），
+                        // video/audio 由 executor 内部回退到 complete 路径
+                        if (this.opencodeClient?.name === 'pi') {
+                            // runtime 热切换后 opencodeClient 实例更换——旧 executor 持有 stale
+                            // runtime 引用，必须重建（dispose 尽力而为，不阻塞 prompt）。
+                            if (!this.mediaRuntimeExecutor || this.mediaRuntimeExecutorRt !== this.opencodeClient) {
+                                void this.mediaRuntimeExecutor?.dispose().catch(() => { });
+                                this.mediaRuntimeExecutor = (0, media_runtime_executor_1.createMediaRuntimeExecutor)(this.opencodeClient);
+                                this.mediaRuntimeExecutorRt = this.opencodeClient;
+                            }
+                            return this.mediaRuntimeExecutor.prompt;
+                        }
+                        return undefined;
+                    },
+                });
             },
         });
         // Determine workspace name: if projectDir resolves to a 'gateway' subdirectory,
@@ -1916,6 +2062,9 @@ class MafwScheduler {
             const collector = new TrajectoryCollector(trajStore, this.getGatewayDb(), projectDir, () => config_1.config.trajectory.retentionDays);
             collector.setRoleFor((sid) => this.internalSessionRoles.get(sid) ?? null);
             this.trajectoryCollector = collector;
+            const pruned = this.getGatewayDb().kvPruneOlderThan('internal-session', INTERNAL_SESSION_TTL_DAYS);
+            if (pruned > 0)
+                logger_1.log.info(`[Scheduler] pruned ${pruned} stale internal-session kv entries (> ${INTERNAL_SESSION_TTL_DAYS}d)`);
             const restored = this.getGatewayDb().kvAll('internal-session');
             for (const { key: sid, value } of restored) {
                 if (value?.role && !this.internalSessionRoles.has(sid)) {
@@ -1932,10 +2081,12 @@ class MafwScheduler {
             const pluginsDir = path.join(os.homedir(), '.mafw', 'usage-plugins');
             const builtinPluginsDir = path.join(__dirname, 'usage', 'builtin-plugins');
             const disabledPlugins = Array.isArray(config_1.config.usage?.disabledPlugins) ? config_1.config.usage.disabledPlugins : [];
+            const statsProvider = createUsageStatsProvider(trajStore);
+            this.usageStatsProvider = statsProvider;
             const pluginLoader = new PluginLoader(pluginsDir, [], {
                 builtinPluginsDir,
                 disabledPlugins,
-                usageStats: createUsageStatsProvider(trajStore),
+                usageStats: statsProvider,
                 // inline provider key 兜底（auth.json 无条目的自建 provider，如 gateway）——
                 // thunk 惰性求值，opencodeClient 此时尚未初始化也不影响。
                 resolveInlineApiKey: async (providerID) => {
@@ -1951,6 +2102,7 @@ class MafwScheduler {
             });
             await pluginLoader.init();
             this.pluginLoader = pluginLoader;
+            this.pluginHost?.bindUsage((entries) => pluginLoader.setPackageEntries(entries));
             const { UsagePoller } = require('./usage/usage-poller');
             this.usagePoller = new UsagePoller(trajStore, () => config_1.config.usage.limits, () => config_1.config.usage.budgets, pluginLoader);
             logger_1.log.info('[Trajectory] store initialized');
@@ -2027,12 +2179,10 @@ class MafwScheduler {
             return;
         }
         logger_1.log.info('Starting OpenCode Serve sidecar...');
-        const port = config_1.config.server.servePort;
-        const host = config_1.config.server.serveHost;
         try {
+            // host/port 归 runtime 自定（serve 端口是实现细节）；sidecar 实际 URL
+            // 由 runtime 吸收（getBaseUrl 跟随），gateway 只记 bookkeeping。
             const sidecar = await spawnServe({
-                host,
-                port,
                 onOutput: (chunk) => logger_1.log.debug(`[Serve] ${chunk.trimEnd()}`),
                 onExit: (code) => this.handleServeExit(code),
             });
@@ -2055,6 +2205,18 @@ class MafwScheduler {
     handleServeExit(code) {
         if (!this.serveOwned || this.serveRecovering)
             return;
+        // After a hot-switch to an in-process/external runtime, the (still owned)
+        // opencode serve is no longer the active backend: its exit must NOT trigger
+        // recovery — pi has no spawnServe, so the orchestrator would fall into the
+        // supervisor's kill+spawn path and retry forever (killing whatever listens
+        // on the serve port each cycle). A later switch back re-ensures via
+        // ensureServeForBuiltinRuntime (probe → adopt or spawn).
+        const rt = this.opencodeClient;
+        if (rt?.external || !rt?.agentProcess?.spawnServe) {
+            this.serveOwned = false;
+            logger_1.log.info('[Scheduler] owned serve exited after runtime switch; recovery skipped (active runtime does not own serve)');
+            return;
+        }
         this.serveInstance = undefined;
         if (this.serveStableTimer) {
             clearTimeout(this.serveStableTimer);
@@ -2282,18 +2444,14 @@ class MafwScheduler {
         return projectID ? await this.sdkSession.listByProject(projectID) : await this.sdkSession.list();
     }
     async isServeHealthy() {
-        const url = `${this.serveUrl}/global/health`;
-        return new Promise((resolve) => {
-            const req = http.get(url, { timeout: 5000 }, (res) => {
-                resolve(res.statusCode === 200);
-                res.resume();
-            });
-            req.on('error', () => resolve(false));
-            req.on('timeout', () => {
-                req.destroy();
-                resolve(false);
-            });
-        });
+        // 健康唯一真相源 = runtime 契约 healthCheck()（serve 型探测 serve，
+        // 进程内 runtime 探测自身引擎）；gateway 不自带 HTTP 探测。
+        try {
+            return (await this.opencodeClient?.healthCheck?.()) ?? false;
+        }
+        catch {
+            return false;
+        }
     }
     async waitForServeReady() {
         const maxRetries = config_1.config.timeouts.serveReadyMaxRetries;
@@ -2310,9 +2468,45 @@ class MafwScheduler {
     // 鈹€鈹€ 2. HTTP API 鈹€鈹€
     async startApiServer() {
         return new Promise((resolve) => {
+            // P5 Wave 1: catalog shadow 登记 + 模块 handler 绑定（一次性，重复 attach 会抛错）。
+            // adapter 显式桥接私有成员（结构化类型不认 private）。
+            (0, wave1_handlers_1.attachWave1Handlers)(this.routeRegistry, {
+                getGatewayDb: () => this.getGatewayDb(),
+                opencodeClient: this.opencodeClient,
+                automationEngine: this.automationEngine,
+                ledger: this.ledger,
+                rotateDeps: () => this.rotateDeps(),
+                embeddingConfigDeps: () => this.embeddingConfigDeps(),
+                modelConfigDeps: () => this.modelConfigDeps(),
+                usagePluginsDeps: () => this.usagePluginsDeps(),
+                pluginLoader: this.pluginLoader,
+                mediaPluginLoader: this.mediaPluginLoader,
+                broadcast: (e) => this.broadcast(e),
+                runtimeCaps: this.runtimeCaps,
+            });
+            (0, wave2_handlers_1.attachWave2Handlers)(this.routeRegistry, {
+                runtimeDeps: () => this.runtimeDeps(),
+                restartAgentDeps: () => this.restartAgentDeps(),
+                pluginHubDeps: () => this.pluginHubDeps(),
+                runtimeSwitchBlocked: () => this.serveRecovering || this.switchingRuntime,
+                beginRuntimeSwitch: () => { this.switchingRuntime = true; },
+                endRuntimeSwitch: () => { this.switchingRuntime = false; },
+            });
             const server = http.createServer(async (req, res) => {
                 try {
                     res.setHeader('Content-Type', 'application/json');
+                    // P5 Wave 1: registry dispatch —— attach 过 handler 的路由在 legacy 链之前
+                    // 统一接管（shadow 条目无 handler 自然落回内联链）。挂在鉴权之后、一切
+                    // /api matcher 之前：goals.sessions 须先于 dashboard 兜底、embedding-config
+                    // 须先于 /api/memory/* 委托（AGENTS.md §6.5 顺序教训由 dispatch 位置一次性满足）。
+                    {
+                        const matched = this.routeRegistry.match(req.method, req.url || '');
+                        if (matched?.def.handler) {
+                            const handled = await matched.def.handler(req, res, matched.params);
+                            if (handled !== false)
+                                return;
+                        }
+                    }
                     // CORS headers for SSE
                     res.setHeader("Access-Control-Allow-Origin", config_1.config.server.cors.origin);
                     res.setHeader("Access-Control-Allow-Methods", config_1.config.server.cors.methods);
@@ -3141,6 +3335,32 @@ class MafwScheduler {
                                 res.end(JSON.stringify({ ok: true, text: answer }));
                                 return;
                             }
+                            if (cmd === "waitwhat") {
+                                if (!sessionID) {
+                                    res.writeHead(400);
+                                    res.end(JSON.stringify({ ok: false, error: "sessionID required" }));
+                                    return;
+                                }
+                                if (!this.opencodeClient) {
+                                    res.writeHead(503);
+                                    res.end(JSON.stringify({ ok: false, error: "LLM client not available" }));
+                                    return;
+                                }
+                                const result = await (0, waitwhat_command_1.runWaitwhat)(String(sessionID), {
+                                    listMessages: async (sid) => {
+                                        const r = await this.opencodeClient.session.messages({ sessionID: sid, limit: 50 });
+                                        return (r?.data || []);
+                                    },
+                                    promptAsync: async (sid, text) => {
+                                        await this.opencodeClient.session.promptAsync({ sessionID: sid, parts: [{ type: "text", text }] });
+                                    },
+                                });
+                                res.writeHead(result.ok ? 200 : 400, { 'Content-Type': 'application/json' });
+                                res.end(JSON.stringify(result.ok
+                                    ? { ok: true, message: '重述请求已发送到当前会话' }
+                                    : { ok: false, error: result.error }));
+                                return;
+                            }
                             if (cmd === "status") {
                                 const statusPath = path.join(this.mafwDir, 'STATUS.md');
                                 const text = fs.existsSync(statusPath) ? fs.readFileSync(statusPath, 'utf-8') : 'No active Goals. Use /goal to create one.';
@@ -3254,16 +3474,8 @@ class MafwScheduler {
                         return;
                     }
                     // GET/POST /api/memory/embedding-config — memory embedding engine
-                    // settings (hot-swap: rebuild runtime + background backfill). MUST
-                    // stay above the /api/memory/* dashboard delegation below.
-                    if (req.url?.match(/^\/api\/memory\/embedding-config(?:\?|$)/) && req.method === 'GET') {
-                        await (0, embedding_config_1.handleEmbeddingConfigGet)(req, res, this.embeddingConfigDeps());
-                        return;
-                    }
-                    if (req.url?.match(/^\/api\/memory\/embedding-config(?:\?|$)/) && req.method === 'POST') {
-                        await (0, embedding_config_1.handleEmbeddingConfigUpdate)(req, res, this.embeddingConfigDeps());
-                        return;
-                    }
+                    // settings（P5 Wave 1 起由 registry dispatch 接管，见 routes/wave1-handlers.ts；
+                    // 历史顺序约束"须高于 /api/memory/* dashboard 委托"由 dispatch 位置满足）
                     // GET /api/memory/stats — consolidation health + vector coverage (P2)
                     if (req.url?.match(/^\/api\/memory\/stats(?:\?|$)/) && req.method === 'GET') {
                         try {
@@ -3510,16 +3722,8 @@ class MafwScheduler {
                         res.end(JSON.stringify({ status: 'accepted' }));
                         return;
                     }
-                    // GET /api/goals/:id/sessions — goal session 映射（编排可视化下钻）。
-                    // 必须挂在 Dashboard API 的 /api/goals* 兜底之前（AGENTS.md §6.5 路由顺序教训）。
-                    if (req.url?.match(/^\/api\/goals\/[^/]+\/sessions(?:\?|$)/) && req.method === 'GET') {
-                        const handled = await (0, goal_sessions_1.handleGoalSessions)(req, res, req.url, {
-                            listGoalSessions: (goalId) => this.getGatewayDb().listGoalSessions(goalId),
-                            getSession: (sessionID) => this.opencodeClient?.session.get({ sessionID }).catch(() => null),
-                        });
-                        if (handled)
-                            return;
-                    }
+                    // GET /api/goals/:id/sessions — P5 Wave 1 起由 registry dispatch 接管
+                    // （历史约束"须挂 Dashboard /api/goals* 兜底之前"由 dispatch 位置满足）。
                     // Dashboard API
                     if (req.url?.startsWith("/api/goals") || req.url?.startsWith("/api/stats") || req.url?.startsWith("/api/memory")) {
                         res.setHeader("Content-Type", "application/json");
@@ -3633,8 +3837,8 @@ class MafwScheduler {
                         });
                         return;
                     }
-                    // 控制指令
-                    if (req.url === '/control' && req.method === 'POST') {
+                    // 控制指令（/control 为 MCP handler 兼容路径；/api/goals/control 为 SDK goals.control 契约路径，两者等价）
+                    if ((req.url === '/control' || req.url === '/api/goals/control') && req.method === 'POST') {
                         let body = '';
                         req.on('data', chunk => body += chunk);
                         req.on('end', async () => {
@@ -3737,12 +3941,7 @@ class MafwScheduler {
                         }
                         return;
                     }
-                    // POST /api/manager/session/rotate — start a new manager topic
-                    // (thin wiring → routes/manager-rotate.ts).
-                    if (req.method === 'POST' && req.url?.match(/^\/api\/manager\/session\/rotate(?:\?|$)/)) {
-                        await (0, manager_rotate_1.handleManagerRotate)(req, res, this.rotateDeps());
-                        return;
-                    }
+                    // POST /api/manager/session/rotate — P5 Wave 1 起由 registry dispatch 接管
                     // GET /api/manager/session — return manager session info (per-project,
                     // read from the gateway DB). ?projectDir= filters a single project.
                     if (req.url && req.url.startsWith('/api/manager/session') && req.method === 'GET') {
@@ -3750,8 +3949,14 @@ class MafwScheduler {
                         const filter = parsedUrl.searchParams.get('projectDir') || '';
                         try {
                             const all = this.getGatewayDb().kvAll('manager-session');
+                            // Per-runtime slots: surface only the ACTIVE runtime's manager
+                            // slot per project. Other runtimes' slots stay dormant (resumed
+                            // when switching back) — nothing is deleted here.
+                            const live = all
+                                .map((e) => ({ key: e.key, value: (0, manager_session_runtime_1.readManagerSlot)(e.value, this.runtimeName) }))
+                                .filter((e) => e.value !== null);
                             if (filter) {
-                                const found = all.find((e) => e.key === filter);
+                                const found = live.find((e) => e.key === filter);
                                 if (!found) {
                                     res.writeHead(404);
                                     res.end(JSON.stringify({ error: 'No manager session for project' }));
@@ -3765,13 +3970,13 @@ class MafwScheduler {
                                 }));
                                 return;
                             }
-                            if (all.length === 0) {
+                            if (live.length === 0) {
                                 res.writeHead(404);
                                 res.end(JSON.stringify({ error: 'No manager session' }));
                                 return;
                             }
                             res.writeHead(200);
-                            res.end(JSON.stringify(all.map((e) => ({
+                            res.end(JSON.stringify(live.map((e) => ({
                                 projectDir: e.key,
                                 sessionId: e.value.sessionId,
                                 createdAt: e.value.createdAt || null,
@@ -3982,17 +4187,15 @@ class MafwScheduler {
                         return;
                     }
                     // 鈹€鈹€ Question endpoints (AskCard 鈹€ proxy to native opencode Question API) 鈹€鈹€
-                    // GET /api/questions 鈹€ list pending questions
+                    // GET /api/questions ── list pending questions（契约：session.question.list）
                     if (req.url?.match(/^\/api\/questions(?:\?|$)/) && req.method === 'GET') {
                         if (this.capGuardQuestion(res))
                             return;
                         try {
-                            const dir = new URL(req.url, this.serveUrl).searchParams.get('directory') || this.projectDir || '.';
-                            const r = await fetch(`${this.serveUrl}/question?directory=${encodeURIComponent(dir)}`, {
-                                headers: { 'x-opencode-directory': encodeURIComponent(dir) },
-                            });
-                            const items = await r.json();
-                            res.end(JSON.stringify({ items }));
+                            const dir = new URL(req.url, this.serveUrl).searchParams.get('directory') || this.projectDir || undefined;
+                            const question = this.opencodeClient?.session?.question;
+                            const items = question ? await question.list(dir ? { directory: dir } : undefined) : [];
+                            res.end(JSON.stringify({ items: items ?? [] }));
                         }
                         catch (err) {
                             logger_1.log.error('[Question] list error:', err.message);
@@ -4000,20 +4203,34 @@ class MafwScheduler {
                         }
                         return;
                     }
-                    // POST /api/questions/{id}/reply 鈹€ { answers: string[][] }
+                    // POST /api/questions/{id}/reply ── { answers: string[][] }（契约 + workspace 重试）
                     const qReplyMatch = req.url?.match(/^\/api\/questions\/([^/]+)\/reply(?:\?|$)/);
                     if (qReplyMatch && req.method === 'POST') {
                         if (this.capGuardQuestion(res))
                             return;
+                        const question = this.opencodeClient?.session?.question;
+                        if (!question) {
+                            res.writeHead(503);
+                            res.end(JSON.stringify({ status: 'error', error: 'question API not available on this runtime' }));
+                            return;
+                        }
                         try {
                             const body = JSON.parse(await readBody(req));
-                            const r = await this.proxyNativeWorkspaces(`/question/${qReplyMatch[1]}/reply`, 'POST', { answers: body.answers });
-                            if (!r.ok) {
-                                res.writeHead(r.status);
-                                res.end(JSON.stringify({ status: 'error', code: r.status }));
-                                return;
+                            // workspace 路由：默认（SDK 自带 projectDir）→ 各注册项目逐试
+                            const dirs = [undefined, this.projectDir, ...this.registeredProjects.keys()];
+                            let lastErr = null;
+                            for (const dir of [...new Set(dirs)]) {
+                                try {
+                                    await question.reply({ requestID: qReplyMatch[1], answers: body.answers, ...(dir ? { directory: dir } : {}) });
+                                    res.end(JSON.stringify({ status: 'ok' }));
+                                    return;
+                                }
+                                catch (err) {
+                                    lastErr = err;
+                                }
                             }
-                            res.end(JSON.stringify({ status: 'ok' }));
+                            res.writeHead(400);
+                            res.end(JSON.stringify({ status: 'error', error: lastErr?.message ?? 'question reply failed on all workspaces' }));
                         }
                         catch (err) {
                             logger_1.log.error('[Question] reply error:', err.message);
@@ -4022,19 +4239,32 @@ class MafwScheduler {
                         }
                         return;
                     }
-                    // POST /api/questions/{id}/reject
+                    // POST /api/questions/{id}/reject（契约 + workspace 重试）
                     const qRejectMatch = req.url?.match(/^\/api\/questions\/([^/]+)\/reject(?:\?|$)/);
                     if (qRejectMatch && req.method === 'POST') {
                         if (this.capGuardQuestion(res))
                             return;
+                        const question = this.opencodeClient?.session?.question;
+                        if (!question) {
+                            res.writeHead(503);
+                            res.end(JSON.stringify({ status: 'error', error: 'question API not available on this runtime' }));
+                            return;
+                        }
                         try {
-                            const r = await this.proxyNativeWorkspaces(`/question/${qRejectMatch[1]}/reject`, 'POST');
-                            if (!r.ok) {
-                                res.writeHead(r.status);
-                                res.end(JSON.stringify({ status: 'error', code: r.status }));
-                                return;
+                            const dirs = [undefined, this.projectDir, ...this.registeredProjects.keys()];
+                            let lastErr = null;
+                            for (const dir of [...new Set(dirs)]) {
+                                try {
+                                    await question.reject({ requestID: qRejectMatch[1], ...(dir ? { directory: dir } : {}) });
+                                    res.end(JSON.stringify({ status: 'ok' }));
+                                    return;
+                                }
+                                catch (err) {
+                                    lastErr = err;
+                                }
                             }
-                            res.end(JSON.stringify({ status: 'ok' }));
+                            res.writeHead(400);
+                            res.end(JSON.stringify({ status: 'error', error: lastErr?.message ?? 'question reject failed on all workspaces' }));
                         }
                         catch (err) {
                             logger_1.log.error('[Question] reject error:', err.message);
@@ -4044,17 +4274,16 @@ class MafwScheduler {
                         return;
                     }
                     // 鈹€鈹€ Permission endpoints (PermissionCard 鈹€ proxy to native opencode Permission API) 鈹€鈹€
-                    // GET /api/permissions 鈹€ list pending permission requests
+                    // GET /api/permissions ── list pending permission requests（契约：session.permissionList）
                     if (req.url?.match(/^\/api\/permissions(?:\?|$)/) && req.method === 'GET') {
                         if (this.capGuard(res, 'nativeApprovals'))
                             return;
                         try {
-                            const dir = new URL(req.url, this.serveUrl).searchParams.get('directory') || this.projectDir || '.';
-                            const r = await fetch(`${this.serveUrl}/permission?directory=${encodeURIComponent(dir)}`, {
-                                headers: { 'x-opencode-directory': encodeURIComponent(dir) },
-                            });
-                            const items = await r.json();
-                            res.end(JSON.stringify({ items }));
+                            const dir = new URL(req.url, this.serveUrl).searchParams.get('directory') || this.projectDir || undefined;
+                            const items = this.opencodeClient?.session?.permissionList
+                                ? await this.opencodeClient.session.permissionList(dir ? { directory: dir } : undefined)
+                                : [];
+                            res.end(JSON.stringify({ items: items ?? [] }));
                         }
                         catch (err) {
                             logger_1.log.error('[Permission] list error:', err.message);
@@ -4063,170 +4292,12 @@ class MafwScheduler {
                         return;
                     }
                     // 鈹€鈹€ Provider & Agents (composer model pill / @agent mention) 鈹€鈹€
-                    // ── /api/runtime routes (thin wiring → routes/runtime-switch.ts) ──
-                    if (req.url?.match(/^\/api\/runtime(?:\/|$)/)) {
-                        const runtimeDeps = {
-                            loader: this.runtimeLoader,
-                            persist: (o) => config_1.config.persistOverrides(o),
-                            getCurrent: () => this.opencodeClient,
-                            runtimeName: () => this.runtimeName,
-                            runtimeCaps: () => this.runtimeCaps,
-                            envOverride: () => !!process.env.MAFW_RUNTIME_PLUGIN,
-                            createRuntime: async () => {
-                                const sdkConfig = {
-                                    baseUrl: this.serveUrl,
-                                    directory: this.projectDir,
-                                    headers: {},
-                                };
-                                const opencodePassword = process.env.MAFW_OPENCODE_PASSWORD;
-                                if (opencodePassword) {
-                                    sdkConfig.headers = { Authorization: 'Basic ' + Buffer.from(`opencode:${opencodePassword}`).toString('base64') };
-                                }
-                                return this.createRuntime(sdkConfig);
-                            },
-                            onSwitched: async (rt, prev) => {
-                                this.opencodeClient = rt;
-                                this.runtimeCaps = rt.capabilities;
-                                this.runtimeName = rt.name;
-                                // Switching onto a runtime that owns serve (builtin opencode) must
-                                // ensure the sidecar exists — the gateway may have started under an
-                                // external runtime (pi) that never spawned one. Must run AFTER the
-                                // assignment above: the supervisor's spawn closure reads
-                                // this.opencodeClient to find agentProcess.spawnServe.
-                                if (rt.agentProcess?.spawnServe) {
-                                    await (0, serve_for_runtime_1.ensureServeForBuiltinRuntime)(this.serveSupervisor, { startWatchdog: () => this.startServeWatchdog() }, logger_1.log);
-                                }
-                                this.sdkSession.setClient(this.opencodeClient);
-                                if (this.trajectoryCollector)
-                                    this.trajectoryCollector.setOpencodeClient(this.opencodeClient);
-                                if (this.automationEngine)
-                                    this.automationEngine.setRuntimeClient(rt);
-                                await this.resubscribeEvents(`runtime switched to '${rt.name}'`);
-                                // Desktop hint: a runtime switch swaps the session storage backend
-                                // (opencode SQLite vs pi), so cached session lists are stale.
-                                this.broadcast({ type: 'runtime_switched', runtime: rt.name, previous: prev?.name ?? null });
-                                if (prev && prev.dispose) {
-                                    try {
-                                        await prev.dispose();
-                                    }
-                                    catch (err) {
-                                        logger_1.log.warn(`[Runtime] dispose old runtime failed: ${err.message}`);
-                                    }
-                                }
-                            },
-                        };
-                        if (req.method === 'GET' && req.url?.match(/^\/api\/runtime(?:\?|$)/)) {
-                            await (0, runtime_switch_1.handleRuntimeGet)(req, res, runtimeDeps);
-                            return;
-                        }
-                        if (req.method === 'POST' && req.url?.match(/^\/api\/runtime\/switch(?:\?|$)/)) {
-                            if (this.serveRecovering || this.switchingRuntime) {
-                                res.writeHead(409, { 'Content-Type': 'application/json' });
-                                res.end(JSON.stringify({ error: 'Cannot switch runtime during agent restart' }));
-                                return;
-                            }
-                            this.switchingRuntime = true;
-                            try {
-                                await (0, runtime_switch_1.handleRuntimeSwitch)(req, res, runtimeDeps);
-                            }
-                            finally {
-                                this.switchingRuntime = false;
-                            }
-                            return;
-                        }
-                        if (req.method === 'POST' && req.url?.match(/^\/api\/runtime\/reload(?:\?|$)/)) {
-                            await (0, runtime_switch_1.handleRuntimeReload)(req, res, runtimeDeps);
-                            return;
-                        }
-                        if (req.method === 'POST' && req.url?.match(/^\/api\/runtime\/restart-agent(?:\?|$)/)) {
-                            await (0, restart_agent_1.handleRestartAgent)(req, res, {
-                                capabilities: () => this.runtimeCaps,
-                                isRecovering: () => this.serveRecovering,
-                                isSwitching: () => this.switchingRuntime,
-                                begin: () => { this.serveRecovering = true; },
-                                end: () => { this.serveRecovering = false; },
-                                restartAgent: () => this.restartAgentOrchestrated(),
-                            });
-                            return;
-                        }
-                        return;
-                    }
-                    // ── Plugin Hub (all four plugin types) ──
-                    const pluginHubDeps = {
-                        hub: {
-                            dirs: {
-                                runtime: config_1.config.resolvePath('runtime-plugins'),
-                                media: config_1.config.resolvePath('media-plugins'),
-                                usage: config_1.config.resolvePath('usage-plugins'),
-                                ui: process.env.MAFW_UI_PLUGINS_DIR || path.join(os.homedir(), '.mafw', 'ui-plugins'),
-                            },
-                            builtinEntries: () => {
-                                const entries = [];
-                                const rt = (name) => ({ type: 'runtime', name, file: '(builtin)', status: 'enabled', size: 0, mtime: '' });
-                                entries.push(rt('opencode'));
-                                for (const name of this.runtimeLoader?.getBuiltinNames?.() ?? [])
-                                    entries.push(rt(name));
-                                entries.push({ type: 'media', name: 'pi', file: '(builtin)', status: 'enabled', size: 0, mtime: '' });
-                                const usageState = this.pluginLoader?.getState?.() ?? [];
-                                for (const s of usageState) {
-                                    if (s.builtin && s.status === 'ok' && s.name) {
-                                        entries.push({ type: 'usage', name: s.name, file: s.file, status: 'enabled', size: 0, mtime: '', pluginType: s.pluginType });
-                                    }
-                                }
-                                return entries;
-                            },
-                            getErrors: (type) => {
-                                const stateOf = (loader) => (loader && typeof loader.getState === 'function' ? loader.getState() : []);
-                                const source = type === 'runtime' ? this.runtimeLoader : type === 'media' ? this.mediaPluginLoader : type === 'usage' ? this.pluginLoader : null;
-                                const out = {};
-                                for (const p of stateOf(source)) {
-                                    if (p && p.error)
-                                        out[p.name || p.file] = p.error;
-                                }
-                                return out;
-                            },
-                            configDisabledUsage: () => new Set(Array.isArray(config_1.config.usage?.disabledPlugins) ? config_1.config.usage.disabledPlugins : []),
-                            reload: async (type) => {
-                                if (type === 'runtime')
-                                    await this.runtimeLoader?.scan();
-                                else if (type === 'media')
-                                    await this.mediaPluginLoader?.reload();
-                                else if (type === 'usage')
-                                    await this.pluginLoader?.reload();
-                                // ui: desktop main fs.watch picks it up automatically
-                            },
-                        },
-                    };
-                    try {
-                        const cleaned = (0, hub_1.cleanupExamples)(pluginHubDeps.hub);
-                        if (cleaned.removed.length)
-                            logger_1.log.info(`[PluginsHub] removed stale examples: ${cleaned.removed.length}`);
-                        if (cleaned.failed.length)
-                            logger_1.log.warn(`[PluginsHub] cleanupExamples failed: ${cleaned.failed.join(', ')}`);
-                    }
-                    catch (err) {
-                        logger_1.log.warn(`[PluginsHub] cleanupExamples error: ${err.message}`);
-                    }
-                    if (req.method === 'GET' && req.url?.match(/^\/api\/plugins(?:\?|$)/)) {
-                        await (0, plugins_1.handlePluginsList)(req, res, pluginHubDeps);
-                        return;
-                    }
-                    if (req.method === 'POST' && req.url?.match(/^\/api\/plugins\/install(?:\?|$)/)) {
-                        await (0, plugins_1.handlePluginsInstall)(req, res, pluginHubDeps);
-                        return;
-                    }
-                    if (req.method === 'POST' && req.url?.match(/^\/api\/plugins\/enable(?:\?|$)/)) {
-                        await (0, plugins_1.handlePluginsEnable)(req, res, pluginHubDeps);
-                        return;
-                    }
-                    if (req.method === 'POST' && req.url?.match(/^\/api\/plugins\/disable(?:\?|$)/)) {
-                        await (0, plugins_1.handlePluginsDisable)(req, res, pluginHubDeps);
-                        return;
-                    }
-                    if (req.method === 'POST' && req.url?.match(/^\/api\/plugins\/delete(?:\?|$)/)) {
-                        await (0, plugins_1.handlePluginsDelete)(req, res, pluginHubDeps);
-                        return;
-                    }
+                    // ── /api/runtime routes — P5 Wave 2 起由 registry dispatch 接管
+                    // （runtimeDeps/restartAgentDeps 构造上移至私有方法；内联块对未知
+                    //   /api/runtime/* 悬空 return 吞请求的行为随之终结——现落回 legacy 链）
+                    // ── Plugin Hub (all four plugin types) — P5 Wave 2 起由 registry dispatch
+                    // 接管（pluginHubDeps 构造上移至私有方法；cleanupExamples 改为命中
+                    // /api/plugins 路由时才执行——内联时代每个到达此处的请求都跑）。
                     // GET /api/orchestration/outcomes — goal outcome query
                     if (req.url?.match(/^\/api\/orchestration\/outcomes(?:\?|$)/) && req.method === 'GET') {
                         const u = new URL(req.url, 'http://localhost');
@@ -4322,20 +4393,37 @@ class MafwScheduler {
                         }
                         return;
                     }
-                    // POST /api/permissions/{id}/reply 鈹€ { reply: 'once'|'always'|'reject', message?: string }
+                    // POST /api/permissions/{id}/reply ── { reply, message? }（契约：列表反查 sessionID → permissionReply）
                     const pReplyMatch = req.url?.match(/^\/api\/permissions\/([^/]+)\/reply(?:\?|$)/);
                     if (pReplyMatch && req.method === 'POST') {
                         if (this.capGuard(res, 'nativeApprovals'))
                             return;
+                        const runtime = this.opencodeClient;
+                        if (!runtime?.session?.permissionList || !runtime?.session?.permissionReply) {
+                            res.writeHead(503);
+                            res.end(JSON.stringify({ status: 'error', error: 'permission API not available on this runtime' }));
+                            return;
+                        }
                         try {
                             const body = JSON.parse(await readBody(req));
-                            const payload = { reply: body.reply };
-                            if (body.message)
-                                payload.message = body.message;
-                            const r = await this.proxyNativeWorkspaces(`/permission/${pReplyMatch[1]}/reply`, 'POST', payload);
-                            if (!r.ok) {
-                                res.writeHead(r.status);
-                                res.end(JSON.stringify({ status: 'error', code: r.status }));
+                            const reply = body.reply;
+                            if (reply !== 'once' && reply !== 'always' && reply !== 'reject') {
+                                res.writeHead(400);
+                                res.end(JSON.stringify({ status: 'error', error: "reply must be 'once'|'always'|'reject'" }));
+                                return;
+                            }
+                            // 反查 sessionID：pending 列表项携带（跨 runtime 形状一致）
+                            const pending = await runtime.session.permissionList();
+                            const found = (Array.isArray(pending) ? pending : []).find((p) => p?.id === pReplyMatch[1]);
+                            if (!found?.sessionID) {
+                                res.writeHead(404);
+                                res.end(JSON.stringify({ status: 'error', error: 'permission request not found' }));
+                                return;
+                            }
+                            const ok = await runtime.session.permissionReply(found.sessionID, pReplyMatch[1], reply, body.message);
+                            if (!ok) {
+                                res.writeHead(404);
+                                res.end(JSON.stringify({ status: 'error', error: 'permission request not found' }));
                                 return;
                             }
                             res.end(JSON.stringify({ status: 'ok' }));
@@ -4672,13 +4760,7 @@ class MafwScheduler {
                         }
                         return;
                     }
-                    // DELETE/PATCH /api/sessions/:id — true forwards (rename / delete)
-                    if (await (0, session_mutations_1.handleSessionMutations)(req, res, {
-                        getCapabilities: () => this.runtimeCaps,
-                        getClient: () => (this.opencodeClient ?? null),
-                    })) {
-                        return;
-                    }
+                    // DELETE/PATCH /api/sessions/:id — P5 Wave 1 起由 registry dispatch 接管
                     // GET /api/sessions — list sessions (optional ?projectID=xxx)
                     if (req.url?.match(/^\/api\/sessions(?:\?|$)/) && req.method === 'GET') {
                         try {
@@ -4842,44 +4924,7 @@ class MafwScheduler {
                         }
                         return;
                     }
-                    // GET /api/usage/plugins — plugin state list (+templates for the wizard)
-                    if (req.url?.match(/^\/api\/usage\/plugins(?:\?|$)/) && req.method === 'GET') {
-                        await (0, usage_plugins_1.handleUsagePluginsList)(req, res, this.usagePluginsDeps());
-                        return;
-                    }
-                    // POST /api/usage/plugins/create — template wizard or raw source
-                    if (req.url?.match(/^\/api\/usage\/plugins\/create$/) && req.method === 'POST') {
-                        await (0, usage_plugins_1.handleUsagePluginCreate)(req, res, this.usagePluginsDeps());
-                        return;
-                    }
-                    // GET/PUT /api/usage/plugins/:name/source — user plugin code editor
-                    const mSource = req.url?.match(/^\/api\/usage\/plugins\/([^/]+)\/source$/);
-                    if (mSource && req.method === 'GET') {
-                        await (0, usage_plugins_1.handleUsagePluginSourceGet)(req, res, this.usagePluginsDeps(), decodeURIComponent(mSource[1]));
-                        return;
-                    }
-                    if (mSource && req.method === 'PUT') {
-                        await (0, usage_plugins_1.handleUsagePluginSourcePut)(req, res, this.usagePluginsDeps(), decodeURIComponent(mSource[1]));
-                        return;
-                    }
-                    // POST /api/usage/plugins/:name/test — one-shot adapter fetch
-                    const mTest = req.url?.match(/^\/api\/usage\/plugins\/([^/]+)\/test$/);
-                    if (mTest && req.method === 'POST') {
-                        await (0, usage_plugins_1.handleUsagePluginTest)(req, res, this.usagePluginsDeps(), decodeURIComponent(mTest[1]));
-                        return;
-                    }
-                    // DELETE /api/usage/plugins/:name — remove user plugin file
-                    const mDel = req.url?.match(/^\/api\/usage\/plugins\/([^/]+)$/);
-                    if (mDel && req.method === 'DELETE') {
-                        await (0, usage_plugins_1.handleUsagePluginDelete)(req, res, this.usagePluginsDeps(), decodeURIComponent(mDel[1]));
-                        return;
-                    }
-                    // POST /api/usage/plugins/reload — manual reload
-                    if (req.url?.match(/^\/api\/usage\/plugins\/reload$/) && req.method === 'POST') {
-                        await this.pluginLoader?.reload();
-                        await (0, usage_plugins_1.handleUsagePluginsList)(req, res, this.usagePluginsDeps());
-                        return;
-                    }
+                    // /api/usage/plugins* — P5 Wave 1 起由 registry dispatch 接管（7 条）
                     // GET /api/media/plugins — media engine plugin state list
                     if (req.url?.match(/^\/api\/media\/plugins(?:\?|$)/) && req.method === 'GET') {
                         const plugins = (this.mediaPluginLoader?.getState() ?? []).map(s => ({
@@ -4907,43 +4952,10 @@ class MafwScheduler {
                         res.end(JSON.stringify({ ok: true, plugins }));
                         return;
                     }
-                    // POST /api/media/switch — switch media engine per modality
-                    if (req.url?.match(/^\/api\/media\/switch(?:\?|$)/) && req.method === 'POST') {
-                        await (0, media_switch_1.handleMediaSwitch)(req, res, {
-                            persist: (o) => config_1.config.persistOverrides(o),
-                            reloadPlugins: async () => { await this.mediaPluginLoader?.reload(); },
-                            availableEngines: () => (this.mediaPluginLoader?.getState().map(s => s.name).filter((n) => !!n) ?? []),
-                            currentMedia: () => ({
-                                engine: config_1.config.raw.media.engine,
-                                image: config_1.config.raw.media.image,
-                                video: config_1.config.raw.media.video,
-                                audio: config_1.config.raw.media.audio,
-                            }),
-                        });
-                        return;
-                    }
-                    // GET/POST /api/model-config — recall worker model + media models (hot-apply)
-                    if (req.url?.match(/^\/api\/model-config(?:\?|$)/) && req.method === 'GET') {
-                        await (0, model_config_1.handleModelConfigGet)(req, res, this.modelConfigDeps());
-                        return;
-                    }
-                    if (req.url?.match(/^\/api\/model-config(?:\?|$)/) && req.method === 'POST') {
-                        await (0, model_config_1.handleModelConfigUpdate)(req, res, this.modelConfigDeps());
-                        return;
-                    }
-                    // POST /api/sessions/:id/fork|revert|unrevert — session branch primitives
-                    // (capability-gated: sessionBranchApi; unrevert is opencode-only → 404 on pi)
-                    if (req.url?.match(/^\/api\/sessions\/[^/]+\/(fork|revert|unrevert)(?:\?|$)/) && req.method === 'POST') {
-                        const handled = await (0, session_branch_1.handleSessionBranch)(req, res, req.url, { getRuntime: () => this.opencodeClient ?? null });
-                        if (handled)
-                            return;
-                    }
-                    // POST /api/session/:id/summarize — 手动压缩会话（TUI /compact；runtime 薄代理）
-                    if (req.url?.match(/^\/api\/session\/[^/]+\/summarize(?:\?|$)/) && req.method === 'POST') {
-                        const handled = await (0, session_summarize_1.handleSessionSummarize)(req, res, req.url, { getRuntime: () => this.opencodeClient ?? null });
-                        if (handled)
-                            return;
-                    }
+                    // POST /api/media/switch — P5 Wave 1 起由 registry dispatch 接管
+                    // GET/POST /api/model-config — P5 Wave 1 起由 registry dispatch 接管
+                    // POST /api/sessions/:id/fork|revert|unrevert + /api/session/:id/summarize
+                    // — P5 Wave 1 起由 registry dispatch 接管
                     // GET /api/usage?sessionID=xxx&projectID=xxx — consolidated usage (summary + providers)
                     if (req.url?.match(/^\/api\/usage(?:\?|$)/) && req.method === 'GET') {
                         try {
@@ -5183,7 +5195,10 @@ class MafwScheduler {
                                     session_id: sessionID,
                                     turn_id: turnId,
                                     source: source,
-                                    content: content.slice(0, 100_000),
+                                    // Redact secrets once at capture so every downstream consumer
+                                    // (turnCompress transcripts, worker prompts, archive) only
+                                    // ever sees redacted content.
+                                    content: (0, redact_1.redactSecrets)(content).slice(0, 100_000),
                                     failure,
                                 });
                                 // Async scan prefetch: precompute semantic recall for this turn
@@ -5203,6 +5218,7 @@ class MafwScheduler {
                         });
                         return;
                     }
+                    // POST /api/events — P5 Wave 1 起由 registry dispatch 接管
                     // SSE 事件（→ Dashboard / Chat）
                     if (req.url && req.url.startsWith('/api/events') && req.method === 'GET') {
                         const parsedUrl = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
@@ -5231,8 +5247,9 @@ class MafwScheduler {
                         res.end(JSON.stringify({ status: 'ok' }));
                         return;
                     }
-                    // Reverse proxy to opencode server for non-MAFW routes
-                    const serveUrl = config_1.config.server.serveUrl;
+                    // Reverse proxy to the agent backend for non-MAFW routes —
+                    // target from the runtime contract (getBaseUrl), config 仅 bootstrap 兜底
+                    const serveUrl = this.opencodeClient?.getBaseUrl?.() ?? config_1.config.server.serveUrl;
                     try {
                         const proxyUrl = new URL(req.url || '/', serveUrl);
                         const proxyReq = http.request(proxyUrl, {
@@ -5289,7 +5306,7 @@ class MafwScheduler {
             server.listen(this.apiPort, () => {
                 logger_1.log.info(`[Scheduler] HTTP API on port ${this.apiPort}`);
                 logger_1.log.info(`[Scheduler]  - POST /register  { projectDir, mafwDir }`);
-                logger_1.log.info(`[Scheduler]  - POST /control  { action, goalId, ... }`);
+                logger_1.log.info(`[Scheduler]  - POST /control | /api/goals/control  { action, goalId, ... }`);
                 logger_1.log.info(`[Scheduler]  - GET  /health`);
                 logger_1.log.info(`[Scheduler]  - GET  /mcp           (MCP legacy SSE / StreamableHTTP 405)`);
                 logger_1.log.info(`[Scheduler]  - POST /mcp           (MCP StreamableHTTP stateless + legacy SSE messages)`);
@@ -6204,6 +6221,14 @@ ${observations.map((o, i) => `[${i + 1}] ${o}`).join('\n')}`;
         });
         return run;
     }
+    // Slot-based read of a manager-session kv entry: each runtime owns a slot
+    // in the value (byRuntime), so switching runtimes never drops a topic —
+    // switching back resumes the previous manager. Legacy v1 entries are
+    // inferred by session id prefix and only surface under their own runtime.
+    // See manager-session-runtime.ts.
+    readManagerSessionEntry(projectDir) {
+        return (0, manager_session_runtime_1.readManagerSlot)(this.getGatewayDb().kvGet('manager-session', projectDir), this.runtimeName);
+    }
     // Serialized rotate: joins any in-flight ensure/create for the same project
     // so rotate and lazy-init never double-create (spec §4).
     async runManagerExclusive(projectDir, fn) {
@@ -6220,7 +6245,7 @@ ${observations.map((o, i) => `[${i + 1}] ${o}`).join('\n')}`;
         // The inflight map is shared with ensureManagerSession, whose joiners
         // expect the promise to resolve to a session id string — map the rotate
         // result onto the resulting kv entry.
-        const mapped = run.then(() => this.getGatewayDb().kvGet('manager-session', projectDir)?.sessionId ?? '', () => '');
+        const mapped = run.then(() => this.readManagerSessionEntry(projectDir)?.sessionId ?? '', () => '');
         this.managerSessionInflight.set(projectDir, mapped);
         try {
             return await run;
@@ -6235,7 +6260,7 @@ ${observations.map((o, i) => `[${i + 1}] ${o}`).join('\n')}`;
             throw new Error('opencodeClient not available');
         // Manager identity lives in the gateway DB (kv_store), so it survives
         // project-directory churn and never gets orphaned by directory moves.
-        const existing = this.getGatewayDb().kvGet('manager-session', projectDir);
+        const existing = this.readManagerSessionEntry(projectDir);
         if (existing?.sessionId) {
             await this.sdkSession.registerExternal(existing.sessionId, projectDir, {
                 mafw: { role: 'manager', pinned: true, exemptFromTrim: true, exemptFromEvict: true, exemptFromArchive: true },
@@ -6251,7 +6276,7 @@ ${observations.map((o, i) => `[${i + 1}] ${o}`).join('\n')}`;
             throw new Error('Failed to create manager session: no id returned');
         }
         const createdAt = new Date().toISOString();
-        this.getGatewayDb().kvSet('manager-session', projectDir, { sessionId, createdAt });
+        this.getGatewayDb().kvSet('manager-session', projectDir, (0, manager_session_runtime_1.writeManagerSlot)(this.getGatewayDb().kvGet('manager-session', projectDir), this.runtimeName, { sessionId, createdAt }));
         this.registerInternalSession(sessionId, 'manager');
         try {
             await this.sdkSession.registerExternal(sessionId, projectDir, {
@@ -6283,7 +6308,7 @@ ${observations.map((o, i) => `[${i + 1}] ${o}`).join('\n')}`;
     }
     rotateDeps() {
         return {
-            getManagerSession: (pd) => this.getGatewayDb().kvGet('manager-session', pd),
+            getManagerSession: (pd) => this.readManagerSessionEntry(pd),
             lock: (pd, fn) => this.runManagerExclusive(pd, fn),
             ensure: (pd) => this.ensureManagerSession(pd, this.mafwDirFor(pd)),
             downgrade: async (sid) => {
@@ -6330,7 +6355,7 @@ ${observations.map((o, i) => `[${i + 1}] ${o}`).join('\n')}`;
             return undefined;
         if (!this.milestonePush) {
             this.milestonePush = new milestone_push_1.MilestonePushNotifier({
-                getManagerSession: (pd) => this.getGatewayDb().kvGet('manager-session', pd),
+                getManagerSession: (pd) => this.readManagerSessionEntry(pd),
                 wasNotified: (key) => !!this.getGatewayDb().kvGet('milestone-notified', key),
                 markNotified: (key) => this.getGatewayDb().kvSet('milestone-notified', key, { at: new Date().toISOString() }),
                 readGoalState: (goalId, pd) => {
@@ -6359,7 +6384,7 @@ ${observations.map((o, i) => `[${i + 1}] ${o}`).join('\n')}`;
         const sessionId = session.id;
         if (!sessionId)
             throw new Error('Failed to create manager session: no id returned');
-        this.getGatewayDb().kvSet('manager-session', projectDir, { sessionId, createdAt: new Date().toISOString() });
+        this.getGatewayDb().kvSet('manager-session', projectDir, (0, manager_session_runtime_1.writeManagerSlot)(this.getGatewayDb().kvGet('manager-session', projectDir), this.runtimeName, { sessionId, createdAt: new Date().toISOString() }));
         this.registerInternalSession(sessionId, 'manager');
         await this.sdkSession.registerExternal(sessionId, projectDir, {
             mafw: { role: 'manager', pinned: true, exemptFromTrim: true, exemptFromEvict: true, exemptFromArchive: true },