aws-runtime-bridge 1.9.40 → 1.9.45

package/package/aws-client-agent-mcp/dist/mcp-server.js

@@ -11,7 +11,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 import { AgentClient } from "./agent-client.js";
 import { MCP_SERVER_NAME, MCP_SERVER_VERSION, REGISTER_MAX_RETRIES, REGISTER_RETRY_INTERVAL_MS, DEGRADED_MODE_ENABLED, DEGRADED_MODE_RETRY_INTERVAL_MS, DEGRADED_MODE_MAX_RETRIES, } from "./constants.js";
 import { logger } from "./logger.js";
-import { MCP_TOOLS } from "./mcp-tools.js";
+import { MCP_TOOLS, MEMORY_TOOL_NAMES } from "./mcp-tools.js";
 import { MessageBuffer } from "./message-buffer.js";
 import { ContextManager } from "./context-manager.js";
 import { MemoryCapacityError, MemoryStore, } from "./memory-store.js";
@@ -24,7 +24,6 @@ const DEFAULT_MCP_HTTP_REQUEST_TIMEOUT_MS = 120_000;
  * poll_message 永不超时返回空，只在有消息可返回时才退出。
  */
 const POLL_MESSAGE_INTERNAL_POLL_INTERVAL_MS = 30_000;
-const DEFAULT_MEMORY_FILE_CHECK_INTERVAL_MS = 5_000;
 const PATH_UNSAFE_CHARACTERS = new Set([
     "<",
     ">",
@@ -49,6 +48,8 @@ export class McpServer {
     hasRoleName = false;
     /** 上下文管理器 (v1.8.0) */
     contextManager;
+    /** 子 Agent 模式：仅暴露 Memory 工具，拒绝非 Memory 工具调用 */
+    isSubAgent;
     /**
      * 内存级去重缓存：记录本轮已通知过的 listable memory 文件变更状态。
      * key = memoryId，value = 已通知时刻各绑定文件的 MD5 复合哈希。
@@ -56,14 +57,40 @@ export class McpServer {
      * 进程重启后自动清空（届时重新检测）。
      */
     notifiedFileChangeMemoryIds = new Map();
+    /**
+     * Step1「memory 仍处于 updating 状态」提醒的冷却时间戳表。
+     * key = memory URI，value = 上次发送「请继续更新」提醒的时间戳。
+     * 用于避免 buildMemoryFileChangeNotification 在 polling 周期内对 sticky 的 updating
+     * memory 每轮都裸发 _acodeAutoDelegate（进而导致运行层反复 spawn 相同子任务）。
+     * 冷却窗口内不再发出该提醒；窗口到期后若 memory 仍未处理，才会重新委托。
+     */
+    lastUpdatePendingNotifyAt = new Map();
+    /** Step1「仍 updating」提醒的冷却窗口（5 分钟）。冷却期内不重复裸发 _acodeAutoDelegate。 */
+    static UPDATE_PENDING_NOTIFY_COOLDOWN_MS = 5 * 60 * 1000;
     /**
      * 本地缓存 listable 记忆（recently_memory/agent_memory）的文件 MD5 map。
      * 服务端（Java 后端）不持久化 file_md5_map 字段，listByType 返回的记录该字段为 undefined。
      * 必须本地缓存才能让 checkMemoriesFileChanges 有正确的旧 MD5 做对比。
      */
     listableMd5Cache = new Map();
-    /** 后台 Memory 文件变更检测定时器 (v1.9.0) */
-    memoryFileCheckInterval = null;
+    /**
+     * 租约续期定时器 (v1.21.0)。
+     * 每 60 秒续期一次当前 agent 持有的所有 updating memory 的租约。
+     */
+    leaseRenewalTimer = null;
+    static LEASE_DURATION_MINUTES = 10;
+    static LEASE_RENEW_INTERVAL_MS = 60_000;
+    /**
+     * claim 去重缓存 (v1.21.0)。
+     * 避免 5s 后台定时器重复调 server claim 同一个 memory。
+     * key = memory URI, value = 本地缓存的租约到期时间戳。
+     * 仅缓存 claim 成功的 URI，在 lease 到期前不再调 server。
+     */
+    claimedCache = new Map();
+    /** syncClaimStatusFromServer 互斥锁，防止后台定时器与 poll 路径并发执行 (v1.21.0) */
+    syncClaimMutex = Promise.resolve();
+    /** profile 是否已同步（防止 activelySyncProfile 与 profileHandler 双重同步） */
+    profileSynced = false;
     /**
      * Memory 通知 null 结果缓存：key → expiresAt 时间戳。
      * 仅缓存 null（无通知）结果，避免 while(true) 每 30s 重复读盘。
@@ -76,12 +103,6 @@ export class McpServer {
      * 当已有 poll 在进行时，后续调用直接等待同一个 Promise。
      */
     pendingPollMessage = null;
-    /**
-     * Todo 未完成项提醒去重指纹：记录上次通知时的未完成项内容/状态/优先级快照。
-     * 指纹一致则不重复通知；todos 变化时再次通知。
-     * 进程重启后自动清空（届时会重新通知一次，可接受）。
-     */
-    lastTodoNotificationFingerprint = null;
     // 系统提示词由 runtime adapter（ACode/OpenCode/Codex/Claude）在会话创建时注入，
     // 无需通过 MCP 工具返回。三方 runtime（OpenCode/Claude）将三层提示词合并为一条 system prompt，
     // ACode 则直接注入为前三条 system role 消息。
@@ -90,7 +111,9 @@ export class McpServer {
      * 当服务端返回的 roleName 与进程初始化时不一致时，重建 roleMemoryStore 指向正确的目录。
      */
     syncRoleMemoryStore(profile) {
+        logger.info(`[McpServer] syncRoleMemoryStore 被调用: displayName=${profile.displayName}, roleName="${profile.roleName ?? '(空)'}", id=${profile.id}`);
         if (!profile.roleName) {
+            logger.warn(`[McpServer] syncRoleMemoryStore: profile.roleName 为空，hasRoleName 保持 false。profile=${JSON.stringify({ id: profile.id, displayName: profile.displayName, roleName: profile.roleName, instanceName: profile.instanceName })}`);
             return;
         }
         const expectedRoleDir = McpServer.sanitizeRoleDirectoryName(profile.roleName);
@@ -112,7 +135,7 @@ export class McpServer {
      */
     maybeSyncPermanentMemoryToServer() {
         this.doMaybeSyncPermanentMemoryToServer().catch((e) => {
-            logger.warn("[McpServer] maybeSyncPermanentMemoryToServer 异常:", e);
+            logger.warn('[McpServer] maybeSyncPermanentMemoryToServer 异常: %s, stack=%s', e instanceof Error ? e.message : String(e), e instanceof Error ? e.stack : '(no stack)');
         });
     }
     async doMaybeSyncPermanentMemoryToServer() {
@@ -285,7 +308,7 @@ export class McpServer {
             keywords: record.keywords,
             bound_files: record.bound_files,
             file_md5_map: record.file_md5_map,
-            update_status: record.update_status,
+            memory_status: record.memory_status,
             updating_agent_id: record.updating_agent_id,
             last_check_time: record.last_check_time,
         };
@@ -300,6 +323,7 @@ export class McpServer {
         this.roleMemoryStore = new MemoryStore(memoryStorePaths.rolePath);
         this.sessionContextMemoryStore = new MemoryStore(path.join(path.dirname(memoryStorePaths.rolePath), "..", "session_context"));
         this.memoryStoresShareFile = false;
+        this.isSubAgent = process.env.AWS_SUB_AGENT === "true";
         this.contextManager = new ContextManager(this.sessionContextMemoryStore);
         this.server = new Server({
             name: MCP_SERVER_NAME,
@@ -313,7 +337,10 @@ export class McpServer {
     }
     setupHandlers() {
         this.server.setRequestHandler(ListToolsRequestSchema, async () => {
-            return { tools: MCP_TOOLS };
+            const tools = this.isSubAgent
+                ? MCP_TOOLS.filter((t) => MEMORY_TOOL_NAMES.has(t.name))
+                : MCP_TOOLS;
+            return { tools };
         });
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const { name, arguments: args } = request.params;
@@ -336,6 +363,8 @@ export class McpServer {
                         ...error.details,
                     }
                     : { error: errorMessage };
+                // 服务端记录完整异常，方便排查 LOST 等异常状态
+                logger.error('[McpServer] 工具调用异常: tool=%s, error=%s, stack=%s', name, errorMessage, error instanceof Error ? error.stack : '(no stack)');
                 return {
                     content: [
                         {
@@ -352,24 +381,44 @@ export class McpServer {
      * 处理工具调用
      */
     async handleToolCall(name, args) {
+        // 子 agent 共享父 agent MCP 连接时注入的标记：
+        // 剥离后跳过状态上报，避免子 agent 事件出现在父 agent 时间线上
+        const isSubAgentCall = args?._aws_sub_agent === true;
+        // 委托等待循环中后续 poll_message 注入的标记：
+        // 跳过 reportToolUse/reportToolResult，只保留 reportThinking，
+        // 避免"调用MCP↔思考中"状态反复跳动
+        const isSilentPoll = args?._aws_silent_poll === true;
+        const cleanArgs = { ...args };
+        delete cleanArgs._aws_sub_agent;
+        delete cleanArgs._aws_silent_poll;
         // 报告工具调用状态
-        const statusReporter = this.agentClient.getStatusReporter();
-        if (statusReporter) {
-            statusReporter.reportToolUse(name, this.sanitizeToolUseArgs(name, args));
+        // - 子 agent 调用：完全跳过（不污染父 agent 时间线）
+        // - 静默 poll：跳过 reportToolUse（不报"调用MCP"），但仍保留 statusReporter 供 reportThinking
+        const statusReporter = isSubAgentCall
+            ? null
+            : this.agentClient.getStatusReporter();
+        if (statusReporter && !isSilentPoll) {
+            statusReporter.reportToolUse(name, this.sanitizeToolUseArgs(name, cleanArgs));
         }
         try {
-            const result = await this.executeToolCall(name, args);
+            const result = await this.executeToolCall(name, cleanArgs);
             // 工具调用完成后，先上报返回数据供时间线日志查看，再切换为思考状态
             // （Agent 正在处理工具结果、决定下一步动作，而非真正的空闲等待）
-            if (statusReporter) {
-                statusReporter.reportToolResult(result);
-                statusReporter.reportThinking();
+            if (statusReporter && !isSilentPoll) {
+                const reportableResult = this.stripAutoDelegateForReporting(result);
+                if (reportableResult !== null) {
+                    // 正常结果：上报 toolResult + thinking（工具调用完成，回到思考状态）
+                    statusReporter.reportToolResult(reportableResult);
+                    statusReporter.reportThinking();
+                }
+                // 委托消息（reportableResult === null）：跳过 reportToolResult 和 reportThinking
+                // ACode runtime 会重新 poll_message，工具调用未真正结束，保持"调用MCP"状态
             }
             return result;
         }
         catch (error) {
             // 工具调用失败，报告错误状态
-            if (statusReporter) {
+            if (statusReporter && !isSilentPoll) {
                 statusReporter.reportToolError(error);
             }
             throw error;
@@ -379,6 +428,9 @@ export class McpServer {
      * 执行具体的工具调用
      */
     async executeToolCall(name, args) {
+        if (this.isSubAgent && !MEMORY_TOOL_NAMES.has(name)) {
+            throw new Error(`Sub-agent is not allowed to call tool: ${name}`);
+        }
         switch (name) {
             case "get_colleague":
                 return await this.agentClient.discoverColleagues();
@@ -597,7 +649,17 @@ export class McpServer {
             return await this.memoryStore.readMemory(input);
         }
         if (input.memory_type) {
-            return await this.getMemoryStoreForType(input.memory_type).readMemory(input);
+            const localStore = this.getMemoryStoreForType(input.memory_type);
+            const localRecord = await localStore.readMemory(input);
+            if (localRecord) {
+                return localRecord;
+            }
+            // project_memory 跨实例可见性：本地未命中时回退服务端角色级 scope，
+            // 使兄弟实例创建的记忆也能被读取（文件变更通知后 agent 需 read_memory）。
+            if (input.memory_type === "project_memory") {
+                return await this.memoryStore.readMemory(input);
+            }
+            return null;
         }
         const longTermRecord = await this.roleMemoryStore.readMemory({
             ...input,
@@ -606,6 +668,14 @@ export class McpServer {
         if (longTermRecord) {
             return longTermRecord;
         }
+        // 本地角色级未命中，回退服务端角色级 project_memory（兄弟实例创建的记忆）
+        const serverLongTerm = await this.memoryStore.readMemory({
+            ...input,
+            memory_type: "project_memory",
+        });
+        if (serverLongTerm) {
+            return serverLongTerm;
+        }
         return await this.memoryStore.readMemory(input);
     }
     /**
@@ -617,10 +687,17 @@ export class McpServer {
             return { store: this.memoryStore, memory_type: input.memory_type };
         }
         if (input.memory_type) {
-            return {
-                store: this.getMemoryStoreForType(input.memory_type),
-                memory_type: input.memory_type,
-            };
+            const localStore = this.getMemoryStoreForType(input.memory_type);
+            // project_memory 跨实例：本地有则用本地，否则用服务端角色级 scope
+            // （兄弟实例创建的记忆仅在服务端可见，需路由到 server 才能 update/delete）
+            if (input.memory_type === "project_memory") {
+                const localRecord = await localStore.readMemory(input);
+                if (localRecord) {
+                    return { store: localStore, memory_type: "project_memory" };
+                }
+                return { store: this.memoryStore, memory_type: "project_memory" };
+            }
+            return { store: localStore, memory_type: input.memory_type };
         }
         const longTermRecord = await this.roleMemoryStore.readMemory({
             uri: input.uri,
@@ -629,6 +706,14 @@ export class McpServer {
         if (longTermRecord) {
             return { store: this.roleMemoryStore, memory_type: "project_memory" };
         }
+        // 回退服务端角色级 project_memory（兄弟实例创建的记忆）
+        const serverLongTerm = await this.memoryStore.readMemory({
+            uri: input.uri,
+            memory_type: "project_memory",
+        });
+        if (serverLongTerm) {
+            return { store: this.memoryStore, memory_type: "project_memory" };
+        }
         return { store: this.memoryStore };
     }
     /**
@@ -713,6 +798,43 @@ export class McpServer {
         }
         return sanitized;
     }
+    /**
+     * 过滤工具返回结果中的 _acodeAutoDelegate 消息，避免自动委托通知
+     * （memory 文件变更/过期/容量整理）作为工具返回数据泄露到时间线。
+     *
+     * 背景：ACode 运行时在 processMemoryAutoDelegates 中拦截这些消息并 spawn
+     * 子 agent 处理，主 agent 不会感知。但 MCP server 的 statusReporter 在
+     * 拦截之前就已上报原始结果，Java 后端 AgentEventService 会将含 actionResult
+     * 的状态事件持久化并通过 AGENT_EVENTS_DELTA 推送到 dashboard 时间线，
+     * 导致本应被隐藏的委托通知暴露给用户。
+     *
+     * 返回 null 表示结果全部为委托消息，应跳过 reportToolResult
+     * （由 ACode 运行时在拦截后上报最终结果）。
+     */
+    stripAutoDelegateForReporting(result) {
+        if (!result || typeof result !== "object") {
+            return result;
+        }
+        const pollResult = result;
+        const directMessages = Array.isArray(pollResult.directMessages)
+            ? pollResult.directMessages
+            : [];
+        const groupMessages = Array.isArray(pollResult.groupMessages)
+            ? pollResult.groupMessages
+            : [];
+        const isDelegate = (m) => !!m &&
+            typeof m === "object" &&
+            "_acodeAutoDelegate" in m;
+        const hasDelegate = directMessages.some(isDelegate);
+        if (!hasDelegate) {
+            return result;
+        }
+        const remainingDm = directMessages.filter((m) => !isDelegate(m));
+        if (remainingDm.length === 0 && groupMessages.length === 0) {
+            return null;
+        }
+        return { ...pollResult, directMessages: remainingDm };
+    }
     /**
      * 创建本地记忆。
      * 主流程：校验必填字段 -> 交给 MemoryStore 规范化 URI 和类型 -> 返回不含 content 的写入结果。
@@ -771,7 +893,9 @@ export class McpServer {
     }
     /**
      * 更新本地记忆。
-     * 主流程：要求至少一种变更方式 -> MemoryStore 执行精确替换/追加和版本递增 -> 返回不含 content 的写入结果。
+     * 主流程：精确替换/追加/仅状态更新 -> MemoryStore 执行变更和版本递增 -> 返回不含 content 的写入结果。
+     * 支持三种写法：1) 精确替换（old_string + new_string）；2) 追加（append）；3) 无内容更新（仅传 uri，
+     * 用于过期续期、刷新绑定文件 MD5、释放 updating 状态等场景）。
      */
     async handleUpdateMemory(args) {
         const hasReplace = typeof args.old_string === "string" ||
@@ -782,10 +906,9 @@ export class McpServer {
         if (hasReplace && !hasCompleteReplace) {
             throw new Error("old_string and new_string must be provided together");
         }
-        if (!hasCompleteReplace &&
-            (typeof append !== "string" || append.length === 0)) {
-            throw new Error("Provide either old_string/new_string or append");
-        }
+        // 允许无内容更新：当未提供 old_string/new_string 且未提供有效 append 时，
+        // 视为"仅状态更新"——用于过期续期、刷新绑定文件 MD5、释放 updating 状态等场景。
+        // 此时内容不变，但会重算绑定文件 MD5 并续期（expirable 类型）。
         const input = {
             uri: this.getRequiredString(args, "uri"),
             memory_type: this.getOptionalMemoryType(args),
@@ -827,7 +950,8 @@ export class McpServer {
         });
         await this.reportCombinedMemoryStats();
         // Dual-write permanent memory update to server（同步 MD5 map 避免服务端重复检测）
-        if (target.memory_type === "project_memory") {
+        // 当 target.store 已是服务端（兄弟实例创建的记忆回退场景）时跳过，避免重复写
+        if (target.memory_type === "project_memory" && target.store !== this.memoryStore) {
             try {
                 await this.memoryStore.updateMemory({
                     ...input,
@@ -841,9 +965,20 @@ export class McpServer {
             }
         }
         // v1.13.0: agent_memory 过期与回忆状态由服务端 memory_status 字段管理。
-        // 显式传入的 recall_status / memory_status 已在 updateMemory 内部透传到服务端。
-        // agent_memory 内容变更会触发 TTL ×2 续期（由 MemoryStore.updateMemory 内部处理），
-        // recently_memory 续期建议重新 createMemory 替代。
+        // v1.21.0: 如果是 project_memory 且之前是 updating 状态，释放 Server claim
+        if (target.memory_type === 'project_memory' && existingForMd5?.memory_status === 'updating') {
+            try {
+                await this.memoryStore.releaseMemoryClaim(input.uri);
+                this.claimedCache.delete(input.uri);
+                // 所有 claim 已释放，停止续期定时器避免无意义请求
+                if (this.claimedCache.size === 0) {
+                    this.stopLeaseRenewal();
+                }
+            }
+            catch (e) {
+                logger.warn('[McpServer] 释放 memory claim 失败: uri=%s, error=%s', input.uri, e instanceof Error ? e.message : String(e));
+            }
+        }
         return this.toMemoryWriteResult(updated);
     }
     /**
@@ -866,7 +1001,8 @@ export class McpServer {
             // v1.13.0: 服务端 deleteMemory 内部已处理相关清理逻辑，
             // TS 侧无需任何本地元数据清理。
             // Dual-write permanent memory delete to server
-            if (effectiveType === "project_memory") {
+            // 当 target.store 已是服务端时跳过，避免重复删除
+            if (effectiveType === "project_memory" && target.store !== this.memoryStore) {
                 try {
                     await this.memoryStore.deleteMemory({ uri: input.uri, memory_type: "project_memory" });
                 }
@@ -1214,24 +1350,38 @@ export class McpServer {
         return merged;
     }
     /**
-     * 放弃 Memory 更新状态
+     * 放弃 Memory 更新状态 (v1.21.0 改为走 release API)
      * Memory 增强功能 (v1.6.0)
      */
     async handleAbandonMemoryUpdate(args) {
         const uri = this.getRequiredString(args, "uri");
         const memoryType = this.getOptionalMemoryType(args);
+        // 调 Server release API 释放 claim
+        await this.memoryStore.releaseMemoryClaim(uri);
+        // 同时清除本地 roleMemoryStore 的 updating 状态（如果是 project_memory）
+        // 兄弟实例创建的记忆本地不存在时静默跳过，服务端 release 才是权威操作
         const record = await this.memoryStore.readMemory({ uri, memory_type: memoryType });
-        if (!record) {
-            throw new Error(`Memory not found: ${uri}`);
+        if (record?.memory_type === 'project_memory') {
+            try {
+                await this.roleMemoryStore.updateMemory({
+                    uri,
+                    memory_type: 'project_memory',
+                });
+                // 不传 memory_status → MemoryStore 默认重置为 normal
+            }
+            catch (e) {
+                logger.info(`[McpServer] abandon_memory_update: 本地无此记忆，跳过本地状态清理: ${uri}`);
+            }
+        }
+        // 从去重缓存移除
+        this.claimedCache.delete(uri);
+        // 所有 claim 已释放，停止续期定时器避免无意义请求
+        if (this.claimedCache.size === 0) {
+            this.stopLeaseRenewal();
         }
-        // 清除 updating 状态
-        await this.memoryStore.updateMemory({
-            uri: record.uri,
-            memory_type: record.memory_type,
-        });
         return {
             success: true,
-            uri: record.uri,
+            uri,
             message: "Memory 更新状态已清除",
         };
     }
@@ -1273,7 +1423,7 @@ export class McpServer {
             await this.memoryStore.markExpiredMemoriesRecalling(batchUris);
         }
         catch (e) {
-            logger.warn("[McpServer] 标记过期记忆为 recalling 失败:", e);
+            logger.warn('[McpServer] 标记过期记忆为 recalling 失败: uriCount=%s, error=%s', batchUris.length, e instanceof Error ? e.message : String(e));
         }
         const remaining = Math.max(0, expiredMemories.length - batch.length);
         // 返回过期记忆的摘要（不含完整 content 以减少上下文占用）
@@ -1282,7 +1432,6 @@ export class McpServer {
             title: m.title,
             domain: m.domain,
             path: m.path,
-            recall_status: 'recalling',
             memory_status: 'recalling',
             contentPreview: typeof m.content === 'string' && m.content.length > 200 ? m.content.substring(0, 200) + '...' : m.content,
             createdAt: m.createdAt,
@@ -1314,7 +1463,7 @@ export class McpServer {
             result = await this.memoryStore.clearRecallingExpiredMemories();
         }
         catch (e) {
-            logger.warn("[McpServer] 清理回忆中记忆失败:", e);
+            logger.warn('[McpServer] 清理回忆中记忆失败: %s', e instanceof Error ? e.message : String(e));
         }
         await this.reportCombinedMemoryStats();
         const deletedCount = result.deleted ?? 0;
@@ -1435,21 +1584,12 @@ export class McpServer {
         return result;
     }
     async handlePollMessage() {
+        logger.info('[McpServer] handlePollMessage 被调用');
         if (this.pendingPollMessage) {
             logger.info('[McpServer] poll_message 已有进行中的调用，等待其完成');
             return await this.pendingPollMessage;
         }
         this.pendingPollMessage = (async () => {
-            // 入口处检查 Todo 未完成项提醒：仅在每次 poll_message 调用时检查一次，
-            // 不引入后台定时器。状态变化（指纹不同）且有未完成项时立即返回通知；
-            // 否则进入原有阻塞等待真实消息的流程。
-            const todoNotification = await this.buildTodoReminderNotification();
-            if (todoNotification) {
-                return this.buildPollResult({
-                    directMessages: [todoNotification],
-                    groupMessages: [],
-                });
-            }
             return await this.doPollMessage();
         })();
         try {
@@ -1459,35 +1599,100 @@ export class McpServer {
             this.pendingPollMessage = null;
         }
     }
+    /**
+     * poll_message 主循环逻辑。
+     *
+     * 紧急/非紧急分类策略：
+     * - 紧急类：未读消息（私信/群聊）、task、todo
+     * - 非紧急类：memory过期回忆、memory文件变更、memory容量整理
+     * - 规则：有紧急类时返回所有命中的紧急项（不搭配非紧急类）；
+     *   无紧急类时返回所有命中的非紧急项。
+     *
+     * 返回组合（只可能是以下两种之一）：
+     * 1、所有命中的紧急项（未读消息 + todo + task 中命中的全部）
+     * 2、所有命中的非紧急项（memory过期 + 文件变更 + 容量整理 中命中的全部）
+     *
+     * 注：subAgent 终态事件由 ACode 运行时层（runtime.ts callPollMessageWithSubAgentRace）
+     * 在 MCP 调用前后注入，MCP server 内部不直接检测子 agent 状态。
+     * 注：Todo 在入口和 while 循环中均检查，确保阻塞期间创建的 Todo 也能被感知。
+     */
     async doPollMessage() {
+        logger.info('[McpServer] doPollMessage 被调用');
+        // 紧急类检查：hydrate 未读消息 + task
         await this.hydrateUnreadMessagesFromServer({
             blockIfEmpty: false,
-            includePipelineTasks: false,
+            includePipelineTasks: true,
         });
-        while (true) {
-            const buffered = this.messageBuffer.get();
-            if (buffered.directMessages.length > 0 || buffered.groupMessages.length > 0) {
-                return await this.finalizeWithMemoryNotifications(buffered);
+        // 紧急类检查：Todo（只检查一次）
+        const todoNotif = await this.buildTodoReminderNotification();
+        // 紧急类：有未读消息/task 时，加上 todo（如果有），返回所有紧急项
+        const urgentBuffered = this.messageBuffer.get();
+        if (urgentBuffered.directMessages.length > 0 || urgentBuffered.groupMessages.length > 0) {
+            if (todoNotif) {
+                urgentBuffered.directMessages.unshift(todoNotif);
             }
+            return this.buildPollResult(urgentBuffered);
+        }
+        // 紧急类：无未读消息/task 但有 todo，直接返回 todo
+        if (todoNotif) {
+            return this.buildPollResult({ directMessages: [todoNotif], groupMessages: [] });
+        }
+        // 非紧急类：无紧急类时，检查所有非紧急项（memory过期 + 文件变更 + 容量整理）
+        const nonUrgentMessages = await this.checkAllLocalNonUrgentNotifications();
+        if (nonUrgentMessages.length > 0) {
+            return this.buildPollResult({ directMessages: nonUrgentMessages, groupMessages: [] });
+        }
+        // 无紧急类且无非紧急类：进入 while 循环等待新消息
+        while (true) {
             const polled = await this.messageBuffer.poll(POLL_MESSAGE_INTERNAL_POLL_INTERVAL_MS);
+            // 紧急类：poll 到消息（私信/群聊），立即返回
             if (polled.directMessages.length > 0 || polled.groupMessages.length > 0) {
-                return await this.finalizeWithMemoryNotifications(polled);
+                return this.buildPollResult(polled);
+            }
+            // poll 超时无消息时，重新检查紧急类（task + todo 可能在此期间到达/创建）
+            // 与入口处逻辑一致：先查 todo，再合并消息/task，紧急项一起返回
+            await this.hydrateUnreadMessagesFromServer({
+                blockIfEmpty: false,
+                includePipelineTasks: true,
+            });
+            const todoNotifLoop = await this.buildTodoReminderNotification();
+            const taskBuffered = this.messageBuffer.get();
+            if (taskBuffered.directMessages.length > 0 || taskBuffered.groupMessages.length > 0) {
+                if (todoNotifLoop) {
+                    taskBuffered.directMessages.unshift(todoNotifLoop);
+                }
+                return this.buildPollResult(taskBuffered);
+            }
+            // 紧急类：无消息/task 但有 todo，返回 todo
+            if (todoNotifLoop) {
+                return this.buildPollResult({ directMessages: [todoNotifLoop], groupMessages: [] });
+            }
+            // 非紧急类：无紧急类时，检查所有非紧急项
+            const nonUrgent = await this.checkAllLocalNonUrgentNotifications();
+            if (nonUrgent.length > 0) {
+                return this.buildPollResult({ directMessages: nonUrgent, groupMessages: [] });
             }
         }
     }
     /**
-     * 后检 Memory 通知并注入到待返回的消息中。按优先级从高到低注入：
-     * 文件变更（始终注入）→ 近期记忆过期回忆（触发即返回）→ TODO（触发即返回）→ 容量整理（始终注入）
-     */
-    async finalizeWithMemoryNotifications(messages) {
-        if (!this.memoryFileCheckInterval) {
-            await this.prependMemoryNotification(messages, () => this.buildMemoryFileChangeNotification());
-        }
-        if (await this.prependMemoryNotification(messages, () => this.getCachedMemoryNotification('recurrence', () => this.buildMemoryRecurrenceNotification()))) {
-            return this.buildPollResult(messages);
-        }
-        await this.prependMemoryNotification(messages, () => this.getCachedMemoryNotification('cleanup', () => this.buildMemoryCleanupNotification()));
-        return this.buildPollResult(messages);
+     * 检查本地非紧急通知（memory过期回忆、文件变更、容量整理），返回所有命中的通知。
+     * Task 不在此方法中检查，因为 Task 通过服务端 hydrate 以消息形式返回。
+     */
+    async checkAllLocalNonUrgentNotifications() {
+        const messages = [];
+        // Memory 过期回忆
+        const recurrenceNotif = await this.getCachedMemoryNotification('recurrence', () => this.buildMemoryRecurrenceNotification());
+        if (recurrenceNotif)
+            messages.push(recurrenceNotif);
+        // Memory 文件变更（需要更新）
+        const fileChangeNotif = await this.buildMemoryFileChangeNotification();
+        if (fileChangeNotif)
+            messages.push(fileChangeNotif);
+        // Memory 容量整理
+        const cleanupNotif = await this.getCachedMemoryNotification('cleanup', () => this.buildMemoryCleanupNotification());
+        if (cleanupNotif)
+            messages.push(cleanupNotif);
+        return messages;
     }
     buildPollResult(messages, fromBuffer = true) {
         return {
@@ -1556,10 +1761,14 @@ export class McpServer {
                 requireReply: false,
                 prompt: "这是一条本地 memory 容量整理提醒，自动生成，无需持久化。请优先整理已超过建议上限的短期/近期 memory 类型，或具体类型下的 memory 条目。",
                 timestamp: new Date().toISOString(),
+                _acodeAutoDelegate: {
+                    type: 'memory_cleanup',
+                    uris: exceededDomains.map(d => `${d.memoryType}/${d.domain}`),
+                },
             };
         }
         catch (error) {
-            logger.warn("[McpServer] 构建本地 memory 整理提醒失败:", error);
+            logger.warn('[McpServer] 构建本地 memory 整理提醒失败: %s', error instanceof Error ? error.message : String(error));
             return null;
         }
     }
@@ -1583,7 +1792,7 @@ export class McpServer {
             const agentId = this.getCurrentAgentId();
             if (!agentId)
                 return null;
-            const recallingExpired = expiredMemories.filter(m => m.recall_status === 'recalling' || m.memory_status === 'recalling');
+            const recallingExpired = expiredMemories.filter(m => m.memory_status === 'recalling');
             const normalExpired = expiredMemories.filter(m => !recallingExpired.includes(m));
             // 场景1: 有 recalling 状态的过期记忆（Agent 未完成疏理）
             if (recallingExpired.length > 0) {
@@ -1597,6 +1806,10 @@ export class McpServer {
                     requireReply: false,
                     prompt: "memory_recurrence 取回的记忆仍在回忆中，请通过 memory_recurrence_complete 完成疏理，或继续归档/续期。",
                     timestamp: new Date().toISOString(),
+                    _acodeAutoDelegate: {
+                        type: 'memory_expiration',
+                        uris: recallingExpired.map(m => m.uri),
+                    },
                 };
             }
             // 场景2: 有待回忆的过期记忆
@@ -1611,12 +1824,16 @@ export class McpServer {
                     requireReply: false,
                     prompt: `这是一条近期记忆过期提醒，共有 ${normalExpired.length} 条记忆即将遗忘，请调用 memory_recurrence 分批次获取并决定处理方式。`,
                     timestamp: new Date().toISOString(),
+                    _acodeAutoDelegate: {
+                        type: 'memory_expiration',
+                        uris: normalExpired.map(m => m.uri),
+                    },
                 };
             }
             return null;
         }
         catch (error) {
-            logger.warn("[McpServer] 构建近期记忆过期回忆通知失败:", error);
+            logger.warn('[McpServer] 构建近期记忆过期回忆通知失败: %s', error instanceof Error ? error.message : String(error));
             return null;
         }
     }
@@ -1625,24 +1842,38 @@ export class McpServer {
      * Memory 增强功能 (v1.6.0)
      *
      * 检测流程：
+     * 0. 同步 Server 的 claim 状态到本地，清理过期 claim
      * 1. 检查本 Agent 标记为 updating 但未处理的 Memory
      * 2. 检查短期记忆、近期记忆绑定的文件是否变更
-     * 3. 如果没有变更，检查永久记忆的文件变更，标记最多 5 个为 updating
+     * 3. 检查永久记忆的文件变更，先走 Server 原子 claim，再标记本地
      */
     async buildMemoryFileChangeNotification() {
+        logger.info(`[McpServer] buildMemoryFileChangeNotification 被调用: hasRoleName=${this.hasRoleName}, agentId=${this.getCurrentAgentId() ?? '(空)'}`);
         // 无角色名时不检测本地永久记忆文件变更（避免 default-role 跨角色污染）
-        if (!this.hasRoleName)
+        if (!this.hasRoleName) {
+            logger.info('[McpServer] 文件变更检测跳过: hasRoleName=false');
             return null;
+        }
         try {
             const agentId = this.getCurrentAgentId();
             if (!agentId) {
+                logger.info('[McpServer] 文件变更检测跳过: agentId 为空');
                 return null;
             }
-            // 步骤1: 检查是否有 pending 的 updating memories（角色本地永久记忆），
+            // Step 0: 同步 Server 的 claim 状态到本地 roleMemoryStore（可选，失败降级）。
+            // 清理那些 Server 上已释放（租约过期或被清理）但本地仍标记为 updating 的记录。
+            // Server API 不可用时降级，依赖本地状态，不影响检测流程。
+            await this.syncClaimStatusFromServer(agentId).catch(e => logger.info("[McpServer] Step 0 同步 claim 状态失败（降级）:", e));
+            // 步骤1: 检查是否有 pending 的 updating memories（服务端角色级永久记忆），
             // 同时检测绑定文件是否再次变更（用户可能在 Agent 处理前又改了文件）
-            const permanentList = await this.roleMemoryStore.listByType('project_memory');
-            const updatingMemories = permanentList.filter(m => m.update_status === 'updating' && m.updating_agent_id === agentId);
+            // 数据源切换：从服务端角色级 scope 读取（同角色所有实例共享），
+            // 不再用本地 roleMemoryStore（仅本实例可见，兄弟实例无法检测到彼此创建的 memory）。
+            const permanentList = await this.memoryStore.listByType('project_memory');
+            const updatingMemories = permanentList.filter(m => m.memory_status === 'updating' && m.updating_agent_id === agentId);
             if (updatingMemories.length > 0) {
+                // 当前 agent 持有未完成的 updating memory，确保租约续期定时器在运行，
+                // 避免 agent 在更新过程中租约过期被其他实例接管。
+                this.startLeaseRenewal();
                 // 对 updating 记忆也检测文件是否再次变更
                 const updatingChanges = await this.checkMemoriesFileChanges(updatingMemories);
                 if (updatingChanges.length > 0) {
@@ -1650,10 +1881,11 @@ export class McpServer {
                     for (const change of updatingChanges) {
                         const memory = updatingMemories.find(m => m.id === change.memoryId);
                         if (memory) {
-                            await this.roleMemoryStore.updateMemory({
+                            // MD5 回写到服务端角色级 scope（显式传 memory_status:updating 防止 auto-release）
+                            await this.memoryStore.updateMemory({
                                 uri: memory.uri,
                                 memory_type: 'project_memory',
-                                update_status: 'updating',
+                                memory_status: 'updating',
                                 updating_agent_id: agentId,
                                 file_md5_map: memory.file_md5_map,
                                 last_check_time: memory.last_check_time,
@@ -1674,12 +1906,37 @@ export class McpServer {
                         requireReply: false,
                         prompt: "这是一条文件变更提醒，您之前标记为更新中的记忆绑定的文件又有新变更，请处理。",
                         timestamp: new Date().toISOString(),
+                        _acodeAutoDelegate: {
+                            type: 'memory_file_change',
+                            uris: updatingChanges.slice(0, 5).map(c => c.memoryUri),
+                        },
                     };
                 }
-                const memoryList = updatingMemories
+                // Step1「仍 updating」提醒去重：sticky 的 updating memory 若不在冷却窗口内才发提醒，
+                // 否则本轮直接返回 null，避免每轮 poll 都裸发 _acodeAutoDelegate 触发运行层反复 spawn 子任务。
+                const now = Date.now();
+                const pendingToNotify = updatingMemories.filter(m => {
+                    const last = this.lastUpdatePendingNotifyAt.get(m.uri) ?? 0;
+                    return now - last >= McpServer.UPDATE_PENDING_NOTIFY_COOLDOWN_MS;
+                });
+                // 清理已不在 updating 列表中的过期冷却记录
+                for (const uri of this.lastUpdatePendingNotifyAt.keys()) {
+                    if (!updatingMemories.some(m => m.uri === uri)) {
+                        this.lastUpdatePendingNotifyAt.delete(uri);
+                    }
+                }
+                if (pendingToNotify.length === 0) {
+                    logger.info(`[McpServer] 文件变更检测 Step1: ${updatingMemories.length} 个 updating memory 均处于冷却窗口内，跳过提醒`);
+                    return null;
+                }
+                for (const m of pendingToNotify) {
+                    this.lastUpdatePendingNotifyAt.set(m.uri, now);
+                }
+                const memoryList = pendingToNotify
                     .slice(0, 5)
                     .map(m => `- ${m.uri} (文件: ${m.bound_files?.join(', ') || '未知'})`)
                     .join('\n');
+                logger.info(`[McpServer] 文件变更检测 Step1: ${pendingToNotify.length}/${updatingMemories.length} 个 updating memory 待更新（其余冷却中），租约已续期`);
                 return {
                     msgId: `memory-update-pending-${Date.now()}`,
                     senderId: "MCP-System",
@@ -1689,14 +1946,22 @@ export class McpServer {
                     requireReply: false,
                     prompt: "这是一条更新提醒，您之前已标记这些记忆为更新中，请继续处理。",
                     timestamp: new Date().toISOString(),
+                    _acodeAutoDelegate: {
+                        type: 'memory_file_change',
+                        uris: pendingToNotify.slice(0, 5).map(m => m.uri),
+                    },
                 };
             }
             // 步骤2: 检查短期记忆和近期记忆（服务端存储）
             const recentlyMemoryMemories = await this.memoryStore.listByType('recently_memory');
             const agentMemoryMemories = await this.memoryStore.listByType('agent_memory');
             const listableMemories = [...recentlyMemoryMemories, ...agentMemoryMemories];
+            // 诊断日志：列出 listable memory 的绑定文件和 MD5 基线情况
+            const listableWithFiles = listableMemories.filter(m => m.bound_files && m.bound_files.length > 0);
+            logger.info(`[McpServer] 文件变更检测 Step2: recently=${recentlyMemoryMemories.length}, agent=${agentMemoryMemories.length}, ` +
+                `有绑定文件=${listableWithFiles.length}/${listableMemories.length}。` +
+                `详情: ${listableMemories.map(m => `${m.uri}(bound=${m.bound_files?.length ?? 0},md5=${Object.keys(m.file_md5_map ?? {}).length})`).join('; ') || '无 memory'}`);
             // 用本地 MD5 缓存补全 listable 记忆（服务端可能不持久化 file_md5_map 字段）
-            // 确保 checkMemoriesFileChanges 有正确的旧 MD5 做比对而非始终以空字典开始
             for (const m of listableMemories) {
                 if (!m.file_md5_map) {
                     const cached = this.listableMd5Cache.get(m.id);
@@ -1706,17 +1971,20 @@ export class McpServer {
                 }
             }
             const listableChanges = await this.checkMemoriesFileChanges(listableMemories);
-            // 使用复合 key（memoryId + 当前各绑定文件 MD5）过滤已通知变更，
-            // 同一条记忆文件再次变更（MD5 变化）时仍能触发新通知
             const newListableChanges = listableChanges.filter(c => {
                 const memory = listableMemories.find(m => m.id === c.memoryId);
                 const md5Map = memory?.file_md5_map;
                 const changeKey = this.buildMemoryChangeNotificationKey(c.memoryId, md5Map);
-                return this.notifiedFileChangeMemoryIds.get(c.memoryId) !== changeKey;
+                const lastNotified = this.notifiedFileChangeMemoryIds.get(c.memoryId);
+                const isNew = lastNotified !== changeKey;
+                if (!isNew) {
+                    logger.info(`[McpServer] 文件变更检测 Step2: ${c.memoryUri} 变更被去重吞掉 (changeKey=${changeKey}, lastNotified=${lastNotified})`);
+                }
+                return isNew;
             });
+            logger.info(`[McpServer] 文件变更检测 Step2: 检测到变更=${listableChanges.length}, 去重后=${newListableChanges.length}` +
+                (listableChanges.length > 0 ? ` 变更项: ${listableChanges.map(c => `${c.memoryUri}(${c.changedFiles.join(',')})`).join('; ')}` : ''));
             if (newListableChanges.length > 0) {
-                // 记录当前状态的复合键，下次对比时若 MD5 变化则重新通知
-                // 同时将 MD5 map 写入本地缓存，弥补服务端不持久化 file_md5_map 的问题
                 for (const c of newListableChanges) {
                     const memory = listableMemories.find(m => m.id === c.memoryId);
                     const md5Map = memory?.file_md5_map;
@@ -1737,52 +2005,164 @@ export class McpServer {
                     requireReply: false,
                     prompt: "这是一条文件变更提醒，自动生成，无需持久化。",
                     timestamp: new Date().toISOString(),
+                    _acodeAutoDelegate: {
+                        type: 'memory_file_change',
+                        uris: newListableChanges.map(c => c.memoryUri),
+                    },
                 };
             }
-            // 步骤3: 检查永久记忆（角色本地存储）
-            const normalPermanentMemories = permanentList.filter(m => m.bound_files && m.bound_files.length > 0 &&
-                (m.update_status === 'normal' || !m.update_status));
-            const permanentChanges = await this.checkMemoriesFileChanges(normalPermanentMemories);
+            // 步骤3: 检查永久记忆（角色本地存储）— 优先走 Server 原子 claim，失败时降级到本地直接标记
+            const permanentMemoriesWithFiles = permanentList.filter(m => m.bound_files && m.bound_files.length > 0
+                && (m.memory_status === 'normal' || !m.memory_status)
+                && !this.isClaimCached(m.uri));
+            const permanentTotalWithFiles = permanentList.filter(m => m.bound_files && m.bound_files.length > 0);
+            logger.info(`[McpServer] 文件变更检测 Step3: project_memory 总数=${permanentList.length}, ` +
+                `有绑定文件=${permanentTotalWithFiles.length}, 待检测(过滤updating/claimed后)=${permanentMemoriesWithFiles.length}。` +
+                `被过滤原因: ${permanentTotalWithFiles.length - permanentMemoriesWithFiles.length} 项(memory_status=updating 或 isClaimCached)`);
+            const permanentChanges = await this.checkMemoriesFileChanges(permanentMemoriesWithFiles);
+            // 回写无基线 memory 的新 MD5 到服务端（修复前创建的旧数据补基线）
+            const baselineUpdatedMemories = permanentMemoriesWithFiles.filter(m => m.file_md5_map && Object.keys(m.file_md5_map).length > 0
+                && !permanentChanges.some(c => c.memoryId === m.id));
+            if (baselineUpdatedMemories.length > 0) {
+                logger.info(`[McpServer] 文件变更检测 Step3: 回写 ${baselineUpdatedMemories.length} 个无基线 memory 的 MD5 基线到服务端`);
+                for (const m of baselineUpdatedMemories) {
+                    try {
+                        await this.memoryStore.updateMemory({
+                            uri: m.uri,
+                            memory_type: 'project_memory',
+                            file_md5_map: m.file_md5_map,
+                            last_check_time: m.last_check_time,
+                        });
+                    }
+                    catch (e) {
+                        logger.info(`[McpServer] 回写基线 MD5 失败: ${m.uri}`, e);
+                    }
+                }
+            }
+            logger.info(`[McpServer] 文件变更检测 Step3: 检测到变更=${permanentChanges.length}` +
+                (permanentChanges.length > 0 ? ` 变更项: ${permanentChanges.map(c => `${c.memoryUri}(${c.changedFiles.join(',')})`).join('; ')}` : ''));
             if (permanentChanges.length > 0) {
                 // 最多选取 5 个
                 const selectedChanges = permanentChanges.slice(0, 5);
-                // 标记为 updating 状态，同时持久化当前 MD5 map，
-                // 确保后续检测能正确对比文件变更，而非每次都视为"已变更"
-                for (const change of selectedChanges) {
-                    const memory = permanentList.find(m => m.id === change.memoryId);
-                    if (memory) {
-                        await this.roleMemoryStore.updateMemory({
-                            uri: memory.uri,
-                            memory_type: 'project_memory',
-                            update_status: 'updating',
-                            updating_agent_id: agentId,
-                            // checkMemoriesFileChanges 已更新 in-memory 对象中的 MD5 map
-                            file_md5_map: memory.file_md5_map,
-                            last_check_time: memory.last_check_time,
-                        });
+                const urisToClaim = selectedChanges.map(c => c.memoryUri);
+                let claimedViaServer = false;
+                let claimedUris = new Set();
+                try {
+                    // Path A: 尝试走 Server 原子 claim
+                    const claimResult = await this.memoryStore.claimMemoryUpdate(urisToClaim, McpServer.LEASE_DURATION_MINUTES, 'project_memory');
+                    claimedUris = new Set(claimResult.claimed_uris ?? []);
+                    claimedViaServer = true;
+                }
+                catch (e) {
+                    // Path B: Server API 不可用 → 降级到本地直接标记
+                    logger.info("[McpServer] Server claim API 不可用，降级到本地直接标记:", e);
+                    claimedUris = new Set(urisToClaim);
+                }
+                if (claimedUris.size > 0) {
+                    const claimedChanges = selectedChanges.filter(c => claimedUris.has(c.memoryUri));
+                    // 标记本地 roleMemoryStore
+                    for (const change of claimedChanges) {
+                        const memory = permanentList.find(m => m.id === change.memoryId);
+                        if (memory) {
+                            // claim 状态由 batchClaimUpdate 在服务端原子写入；此处仅回写新 MD5 基线到服务端角色级 scope，
+                            // 显式传 memory_status:updating/updating_agent_id 防止 Java updateMemory auto-release 误释放 claim。
+                            await this.memoryStore.updateMemory({
+                                uri: memory.uri,
+                                memory_type: 'project_memory',
+                                memory_status: 'updating',
+                                updating_agent_id: agentId,
+                                file_md5_map: memory.file_md5_map,
+                                last_check_time: memory.last_check_time,
+                            });
+                            // 加入去重缓存（lease 有效期内不再重复 claim）
+                            this.claimedCache.set(memory.uri, Date.now() + McpServer.LEASE_DURATION_MINUTES * 60 * 1000);
+                        }
+                    }
+                    // 启动租约续期（仅 Server claim 成功时需要，降级模式不续期）
+                    if (claimedViaServer && claimedUris.size > 0) {
+                        this.startLeaseRenewal();
                     }
+                    const changeDetails = claimedChanges
+                        .map(change => `- ${change.memoryUri} (文件: ${change.changedFiles.join(', ')})`)
+                        .join('\n');
+                    return {
+                        msgId: `memory-file-change-${Date.now()}`,
+                        senderId: "MCP-System",
+                        senderName: "系统",
+                        receiverId: agentId,
+                        content: `检测到以下 ${claimedChanges.length} 个永久记忆绑定的文件已变更，已为您标记为更新中：\n\n${changeDetails}\n\n请调用 read_memory 查看内容并调用 update_memory 更新。更新完成后状态将自动恢复为正常。`,
+                        requireReply: false,
+                        prompt: "这是一条文件变更提醒，已自动标记更新状态，请处理。",
+                        timestamp: new Date().toISOString(),
+                        _acodeAutoDelegate: {
+                            type: 'memory_file_change',
+                            uris: claimedChanges.map(c => c.memoryUri),
+                        },
+                    };
                 }
-                const changeDetails = selectedChanges
-                    .map(change => `- ${change.memoryUri} (文件: ${change.changedFiles.join(', ')})`)
-                    .join('\n');
-                return {
-                    msgId: `memory-file-change-${Date.now()}`,
-                    senderId: "MCP-System",
-                    senderName: "系统",
-                    receiverId: agentId,
-                    content: `检测到以下 ${selectedChanges.length} 个永久记忆绑定的文件已变更，已为您标记为更新中：\n\n${changeDetails}\n\n请调用 read_memory 查看内容并调用 update_memory 更新。更新完成后状态将自动恢复为正常。`,
-                    requireReply: false,
-                    prompt: "这是一条文件变更提醒，已自动标记更新状态，请处理。",
-                    timestamp: new Date().toISOString(),
-                };
             }
+            logger.info('[McpServer] 文件变更检测完成: 无变更通知产生');
             return null;
         }
         catch (error) {
-            logger.warn("[McpServer] 构建 Memory 文件变更检测通知失败:", error);
+            logger.warn('[McpServer] 构建 Memory 文件变更检测通知失败: %s', error instanceof Error ? error.message : String(error));
             return null;
         }
     }
+    /**
+     * Step 0: 同步 Server 的 claim 状态到本地 roleMemoryStore (v1.21.0)。
+     * 查询 Server 上当前 agent 持有的 updating 记忆 URI 列表，
+     * 本地中标记为 updating 但 Server 不持有的 → 重置为 normal。
+     * 处理场景：agent crash 后重启，Server 租约已过期被清理，但本地 JSON 仍卡在 updating。
+     */
+    async syncClaimStatusFromServer(agentId) {
+        // 互斥锁：防止后台定时器与 poll 路径并发执行导致 TOCTOU
+        const previous = this.syncClaimMutex;
+        let release;
+        this.syncClaimMutex = new Promise((resolve) => { release = resolve; });
+        await previous;
+        try {
+            // 从 Server 查询当前 agent 持有的 claimed URIs
+            const serverClaimedUris = await this.memoryStore.getMyClaimedUris();
+            const serverClaimedSet = new Set(serverClaimedUris);
+            // 读取本地 roleMemoryStore 中所有 project_memory
+            const localMemories = await this.roleMemoryStore.listByType('project_memory');
+            const staleLocalClaims = localMemories.filter(m => m.memory_status === 'updating'
+                && m.updating_agent_id === agentId
+                && !serverClaimedSet.has(m.uri));
+            if (staleLocalClaims.length > 0) {
+                logger.info(`[McpServer] Step 0: 清理 ${staleLocalClaims.length} 条本地过期 claim（Server 已释放）`);
+                for (const m of staleLocalClaims) {
+                    await this.roleMemoryStore.updateMemory({
+                        uri: m.uri,
+                        memory_type: 'project_memory',
+                    });
+                    // 不传 memory_status → MemoryStore 默认重置为 normal
+                }
+            }
+        }
+        catch (e) {
+            // Server 不可用时降级，依赖本地状态
+            logger.warn('[McpServer] Step 0: 同步 claim 状态失败（降级）: %s', e instanceof Error ? e.message : String(e));
+        }
+        finally {
+            release();
+        }
+    }
+    /**
+     * 检查指定 URI 是否在 claim 去重缓存内 (v1.21.0)。
+     * 在 lease 有效期内不再重复 claim。
+     */
+    isClaimCached(uri) {
+        const expiry = this.claimedCache.get(uri);
+        if (expiry === undefined)
+            return false;
+        if (expiry <= Date.now()) {
+            this.claimedCache.delete(uri);
+            return false;
+        }
+        return true;
+    }
     /**
      * 检查一组 Memory 的文件变更
      * Memory 增强功能 (v1.6.0)
@@ -1797,25 +2177,47 @@ export class McpServer {
                 const changedFiles = [];
                 const newMd5Map = {};
                 const oldMd5Map = memory.file_md5_map || {};
+                const workspacePath = process.env.AWS_WORKSPACE_PATH || process.cwd();
+                const hasNoBaseline = Object.keys(oldMd5Map).length === 0;
                 for (const filePath of memory.bound_files) {
                     try {
                         const currentMd5 = await this.calculateFileMd5(filePath);
                         if (currentMd5 === null) {
                             // 文件不存在或无法读取
-                            changedFiles.push(`${filePath} (文件不存在或无法访问)`);
+                            const resolvedPath = path.resolve(workspacePath, filePath);
+                            logger.info(`[McpServer] MD5 计算返回 null: ${filePath} -> ${resolvedPath} (workspace=${workspacePath})`);
+                            if (!hasNoBaseline) {
+                                // 已有基线但文件读不到 → 视为变更（文件被删除/移动）
+                                changedFiles.push(`${filePath} (文件不存在或无法访问)`);
+                            }
                             continue;
                         }
                         newMd5Map[filePath] = currentMd5;
                         const oldMd5 = oldMd5Map[filePath];
                         if (!oldMd5 || oldMd5 !== currentMd5) {
-                            changedFiles.push(filePath);
+                            if (hasNoBaseline) {
+                                // 无基线（修复前创建的旧数据或新建未计算 MD5）：静默建立基线，不视为变更
+                                logger.info(`[McpServer] 建立基线: ${filePath} new=${currentMd5} (workspace=${workspacePath}, memory=${memory.uri})`);
+                            }
+                            else {
+                                logger.info(`[McpServer] 文件变更: ${filePath} old=${oldMd5} new=${currentMd5} (workspace=${workspacePath})`);
+                                changedFiles.push(filePath);
+                            }
                         }
                     }
                     catch (error) {
                         logger.info(`[McpServer] 计算文件 MD5 失败: ${filePath}`, error);
-                        changedFiles.push(`${filePath} (MD5计算失败)`);
+                        if (!hasNoBaseline) {
+                            changedFiles.push(`${filePath} (MD5计算失败)`);
+                        }
                     }
                 }
+                // 无基线时：更新 MD5 map 到 memory 对象（供调用方回写），但不计入变更
+                if (hasNoBaseline && Object.keys(newMd5Map).length > 0) {
+                    memory.file_md5_map = newMd5Map;
+                    memory.last_check_time = new Date().toISOString();
+                    continue; // 不 push 到 changes
+                }
                 if (changedFiles.length > 0) {
                     changes.push({
                         memoryId: memory.id,
@@ -1841,9 +2243,20 @@ export class McpServer {
         try {
             const { createReadStream } = await import('node:fs');
             const { createHash } = await import('node:crypto');
+            // 绑定文件以工作区相对路径存储（./xxx），需相对 AWS_WORKSPACE_PATH 解析，
+            // 与 validateBoundFilesExist 保持一致，避免 cwd ≠ 工作区时读不到文件。
+            const workspacePath = process.env.AWS_WORKSPACE_PATH || process.cwd();
+            const resolvedPath = path.resolve(workspacePath, filePath);
+            // L-5: 防止路径逃逸（如 ../../../etc/passwd）
+            const normalizedWorkspace = path.resolve(workspacePath);
+            const normalizedResolved = path.resolve(resolvedPath);
+            if (!normalizedResolved.startsWith(normalizedWorkspace + path.sep) && normalizedResolved !== normalizedWorkspace) {
+                logger.warn(`[McpServer] calculateFileMd5: 路径逃逸被拒绝: ${filePath}`);
+                return null;
+            }
             return new Promise((resolve) => {
                 const hash = createHash('md5');
-                const stream = createReadStream(filePath);
+                const stream = createReadStream(resolvedPath);
                 stream.on('data', (chunk) => hash.update(chunk));
                 stream.on('end', () => resolve(hash.digest('hex')));
                 stream.on('error', () => resolve(null));
@@ -1872,7 +2285,7 @@ export class McpServer {
         // - buffer 空、hydrate 从服务端拉到消息 → fromBuffer=false（来自服务端）
         // - buffer 空、hydrate 也无消息（仅有 Memory 通知注入）→ fromBuffer=true（本地注入）
         const hadBufferedMessages = this.messageBuffer.size() > 0;
-        await this.hydrateUnreadMessagesIfNeeded();
+        await this.hydrateUnreadMessagesFromServer();
         const messages = this.messageBuffer.get();
         const hasRealMessages = messages.directMessages.length > 0 || messages.groupMessages.length > 0;
         const fromBuffer = hadBufferedMessages || !hasRealMessages;
@@ -1884,16 +2297,6 @@ export class McpServer {
         }
         return this.buildPollResult(messages, fromBuffer);
     }
-    /**
-     * 在本地缓冲区为空时，从服务端补拉离线期间积累的未读消息。
-     * 这样 Agent 重启或重连后，poll_message/get_message 仍能取到持久化未读消息。
-     */
-    async hydrateUnreadMessagesIfNeeded(options = {}) {
-        if (this.messageBuffer.size() > 0) {
-            return true;
-        }
-        return await this.hydrateUnreadMessagesFromServer(options);
-    }
     /**
      * 从服务端补拉未读消息并写入本地缓冲。
      * 主流程：按调用方指定的阻塞/流程线任务参数请求服务端 -> 过滤本地不可投递消息 -> 追加到当前消息缓存。
@@ -1921,7 +2324,7 @@ export class McpServer {
             return true;
         }
         catch (error) {
-            logger.error("[McpServer] 补拉未读消息失败:", error);
+            logger.error('[McpServer] 补拉未读消息失败: %s, stack=%s', error instanceof Error ? error.message : String(error), error instanceof Error ? error.stack : '(no stack)');
             return false;
         }
     }
@@ -1994,6 +2397,12 @@ export class McpServer {
      */
     async handleIncomingMessage(message) {
         if (!this.shouldBufferIncomingMessage(message)) {
+            // pipeline_task_assigned 不进 buffer，但需唤醒 poll 走 hydrate 重查任务，
+            // 否则 poll_message 会被 messageBuffer.poll(30s) 阻塞，task 流转最长延迟 30s。
+            if (!this.isGroupMessage(message) && this.isPipelineTaskAssignedNotification(message)) {
+                logger.info("[McpServer] 收到 pipeline_task_assigned 唤醒信号，立即唤醒 poll 走 hydrate 重查");
+                this.messageBuffer.wakeUpWaiters();
+            }
             return undefined;
         }
         logger.info(`[McpServer] 收到消息: ${message.content?.substring(0, 50) || "(无内容)"}`);
@@ -2073,19 +2482,17 @@ export class McpServer {
     /**
      * 构建 Todo 未完成项提醒通知。
      *
-     * 触发条件（同时满足）：
+     * 触发条件（全部满足）：
      *   1. 当前 agentId 可读取
      *   2. ~/.acode/todos/{agentId}.json 存在且可解析
      *   3. 存在 status !== "completed" 的未完成项
-     *   4. 未完成项内容/状态/优先级指纹与上次通知时不同（去重）
      *
      * 行为：
-     *   - 指纹变化且有未完成项：构造系统通知并返回；指纹更新为本轮快照。
-     *   - 指纹未变：返回 null（不重复通知）。
-     *   - 全部完成：重置指纹为 null，下次有未完成项时能再次通知。
-     *   - 任何异常（文件不存在/JSON 损坏/agentId 缺失）：静默返回 null，不阻断 poll_message。
+     *   - 有未完成项：构造轻量系统通知并返回（不持久化）。
+     *   - 全部完成 / 无文件 / 异常：静默返回 null，不阻断 poll_message。
      *
      * 通知以 DirectMessage 形式注入，senderId="MCP-System"，不落库、不持久化。
+     * 提示内容简洁，仅提醒有未完成待办，Agent 如需查看详情应调用 todo_read。
      */
     async buildTodoReminderNotification() {
         try {
@@ -2114,20 +2521,8 @@ export class McpServer {
                     t.status === "in_progress" ||
                     t.status === "cancelled"));
             if (incomplete.length === 0) {
-                // 全完成（或无未完成项）：重置指纹，下次有未完成项时能再次通知
-                this.lastTodoNotificationFingerprint = null;
-                return null;
-            }
-            const fingerprint = JSON.stringify(incomplete.map((t) => ({
-                c: t.content,
-                s: t.status,
-                p: t.priority,
-            })));
-            if (fingerprint === this.lastTodoNotificationFingerprint) {
-                // 指纹未变：不重复通知
                 return null;
             }
-            this.lastTodoNotificationFingerprint = fingerprint;
             return {
                 msgId: `todo-reminder-${Date.now()}`,
                 senderId: "MCP-System",
@@ -2140,7 +2535,7 @@ export class McpServer {
             };
         }
         catch (error) {
-            logger.warn("[McpServer] 构建 Todo 提醒失败:", error);
+            logger.warn('[McpServer] 构建 Todo 提醒失败: %s', error instanceof Error ? error.message : String(error));
             return null;
         }
     }
@@ -2159,53 +2554,64 @@ export class McpServer {
         // v1.13.0: 不再加载本地元数据缓存，过期/TODO/回忆状态统一由服务端 memory_status 字段管理
         // 后台注册：不阻塞 MCP 工具暴露，Agent 可立即接收工具调用
         this.autoRegisterInBackground();
-        // 启动后台 Memory 文件变更检测
-        this.startMemoryFileWatcher();
         logger.info("[McpServer] MCP Server 已就绪，工具已可用");
     }
     /**
-     * 停止 McpServer，清理后台定时器。
-     * 主流程：清理文件变更检测定时器 -> 停止 Agent 客户端消息循环。
-     */
-    stop() {
-        this.stopMemoryFileWatcher();
-        this.agentClient.stop();
-        logger.info("[McpServer] MCP Server 已停止");
-    }
-    /**
-     * 启动后台 Memory 文件变更检测定时器。
-     * 主流程：读取 AWS_MEMORY_FILE_CHECK_INTERVAL_MS -> 启动 setInterval -> 每次触发时检查绑定文件 MD5 变更 -> 有变更时直接推入消息缓冲区。
-     * 后台定时器启用后，poll_message 不再重复检查，避免重复推送通知。
+     * 启动租约续期定时器 (v1.21.0)。
+     * 每 60 秒续期一次当前 agent 持有的所有 updating memory 的租约，
+     * 防止租约过期导致其他实例接管。
      */
-    startMemoryFileWatcher() {
-        const intervalMs = this.parsePositiveIntegerEnv("AWS_MEMORY_FILE_CHECK_INTERVAL_MS", DEFAULT_MEMORY_FILE_CHECK_INTERVAL_MS);
-        if (intervalMs <= 0) {
-            logger.info("[McpServer] 后台文件变更检测已禁用（AWS_MEMORY_FILE_CHECK_INTERVAL_MS=0），将回退到 poll_message 时检测");
+    startLeaseRenewal() {
+        if (this.leaseRenewalTimer)
             return;
-        }
-        this.memoryFileCheckInterval = setInterval(async () => {
+        this.leaseRenewalTimer = setInterval(async () => {
             try {
-                const notification = await this.buildMemoryFileChangeNotification();
-                if (notification) {
-                    this.messageBuffer.push(notification);
-                    logger.info("[McpServer] 后台文件变更检测: 已推送 Memory 变更通知到消息缓冲区");
+                const agentId = this.getCurrentAgentId();
+                if (!agentId)
+                    return;
+                const result = await this.memoryStore.renewMemoryLease(McpServer.LEASE_DURATION_MINUTES);
+                // 续期返回 0 说明租约已丢失（被过期清理或被其他 agent 接管），停止续期
+                if (result.renewed === 0) {
+                    logger.warn("[McpServer] 租约已丢失（renewed=0），停止续期定时器");
+                    this.stopLeaseRenewal();
+                }
+                // L-1: 主动清理 claimedCache 中的过期条目，避免堆积
+                const now = Date.now();
+                for (const [uri, expiry] of this.claimedCache) {
+                    if (expiry <= now) {
+                        this.claimedCache.delete(uri);
+                    }
                 }
             }
-            catch (error) {
-                logger.warn("[McpServer] 后台文件变更检测失败:", error);
+            catch (e) {
+                logger.warn('[McpServer] 续期租约失败: %s', e instanceof Error ? e.message : String(e));
             }
-        }, intervalMs);
-        logger.info(`[McpServer] 后台文件变更检测已启动，间隔: ${intervalMs}ms（可通过 AWS_MEMORY_FILE_CHECK_INTERVAL_MS 环境变量调整，设为 0 禁用）`);
+        }, McpServer.LEASE_RENEW_INTERVAL_MS);
+        logger.info("[McpServer] 租约续期定时器已启动，间隔: 60s");
     }
     /**
-     * 停止后台 Memory 文件变更检测定时器。
+     * 停止租约续期定时器 (v1.21.0)。
      */
-    stopMemoryFileWatcher() {
-        if (this.memoryFileCheckInterval) {
-            clearInterval(this.memoryFileCheckInterval);
-            this.memoryFileCheckInterval = null;
-            logger.info("[McpServer] 后台文件变更检测已停止");
+    stopLeaseRenewal() {
+        if (this.leaseRenewalTimer) {
+            clearInterval(this.leaseRenewalTimer);
+            this.leaseRenewalTimer = null;
+            logger.info("[McpServer] 租约续期定时器已停止");
+        }
+    }
+    /**
+     * 停止 McpServer，清理后台定时器。
+     * 主流程：停止租约续期 -> 释放所有 claim -> 停止 Agent 客户端消息循环。
+     */
+    stop() {
+        this.stopLeaseRenewal();
+        // 释放所有持有的 claim
+        const agentId = this.getCurrentAgentId();
+        if (agentId) {
+            this.memoryStore.releaseAllMemoryClaims().catch(e => logger.warn('[McpServer] 释放 claim 失败: %s', e instanceof Error ? e.message : String(e)));
         }
+        this.agentClient.stop();
+        logger.info("[McpServer] MCP Server 已停止");
     }
     // ============ 记忆统一状态字段 (v1.13.0) ============
     // v1.13.0 改用服务端 memory_status 字段管理 agent_memory 过期/回忆状态，
@@ -2274,7 +2680,7 @@ export class McpServer {
      */
     autoRegisterInBackground() {
         this.autoRegister().catch((error) => {
-            logger.error("[McpServer] 后台注册异常:", error);
+            logger.error('[McpServer] 后台注册异常: %s, stack=%s', error instanceof Error ? error.message : String(error), error instanceof Error ? error.stack : '(no stack)');
         });
     }
     /**
@@ -2282,30 +2688,52 @@ export class McpServer {
      */
     startListeningInternal() {
         logger.info("[McpServer] startListeningInternal 被调用");
+        const profileHandler = (profile) => {
+            // 收到 Profile 信息后，存储到消息缓冲区
+            logger.info(`[McpServer] profileHandler 被调用，displayName: ${profile.displayName}`);
+            this.messageBuffer.setProfileMessage(profile);
+            this.profileSynced = true;
+            this.syncRoleMemoryStore(profile);
+            this.maybeSyncPermanentMemoryToServer();
+        };
         // 降级模式下跳过 WebSocket 连接
         if (this.agentClient.isInDegradedMode()) {
             logger.info("[McpServer] 降级模式：跳过 WebSocket 连接，仅启动本地消息监听");
             this.agentClient.start(this.handleIncomingMessage.bind(this), {
                 pollMode: false,
-                profileHandler: (profile) => {
-                    // 收到 Profile 信息后，存储到消息缓冲区
-                    logger.info(`[McpServer] profileHandler 被调用，displayName: ${profile.displayName}`);
-                    this.messageBuffer.setProfileMessage(profile);
-                    this.syncRoleMemoryStore(profile);
-                    this.maybeSyncPermanentMemoryToServer();
-                },
+                profileHandler,
             });
+            this.activelySyncProfile();
             return;
         }
         this.agentClient.start(this.handleIncomingMessage.bind(this), {
             pollMode: false,
-            profileHandler: (profile) => {
-                // 收到 Profile 信息后，存储到消息缓冲区
-                logger.info(`[McpServer] profileHandler 被调用，displayName: ${profile.displayName}`);
-                this.messageBuffer.setProfileMessage(profile);
-                this.syncRoleMemoryStore(profile);
-                this.maybeSyncPermanentMemoryToServer();
-            },
+            profileHandler,
+        });
+        // 注册时 getProfileByAgentId 会触发 Java markProfileFetched，导致 WebSocket 连接后
+        // Java 不再推送 PROFILE_INFO 消息（AgentWebSocketHandler 检查 hasProfileFetched 跳过）。
+        // 因此 profileHandler 可能永远不会被触发，需要主动获取 profile 同步 hasRoleName。
+        this.activelySyncProfile();
+    }
+    /**
+     * 主动获取 profile 并同步角色存储路径。
+     * 当 Java 侧因 hasProfileFetched=true 跳过 PROFILE_INFO 推送时，
+     * profileHandler 不会被调用，hasRoleName 永远为 false，导致文件变更检测被跳过。
+     * 此方法在 startListeningInternal 后主动拉取 profile，确保 hasRoleName 被正确设置。
+     */
+    activelySyncProfile() {
+        if (this.profileSynced)
+            return;
+        this.agentClient.getProfile().then((profile) => {
+            if (this.profileSynced)
+                return;
+            this.profileSynced = true;
+            logger.info(`[McpServer] 主动获取 profile 成功: displayName=${profile.displayName}, roleName="${profile.roleName ?? '(空)'}"`);
+            this.messageBuffer.setProfileMessage(profile);
+            this.syncRoleMemoryStore(profile);
+            this.maybeSyncPermanentMemoryToServer();
+        }).catch((e) => {
+            logger.warn('[McpServer] 主动获取 profile 失败: %s', e instanceof Error ? e.message : String(e));
         });
     }
     delay(ms) {