@jack200714/mafw 4.10.1 → 4.10.2

package/gateway/dist/index.js

@@ -97,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");
@@ -110,24 +109,15 @@ 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 event_publish_1 = require("./routes/event-publish");
-const runtime_switch_1 = require("./routes/runtime-switch");
-const plugins_1 = require("./routes/plugins");
 const package_host_1 = require("./plugins/package-host");
 const package_context_1 = require("./plugins/package-context");
-const hub_1 = require("./plugins/hub");
-const restart_agent_1 = require("./routes/restart-agent");
-const session_mutations_1 = require("./routes/session-mutations");
 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) => {
@@ -228,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;
@@ -272,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
@@ -433,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;
@@ -1279,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: () => {
@@ -2085,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),
             });
@@ -2352,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;
@@ -2380,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);
@@ -3350,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 {
@@ -3606,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");
@@ -3729,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 () => {
@@ -3833,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') {
@@ -4189,173 +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: '' });
-                                // opencode 经 registerBuiltin 注册，getBuiltinNames 已含——不再手工 push（防重复）
-                                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() ?? [],
-                        },
-                    };
-                    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');
@@ -4818,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 {
@@ -4988,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 => ({
@@ -5053,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 {
@@ -5352,11 +5218,7 @@ class MafwScheduler {
                         });
                         return;
                     }
-                    // POST /api/events —— 事件发布（插件/外部程序 → 全 UI 通道；契约见 routes/event-publish.ts）
-                    if (req.url && req.url.startsWith('/api/events') && req.method === 'POST') {
-                        await (0, event_publish_1.handleEventPublish)({ broadcast: (e) => this.broadcast(e) }, req, res);
-                        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'}`);
@@ -5385,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, {
@@ -5443,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)`);