@steerable/agent-shell 0.6.56 → 0.6.57

package/dist/local-backend/router.js

@@ -3,7 +3,8 @@ import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import os from 'node:os';
-import { getAppRootDir, shellOpenPath } from '../runtime.js';
+import { getAppRootDir, getUserDataDir, shellOpenPath } from '../runtime.js';
+import { acquireChatWriteLock, ChatBusyError, } from '../storage/process-locks.js';
 import { llmService, getSidecarSupervisor, whenSidecarSupervisor } from '../llm/index.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 import { buildWorldState, getActiveCoreLoopStreamId, streamCoreLoopTurn, } from './coreloop-stream.js';
@@ -48,6 +49,8 @@ import { allocateProjectHome, ensureChatWorkspace, ensureProjectHome, expandUser
 import { registerLiveStream, getLiveStream, removeLiveStream } from './live-stream.js';
 import { beginPackTurnObservers, collectPackExecWritableRoots, collectPackForcedSkillVars, collectPackWorldState, } from './pack-turn-hooks.js';
 import { matchPackBackendRoute } from './pack-backend-routes.js';
+import { invokePackHttpRoute } from '../host/http-routes.js';
+import { installProductCli } from '../cli-install.js';
 import { collectTurnFiles } from './turn-files.js';
 import { resolveMentionedPaths } from './mentioned-paths.js';
 import { getAuthProvider } from '../auth/index.js';
@@ -675,31 +678,48 @@ export class LocalBackendRouter {
                 };
             }
             if (method === 'DELETE') {
-                if (url.searchParams.get('onlyIfEmpty') === '1') {
-                    const deleted = await this.store.deleteChatIfEmpty(chatId);
+                const lease = this.tryChatLock(chatId);
+                if (!lease)
+                    return this.chatBusy();
+                try {
+                    if (url.searchParams.get('onlyIfEmpty') === '1') {
+                        const deleted = await this.store.deleteChatIfEmpty(chatId);
+                        return {
+                            status: 200,
+                            data: { success: true, deleted, chatId },
+                        };
+                    }
+                    const ok = await this.store.deleteChat(chatId);
+                    if (!ok)
+                        return this.notFound('Chat not found');
                     return {
                         status: 200,
-                        data: { success: true, deleted, chatId },
+                        data: {
+                            success: true,
+                            message: '删除成功',
+                            chatId,
+                        },
                     };
                 }
-                const ok = await this.store.deleteChat(chatId);
-                if (!ok)
-                    return this.notFound('Chat not found');
-                return {
-                    status: 200,
-                    data: {
-                        success: true,
-                        message: '删除成功',
-                        chatId,
-                    },
-                };
+                finally {
+                    lease.release();
+                }
             }
         }
         const chatPinMatch = pathname.match(/^\/api\/v2\/chats\/([^/]+)\/pin$/);
         if (chatPinMatch && method === 'PUT') {
             const chatId = chatPinMatch[1];
             const payload = this.toRecord(request.body);
-            const updated = await this.store.updateChat(chatId, { isPinned: Boolean(payload.isPinned) });
+            const lease = this.tryChatLock(chatId);
+            if (!lease)
+                return this.chatBusy();
+            let updated;
+            try {
+                updated = await this.store.updateChat(chatId, { isPinned: Boolean(payload.isPinned) });
+            }
+            finally {
+                lease.release();
+            }
             if (!updated)
                 return this.notFound('Chat not found');
             return {
@@ -737,12 +757,21 @@ export class LocalBackendRouter {
                     return this.badRequest('projectId 必须是项目 id 字符串或 null');
                 }
             }
-            const updated = await this.store.updateChat(chatId, {
-                title: typeof payload.title === 'string' ? payload.title : undefined,
-                systemPrompt: typeof payload.systemPrompt === 'string' ? payload.systemPrompt : undefined,
-                pinnedRefs: Array.isArray(payload.pinnedRefs) ? payload.pinnedRefs : undefined,
-                projectId: projectIdUpdate,
-            });
+            const lease = this.tryChatLock(chatId);
+            if (!lease)
+                return this.chatBusy();
+            let updated;
+            try {
+                updated = await this.store.updateChat(chatId, {
+                    title: typeof payload.title === 'string' ? payload.title : undefined,
+                    systemPrompt: typeof payload.systemPrompt === 'string' ? payload.systemPrompt : undefined,
+                    pinnedRefs: Array.isArray(payload.pinnedRefs) ? payload.pinnedRefs : undefined,
+                    projectId: projectIdUpdate,
+                });
+            }
+            finally {
+                lease.release();
+            }
             if (!updated)
                 return this.notFound('Chat not found');
             return {
@@ -1488,6 +1517,19 @@ export class LocalBackendRouter {
         // W-llm-diagnose：LLM 链路诊断。设置页「诊断」按钮触发，在主进程内
         // 探测 DNS/TCP/TLS/HTTP/chat 五级连通性，并报告宿主机的 ambient 代理
         // 配置（sidecar 沙箱视角会隐藏用户需要看到的代理问题）。
+        if (method === 'POST' && pathname === '/api/v2/cli/install') {
+            const payload = this.toRecord(request.body);
+            const name = typeof payload.name === 'string' ? payload.name : '';
+            try {
+                return { status: 200, data: installProductCli(name) };
+            }
+            catch (error) {
+                return {
+                    status: 400,
+                    data: { error: error instanceof Error ? error.message : String(error) },
+                };
+            }
+        }
         if (method === 'POST' && pathname === '/api/v2/llm/diagnose') {
             const payload = this.toRecord(request.body);
             const settings = llmService.getSettings();
@@ -1854,6 +1896,9 @@ export class LocalBackendRouter {
                 body: request.body,
             });
         }
+        const packHttp = await invokePackHttpRoute(method, pathname, request.body);
+        if (packHttp)
+            return packHttp;
         return this.fallbackResponse(method, pathname);
     }
     /**
@@ -1949,242 +1994,244 @@ export class LocalBackendRouter {
             emit(this.sse('error', { message: 'chat not found' }));
             return { status: 404 };
         }
-        // W7-1: resume=true（仅 send 路由）续跑 durable record 里被中断的 turn，
-        // 不追加新用户消息；与 regenerate 互斥（regenerate 有自己的路径参数语义）。
-        const isResume = !regenerateMatch && payload.resume === true;
-        let userMessageText;
-        if (regenerateMatch) {
-            // Regenerate = truncate-and-rerun, *not* "append a fresh 'please
-            // regenerate' user turn on top of the old reply". The old bug ignored
-            // the :messageId path param entirely, so regenerating just piled a new
-            // user+assistant pair onto history while the original (possibly bad)
-            // assistant reply stayed in place — the model saw both and had no real
-            // reason to answer differently.
-            //
-            // sidecar 门必须先于任何写操作：rerun 回合只能跑在 sidecar 上
-            // （handleCoreLoopTurn 无 sidecar 直接 503）。若先截断再 503，旧回复
-            // 已删、新回复不会产生、record 也不存在——非破坏性承诺破窗。
-            if (!getSidecarSupervisor()) {
-                emit(this.sse('error', { message: 'coreloop enabled but sidecar is not running' }));
-                return { status: 503 };
-            }
-            const targetMessageId = regenerateMatch[2];
-            // The user turn that prompted the target reply is whatever immediately
-            // precedes it — re-derive its text so buildConversationMessages gets
-            // the *real* request instead of a generic placeholder (matters for
-            // deferred-exec detection, mode preamble, etc., which all key off the
-            // actual ask).
-            const priorMessages = (await this.store.listMessages(chatId, 200)).reverse();
-            const resolution = resolveRegenerateContext(priorMessages, targetMessageId);
-            if (!resolution.ok) {
-                emit(this.sse('error', { message: 'regenerate target message not found or not an assistant message' }));
-                return { status: 404 };
-            }
-            userMessageText = resolution.userMessageText;
-            // W5-2: fork the durable record BEFORE truncating the UI store, so
-            // the old tail survives as a discoverable branch instead of being
-            // destroyed (UI store) / interleaved with the new tail (record).
-            // The fork point is addressed by user-message ordinal: the prompting
-            // user turn is the last user message before the target, i.e. index
-            // (count of user messages before the target) - 1. An ordinal the sidecar
-            // declines to split — no record, or a point inside a branch seed — is the
-            // protocol's documented fallback and truncates; a fork that failed instead
-            // of answering refuses the request (planRegenerateTruncate).
-            const supervisor = getSidecarSupervisor();
-            const outcome = supervisor
-                ? await supervisor.forkSession({
-                    recordId: await this.store.getChatRecordId(chatId) ?? chatId,
-                    beforeUserIndex: resolveRegenerateForkOrdinal(priorMessages, targetMessageId),
-                    newRecordId: `${chatId}:r${Date.now().toString(36)}`,
-                })
-                : null;
-            if (outcome?.ok) {
-                await this.store.setChatRecordId(chatId, outcome.fork.recordId);
-                console.log('[local-backend] regenerate: record forked (old tail preserved)', {
+        return this.withChatWriteLock(chatId, emit, async () => {
+            // W7-1: resume=true（仅 send 路由）续跑 durable record 里被中断的 turn，
+            // 不追加新用户消息；与 regenerate 互斥（regenerate 有自己的路径参数语义）。
+            const isResume = !regenerateMatch && payload.resume === true;
+            let userMessageText;
+            if (regenerateMatch) {
+                // Regenerate = truncate-and-rerun, *not* "append a fresh 'please
+                // regenerate' user turn on top of the old reply". The old bug ignored
+                // the :messageId path param entirely, so regenerating just piled a new
+                // user+assistant pair onto history while the original (possibly bad)
+                // assistant reply stayed in place — the model saw both and had no real
+                // reason to answer differently.
+                //
+                // sidecar 门必须先于任何写操作：rerun 回合只能跑在 sidecar 上
+                // （handleCoreLoopTurn 无 sidecar 直接 503）。若先截断再 503，旧回复
+                // 已删、新回复不会产生、record 也不存在——非破坏性承诺破窗。
+                if (!getSidecarSupervisor()) {
+                    emit(this.sse('error', { message: 'coreloop enabled but sidecar is not running' }));
+                    return { status: 503 };
+                }
+                const targetMessageId = regenerateMatch[2];
+                // The user turn that prompted the target reply is whatever immediately
+                // precedes it — re-derive its text so buildConversationMessages gets
+                // the *real* request instead of a generic placeholder (matters for
+                // deferred-exec detection, mode preamble, etc., which all key off the
+                // actual ask).
+                const priorMessages = (await this.store.listMessages(chatId, 200)).reverse();
+                const resolution = resolveRegenerateContext(priorMessages, targetMessageId);
+                if (!resolution.ok) {
+                    emit(this.sse('error', { message: 'regenerate target message not found or not an assistant message' }));
+                    return { status: 404 };
+                }
+                userMessageText = resolution.userMessageText;
+                // W5-2: fork the durable record BEFORE truncating the UI store, so
+                // the old tail survives as a discoverable branch instead of being
+                // destroyed (UI store) / interleaved with the new tail (record).
+                // The fork point is addressed by user-message ordinal: the prompting
+                // user turn is the last user message before the target, i.e. index
+                // (count of user messages before the target) - 1. An ordinal the sidecar
+                // declines to split — no record, or a point inside a branch seed — is the
+                // protocol's documented fallback and truncates; a fork that failed instead
+                // of answering refuses the request (planRegenerateTruncate).
+                const supervisor = getSidecarSupervisor();
+                const outcome = supervisor
+                    ? await supervisor.forkSession({
+                        recordId: await this.store.getChatRecordId(chatId) ?? chatId,
+                        beforeUserIndex: resolveRegenerateForkOrdinal(priorMessages, targetMessageId),
+                        newRecordId: `${chatId}:r${Date.now().toString(36)}`,
+                    })
+                    : null;
+                if (outcome?.ok) {
+                    await this.store.setChatRecordId(chatId, outcome.fork.recordId);
+                    console.log('[local-backend] regenerate: record forked (old tail preserved)', {
+                        chatId,
+                        branchRecordId: outcome.fork.recordId,
+                        label: outcome.fork.label,
+                    });
+                }
+                else if (outcome) {
+                    console.log('[local-backend] regenerate: no fork', {
+                        chatId,
+                        declined: outcome.declined,
+                        reason: outcome.reason,
+                    });
+                }
+                const plan = planRegenerateTruncate(outcome);
+                if (!plan.proceed) {
+                    emit(this.sse('error', { message: plan.message }));
+                    return { status: 409 };
+                }
+                const deleted = await this.store.deleteMessagesFrom(chatId, targetMessageId);
+                console.log('[local-backend] regenerate: truncated history', {
                     chatId,
-                    branchRecordId: outcome.fork.recordId,
-                    label: outcome.fork.label,
+                    targetMessageId,
+                    deletedCount: deleted,
                 });
             }
-            else if (outcome) {
-                console.log('[local-backend] regenerate: no fork', {
-                    chatId,
-                    declined: outcome.declined,
-                    reason: outcome.reason,
+            else if (isResume) {
+                // W7-1: 继续被中断的 turn —— 不追加新用户消息（记录里已有），而是让
+                // sidecar 回放 durable record 的投影作为循环种子。只在检测确为
+                // interrupted 时接受：对一个已正常完结的 turn 续跑只会给完整对话
+                // 凭空多接一段回复。
+                const prior = await this.store.listMessages(chatId, 200);
+                const interrupted = detectInterruptedTurn({
+                    turnActive: await this.store.getTurnActive(chatId) !== null,
+                    streamActive: getActiveCoreLoopStreamId(chatId) !== undefined,
+                    lastMessageRole: prior[0]?.role ?? null,
                 });
+                const lastUser = prior.find(m => m.role === 'user');
+                if (!interrupted || !lastUser) {
+                    emit(this.sse('error', { message: '没有可继续的中断回复' }));
+                    return { status: 409 };
+                }
+                // 触发轮的用户消息仍在库里（崩溃只丢了回复）——取其原文喂给
+                // buildConversationMessages，让 mode  preamble / deferred-exec 检测
+                // 仍然基于真实诉求。发给 sidecar 的 messages 为空（见下方调用点）。
+                userMessageText = lastUser.content;
             }
-            const plan = planRegenerateTruncate(outcome);
-            if (!plan.proceed) {
-                emit(this.sse('error', { message: plan.message }));
-                return { status: 409 };
-            }
-            const deleted = await this.store.deleteMessagesFrom(chatId, targetMessageId);
-            console.log('[local-backend] regenerate: truncated history', {
+            else {
+                userMessageText = String(payload.message || '').trim();
+            }
+            if (!userMessageText) {
+                emit(this.sse('error', { message: 'message is required' }));
+                return { status: 400 };
+            }
+            const cleanedResult = await this.cleanUserMessage(userMessageText);
+            const cleanUserMessageText = cleanedResult.cleanText;
+            const forcedSkillName = cleanedResult.skillName;
+            const forcedMcpToolToken = cleanedResult.mcpToolToken;
+            // 仅在以下条件全部成立时才在本轮结束后生成 AI 标题：
+            //   1. 当前标题仍是 storage.createChat 默认值「新对话」（用户没自己改过）
+            //   2. 这是非 regenerate 的真实 user turn（regenerate 不应改写标题）
+            //   3. 历史里目前没有任何 assistant 消息——也就是说，本轮即将产生的是第一条助手回复
+            // 这避免在已经聊到一半的对话里突然把标题换掉。listMessages 是 DESC，limit 拉
+            // 大一点确保看到完整历史（200 已经覆盖绝大多数本地会话）。
+            const existingAssistant = (await this.store
+                .listMessages(chatId, 200))
+                .some((m) => m.role === 'assistant');
+            const shouldGenerateTitle = !regenerateMatch &&
+                !isResume &&
+                !existingAssistant &&
+                (chat.title === '新对话' || chat.title.trim() === '');
+            const firstUserMessageForTitle = cleanUserMessageText;
+            console.log('[local-backend] title-gen decision', {
                 chatId,
-                targetMessageId,
-                deletedCount: deleted,
-            });
-        }
-        else if (isResume) {
-            // W7-1: 继续被中断的 turn —— 不追加新用户消息（记录里已有），而是让
-            // sidecar 回放 durable record 的投影作为循环种子。只在检测确为
-            // interrupted 时接受：对一个已正常完结的 turn 续跑只会给完整对话
-            // 凭空多接一段回复。
-            const prior = await this.store.listMessages(chatId, 200);
-            const interrupted = detectInterruptedTurn({
-                turnActive: await this.store.getTurnActive(chatId) !== null,
-                streamActive: getActiveCoreLoopStreamId(chatId) !== undefined,
-                lastMessageRole: prior[0]?.role ?? null,
+                shouldGenerateTitle,
+                currentTitle: chat.title,
+                isRegenerate: !!regenerateMatch,
+                existingAssistant,
             });
-            const lastUser = prior.find(m => m.role === 'user');
-            if (!interrupted || !lastUser) {
-                emit(this.sse('error', { message: '没有可继续的中断回复' }));
-                return { status: 409 };
-            }
-            // 触发轮的用户消息仍在库里（崩溃只丢了回复）——取其原文喂给
-            // buildConversationMessages，让 mode  preamble / deferred-exec 检测
-            // 仍然基于真实诉求。发给 sidecar 的 messages 为空（见下方调用点）。
-            userMessageText = lastUser.content;
-        }
-        else {
-            userMessageText = String(payload.message || '').trim();
-        }
-        if (!userMessageText) {
-            emit(this.sse('error', { message: 'message is required' }));
-            return { status: 400 };
-        }
-        const cleanedResult = await this.cleanUserMessage(userMessageText);
-        const cleanUserMessageText = cleanedResult.cleanText;
-        const forcedSkillName = cleanedResult.skillName;
-        const forcedMcpToolToken = cleanedResult.mcpToolToken;
-        // 仅在以下条件全部成立时才在本轮结束后生成 AI 标题：
-        //   1. 当前标题仍是 storage.createChat 默认值「新对话」（用户没自己改过）
-        //   2. 这是非 regenerate 的真实 user turn（regenerate 不应改写标题）
-        //   3. 历史里目前没有任何 assistant 消息——也就是说，本轮即将产生的是第一条助手回复
-        // 这避免在已经聊到一半的对话里突然把标题换掉。listMessages 是 DESC，limit 拉
-        // 大一点确保看到完整历史（200 已经覆盖绝大多数本地会话）。
-        const existingAssistant = (await this.store
-            .listMessages(chatId, 200))
-            .some((m) => m.role === 'assistant');
-        const shouldGenerateTitle = !regenerateMatch &&
-            !isResume &&
-            !existingAssistant &&
-            (chat.title === '新对话' || chat.title.trim() === '');
-        const firstUserMessageForTitle = cleanUserMessageText;
-        console.log('[local-backend] title-gen decision', {
-            chatId,
-            shouldGenerateTitle,
-            currentTitle: chat.title,
-            isRegenerate: !!regenerateMatch,
-            existingAssistant,
-        });
-        // Regenerate reruns against the (now-truncated) existing history — the
-        // triggering user message is already in it, so unlike `send` we must not
-        // insert another copy or the model would see it twice. Resume (W7-1)
-        // likewise appends nothing: the crashed turn's user message is already
-        // persisted (and already in the durable record).
-        let currentUserMessageId;
-        // 本轮被点名的智能体：菜单点选带来的 id 优先，手打的 `@名字` 从正文
-        // 解析补齐（两者缺一，提及就在后端消失，只剩前端徽章）。
-        const chatAgents = await this.store.listChatAgents();
-        const mentionedAgentIds = resolveMentionedAgentIds(payload, userMessageText, chatAgents);
-        if (!regenerateMatch && !isResume) {
-            const userMeta = mentionedAgentIds.length > 0
-                ? JSON.stringify({ mentionedAgentIds })
-                : null;
-            const userMessage = await this.store.addMessage(chatId, 'user', userMessageText, userMeta);
-            currentUserMessageId = userMessage.id;
-            emit(this.sseData({ type: 'user_message', message: userMessage }));
-        }
-        // Plan 模式（类 Cursor "先出计划"）：仅暴露只读工具给模型，引导它先调研、
-        // 再输出结构化计划，不做任何写操作/执行。其余值一律视为常规 agent 模式。
-        const chatMode = resolveTurnChatMode(payload.mode);
-        // 本轮生效的智能体：人设、技能勾选、工具策略同源。必须先解析——工具
-        // 策略决定工具列表，工具列表又决定技能的触发条件。
-        const turnAgents = await this.resolveTurnAgents(chatId, payload, mentionedAgentIds);
-        // Wave 2 工具分层：模型可见列表只出 direct 层（内置工具 + tool_search
-        // 发现缝）；MCP 动态工具全在 deferred 层，经 tool_search 命中即调。
-        // 附带收益：MCP 目录增删不再改动系统提示词里的工具名录，前缀更稳。
-        const turnTools = this.toolRouter
-            .listModelSchemas(turnAgents.capability.toolPolicy)
-            .filter(schema => chatMode !== 'plan' || schema.mode === 'read')
-            .map(schema => ({
-            name: schema.name,
-            description: schema.description,
-            inputSchema: schema.inputSchema,
-        }));
-        // 用户通过 "/" 显式指定的 MCP 工具：从注册表补齐元信息，available 取决于
-        // 该工具本轮是否真的在 turnTools 里（未启用/未连接/被 plan 模式过滤都算
-        // 不可用——指令模块会据此渲染"强制调用"或"如实告知不可用"两种版本）。
-        let forcedMcpTool;
-        if (forcedMcpToolToken) {
-            const resolved = this.toolRouter.mcpRegistry?.findToolByToken(forcedMcpToolToken) ?? null;
-            const token = resolved?.token ?? forcedMcpToolToken;
-            const tokenParts = token.split('__');
-            // 显式指定的工具属于 deferred 层、不在模型可见列表——本轮直接提升
-            // 进列表（用户点名 = 最强信号），省一轮 tool_search 往返。
-            // 智能体的工具策略不因点名而让步：被拒的工具不提升，forcedMcpTool
-            // 随之落到 available: false 分支（指令模块如实告知不可用）。
-            if (resolved &&
-                !turnTools.some((t) => t.name === token) &&
-                isToolAllowed(turnAgents.capability.toolPolicy, token)) {
-                const schema = this.toolRouter.getSchemaByName(token);
-                if (schema && (chatMode !== 'plan' || schema.mode === 'read')) {
-                    turnTools.push({
-                        name: schema.name,
-                        description: schema.description,
-                        inputSchema: schema.inputSchema,
-                    });
+            // Regenerate reruns against the (now-truncated) existing history — the
+            // triggering user message is already in it, so unlike `send` we must not
+            // insert another copy or the model would see it twice. Resume (W7-1)
+            // likewise appends nothing: the crashed turn's user message is already
+            // persisted (and already in the durable record).
+            let currentUserMessageId;
+            // 本轮被点名的智能体：菜单点选带来的 id 优先，手打的 `@名字` 从正文
+            // 解析补齐（两者缺一，提及就在后端消失，只剩前端徽章）。
+            const chatAgents = await this.store.listChatAgents();
+            const mentionedAgentIds = resolveMentionedAgentIds(payload, userMessageText, chatAgents);
+            if (!regenerateMatch && !isResume) {
+                const userMeta = mentionedAgentIds.length > 0
+                    ? JSON.stringify({ mentionedAgentIds })
+                    : null;
+                const userMessage = await this.store.addMessage(chatId, 'user', userMessageText, userMeta);
+                currentUserMessageId = userMessage.id;
+                emit(this.sseData({ type: 'user_message', message: userMessage }));
+            }
+            // Plan 模式（类 Cursor "先出计划"）：仅暴露只读工具给模型，引导它先调研、
+            // 再输出结构化计划，不做任何写操作/执行。其余值一律视为常规 agent 模式。
+            const chatMode = resolveTurnChatMode(payload.mode);
+            // 本轮生效的智能体：人设、技能勾选、工具策略同源。必须先解析——工具
+            // 策略决定工具列表，工具列表又决定技能的触发条件。
+            const turnAgents = await this.resolveTurnAgents(chatId, payload, mentionedAgentIds);
+            // Wave 2 工具分层：模型可见列表只出 direct 层（内置工具 + tool_search
+            // 发现缝）；MCP 动态工具全在 deferred 层，经 tool_search 命中即调。
+            // 附带收益：MCP 目录增删不再改动系统提示词里的工具名录，前缀更稳。
+            const turnTools = this.toolRouter
+                .listModelSchemas(turnAgents.capability.toolPolicy)
+                .filter(schema => chatMode !== 'plan' || schema.mode === 'read')
+                .map(schema => ({
+                name: schema.name,
+                description: schema.description,
+                inputSchema: schema.inputSchema,
+            }));
+            // 用户通过 "/" 显式指定的 MCP 工具：从注册表补齐元信息，available 取决于
+            // 该工具本轮是否真的在 turnTools 里（未启用/未连接/被 plan 模式过滤都算
+            // 不可用——指令模块会据此渲染"强制调用"或"如实告知不可用"两种版本）。
+            let forcedMcpTool;
+            if (forcedMcpToolToken) {
+                const resolved = this.toolRouter.mcpRegistry?.findToolByToken(forcedMcpToolToken) ?? null;
+                const token = resolved?.token ?? forcedMcpToolToken;
+                const tokenParts = token.split('__');
+                // 显式指定的工具属于 deferred 层、不在模型可见列表——本轮直接提升
+                // 进列表（用户点名 = 最强信号），省一轮 tool_search 往返。
+                // 智能体的工具策略不因点名而让步：被拒的工具不提升，forcedMcpTool
+                // 随之落到 available: false 分支（指令模块如实告知不可用）。
+                if (resolved &&
+                    !turnTools.some((t) => t.name === token) &&
+                    isToolAllowed(turnAgents.capability.toolPolicy, token)) {
+                    const schema = this.toolRouter.getSchemaByName(token);
+                    if (schema && (chatMode !== 'plan' || schema.mode === 'read')) {
+                        turnTools.push({
+                            name: schema.name,
+                            description: schema.description,
+                            inputSchema: schema.inputSchema,
+                        });
+                    }
                 }
+                forcedMcpTool = {
+                    token,
+                    toolName: resolved?.toolName ?? tokenParts.slice(2).join('__'),
+                    serverName: resolved?.serverName ?? '',
+                    description: resolved?.description ?? '',
+                    available: turnTools.some((t) => t.name === token),
+                };
             }
-            forcedMcpTool = {
-                token,
-                toolName: resolved?.toolName ?? tokenParts.slice(2).join('__'),
-                serverName: resolved?.serverName ?? '',
-                description: resolved?.description ?? '',
-                available: turnTools.some((t) => t.name === token),
-            };
-        }
-        const turnToolNames = turnTools.map((tool) => tool.name);
-        const mentionRoster = await buildMentionDelegateRoster(turnAgents.delegates, turnToolNames);
-        // 常驻可委派名单：其余智能体也进画像，技能/提示里的「交给 X」无需用户
-        // `@` 就能落成一次真实委派。父代理自己不进——它就是本轮的执行者，给它
-        // 一个自己的画像只会诱导无意义的自委派（`@自己` 走提及那条路，仍然可以）。
-        const ambientRoster = await buildAmbientDelegateRoster(chatAgents, turnToolNames, {
-            excludeAgentIds: [
-                ...mentionRoster.map((row) => row.agentId),
-                ...(turnAgents.parent ? [turnAgents.parent.id] : []),
-            ],
-            reservedProfileNames: [
-                ...Object.keys(BUILTIN_SUBAGENT_PROFILES),
-                ...mentionRoster.map((row) => row.profileName),
-            ],
-        });
-        const { systemPrompt, messages, skillContext } = await this.buildConversationMessages(chatId, cleanUserMessageText, payload, turnTools, turnAgents, forcedSkillName, chatMode, forcedMcpTool, currentUserMessageId, { mention: mentionRoster, ambient: ambientRoster });
-        // A4: the sidecar-hosted CoreLoop is the only chat path (the TS loop
-        // was deleted 2026-08-26 after default-on + canary verification). Tools
-        // round-trip back to this process over the reverse channel. If the
-        // sidecar isn't running, handleCoreLoopTurn fails loud with a 503.
-        return this.handleCoreLoopTurn({
-            chatId,
-            systemPrompt,
-            // W7-1: on resume the sidecar replays the durable record's projection
-            // as the loop seed and rejects a non-empty host history — the record
-            // is authoritative, so the freshly built history stays unsent (only
-            // systemPrompt / skillContext ride along).
-            messages: isResume ? [] : messages,
-            skillContext,
-            turnTools,
-            toolPolicy: turnAgents.capability.toolPolicy,
-            chatMode,
-            payload,
-            emit,
-            signal,
-            shouldGenerateTitle,
-            firstUserMessageForTitle,
-            resume: isResume,
-            subagent: mergeTurnSubagentParam(Object.fromEntries(mentionRoster.map((row) => [row.profileName, row.profile])), Object.fromEntries(ambientRoster.map((row) => [row.profileName, row.profile]))),
-            parentAgentId: turnAgents.parent?.id ?? null,
+            const turnToolNames = turnTools.map((tool) => tool.name);
+            const mentionRoster = await buildMentionDelegateRoster(turnAgents.delegates, turnToolNames);
+            // 常驻可委派名单：其余智能体也进画像，技能/提示里的「交给 X」无需用户
+            // `@` 就能落成一次真实委派。父代理自己不进——它就是本轮的执行者，给它
+            // 一个自己的画像只会诱导无意义的自委派（`@自己` 走提及那条路，仍然可以）。
+            const ambientRoster = await buildAmbientDelegateRoster(chatAgents, turnToolNames, {
+                excludeAgentIds: [
+                    ...mentionRoster.map((row) => row.agentId),
+                    ...(turnAgents.parent ? [turnAgents.parent.id] : []),
+                ],
+                reservedProfileNames: [
+                    ...Object.keys(BUILTIN_SUBAGENT_PROFILES),
+                    ...mentionRoster.map((row) => row.profileName),
+                ],
+            });
+            const { systemPrompt, messages, skillContext } = await this.buildConversationMessages(chatId, cleanUserMessageText, payload, turnTools, turnAgents, forcedSkillName, chatMode, forcedMcpTool, currentUserMessageId, { mention: mentionRoster, ambient: ambientRoster });
+            // A4: the sidecar-hosted CoreLoop is the only chat path (the TS loop
+            // was deleted 2026-08-26 after default-on + canary verification). Tools
+            // round-trip back to this process over the reverse channel. If the
+            // sidecar isn't running, handleCoreLoopTurn fails loud with a 503.
+            return this.handleCoreLoopTurn({
+                chatId,
+                systemPrompt,
+                // W7-1: on resume the sidecar replays the durable record's projection
+                // as the loop seed and rejects a non-empty host history — the record
+                // is authoritative, so the freshly built history stays unsent (only
+                // systemPrompt / skillContext ride along).
+                messages: isResume ? [] : messages,
+                skillContext,
+                turnTools,
+                toolPolicy: turnAgents.capability.toolPolicy,
+                chatMode,
+                payload,
+                emit,
+                signal,
+                shouldGenerateTitle,
+                firstUserMessageForTitle,
+                resume: isResume,
+                subagent: mergeTurnSubagentParam(Object.fromEntries(mentionRoster.map((row) => [row.profileName, row.profile])), Object.fromEntries(ambientRoster.map((row) => [row.profileName, row.profile]))),
+                parentAgentId: turnAgents.parent?.id ?? null,
+            });
         });
     }
     /**
@@ -2952,6 +2999,35 @@ export class LocalBackendRouter {
         }
         return String(value);
     }
+    chatBusy() {
+        return {
+            status: 409,
+            data: { code: 'chat_busy', message: '该会话正在另一个进程中运行' },
+        };
+    }
+    tryChatLock(chatId) {
+        try {
+            return acquireChatWriteLock(getUserDataDir(), chatId);
+        }
+        catch (error) {
+            if (error instanceof ChatBusyError)
+                return null;
+            throw error;
+        }
+    }
+    async withChatWriteLock(chatId, emit, body) {
+        const lease = this.tryChatLock(chatId);
+        if (!lease) {
+            emit(this.sse('error', { code: 'chat_busy', message: '该会话正在另一个进程中运行' }));
+            return { status: 409 };
+        }
+        try {
+            return await body();
+        }
+        finally {
+            lease.release();
+        }
+    }
     sse(event, data) {
         return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
     }