aws-runtime-bridge 1.9.33 → 1.9.41

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

@@ -3,6 +3,7 @@
  * 提供 MCP Tools 供 AI Agent 调用
  */
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -10,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";
@@ -23,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([
     "<",
     ">",
@@ -48,6 +48,8 @@ export class McpServer {
     hasRoleName = false;
     /** 上下文管理器 (v1.8.0) */
     contextManager;
+    /** 子 Agent 模式：仅暴露 Memory 工具，拒绝非 Memory 工具调用 */
+    isSubAgent;
     /**
      * 内存级去重缓存：记录本轮已通知过的 listable memory 文件变更状态。
      * key = memoryId，value = 已通知时刻各绑定文件的 MD5 复合哈希。
@@ -56,13 +58,29 @@ export class McpServer {
      */
     notifiedFileChangeMemoryIds = new Map();
     /**
-     * 本地缓存 listable 记忆（task_list/recently_memory）的文件 MD5 map。
+     * 本地缓存 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 重复读盘。
@@ -70,6 +88,11 @@ export class McpServer {
      */
     memoryNotificationNullCache = new Map();
     static MEMORY_NOTIFICATION_NULL_TTL_MS = 60_000;
+    /**
+     * poll_message 单例控制：防止并发调用导致消息被第一个消费后第二个空等。
+     * 当已有 poll 在进行时，后续调用直接等待同一个 Promise。
+     */
+    pendingPollMessage = null;
     // 系统提示词由 runtime adapter（ACode/OpenCode/Codex/Claude）在会话创建时注入，
     // 无需通过 MCP 工具返回。三方 runtime（OpenCode/Claude）将三层提示词合并为一条 system prompt，
     // ACode 则直接注入为前三条 system role 消息。
@@ -78,7 +101,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);
@@ -90,6 +115,100 @@ export class McpServer {
         this.roleMemoryStore = new MemoryStore(McpServer.buildRoleMemoryStorePath(expectedRoleDir));
         this.initialRoleName = expectedRoleDir;
     }
+    /**
+     * 在 profile 到达后检查是否需要将本地永久记忆同步到 server。
+     * 触发条件：当前角色在 server 上还没有任何 memory 类型记录（通常发生在重部署后 server DB 为空时）。
+     * 主流程：异步执行，不阻塞 profile 处理链路。
+     * 1. 调用 server get_memory_stats 获取当前角色 memory 类型计数
+     * 2. 若 count === 0，读取本地永久记忆（角色子目录 + 遗留父目录 fallback）
+     * 3. 逐条调用 server create_memory 写入（已存在则静默跳过）
+     */
+    maybeSyncPermanentMemoryToServer() {
+        this.doMaybeSyncPermanentMemoryToServer().catch((e) => {
+            logger.warn('[McpServer] maybeSyncPermanentMemoryToServer 异常: %s, stack=%s', e instanceof Error ? e.message : String(e), e instanceof Error ? e.stack : '(no stack)');
+        });
+    }
+    async doMaybeSyncPermanentMemoryToServer() {
+        logger.info("[McpServer] maybeSyncPermanentMemoryToServer 开始，initialRoleName="
+            + this.initialRoleName);
+        // Step 1: 检查 server 当前角色的 memory 计数
+        let stats;
+        try {
+            stats = await this.memoryStore.getStats();
+        }
+        catch (e) {
+            logger.warn("[McpServer] 获取 server 记忆统计失败，跳过同步:", e instanceof Error ? e.message : e);
+            return;
+        }
+        const memoryCount = stats.by_type["project_memory"]?.count ?? 0;
+        logger.info(`[McpServer] server memory 计数=${memoryCount}，`
+            + `是否需要同步=${memoryCount === 0}`);
+        if (memoryCount > 0) {
+            return;
+        }
+        // Step 2: 读取本地永久记忆
+        // 2a: 先读角色子目录
+        let localMemories = [];
+        try {
+            localMemories = await this.roleMemoryStore.listByType("project_memory");
+            logger.info(`[McpServer] 角色子目录读取到 ${localMemories.length} 条永久记忆`);
+        }
+        catch (e) {
+            logger.warn("[McpServer] 读取角色子目录永久记忆失败:", e instanceof Error ? e.message : e);
+        }
+        // 2b: 角色子目录为空时，fallback 读遗留父目录（旧版无角色子目录）
+        if (localMemories.length === 0) {
+            const legacyStorePath = path.dirname(McpServer.buildRoleMemoryStorePath(this.initialRoleName));
+            logger.info(`[McpServer] 尝试从遗留目录读取: ${legacyStorePath}`);
+            try {
+                const legacyStore = new MemoryStore(legacyStorePath);
+                const legacyMemories = await legacyStore.listByType("project_memory");
+                if (legacyMemories.length > 0) {
+                    logger.info(`[McpServer] 从遗留目录读取到 ${legacyMemories.length} 条永久记忆`);
+                    localMemories = legacyMemories;
+                }
+            }
+            catch (e) {
+                logger.warn("[McpServer] 读取遗留目录永久记忆失败:", e instanceof Error ? e.message : e);
+            }
+        }
+        if (localMemories.length === 0) {
+            logger.info("[McpServer] 本地也无永久记忆，跳过同步");
+            return;
+        }
+        // Step 3: 逐条写入 server
+        let synced = 0;
+        let skipped = 0;
+        for (const record of localMemories) {
+            try {
+                await this.memoryStore.createMemory({
+                    memory_type: "project_memory",
+                    uri: record.uri,
+                    title: record.title,
+                    content: record.content,
+                    keywords: record.keywords,
+                    bound_files: record.bound_files,
+                    file_md5_map: record.file_md5_map,
+                    last_check_time: record.last_check_time,
+                });
+                synced++;
+                logger.info(`[McpServer] 同步永久记忆成功: ${record.uri}`);
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                if (msg.includes("already exists")
+                    || msg.includes("Memory already exists")) {
+                    skipped++;
+                }
+                else {
+                    logger.warn(`[McpServer] 同步永久记忆失败 (${record.uri}): ${msg}`);
+                    skipped++;
+                }
+            }
+        }
+        logger.info(`[McpServer] 永久记忆同步完成: 成功 ${synced}, 跳过 ${skipped}, 共 ${localMemories.length}`);
+        await this.reportCombinedMemoryStats();
+    }
     /**
      * 规范化绑定的文件路径。
      * 项目约定以下前缀都表示工作区根路径：
@@ -179,7 +298,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,
         };
@@ -194,6 +313,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,
@@ -207,7 +327,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;
@@ -230,6 +353,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: [
                         {
@@ -246,24 +371,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;
@@ -273,6 +418,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();
@@ -281,8 +429,6 @@ export class McpServer {
             case "get_profile": {
                 return await this.agentClient.getProfile();
             }
-            case "get_status":
-                return this.agentClient.getState();
             case "hire_colleague":
                 return await this.handleHireColleague(args);
             case "hire_colleagues_batch":
@@ -329,8 +475,6 @@ export class McpServer {
                 return await this.handleListMemories(args);
             case "get_memory_stats":
                 return await this.handleGetMemoryStats(args);
-            case "archive_recently_memory":
-                return await this.handleArchiveRecentlyMemory(args);
             // Memory 增强功能工具 (v1.6.0)
             case "list_memories_by_file":
                 return await this.handleListMemoriesByFile(args);
@@ -341,23 +485,15 @@ export class McpServer {
                 return await this.handleMemoryRecurrence(args);
             case "memory_recurrence_complete":
                 return await this.handleMemoryRecurrenceComplete();
-            // Memory 短期记忆 TODO 完成工具 (v1.14.0)
-            case "todo_completed":
-                return await this.handleTodoCompleted(args);
-            // 上下文压缩工具 (v1.8.0)
-            case "get_context_stats":
-                return await this.handleGetContextStats(args);
-            case "compact_context":
-                return await this.handleCompactContext(args);
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
     }
     // ============ 工具处理方法 ============
     static MEMORY_TYPES = [
-        "task_list",
         "recently_memory",
-        "memory",
+        "agent_memory",
+        "project_memory",
         "session_context",
     ];
     static MEMORY_TOOL_NAMES = new Set([
@@ -368,15 +504,12 @@ export class McpServer {
         "search_memory",
         "list_memories",
         "get_memory_stats",
-        "archive_recently_memory",
         // Memory 增强功能工具 (v1.6.0)
         "list_memories_by_file",
         "abandon_memory_update",
         // Memory 近期记忆过期与回忆工具 (v1.11.0)
         "memory_recurrence",
         "memory_recurrence_complete",
-        // Memory 短期记忆 TODO 完成工具 (v1.14.0)
-        "todo_completed",
     ]);
     /**
      * 从 startPath 向上逐级查找 .agentswork 目录。
@@ -427,7 +560,7 @@ export class McpServer {
     }
     /**
      * 解析记忆存储路径。
-     * 主流程：task_list/recently_memory 走 server 数据库；长期 memory 默认写入项目 .agentswork/memory/memory/<roleName>/<domain>.json。
+     * 主流程：recently_memory/agent_memory 走 server 数据库；长期 project_memory 默认写入项目 .agentswork/memory/memory/<roleName>/<domain>.json。
      */
     static resolveMemoryStorePaths() {
         const configuredPath = String(process.env.AWS_MEMORY_STORE_PATH || "").trim();
@@ -483,16 +616,16 @@ export class McpServer {
     }
     /**
      * 按记忆生命周期选择存储作用域。
-     * 主流程：长期 memory 走角色级 store；task_list/recently_memory 走当前 Agent 实例级 store。
+     * 主流程：长期 project_memory 走角色级 store；recently_memory/agent_memory 走当前 Agent 实例级 store。
      */
     /**
      * 按记忆生命周期选择存储作用域。
-     * 主流程：永久记忆(memory)仅在 hasRoleName 为 true 时走角色级 store，
-     *         否则回退到实例级 server store（避免空角色名下所有实例共享 default-role 目录导致跨角色污染）。
-     * task_list/recently_memory/session_context 始终走实例级 store。
+     * 主流程：永久记忆(project_memory)始终走本地 roleMemoryStore（.agentswork），
+     *         确保本地文件始终有副本，后续部署恢复时可通过 Local → Server 同步回 server。
+     * recently_memory/agent_memory/session_context 始终走实例级 server store。
      */
     getMemoryStoreForType(memoryType) {
-        if (memoryType === "memory" && this.hasRoleName) {
+        if (memoryType === "project_memory") {
             return this.roleMemoryStore;
         }
         return this.memoryStore;
@@ -506,17 +639,32 @@ export class McpServer {
             return await this.memoryStore.readMemory(input);
         }
         if (input.memory_type) {
-            return await this.getMemoryStoreForType(input.memory_type).readMemory(input);
-        }
-        // hasRoleName 为 false 时不查 roleMemoryStore，避免空角色名共享 default-role 目录
-        if (this.hasRoleName) {
-            const longTermRecord = await this.roleMemoryStore.readMemory({
-                ...input,
-                memory_type: "memory",
-            });
-            if (longTermRecord) {
-                return longTermRecord;
+            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,
+            memory_type: "project_memory",
+        });
+        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);
     }
@@ -529,19 +677,32 @@ 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,
-            };
-        }
-        if (this.hasRoleName) {
-            const longTermRecord = await this.roleMemoryStore.readMemory({
-                uri: input.uri,
-                memory_type: "memory",
-            });
-            if (longTermRecord) {
-                return { store: this.roleMemoryStore, memory_type: "memory" };
+            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,
+            memory_type: "project_memory",
+        });
+        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 };
     }
@@ -558,17 +719,17 @@ export class McpServer {
         // permanentCount 取两者的较大值作为保守估计（下界）。
         // 注意: 当 instance 和 role 分别有对方没有的唯一 URI 时，实际并集 > Math.max，
         // 但此处只有 count 无 URI 列表，无法精确计算并集，使用下界避免面板显示虚高。
-        const permanentCount = Math.max(instanceStats.by_type.memory.count, roleStats.by_type.memory.count);
-        // total 同样保守估算：用 server 非 memory count + permanentCount 下界
-        const serverNonMemoryTotal = instanceStats.total - instanceStats.by_type.memory.count;
+        const permanentCount = Math.max(instanceStats.by_type.project_memory.count, roleStats.by_type.project_memory.count);
+        // total 同样保守估算：用 server 非 project_memory count + permanentCount 下界
+        const serverNonMemoryTotal = instanceStats.total - instanceStats.by_type.project_memory.count;
         return {
             total: serverNonMemoryTotal + permanentCount,
             listable: instanceStats.listable,
             by_type: {
-                task_list: instanceStats.by_type.task_list,
                 recently_memory: instanceStats.by_type.recently_memory,
-                memory: {
-                    ...roleStats.by_type.memory,
+                agent_memory: instanceStats.by_type.agent_memory,
+                project_memory: {
+                    ...roleStats.by_type.project_memory,
                     count: permanentCount,
                 },
                 session_context: instanceStats.by_type.session_context,
@@ -591,44 +752,6 @@ export class McpServer {
             logger.warn("[McpServer] 上报合并 memory 统计失败，已保留本地记忆写入结果:", error);
         }
     }
-    /**
-     * 同步本地永久记忆到服务端。
-     * 主流程：读取本地 roleMemoryStore 中所有 memory 类型记录 -> 逐条写入服务端 memoryStore -> 已存在的记录静默跳过。
-     */
-    async syncLocalPermanentMemoryToServer() {
-        if (!this.hasRoleName)
-            return;
-        try {
-            const memories = await this.roleMemoryStore.listByType("memory");
-            if (memories.length === 0)
-                return;
-            let syncedCount = 0;
-            for (const memory of memories) {
-                try {
-                    await this.memoryStore.createMemory({
-                        memory_type: "memory",
-                        uri: memory.uri,
-                        title: memory.title,
-                        content: memory.content,
-                        keywords: memory.keywords,
-                        bound_files: memory.bound_files,
-                    });
-                    syncedCount++;
-                }
-                catch (e) {
-                    // If already exists on server, skip
-                    const errMsg = e instanceof Error ? e.message : String(e);
-                    if (!errMsg.includes("already exists")) {
-                        logger.warn(`[McpServer] Failed to sync permanent memory ${memory.uri}:`, e);
-                    }
-                }
-            }
-            logger.info(`[McpServer] Synced ${syncedCount}/${memories.length} permanent memories to server`);
-        }
-        catch (error) {
-            logger.error("[McpServer] Failed to sync permanent memories to server:", error);
-        }
-    }
     /**
      * 系统提示词由 runtime adapter 在会话创建时注入，MCP 层面不再负责返回。
      * 详见 startListeningInternal -> profileHandler 中的合并注入逻辑。
@@ -665,6 +788,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 的写入结果。
@@ -698,16 +858,16 @@ export class McpServer {
         const created = await this.getMemoryStoreForType(input.memory_type).createMemory(input);
         await this.reportCombinedMemoryStats();
         // Dual-write permanent memory to server
-        if (input.memory_type === "memory") {
+        if (input.memory_type === "project_memory") {
             try {
-                await this.memoryStore.createMemory(input).catch(() => { });
+                await this.memoryStore.createMemory(input);
             }
             catch (e) {
                 logger.warn("[McpServer] Failed to sync permanent memory to server:", e);
             }
         }
-        // v1.13.0: recently_memory 过期判定、task_list todo 状态由服务端 memory_status 字段管理，
-        // 无需 TS 侧本地缓存。服务端默认按类型填充正确状态（recently_memory='normal', task_list='pending'）。
+        // v1.13.0: recently_memory 过期判定、agent_memory 过期/回忆状态由服务端 memory_status 字段管理，
+        // 无需 TS 侧本地缓存。服务端默认按类型填充正确状态（recently_memory='normal', agent_memory='normal'）。
         return this.toMemoryWriteResult(created);
     }
     /**
@@ -723,7 +883,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" ||
@@ -734,10 +896,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),
@@ -779,27 +940,35 @@ export class McpServer {
         });
         await this.reportCombinedMemoryStats();
         // Dual-write permanent memory update to server（同步 MD5 map 避免服务端重复检测）
-        if (target.memory_type === "memory") {
+        // 当 target.store 已是服务端（兄弟实例创建的记忆回退场景）时跳过，避免重复写
+        if (target.memory_type === "project_memory" && target.store !== this.memoryStore) {
             try {
-                await this.memoryStore
-                    .updateMemory({
+                await this.memoryStore.updateMemory({
                     ...input,
-                    memory_type: "memory",
+                    memory_type: "project_memory",
                     file_md5_map: fileMd5Map,
                     last_check_time: lastCheckTime,
-                })
-                    .catch(() => { });
+                });
             }
             catch (e) {
                 logger.warn("[McpServer] Failed to sync permanent memory update to server:", e);
             }
         }
-        // v1.13.0: task_list TODO 状态、recently_memory 过期与回忆状态均由服务端 memory_status 字段管理。
-        // 显式传入的 todo_status / recall_status / memory_status 已在 updateMemory 内部透传到服务端。
-        // 服务端会自动处理"所有 TODO 已完成时清理全部已完成项"的逻辑（见 AgentMemoryService.updateMemory）。
-        // 内容变更对 recently_memory 的"续期"语义现在由过期判定基于 created_at 决定，
-        // update_memory 内容变更不会重置 created_at，因此"续期"实际对应"修改 created_at" — 当前不提供该能力，
-        // 如需续期建议使用 archive_recently_memory 归档或重新 createMemory 替代。
+        // v1.13.0: agent_memory 过期与回忆状态由服务端 memory_status 字段管理。
+        // 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);
     }
     /**
@@ -819,14 +988,13 @@ export class McpServer {
         });
         if (deleted) {
             await this.reportCombinedMemoryStats();
-            // v1.13.0: 服务端 deleteMemory 内部已处理"task_list 删除后清空 completed 残留"逻辑，
+            // v1.13.0: 服务端 deleteMemory 内部已处理相关清理逻辑，
             // TS 侧无需任何本地元数据清理。
             // Dual-write permanent memory delete to server
-            if (effectiveType === "memory") {
+            // 当 target.store 已是服务端时跳过，避免重复删除
+            if (effectiveType === "project_memory" && target.store !== this.memoryStore) {
                 try {
-                    await this.memoryStore
-                        .deleteMemory({ uri: input.uri, memory_type: "memory" })
-                        .catch(() => { });
+                    await this.memoryStore.deleteMemory({ uri: input.uri, memory_type: "project_memory" });
                 }
                 catch (e) {
                     logger.warn("[McpServer] Failed to sync permanent memory delete to server:", e);
@@ -872,7 +1040,7 @@ export class McpServer {
     }
     /**
      * 搜索自己工作区的所有记忆。
-     * 具体逻辑：按 memory_type 分流 -> 无类型时合并 roleMemoryStore(永久)与 memoryStore(task_list/recently)。
+     * 具体逻辑：按 memory_type 分流 -> 无类型时合并 roleMemoryStore(永久)与 memoryStore(recently/agent)。
      */
     async searchOwnMemories(input) {
         if (input.memory_type) {
@@ -886,7 +1054,7 @@ export class McpServer {
             return await this.memoryStore.searchMemory(input);
         }
         const [roleResult, instanceResult] = await Promise.all([
-            this.roleMemoryStore.searchMemory({ ...input, memory_type: "memory" }),
+            this.roleMemoryStore.searchMemory({ ...input, memory_type: "project_memory" }),
             this.memoryStore.searchMemory(input),
         ]);
         const seen = new Set();
@@ -926,7 +1094,7 @@ export class McpServer {
     }
     /**
      * 列出短期类型记忆。
-     * 主流程：只允许 task_list/recently_memory，由 MemoryStore 阻止长期 memory 的全量列出。
+     * 主流程：只允许 recently_memory/agent_memory/project_memory，由 MemoryStore 阻止 session_context 的全量列出。
      */
     async handleListMemories(args) {
         return await this.memoryStore.listByType(this.getRequiredString(args, "memory_type"));
@@ -952,58 +1120,39 @@ export class McpServer {
             },
         };
     }
-    /**
-     * 归档近期记忆。
-     * 主流程：将 recently_memory 原地转换为长期 memory，并递增版本号。
-     */
-    async handleArchiveRecentlyMemory(args) {
-        const uri = this.getRequiredString(args, "uri");
-        if (this.memoryStoresShareFile) {
-            return await this.memoryStore.archiveRecentlyMemory(uri);
-        }
-        const record = await this.memoryStore.readMemory({
-            uri,
-            memory_type: "recently_memory",
-        });
-        if (!record) {
-            throw new Error(`Memory not found: ${uri}`);
-        }
-        const archived = await this.getMemoryStoreForType("memory").createMemory({
-            memory_type: "memory",
-            uri: record.uri,
-            title: record.title,
-            content: record.content,
-            keywords: record.keywords,
-            bound_files: record.bound_files,
-        });
-        await this.memoryStore.deleteMemory({
-            uri: record.uri,
-            memory_type: "recently_memory",
-        });
-        await this.reportCombinedMemoryStats();
-        return archived;
-    }
     /**
      * 按文件查询绑定了该文件的 Memory
      * Memory 增强功能 (v1.6.0)
      */
     /**
      * 按文件路径查询 Memory（支持 scope 跨 Agent 搜索）。
-     * 主流程：解析scope -> own(默认)仅自己 -> children通过server按path_prefix匹配子Agent -> all合并。
-     * 对于永久记忆(type=memory)同时查询本地roleMemoryStore作为补充。
+     * 主流程：解析scope -> own(默认)仅自己 -> children搜索子Agent -> all合并。
+     * 子 Agent 搜索同时走两条路径：
+     *   1. server searchChildByFilePath（查 DB）
+     *   2. 本地文件系统扫描 child .agentswork/memory/memory/（查本地永久记忆文件）
+     * 两条路径结果按 id 去重合并，确保无论子 Agent 的永久记忆是否已同步到
+     * 服务端数据库，父 Agent 都能搜索到。
      */
     async handleListMemoriesByFile(args) {
         const rawPath = this.getRequiredString(args, "file_path");
         const normalizedPath = this.normalizeBoundFilePath(rawPath);
         const memoryType = this.getOptionalMemoryType(args);
         const rawScope = this.getOptionalString(args, "scope");
-        const scope = rawScope === "children" || rawScope === "all" ? rawScope : "own";
-        // scope='children': 仅通过 server 搜索子 Agent（带 path_prefix 自动匹配）
+        // 默认 scope='all'：合并搜索自身与子Agent绑定文件的记忆
+        const scope = rawScope === "own" || rawScope === "children" ? rawScope : "all";
+        // 搜索子 Agent 的 memory（server + 本地文件系统双路径，并行）
+        const fetchChildMemories = async () => {
+            const [serverResult, localResult] = await Promise.all([
+                this.memoryStore.listByFile(normalizedPath, {
+                    memory_type: memoryType,
+                    scope: "children",
+                }).catch(() => []), // server 不可用时降级
+                this.searchChildMemoriesByFileLocal(normalizedPath, memoryType),
+            ]);
+            return this.mergeIdDedupe(serverResult, localResult);
+        };
         if (scope === "children") {
-            const childResult = await this.memoryStore.listByFile(normalizedPath, {
-                memory_type: memoryType,
-                scope: "children",
-            });
+            const childResult = await fetchChildMemories();
             return {
                 file_path: normalizedPath,
                 count: childResult.length,
@@ -1019,11 +1168,8 @@ export class McpServer {
                 memories: ownMemories.map(m => this.toMemoryRecordWithMetadata(m)),
             };
         }
-        // scope='all': 合并自己的 + 子 Agent 的
-        const childResult = await this.memoryStore.listByFile(normalizedPath, {
-            memory_type: memoryType,
-            scope: "children",
-        });
+        // scope='all': 合并自己的 + 子 Agent 的（server + 本地双路径已由 fetchChildMemories 聚合）
+        const childResult = await fetchChildMemories();
         const seen = new Set(ownMemories.map(m => m.id));
         const merged = [...ownMemories];
         for (const m of childResult) {
@@ -1039,6 +1185,135 @@ export class McpServer {
             memories: merged.map(m => this.toMemoryRecordWithMetadata(m)),
         };
     }
+    /**
+     * 按 id 去重合并两批 MemoryRecord，按 updatedAt 倒序排列。
+     * 首批（left）优先级高，其 id 会标记为 seen，重复的 right 项被丢弃。
+     */
+    mergeIdDedupe(left, right) {
+        const seen = new Set();
+        for (const m of left) {
+            if (m.id)
+                seen.add(m.id);
+        }
+        const merged = [...left];
+        for (const m of right) {
+            if (m.id && !seen.has(m.id)) {
+                merged.push(m);
+                seen.add(m.id);
+            }
+        }
+        merged.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+        return merged;
+    }
+    /**
+     * 通过文件系统扫描子 Agent 的 .agentswork 目录，
+     * 读取永久记忆 JSON 文件，按 path_prefix 匹配 bound_files。
+     *
+     * 主流程：
+     * 1. 解析 file_path（如 ./frontend/src/main.ts）的路径层级
+     * 2. 逐级（从长到短）找到子 Agent 的 .agentswork 目录
+     * 3. 读取该目录下所有 role 的 JSON 文件
+     * 4. 对每条记忆，将 bound_files 与 child-relative 路径比较
+     *
+     * 作为 server searchChildByFilePath 的本地补充，
+     * 确保子 Agent 的本地永久记忆（未同步到 server）也能被搜索到。
+     */
+    async searchChildMemoriesByFileLocal(filePath, memoryType) {
+        const workspacePath = process.env.AWS_WORKSPACE_PATH || process.cwd();
+        const normalizedFilePath = this.normalizeBoundFilePath(filePath);
+        // 解析路径 segments
+        // 例如 ./frontend/src/main.ts → relativePath = "frontend/src/main.ts"
+        //     segments = ["frontend", "src", "main.ts"]
+        const relativePath = normalizedFilePath.startsWith('./')
+            ? normalizedFilePath.substring(2)
+            : normalizedFilePath;
+        const segments = relativePath.split('/');
+        const results = [];
+        const seenById = new Set();
+        const { access, readdir, readFile } = await import('node:fs/promises');
+        // 从最长的路径前缀开始尝试（兼容嵌套子 Agent：深度=2 时 prefix=frontend/src）
+        for (let depth = segments.length - 1; depth >= 1; depth--) {
+            const prefixSegments = segments.slice(0, depth);
+            const childRelativeSegments = segments.slice(depth);
+            const childRelativePath = './' + childRelativeSegments.join('/');
+            // 子 Agent 的候选工作区路径
+            const childWorkspace = path.join(workspacePath, ...prefixSegments);
+            // 跳过父 Agent 自身（避免把 parent 当 child 扫）
+            if (childWorkspace === workspacePath)
+                continue;
+            const childAgentsworkDir = path.join(childWorkspace, '.agentswork');
+            // 检查 .agentswork 是否存在
+            try {
+                await access(childAgentsworkDir);
+            }
+            catch {
+                continue; // 这个前缀不是子 Agent 工作区
+            }
+            // 读取子 Agent 的永久记忆目录 .agentswork/memory/memory/<roleName>/
+            const memoryBaseDir = path.join(childAgentsworkDir, 'memory', 'memory');
+            let roleDirs;
+            try {
+                const entries = await readdir(memoryBaseDir, { withFileTypes: true });
+                roleDirs = entries.filter(e => e.isDirectory()).map(e => e.name);
+            }
+            catch {
+                continue;
+            }
+            for (const roleDir of roleDirs) {
+                const rolePath = path.join(memoryBaseDir, roleDir);
+                let files;
+                try {
+                    files = await readdir(rolePath);
+                }
+                catch {
+                    continue;
+                }
+                for (const file of files) {
+                    if (!file.endsWith('.json'))
+                        continue;
+                    const jsonPath = path.join(rolePath, file);
+                    let content;
+                    try {
+                        content = await readFile(jsonPath, 'utf-8');
+                    }
+                    catch {
+                        continue;
+                    }
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(content);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (!parsed.by_uri)
+                        continue;
+                    // 遍历该 domain 的所有记忆，匹配 bound_files
+                    for (const [uri, record] of Object.entries(parsed.by_uri)) {
+                        if (!record)
+                            continue;
+                        const recordId = record.id || uri;
+                        if (seenById.has(recordId))
+                            continue;
+                        if (memoryType && record.memory_type !== memoryType)
+                            continue;
+                        if (record.bound_files && record.bound_files.length > 0) {
+                            const matched = record.bound_files.some(bf => this.normalizeBoundFilePath(bf) === childRelativePath);
+                            if (matched) {
+                                seenById.add(recordId);
+                                results.push({
+                                    ...record,
+                                    uri: record.uri || uri,
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        results.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+        return results;
+    }
     /**
      * 按文件路径搜索本 Agent 的记忆。
      * 同时查询临时记忆(server)和永久记忆(local roleMemoryStore)。
@@ -1049,8 +1324,8 @@ export class McpServer {
         });
         let localResult = [];
         // 补充查询本地永久记忆（server 可能未同步）；无角色名时跳过（避免 default-role 跨角色污染）
-        if (this.hasRoleName && (!memoryType || memoryType === "memory")) {
-            localResult = await this.roleMemoryStore.listByFile(filePath, "memory");
+        if (this.hasRoleName && (!memoryType || memoryType === "project_memory")) {
+            localResult = await this.roleMemoryStore.listByFile(filePath, "project_memory");
         }
         // 去重合并
         const seen = new Set(serverResult.map(m => `${m.memory_type}:${m.uri}`));
@@ -1065,38 +1340,54 @@ 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 更新状态已清除",
         };
     }
-    // ============ Memory 近期记忆过期与回忆工具处理 (v1.11.0 / v1.13.0) ============
+    // ============ Memory 近期记忆过期与回忆工具处理 (v1.11.0 / v1.13.0 / v1.19.0) ============
     // v1.13.0: 过期判定与 recalling 状态标记已统一迁移到服务端 memory_status 字段，
     // 下方两个工具方法直接调用服务端接口，不再依赖任何本地元数据。
+    // v1.19.0: recently_memory 纳入过期回忆流程，与 agent_memory 行为完全一致。
     /**
      * 处理 memory_recurrence 工具调用。
-     * 主流程：调用服务端 list_expired_memories 拉取已过期 recently_memory ->
+     * 主流程：调用服务端 list_expired_memories 拉取已过期的 recently_memory / agent_memory ->
      * 按过期时间排序（最早优先）-> 取前 limit 条 ->
      * 仅标记这 limit 条为「回忆中」状态 -> 返回这些记忆及剩余数量。
      */
     async handleMemoryRecurrence(args) {
         // v1.13.0: 过期判定与 recalling 状态全部由服务端管理
+        // v1.19.0: recently_memory 同样纳入过期回忆流程
         const limit = Math.max(1, args?.limit ?? 10);
         const expiredMemories = await this.memoryStore.listExpiredRecentlyMemories();
         if (expiredMemories.length === 0) {
@@ -1122,7 +1413,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 以减少上下文占用）
@@ -1131,7 +1422,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,
@@ -1145,10 +1435,10 @@ export class McpServer {
             totalExpired: expiredMemories.length,
             message: remaining > 0
                 ? `本次处理 ${batch.length} 条即将遗忘的记忆（最早过期优先），剩余 ${remaining} 条待处理。\n` +
-                    `请审查后决定（archive_recently_memory 归档 / update_memory 续期），\n` +
+                    `请审查后决定（update_memory 续期，TTL ×2 / 不处理），\n` +
                     `完成后调用 memory_recurrence_complete 清理，再调 memory_recurrence 处理下一批。`
                 : `已处理全部 ${batch.length} 条即将遗忘的记忆。\n` +
-                    `请审查后决定（archive_recently_memory 归档 / update_memory 续期），\n` +
+                    `请审查后决定（update_memory 续期，TTL ×2 / 不处理），\n` +
                     `完成后调用 memory_recurrence_complete 清理。`,
         };
     }
@@ -1163,7 +1453,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;
@@ -1175,104 +1465,6 @@ export class McpServer {
                 : `已清理 ${deletedCount} 条已过期近期记忆。`,
         };
     }
-    // ============ 短期记忆 TODO 完成工具处理 (v1.14.0) ============
-    /**
-     * 标记 task_list 短期记忆为已完成。
-     * 主流程：调用 memoryStore.todoCompleted(uri) -> 标记完成 -> 检查全部完成 -> 自动清理 -> 返回结果。
-     */
-    async handleTodoCompleted(args) {
-        const result = await this.memoryStore.todoCompleted(args.uri);
-        await this.reportCombinedMemoryStats();
-        const allCleanedMsg = result.allCleaned
-            ? `所有 TODO 均已完成，已自动清理 ${result.cleanedCount} 条已完成短期记忆。`
-            : "已标记为已完成。";
-        return {
-            ...result,
-            message: allCleanedMsg,
-        };
-    }
-    // ============ 上下文压缩工具处理 (v1.8.0) ============
-    /**
-     * 获取当前会话的上下文统计。
-     * 主流程：从 profile 获取模型名称 -> 通过模型名查找上下文窗口 -> 调用 ContextManager 获取统计 -> 返回。
-     */
-    async handleGetContextStats(args) {
-        const profile = await this.agentClient.getProfile().catch(() => null);
-        const sessionId = args.sessionId ?? profile?.runtimeSessionId ?? "default";
-        const modelName = profile?.prompt ? this.guessModelName(profile) : "unknown";
-        const modelInfo = {
-            provider: modelName.split("/")[0] || "unknown",
-            model: modelName,
-            contextLimit: 0, // ContextManager 内部会通过 lookupModelLimits 查找
-        };
-        const stats = await this.contextManager.getStats(sessionId, modelInfo);
-        // 如果 contextLimit 仍为 0，用查找表的默认值
-        if (stats.contextLimit === 0) {
-            const limits = this.contextManager.lookupModelLimits(modelName);
-            return { ...stats, contextLimit: limits.contextLimit, remaining: limits.contextLimit - stats.totalUsed, usagePercent: Math.round((stats.totalUsed / limits.contextLimit) * 100) };
-        }
-        return stats;
-    }
-    /**
-     * 从 profile 猜测当前使用的模型名称。
-     * 主流程：读取 prompt 中的模型信息 -> 回退到 runtimeCliCommand 中的提示 -> 最终回退到环境变量或默认值。
-     */
-    guessModelName(profile) {
-        // 尝试从 prompt 中提取模型名（prompt 可能包含 @model 标记）
-        const promptMatch = profile.prompt?.match(/@model\s+(\S+)/i);
-        if (promptMatch?.[1])
-            return promptMatch[1];
-        // 回退到 CLI 命令中的线索
-        if (profile.runtimeMode)
-            return profile.runtimeMode;
-        // 默认值
-        return process.env.AWS_DEFAULT_MODEL || "gpt-4o";
-    }
-    /**
-     * 处理上下文压缩请求。
-     * 主流程：解析策略 -> 获取消息历史 -> 执行压缩 -> 保存结果 -> 返回。
-     */
-    async handleCompactContext(args) {
-        const profile = await this.agentClient.getProfile().catch(() => null);
-        const sessionId = profile?.runtimeSessionId ?? "default";
-        const strategy = args.strategy ?? "auto";
-        const keepLastTurns = args.keepLastTurns ?? 3;
-        // 获取消息历史
-        const messages = await this.fetchRecentMessages();
-        switch (strategy) {
-            case "prune": {
-                const result = this.contextManager.prune(messages, keepLastTurns);
-                await this.contextManager.saveCompactionResult(sessionId, result);
-                return result;
-            }
-            case "summarize": {
-                // summarize 需要 Agent 自己调用 LLM 来完成
-                // 这里先执行 prune 释放部分空间，然后返回需要 Agent 进行 summarize
-                const pruneResult = this.contextManager.prune(messages, keepLastTurns);
-                await this.contextManager.saveCompactionResult(sessionId, pruneResult);
-                return {
-                    ...pruneResult,
-                    strategy: "summarize",
-                    summary: await this.contextManager.getCompactionSummary(sessionId) ?? undefined,
-                };
-            }
-            case "auto":
-            default: {
-                // 先尝试 prune
-                const pruneResult = this.contextManager.prune(messages, keepLastTurns);
-                if (pruneResult.freedTokens >= 20_000) {
-                    await this.contextManager.saveCompactionResult(sessionId, pruneResult);
-                    return pruneResult;
-                }
-                // prune 释放不够，回退到 summarize
-                return {
-                    ...pruneResult,
-                    strategy: "summarize",
-                    summary: await this.contextManager.getCompactionSummary(sessionId) ?? undefined,
-                };
-            }
-        }
-    }
     /**
      * 获取最近的消息历史用于压缩。
      * 主流程：获取未读消息 + 历史消息 -> 合并排序 -> 返回。
@@ -1382,70 +1574,122 @@ 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 () => {
+            return await this.doPollMessage();
+        })();
+        try {
+            return await this.pendingPollMessage;
+        }
+        finally {
+            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,
         });
-        // poll_message 永不超时返回空：while(true) 内部每 30s 轮询一次
-        // WebSocket 消息（主动通知）→ 实时响应
-        // Memory 状态变化（无法主动通知）→ 最长 30s 延迟
-        while (true) {
-            // 1. 检查 WebSocket 缓冲区（来自 push + 后台补拉）
-            const buffered = this.messageBuffer.get();
-            if (buffered.directMessages.length > 0 || buffered.groupMessages.length > 0) {
-                return await this.finalizeWithMemoryNotifications(buffered);
-            }
-            // 2. 检查 Memory 通知（缓冲区无消息时直接返回）
-            if (!this.memoryFileCheckInterval) {
-                const fileChange = await this.buildMemoryFileChangeNotification();
-                if (fileChange) {
-                    return this.buildPollResult({ directMessages: [fileChange], groupMessages: [] });
-                }
+        // 紧急类检查：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);
             }
-            const recurrence = await this.getCachedMemoryNotification('recurrence', () => this.buildMemoryRecurrenceNotification());
-            if (recurrence) {
-                return this.buildPollResult({ directMessages: [recurrence], groupMessages: [] });
+            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 this.buildPollResult(polled);
             }
-            const todo = await this.getCachedMemoryNotification('todo', () => this.buildMemoryTodoNotification());
-            if (todo) {
-                return this.buildPollResult({ directMessages: [todo], groupMessages: [] });
+            // 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);
             }
-            const cleanup = await this.getCachedMemoryNotification('cleanup', () => this.buildMemoryCleanupNotification());
-            if (cleanup) {
-                return this.buildPollResult({ directMessages: [cleanup], groupMessages: [] });
+            // 紧急类：无消息/task 但有 todo，返回 todo
+            if (todoNotifLoop) {
+                return this.buildPollResult({ directMessages: [todoNotifLoop], groupMessages: [] });
             }
-            // 3. 带超时等 WebSocket 消息（内部轮询周期）
-            // poll() 一旦返回就已消费 buffer，不可 `continue` 回 get()（空）
-            const polled = await this.messageBuffer.poll(POLL_MESSAGE_INTERNAL_POLL_INTERVAL_MS);
-            if (polled.directMessages.length > 0 || polled.groupMessages.length > 0) {
-                return await this.finalizeWithMemoryNotifications(polled);
+            // 非紧急类：无紧急类时，检查所有非紧急项
+            const nonUrgent = await this.checkAllLocalNonUrgentNotifications();
+            if (nonUrgent.length > 0) {
+                return this.buildPollResult({ directMessages: nonUrgent, groupMessages: [] });
             }
-            // 超时 → 继续循环，重新检查 Memory 和缓冲区
         }
     }
     /**
-     * 后检 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);
-        }
-        if (await this.prependMemoryNotification(messages, () => this.getCachedMemoryNotification('todo', () => this.buildMemoryTodoNotification()))) {
-            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) {
+    buildPollResult(messages, fromBuffer = true) {
         return {
             directMessages: messages.directMessages,
             groupMessages: messages.groupMessages,
-            fromBuffer: true,
+            fromBuffer,
+            systemMessages: [],
         };
     }
     /**
@@ -1495,8 +1739,8 @@ export class McpServer {
             const cleanupActions = [
                 "请调用 get_memory_stats 查看容量详情",
                 "调用 list_memories 按类型查看超限记忆",
-                "删除不再需要的 task_list",
-                "删除或 archive_recently_memory 归档 recently_memory 为长期 memory",
+                "删除不再需要的 recently_memory",
+                "更新 agent_memory 续期（TTL ×2）或删除过期项",
             ].join("；");
             return {
                 msgId: `memory-cleanup-${Date.now()}`,
@@ -1507,22 +1751,27 @@ 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;
         }
     }
     /**
      * 构建近期记忆过期回忆通知（有即将遗忘的记忆需要整理）。
-     * Memory 近期记忆过期 (v1.11.0) / v1.13.0 改用服务端 memory_status 字段
+     * Memory 近期记忆过期 (v1.11.0) / v1.13.0 改用服务端 memory_status 字段 / v1.19.0 扩展
      *
      * 通知策略（基于服务端 memory_status）：
-     * 1. 有过期 recently_memory 且 memory_status='recalling'（回忆中但未完成疏理）：
+     * 1. 有过期 recently_memory / agent_memory 且 memory_status='recalling'（回忆中但未完成疏理）：
      *    通知 "存在待疏理的即将遗忘记忆，请通过 memory_recurrence 获取进行整理"
-     * 2. 有过期 recently_memory 且 memory_status='normal'（尚未开始回忆）：
+     * 2. 有过期 recently_memory / agent_memory 且 memory_status='normal'（尚未开始回忆）：
      *    通知 "有即将遗忘记忆得整理，请通过 memory_recurrence 进行回忆"
+     * v1.19.0: recently_memory 纳入过期回忆流程，与 agent_memory 一并处理。
      */
     async buildMemoryRecurrenceNotification() {
         try {
@@ -1533,7 +1782,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) {
@@ -1547,6 +1796,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: 有待回忆的过期记忆
@@ -1561,12 +1814,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;
         }
     }
@@ -1575,24 +1832,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('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) {
@@ -1600,10 +1871,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: 'memory',
-                                update_status: 'updating',
+                                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,
@@ -1624,12 +1896,17 @@ 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
                     .slice(0, 5)
                     .map(m => `- ${m.uri} (文件: ${m.bound_files?.join(', ') || '未知'})`)
                     .join('\n');
+                logger.info(`[McpServer] 文件变更检测 Step1: ${updatingMemories.length} 个 updating memory 待更新，租约已续期`);
                 return {
                     msgId: `memory-update-pending-${Date.now()}`,
                     senderId: "MCP-System",
@@ -1639,14 +1916,22 @@ export class McpServer {
                     requireReply: false,
                     prompt: "这是一条更新提醒，您之前已标记这些记忆为更新中，请继续处理。",
                     timestamp: new Date().toISOString(),
+                    _acodeAutoDelegate: {
+                        type: 'memory_file_change',
+                        uris: updatingMemories.slice(0, 5).map(m => m.uri),
+                    },
                 };
             }
             // 步骤2: 检查短期记忆和近期记忆（服务端存储）
-            const recentlyMemories = await this.memoryStore.listByType('recently_memory');
-            const taskListMemories = await this.memoryStore.listByType('task_list');
-            const listableMemories = [...recentlyMemories, ...taskListMemories];
+            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);
@@ -1656,17 +1941,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;
@@ -1687,52 +1975,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: '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)
@@ -1747,25 +2147,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,
@@ -1791,9 +2213,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));
@@ -1817,28 +2250,22 @@ export class McpServer {
         return `${memoryId}:${sorted.map(([k, v]) => `${k}=${v}`).join('|')}`;
     }
     async handleGetMessage() {
-        await this.hydrateUnreadMessagesIfNeeded();
+        // 消息来源标记：
+        // - buffer 在 hydrate 前已有消息 → fromBuffer=true（来自本地 buffer）
+        // - buffer 空、hydrate 从服务端拉到消息 → fromBuffer=false（来自服务端）
+        // - buffer 空、hydrate 也无消息（仅有 Memory 通知注入）→ fromBuffer=true（本地注入）
+        const hadBufferedMessages = this.messageBuffer.size() > 0;
+        await this.hydrateUnreadMessagesFromServer();
         const messages = this.messageBuffer.get();
+        const hasRealMessages = messages.directMessages.length > 0 || messages.groupMessages.length > 0;
+        const fromBuffer = hadBufferedMessages || !hasRealMessages;
         if (await this.prependMemoryNotification(messages, () => this.buildMemoryRecurrenceNotification())) {
-            return this.buildPollResult(messages);
-        }
-        if (await this.prependMemoryNotification(messages, () => this.buildMemoryTodoNotification())) {
-            return this.buildPollResult(messages);
+            return this.buildPollResult(messages, fromBuffer);
         }
         if (await this.prependMemoryNotification(messages, () => this.buildMemoryCleanupNotification())) {
-            return this.buildPollResult(messages);
+            return this.buildPollResult(messages, fromBuffer);
         }
-        return this.buildPollResult(messages);
-    }
-    /**
-     * 在本地缓冲区为空时，从服务端补拉离线期间积累的未读消息。
-     * 这样 Agent 重启或重连后，poll_message/get_message 仍能取到持久化未读消息。
-     */
-    async hydrateUnreadMessagesIfNeeded(options = {}) {
-        if (this.messageBuffer.size() > 0) {
-            return true;
-        }
-        return await this.hydrateUnreadMessagesFromServer(options);
+        return this.buildPollResult(messages, fromBuffer);
     }
     /**
      * 从服务端补拉未读消息并写入本地缓冲。
@@ -1867,7 +2294,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;
         }
     }
@@ -1940,6 +2367,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) || "(无内容)"}`);
@@ -2009,6 +2442,73 @@ export class McpServer {
         }
         return maybeAgentClient.getState().agentId ?? null;
     }
+    /**
+     * 将 agentId 安全化为文件名片段：仅保留字母数字下划线短横，其余替换为下划线。
+     * 与 acode 包 TodoStore.filePath 的路径安全化逻辑保持一致。
+     */
+    sanitizeAgentIdForTodoFile(agentId) {
+        return String(agentId).replace(/[^a-zA-Z0-9_-]/g, "_");
+    }
+    /**
+     * 构建 Todo 未完成项提醒通知。
+     *
+     * 触发条件（全部满足）：
+     *   1. 当前 agentId 可读取
+     *   2. ~/.acode/todos/{agentId}.json 存在且可解析
+     *   3. 存在 status !== "completed" 的未完成项
+     *
+     * 行为：
+     *   - 有未完成项：构造轻量系统通知并返回（不持久化）。
+     *   - 全部完成 / 无文件 / 异常：静默返回 null，不阻断 poll_message。
+     *
+     * 通知以 DirectMessage 形式注入，senderId="MCP-System"，不落库、不持久化。
+     * 提示内容简洁，仅提醒有未完成待办，Agent 如需查看详情应调用 todo_read。
+     */
+    async buildTodoReminderNotification() {
+        try {
+            const agentId = this.getCurrentAgentId();
+            if (!agentId)
+                return null;
+            const todoPath = path.join(os.homedir(), ".acode", "todos", `${this.sanitizeAgentIdForTodoFile(agentId)}.json`);
+            let raw;
+            try {
+                raw = await fs.promises.readFile(todoPath, "utf-8");
+            }
+            catch (error) {
+                // 文件不存在视为无 todo，不通知
+                if (error?.code === "ENOENT")
+                    return null;
+                throw error;
+            }
+            const doc = JSON.parse(raw);
+            const todos = Array.isArray(doc.todos)
+                ? doc.todos
+                : [];
+            const incomplete = todos.filter((t) => t &&
+                typeof t === "object" &&
+                typeof t.content === "string" &&
+                (t.status === "pending" ||
+                    t.status === "in_progress" ||
+                    t.status === "cancelled"));
+            if (incomplete.length === 0) {
+                return null;
+            }
+            return {
+                msgId: `todo-reminder-${Date.now()}`,
+                senderId: "MCP-System",
+                senderName: "系统",
+                receiverId: agentId,
+                content: `Todo 列表存在 ${incomplete.length} 项未完成，请调用 todo_read 查看并处理。`,
+                requireReply: false,
+                prompt: "这是一条 Todo 未完成项提醒，自动生成，无需持久化。请评估是否需要继续处理未完成的 Todo，可调用 todo_read 获取完整列表。",
+                timestamp: new Date().toISOString(),
+            };
+        }
+        catch (error) {
+            logger.warn('[McpServer] 构建 Todo 提醒失败: %s', error instanceof Error ? error.message : String(error));
+            return null;
+        }
+    }
     // ============ 生命周期 ============
     async start() {
         const transport = new StdioServerTransport();
@@ -2024,90 +2524,70 @@ 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");
     }
     /**
-     * 构建短期记忆 TODO 通知。
-     * 主流程：调用服务端 list_by_todo_status({ todo_status: 'pending' }) 获取 pending 待办 -> 注入提醒。
-     * v1.13.0: 由服务端 memory_status 字段管理 todo 状态，TS 侧不再维护本地缓存。
+     * 停止租约续期定时器 (v1.21.0)。
      */
-    async buildMemoryTodoNotification() {
-        try {
-            const pendingTodos = await this.memoryStore.listByTodoStatus('pending');
-            if (pendingTodos.length === 0)
-                return null;
-            const agentId = this.getCurrentAgentId();
-            if (!agentId)
-                return null;
-            const pendingCount = pendingTodos.length;
-            const pendingList = pendingTodos.slice(0, 5).map(m => `- ${m.uri}`).join('\n');
-            return {
-                msgId: `memory-todo-${Date.now()}`,
-                senderId: "MCP-System",
-                senderName: "系统",
-                receiverId: agentId,
-                content: `当前有 ${pendingCount} 个 todo 项未完成，请获取短期记忆(todo 列表)，且已经完成请使用 todo_completed 标注为已完成状态。\n\n待办项：\n${pendingList}${pendingCount > 5 ? `\n  ...及其他 ${pendingCount - 5} 条` : ''}`,
-                requireReply: false,
-                prompt: "这是一条短期记忆 TODO 提醒，请调用 list_memories({ memory_type: 'task_list' }) 查看待办列表，完成后通过 todo_completed({ uri }) 标注为已完成状态。",
-                timestamp: new Date().toISOString(),
-            };
-        }
-        catch (error) {
-            logger.warn("[McpServer] 构建短期记忆 TODO 提醒失败:", error);
-            return null;
+    stopLeaseRenewal() {
+        if (this.leaseRenewalTimer) {
+            clearInterval(this.leaseRenewalTimer);
+            this.leaseRenewalTimer = null;
+            logger.info("[McpServer] 租约续期定时器已停止");
         }
     }
     /**
-     * 停止后台 Memory 文件变更检测定时器。
+     * 停止 McpServer，清理后台定时器。
+     * 主流程：停止租约续期 -> 释放所有 claim -> 停止 Agent 客户端消息循环。
      */
-    stopMemoryFileWatcher() {
-        if (this.memoryFileCheckInterval) {
-            clearInterval(this.memoryFileCheckInterval);
-            this.memoryFileCheckInterval = null;
-            logger.info("[McpServer] 后台文件变更检测已停止");
+    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 字段管理 task_list todo 状态与 recently_memory 过期/回忆状态，
-    // 下方 4 个工具直接调用服务端接口，本地不再维护元数据缓存。
-    // buildMemoryRecurrenceNotification / buildMemoryTodoNotification / handleMemoryRecurrence / handleMemoryRecurrenceComplete
-    // 已在文件其他位置实现（直接使用 this.memoryStore.listExpiredRecentlyMemories / listByTodoStatus / markExpiredMemoriesRecalling / clearRecallingExpiredMemories）。
+    // v1.13.0 改用服务端 memory_status 字段管理 agent_memory 过期/回忆状态，
+    // 下方工具直接调用服务端接口，本地不再维护元数据缓存。
+    // buildMemoryRecurrenceNotification / handleMemoryRecurrence / handleMemoryRecurrenceComplete
+    // 已在文件其他位置实现（直接使用 this.memoryStore.listExpiredRecentlyMemories / markExpiredMemoriesRecalling / clearRecallingExpiredMemories）。
     async autoRegister() {
         const agentConfig = this.agentClient.getAgentConfig();
         logger.info(`[McpServer] 角色: "${agentConfig.roleName}"`);
@@ -2128,11 +2608,10 @@ export class McpServer {
                     statusReporter.reportWaitingInput();
                 }
                 await this.reportCombinedMemoryStats();
-                // 如果是新创建的角色，将本地永久记忆同步到服务端
-                if (result.isExisting === false) {
-                    logger.info("[McpServer] 新角色创建，同步本地永久记忆到服务端...");
-                    await this.syncLocalPermanentMemoryToServer();
-                }
+                // 注册成功后检查是否需要从本地恢复永久记忆到 server
+                // 触发条件：server 当前角色 memory 计数为 0（重部署后 DB 为空）
+                // 不依赖 isExisting / profileHandler，确保所有场景都能触发
+                this.maybeSyncPermanentMemoryToServer();
                 return;
             }
             catch (error) {
@@ -2171,7 +2650,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)');
         });
     }
     /**
@@ -2179,28 +2658,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);
-                },
+                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);
-            },
+            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) {