aws-runtime-bridge 1.9.58 → 1.9.61

package/package/acode/dist/sub-agent-manager.js

@@ -14,13 +14,37 @@ const SUBAGENT_PENDING_ZOMBIE_MS = 2 * 60 * 1000;
  * 正常 LLM 子任务即便较长也应有上界；卡死多因 runtime.start()/submit() 挂起
  * （如复用的父 MCP 连接异常、模型调用无响应），需回收以释放资源并解除锁。
  *
- * ★ 曾为 30min，但实际现象：子 agent 卡死时前端 modal 长时间显示"运行中 + 0消息 + 0tokens"，
- *   且 pendingMemorySubAgents URI 锁会持续抑制该 memory 的重新委托，加上 10min 冷却
- *   总卡顿可达 30~45min。缩到 5min：自动 memory 委托是后台任务，5min 足够覆盖
- *   正常 LLM 子任务（通常 30s~2min），更长时间无终态基本可判定为卡死。
- *   task 工具显式调用的 sub-agent 不走此自动路径，不受影响。
+ * ★ 设为 12min（> SUBAGENT_SUBMIT_TIMEOUT_MS=10min）：
+ *   - 子 agent 卡死时，submit() 10min 超时会先触发，给出明确的错误信息
+ *     （如 "runtime.submit() turn=1 timed out after 600000ms"）
+ *   - zombie 兜底覆盖 submit 内部无超时保护的步骤（如 hookBus.dispatch）
+ *   - 之前 5min 比 submit 10min 更早触发，导致用户永远看不到真正的 submit 超时错误
+ *   - task 工具显式调用的 sub-agent 不走此自动路径，不受影响
  */
-const SUBAGENT_RUNNING_ZOMBIE_MS = 5 * 60 * 1000;
+const SUBAGENT_RUNNING_ZOMBIE_MS = 12 * 60 * 1000;
+/**
+ * store 写入超时兜底（毫秒）。
+ * SubAgentStore.write 使用 writeChain 串行化所有文件写入，若前一个 write 卡住
+ * （磁盘 IO 慢、tmp 文件 rename 卡住、文件系统问题等），后续所有 write 都会
+ * 被永久阻塞，导致 sub-agent 卡在 store.updateStatus 处无法继续 start()。
+ * 5s 超时足够覆盖正常文件 IO（通常 < 100ms），超时后放弃落盘（不影响内存态）。
+ *
+ * ★ 仅用于 running 态写入（非阻塞路径不需要超时）。
+ *   终态写入走 persistFinalStatus 的指数退避重试，不再使用 withTimeout。
+ */
+const STORE_WRITE_TIMEOUT_MS = 5_000;
+/**
+ * 终态落盘的指数退避序列（毫秒）。
+ *
+ * 终态写入失败时按此序列重试，覆盖以下瞬时错误场景：
+ *   - Windows fs.rename EPERM（reader 持有 fd，退避后释放即可成功）
+ *   - writeChain 临时拥堵（前一个 write 慢，退避后队列消化）
+ *   - 磁盘瞬时不可用
+ *
+ * 总耗时 ≈ 100+500+2000+8000 = 10.6s，远大于 EPERM 退避窗口和 writeChain 排队时长，
+ * 同时不至过长影响 bridge 关闭时的 dispose 流程。
+ */
+const PERSIST_BACKOFF_MS = [100, 500, 2_000, 8_000];
 /**
  * 子 agent runtime.start() 整体超时兜底（毫秒）。
  * start() 内部正常路径秒级完成（loadSkills/resolveProvider/filterMcp/fetchProfile/emitStatus），
@@ -78,6 +102,16 @@ export class SubAgentManager {
          * null 表示当前没有等待者。
          */
         this.completionWaiterResolve = null;
+        /**
+         * 正在执行的异步终态落盘 Promise 集合。
+         *
+         * 用于：
+         *   - 测试等待异步落盘完成后再读取 store 验证状态
+         *   - dispose 时确保所有落盘完成后再清理（避免文件句柄占用导致目录非空）
+         *
+         * persistFinalStatus 启动时入集，resolve/reject 后出集。
+         */
+        this.pendingPersists = new Set();
         this.store = opts.store;
         this.maxConcurrent = opts.maxConcurrent ?? 5;
         // 启动定期清理已完成 entry 的定时器（每 5 分钟扫一次）
@@ -112,6 +146,10 @@ export class SubAgentManager {
             initialPrompt: undefined,
             // sub-agent 不允许再 spawn 自己的子 agent（禁止递归嵌套）
             subAgentManager: undefined,
+            // ★ 注入 subagentType：runtime.start() 据此过滤内建写入工具。
+            //   explore 类型仅暴露只读工具（read_file/grep/symbols 等），
+            //   防止 explore 子 agent 改写主工作区文件，违背只读语义。
+            subagentType: opts.subagentType,
             // Sub Agent 模型/强度覆盖：有值则覆盖继承的 model/effort
             ...(opts.parentConfig.subAgentModel
                 ? { model: opts.parentConfig.subAgentModel }
@@ -334,10 +372,24 @@ export class SubAgentManager {
             }
         };
         entry.runtime.on("event", onEvent);
-        // 状态 -> running
+        // ★ 状态 -> running：先同步设置 + emit + currentTool 标记，再异步落盘。
+        //   之前顺序是 status=running → await store.updateStatus → emit running，
+        //   若 store.updateStatus 因 writeChain 串行化卡住（前一个 write 卡死），
+        //   emit running 不会执行，start() 也不会被调用，前端 modal 永远显示
+        //   初始 snapshot（0消息 0tokens 当前工具-），与"从未运行"无法区分。
+        //   调整顺序后即使落盘卡住，前端也能立即看到 [starting] 标记。
         entry.status = "running";
-        await this.store.updateStatus(entry.parentAgentId, entry.subId, { status: "running" });
-        this.emitEvent(entry.subId, "running", {});
+        entry.contextSnapshot.currentTool = "[starting]";
+        entry.contextSnapshot.updatedAt = new Date().toISOString();
+        this.emitEvent(entry.subId, "running", { snapshot: { ...entry.contextSnapshot } });
+        // 落盘带超时保护：writeChain 串行化可能卡住，超时后放弃落盘（不影响内存态）
+        try {
+            await withTimeout(this.store.updateStatus(entry.parentAgentId, entry.subId, { status: "running" }), STORE_WRITE_TIMEOUT_MS, `sub-agent ${entry.subId} store.updateStatus(running)`);
+        }
+        catch (err) {
+            console.error(`[SubAgentManager] store.updateStatus(running) failed for subId=${entry.subId}: ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
         try {
             await entry.runtime.start();
             // 记录启动后的可用工具列表
@@ -353,16 +405,26 @@ export class SubAgentManager {
             entry.result = output;
             entry.endedAt = Date.now();
             entry.durationMs = entry.endedAt - entry.startedAt;
-            await this.store.updateStatus(entry.parentAgentId, entry.subId, {
+            // ★ emit 前置：先把 completed 事件发出，让前端 modal 立即看到状态变化
+            //   （subscribers 同步执行，SSE 路由立即推送）。
+            this.emitEvent(entry.subId, "completed", { result: output });
+            // ★ 终态落盘改为非阻塞：内存已置 completed，立即 settle completionPromise
+            //   + 入队通知，磁盘写入走 persistFinalStatus 的指数退避重试，不阻塞主流程。
+            //   即使落盘最终失败，前端看到的仍是真实 completed 状态（内存态是真相源），
+            //   不会触发列表接口的 "status mismatch" 兜底（兜底逻辑已移除）。
+            entry.completionResolve?.({ output });
+            this.enqueueCompletion(entry, output, undefined);
+            void this.persistFinalStatus(entry, {
                 status: "completed",
                 result: output,
                 endedAt: entry.endedAt,
                 durationMs: entry.durationMs,
+                // ★ 持久化 availableTools：start() 后才填充，必须随终态落盘，
+                //   否则 entry 从内存清理后 store 永远是 spawn 时的空数组，
+                //   前端 modal "可用工具" tab 始终显示"暂无工具信息"。
+                availableTools: entry.availableTools,
                 contextSnapshot: undefined, // 完成后清空快照
             });
-            this.emitEvent(entry.subId, "completed", { result: output });
-            entry.completionResolve?.({ output });
-            this.enqueueCompletion(entry, output, undefined);
         }
         catch (err) {
             const errorMessage = err instanceof Error ? err.message : String(err);
@@ -370,16 +432,18 @@ export class SubAgentManager {
             entry.errorMessage = errorMessage;
             entry.endedAt = Date.now();
             entry.durationMs = entry.endedAt - entry.startedAt;
-            await this.store.updateStatus(entry.parentAgentId, entry.subId, {
+            // ★ emit 前置 + 终态非阻塞落盘（同 completed 路径的设计理由）
+            this.emitEvent(entry.subId, "failed", { error: errorMessage });
+            entry.completionResolve?.({ output: "", error: errorMessage });
+            this.enqueueCompletion(entry, "", errorMessage);
+            void this.persistFinalStatus(entry, {
                 status: "failed",
                 errorMessage,
                 endedAt: entry.endedAt,
                 durationMs: entry.durationMs,
+                availableTools: entry.availableTools,
                 contextSnapshot: undefined,
             });
-            this.emitEvent(entry.subId, "failed", { error: errorMessage });
-            entry.completionResolve?.({ output: "", error: errorMessage });
-            this.enqueueCompletion(entry, "", errorMessage);
         }
         finally {
             // 移除临时监听器
@@ -436,10 +500,24 @@ export class SubAgentManager {
             }
         };
         entry.runtime.on("event", onEvent);
-        // 状态 -> running
+        // ★ 状态 -> running：先同步设置 + emit + currentTool 标记，再异步落盘。
+        //   之前顺序是 status=running → await store.updateStatus → emit running，
+        //   若 store.updateStatus 因 writeChain 串行化卡住（前一个 write 卡死），
+        //   emit running 不会执行，start() 也不会被调用，前端 modal 永远显示
+        //   初始 snapshot（0消息 0tokens 当前工具-），与"从未运行"无法区分。
+        //   调整顺序后即使落盘卡住，前端也能立即看到 [starting] 标记。
         entry.status = "running";
-        await this.store.updateStatus(entry.parentAgentId, entry.subId, { status: "running" });
-        this.emitEvent(entry.subId, "running", {});
+        entry.contextSnapshot.currentTool = "[starting]";
+        entry.contextSnapshot.updatedAt = new Date().toISOString();
+        this.emitEvent(entry.subId, "running", { snapshot: { ...entry.contextSnapshot } });
+        // 落盘带超时保护：writeChain 串行化可能卡住，超时后放弃落盘（不影响内存态）
+        try {
+            await withTimeout(this.store.updateStatus(entry.parentAgentId, entry.subId, { status: "running" }), STORE_WRITE_TIMEOUT_MS, `sub-agent ${entry.subId} store.updateStatus(running)`);
+        }
+        catch (err) {
+            console.error(`[SubAgentManager] store.updateStatus(running) failed for subId=${entry.subId}: ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
         try {
             // ★ 超时兜底：start() 通常秒级完成，超时说明卡在 hookBus/fetchProfile/loadCommands
             //   等无超时保护的步骤。抛错后被外层 catch 标记为 failed，前端可见。
@@ -498,16 +576,19 @@ export class SubAgentManager {
             entry.result = output;
             entry.endedAt = Date.now();
             entry.durationMs = entry.endedAt - entry.startedAt;
-            await this.store.updateStatus(entry.parentAgentId, entry.subId, {
+            // ★ emit 前置 + 终态非阻塞落盘 + 立即 settle completionPromise
+            //   （设计理由同 runEntryToCompletion：内存态是真相源，磁盘写入不阻塞主流程）
+            this.emitEvent(entry.subId, "completed", { result: output });
+            entry.completionResolve?.({ output });
+            this.enqueueCompletion(entry, output, undefined);
+            void this.persistFinalStatus(entry, {
                 status: "completed",
                 result: output,
                 endedAt: entry.endedAt,
                 durationMs: entry.durationMs,
+                availableTools: entry.availableTools,
                 contextSnapshot: undefined,
             });
-            this.emitEvent(entry.subId, "completed", { result: output });
-            entry.completionResolve?.({ output });
-            this.enqueueCompletion(entry, output, undefined);
         }
         catch (err) {
             const errorMessage = err instanceof Error ? err.message : String(err);
@@ -515,16 +596,18 @@ export class SubAgentManager {
             entry.errorMessage = errorMessage;
             entry.endedAt = Date.now();
             entry.durationMs = entry.endedAt - entry.startedAt;
-            await this.store.updateStatus(entry.parentAgentId, entry.subId, {
+            // ★ emit 前置 + 终态非阻塞落盘（同 completed 路径的设计理由）
+            this.emitEvent(entry.subId, "failed", { error: errorMessage });
+            entry.completionResolve?.({ output: "", error: errorMessage });
+            this.enqueueCompletion(entry, "", errorMessage);
+            void this.persistFinalStatus(entry, {
                 status: "failed",
                 errorMessage,
                 endedAt: entry.endedAt,
                 durationMs: entry.durationMs,
+                availableTools: entry.availableTools,
                 contextSnapshot: undefined,
             });
-            this.emitEvent(entry.subId, "failed", { error: errorMessage });
-            entry.completionResolve?.({ output: "", error: errorMessage });
-            this.enqueueCompletion(entry, "", errorMessage);
         }
         finally {
             // 移除临时监听器
@@ -580,16 +663,18 @@ export class SubAgentManager {
         entry.status = "cancelled";
         entry.endedAt = Date.now();
         entry.durationMs = entry.endedAt - entry.startedAt;
-        await this.store.updateStatus(entry.parentAgentId, subId, {
+        // ★ emit 前置 + 终态非阻塞落盘 + 立即 settle completionPromise
+        //   （设计理由同 completed 路径：内存态是真相源，磁盘写入不阻塞主流程）
+        this.emitEvent(subId, "cancelled", {});
+        entry.completionResolve?.({ output: "", error: "aborted" });
+        this.enqueueCompletion(entry, "", "aborted");
+        void this.persistFinalStatus(entry, {
             status: "cancelled",
             endedAt: entry.endedAt,
             durationMs: entry.durationMs,
+            availableTools: entry.availableTools,
             contextSnapshot: undefined,
         });
-        this.emitEvent(subId, "cancelled", {});
-        // settle completionPromise（cancelled 视为 error）
-        entry.completionResolve?.({ output: "", error: "aborted" });
-        this.enqueueCompletion(entry, "", "aborted");
     }
     /** 获取内存中的 entry */
     getSubAgent(subId) {
@@ -681,11 +766,66 @@ export class SubAgentManager {
         }
         const entries = Array.from(this.subAgents.values());
         await Promise.allSettled(entries.map((e) => this.abort(e.subId)));
+        // 等待所有异步终态落盘完成（abort 触发的 cancelled 落盘是异步的），
+        // 避免文件句柄占用导致测试 cleanup 时目录非空
+        await this.flushPendingPersists();
         this.subAgents.clear();
         this.parentToSubs.clear();
         this.subscribers.clear();
     }
     // ---------- 内部方法 ----------
+    /**
+     * 异步落盘终态记录（指数退避重试），不阻塞主流程。
+     *
+     * 设计要点：
+     *   - 内存态已是终态（completed/failed/cancelled），落盘只做历史归档
+     *   - 落盘失败不回滚内存态，前端看到的是真实终态
+     *   - 重试覆盖瞬时错误：Windows fs.rename EPERM、writeChain 拥堵、磁盘瞬时不可用
+     *   - 全部重试失败后仅打日志，下次 bridge 启动时 reconcileZombies 会清理残留
+     *
+     * 调用方约定：必须用 `void this.persistFinalStatus(...)` 触发，不 await。
+     * entry.completionResolve 与 enqueueCompletion 应在此调用之前完成，
+     * 保证主流程不被落盘 IO 阻塞。
+     *
+     * Promise 加入 pendingPersists 集合，供 flushPendingPersists / dispose 等待。
+     */
+    persistFinalStatus(entry, patch) {
+        const run = (async () => {
+            let lastErr;
+            for (let attempt = 0; attempt <= PERSIST_BACKOFF_MS.length; attempt++) {
+                try {
+                    await this.store.updateStatus(entry.parentAgentId, entry.subId, patch);
+                    return;
+                }
+                catch (err) {
+                    lastErr = err;
+                    if (attempt < PERSIST_BACKOFF_MS.length) {
+                        await new Promise((r) => setTimeout(r, PERSIST_BACKOFF_MS[attempt]));
+                    }
+                }
+            }
+            console.error(`[SubAgentManager] persistFinalStatus(${patch.status}) failed after ${PERSIST_BACKOFF_MS.length + 1} attempts ` +
+                `for subId=${entry.subId}: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`);
+        })();
+        // 入集供测试/dispose 等待
+        this.pendingPersists.add(run);
+        run.finally(() => this.pendingPersists.delete(run));
+        return run;
+    }
+    /**
+     * 等待所有正在执行的异步终态落盘完成。
+     *
+     * 主要用途：
+     *   - 测试在终态后读取 store 前调用，确保落盘已完成
+     *   - dispose 前调用，避免文件句柄占用导致目录清理失败
+     *
+     * 生产环境一般不需要调用——落盘失败不影响内存态正确性。
+     */
+    async flushPendingPersists() {
+        if (this.pendingPersists.size === 0)
+            return;
+        await Promise.allSettled(Array.from(this.pendingPersists));
+    }
     /**
      * 将子 agent 终态事件入队并通知等待者。
      * 主流程：构建通知对象 -> 入队 completionQueue -> 若有 waitForAnyCompletion 等待者则立即 resolve。
@@ -782,21 +922,20 @@ export class SubAgentManager {
         entry.errorMessage = errorMessage;
         entry.endedAt = Date.now();
         entry.durationMs = entry.endedAt - entry.startedAt;
-        try {
-            await this.store.updateStatus(entry.parentAgentId, entry.subId, {
-                status: "failed",
-                errorMessage,
-                endedAt: entry.endedAt,
-                durationMs: entry.durationMs,
-                contextSnapshot: undefined,
-            });
-        }
-        catch {
-            /* 落盘失败不影响内存态与事件通知 */
-        }
+        // ★ emit 前置 + 终态非阻塞落盘 + 立即 settle completionPromise
+        //   （与其他终态路径保持一致，zombie 回收路径若 writeChain 卡住，
+        //   也应保证 runtime 收到 failed 事件从而释放 pendingMemorySubAgents URI 锁）
         this.emitEvent(entry.subId, "failed", { error: errorMessage });
         entry.completionResolve?.({ output: "", error: errorMessage });
         this.enqueueCompletion(entry, "", errorMessage);
+        void this.persistFinalStatus(entry, {
+            status: "failed",
+            errorMessage,
+            endedAt: entry.endedAt,
+            durationMs: entry.durationMs,
+            availableTools: entry.availableTools,
+            contextSnapshot: undefined,
+        });
         try {
             await entry.runtime.stop();
         }

package/package/acode/dist/sub-agent-store.d.ts

@@ -1,12 +1,31 @@
 import type { SubAgentDocument, SubAgentEvent, SubAgentRecord } from "./sub-agent-types.js";
 /**
  * Sub Agent JSON 文件存储，按 agentId 隔离。
- * 文件路径：{homedir}/.acode/sub-agents/{agentId}.json
  *
- * 设计与 TodoStore 完全同构：
+ * 文件布局：
+ *   - 主记录文件：{homedir}/.acode/sub-agents/{agentId}.json
+ *       存放 SubAgentRecord[]（不含 events 字段，避免全量读写阻塞终态写入）
+ *   - 事件日志文件：{homedir}/.acode/sub-agents/{agentId}.{subId}.events.jsonl
+ *       每行一个 SubAgentEvent，append-only，O(1) 追加，不进主 writeChain
+ *
+ * 设计要点：
  *   - 不依赖 agent 工作目录，避免 workspacePath 错误时读取失败
  *   - sub-agent 跟随 agent（agentId），不跟随项目工作区
- *   - 写操作通过 Promise 链串行化，tmp + rename 原子替换
+ *   - 主记录写操作通过 Promise 链串行化，tmp + rename 原子替换
+ *     （rename 在 Windows 上目标被打开时会 EPERM，使用 renameWithRetry 退避重试，
+ *      重试仍失败时 fallback 到 copyFile + unlink，彻底规避 EPERM 持续场景）
+ *   - events 走独立文件，避免 tool_start/tool_end 高频落盘阻塞终态 updateStatus
+ *     （历史教训：events 与 updateStatus 共用 writeChain 时，memory delegate
+ *      一次跑数十个工具调用，appendEvent 排队导致 updateStatus 超 5s 超时，
+ *      内存已翻终态但 store 仍 running，触发 "status mismatch" 兜底误报）
+ *
+ * ★ 终态一致性架构（治本方案）：
+ *   - 内存态（SubAgentManager）是运行态的唯一真相源
+ *   - 终态写入通过 persistFinalStatus 异步重试落盘，不阻塞 completionResolve
+ *   - 落盘失败不回滚内存态，前端看到的是真实终态
+ *   - 列表接口不再做"磁盘 running/pending + 内存无 → 改写 failed"的兜底
+ *     （该兜底是 "status mismatch" 误报的直接来源，已移除）
+ *   - bridge 启动时 reconcileZombies 一次性清理上次进程残留的僵尸记录
  *
  * 历史保留策略：全部 sub-agent 记录都持久化（含 completed/failed/cancelled），
  *   按 startedAt 倒序排列。dashboard 按需分页读取。
@@ -15,8 +34,10 @@ export declare class SubAgentStore {
     private readonly dir;
     private writeChain;
     constructor();
-    /** 文件路径（按 agentId 隔离，防路径穿越） */
+    /** 主记录文件路径（按 agentId 隔离，防路径穿越） */
     private filePath;
+    /** 事件日志文件路径（按 agentId + subId 隔离，防路径穿越） */
+    private eventsFilePath;
     /** 读取该 agentId 的完整文档。文件不存在或损坏时返回空文档。 */
     read(agentId: string): Promise<SubAgentDocument>;
     /** 读取单个 sub-agent 记录 */
@@ -29,8 +50,26 @@ export declare class SubAgentStore {
     updateStatus(agentId: string, subId: string, patch: Partial<SubAgentRecord>): Promise<void>;
     /** 列出该 agent 的全部 sub-agent（已按 startedAt 倒序） */
     list(agentId: string): Promise<SubAgentRecord[]>;
-    /** 追加一条事件到指定 sub-agent 的 events 数组（用于 tool_start/tool_end 持久化） */
+    /**
+     * 追加一条事件到指定 sub-agent 的事件日志文件。
+     *
+     * 走独立 jsonl 文件（每行一个事件，append-only），不进主 writeChain：
+     *   - O(1) 追加，无需 read-modify-write 全量主文件
+     *   - 不阻塞终态 updateStatus（避免 status mismatch 兜底误报）
+     *   - 高频 tool_start/tool_end 落盘成本恒定，与历史记录数无关
+     *
+     * 失败时仅打日志（fire-and-forget 语义），不阻断 sub-agent 运行。
+     * 调用方（sub-agent-manager.emitEvent）已用 void + catch 包装。
+     */
     appendEvent(agentId: string, subId: string, event: SubAgentEvent): Promise<void>;
+    /**
+     * 读取指定 sub-agent 的全部历史事件（按时间顺序）。
+     *
+     * 优先读独立 jsonl 文件；不存在时回退到主记录文件中的 events 字段
+     * （向后兼容旧版本数据：旧版把 events 内嵌在 SubAgentRecord 中）。
+     * 供 SSE 路由在客户端重连时补发历史 tool 事件。
+     */
+    readEvents(agentId: string, subId: string): Promise<SubAgentEvent[]>;
     /**
      * 扫描所有 agent 文件，把 status="running"/"pending" 的记录修正为 "failed"。
      * 在 bridge 启动时调用，清理上次进程异常退出留下的僵尸记录。

package/package/acode/dist/sub-agent-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sub-agent-store.d.ts","sourceRoot":"","sources":["../src/sub-agent-store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE5F;;;;;;;;;;;GAWG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,UAAU,CAAoC;;IAMtD,+BAA+B;IAC/B,OAAO,CAAC,QAAQ;IAKhB,wCAAwC;IAClC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAoBtD,wBAAwB;IAClB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAKzE,oCAAoC;IAC9B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBxE,wBAAwB;IAClB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAWpE,eAAe;IACT,YAAY,CAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,OAAO,CAAC,cAAc,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC;IAQhB,+CAA+C;IACzC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAItD,kEAAkE;IAC5D,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAYtF;;;OAGG;IACG,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;CAmC1C"}
+{"version":3,"file":"sub-agent-store.d.ts","sourceRoot":"","sources":["../src/sub-agent-store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG5F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,UAAU,CAAoC;;IAMtD,kCAAkC;IAClC,OAAO,CAAC,QAAQ;IAKhB,2CAA2C;IAC3C,OAAO,CAAC,cAAc;IAMtB,wCAAwC;IAClC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAoBtD,wBAAwB;IAClB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAKzE,oCAAoC;IAC9B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBxE,wBAAwB;IAClB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAWpE,eAAe;IACT,YAAY,CAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,OAAO,CAAC,cAAc,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC;IAQhB,+CAA+C;IACzC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAItD;;;;;;;;;;OAUG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAOtF;;;;;;OAMG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAyB1E;;;OAGG;IACG,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;CAmC1C"}

package/package/acode/dist/sub-agent-store.js

@@ -1,14 +1,34 @@
 import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { renameWithRetry } from "./fs-utils.js";
 /**
  * Sub Agent JSON 文件存储，按 agentId 隔离。
- * 文件路径：{homedir}/.acode/sub-agents/{agentId}.json
  *
- * 设计与 TodoStore 完全同构：
+ * 文件布局：
+ *   - 主记录文件：{homedir}/.acode/sub-agents/{agentId}.json
+ *       存放 SubAgentRecord[]（不含 events 字段，避免全量读写阻塞终态写入）
+ *   - 事件日志文件：{homedir}/.acode/sub-agents/{agentId}.{subId}.events.jsonl
+ *       每行一个 SubAgentEvent，append-only，O(1) 追加，不进主 writeChain
+ *
+ * 设计要点：
  *   - 不依赖 agent 工作目录，避免 workspacePath 错误时读取失败
  *   - sub-agent 跟随 agent（agentId），不跟随项目工作区
- *   - 写操作通过 Promise 链串行化，tmp + rename 原子替换
+ *   - 主记录写操作通过 Promise 链串行化，tmp + rename 原子替换
+ *     （rename 在 Windows 上目标被打开时会 EPERM，使用 renameWithRetry 退避重试，
+ *      重试仍失败时 fallback 到 copyFile + unlink，彻底规避 EPERM 持续场景）
+ *   - events 走独立文件，避免 tool_start/tool_end 高频落盘阻塞终态 updateStatus
+ *     （历史教训：events 与 updateStatus 共用 writeChain 时，memory delegate
+ *      一次跑数十个工具调用，appendEvent 排队导致 updateStatus 超 5s 超时，
+ *      内存已翻终态但 store 仍 running，触发 "status mismatch" 兜底误报）
+ *
+ * ★ 终态一致性架构（治本方案）：
+ *   - 内存态（SubAgentManager）是运行态的唯一真相源
+ *   - 终态写入通过 persistFinalStatus 异步重试落盘，不阻塞 completionResolve
+ *   - 落盘失败不回滚内存态，前端看到的是真实终态
+ *   - 列表接口不再做"磁盘 running/pending + 内存无 → 改写 failed"的兜底
+ *     （该兜底是 "status mismatch" 误报的直接来源，已移除）
+ *   - bridge 启动时 reconcileZombies 一次性清理上次进程残留的僵尸记录
  *
  * 历史保留策略：全部 sub-agent 记录都持久化（含 completed/failed/cancelled），
  *   按 startedAt 倒序排列。dashboard 按需分页读取。
@@ -18,11 +38,17 @@ export class SubAgentStore {
         this.writeChain = Promise.resolve();
         this.dir = path.join(os.homedir(), ".acode", "sub-agents");
     }
-    /** 文件路径（按 agentId 隔离，防路径穿越） */
+    /** 主记录文件路径（按 agentId 隔离，防路径穿越） */
     filePath(agentId) {
         const safe = String(agentId).replace(/[^a-zA-Z0-9_-]/g, "_");
         return path.join(this.dir, `${safe}.json`);
     }
+    /** 事件日志文件路径（按 agentId + subId 隔离，防路径穿越） */
+    eventsFilePath(agentId, subId) {
+        const safeAgent = String(agentId).replace(/[^a-zA-Z0-9_-]/g, "_");
+        const safeSub = String(subId).replace(/[^a-zA-Z0-9_-]/g, "_");
+        return path.join(this.dir, `${safeAgent}.${safeSub}.events.jsonl`);
+    }
     /** 读取该 agentId 的完整文档。文件不存在或损坏时返回空文档。 */
     async read(agentId) {
         const empty = { agentId, updatedAt: "", subAgents: [] };
@@ -59,11 +85,19 @@ export class SubAgentStore {
             const doc = {
                 agentId,
                 updatedAt: new Date().toISOString(),
-                subAgents: subAgents.sort((a, b) => b.startedAt - a.startedAt),
+                // ★ 主记录文件不再存 events 字段（events 走独立 jsonl 文件）。
+                //   剥离 events 避免每次 appendEvent 都全量重写主文件，
+                //   也能显著减小主文件体积（events 是高频大字段）。
+                subAgents: subAgents
+                    .map(({ events: _events, ...rest }) => rest)
+                    .sort((a, b) => b.startedAt - a.startedAt),
             };
             const tmp = `${target}.tmp`;
             await fs.writeFile(tmp, JSON.stringify(doc, null, 2), "utf-8");
-            await fs.rename(tmp, target);
+            // ★ Windows 上 fs.rename 目标被 reader 打开时会 EPERM/EBUSY/EACCES，
+            //   瞬时错误，短退避后重试通常即可成功（reader 已释放 fd）。
+            //   POSIX 上 rename 原子，不会触发此类错误。
+            await renameWithRetry(tmp, target);
         });
         this.writeChain = run.catch(() => { });
         await run;
@@ -93,18 +127,56 @@ export class SubAgentStore {
     async list(agentId) {
         return (await this.read(agentId)).subAgents;
     }
-    /** 追加一条事件到指定 sub-agent 的 events 数组（用于 tool_start/tool_end 持久化） */
+    /**
+     * 追加一条事件到指定 sub-agent 的事件日志文件。
+     *
+     * 走独立 jsonl 文件（每行一个事件，append-only），不进主 writeChain：
+     *   - O(1) 追加，无需 read-modify-write 全量主文件
+     *   - 不阻塞终态 updateStatus（避免 status mismatch 兜底误报）
+     *   - 高频 tool_start/tool_end 落盘成本恒定，与历史记录数无关
+     *
+     * 失败时仅打日志（fire-and-forget 语义），不阻断 sub-agent 运行。
+     * 调用方（sub-agent-manager.emitEvent）已用 void + catch 包装。
+     */
     async appendEvent(agentId, subId, event) {
-        const doc = await this.read(agentId);
-        const idx = doc.subAgents.findIndex((r) => r.subId === subId);
-        if (idx < 0)
-            return;
-        const record = doc.subAgents[idx];
-        if (!Array.isArray(record.events)) {
-            record.events = [];
+        const target = this.eventsFilePath(agentId, subId);
+        await fs.mkdir(this.dir, { recursive: true });
+        // 每行一个 JSON 事件，以 \n 结尾，便于流式读取和解析
+        await fs.appendFile(target, JSON.stringify(event) + "\n", "utf-8");
+    }
+    /**
+     * 读取指定 sub-agent 的全部历史事件（按时间顺序）。
+     *
+     * 优先读独立 jsonl 文件；不存在时回退到主记录文件中的 events 字段
+     * （向后兼容旧版本数据：旧版把 events 内嵌在 SubAgentRecord 中）。
+     * 供 SSE 路由在客户端重连时补发历史 tool 事件。
+     */
+    async readEvents(agentId, subId) {
+        const jsonlPath = this.eventsFilePath(agentId, subId);
+        try {
+            const raw = await fs.readFile(jsonlPath, "utf-8");
+            const events = [];
+            for (const line of raw.split("\n")) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    events.push(JSON.parse(trimmed));
+                }
+                catch {
+                    /* 跳过损坏行 */
+                }
+            }
+            return events;
+        }
+        catch (err) {
+            if (err && err.code === "ENOENT") {
+                // jsonl 不存在：回退到主记录文件中的 events 字段（旧版本兼容）
+                const record = await this.get(agentId, subId);
+                return Array.isArray(record?.events) ? record.events : [];
+            }
+            throw err;
         }
-        record.events.push(event);
-        await this.write(agentId, doc.subAgents);
     }
     /**
      * 扫描所有 agent 文件，把 status="running"/"pending" 的记录修正为 "failed"。

package/package/acode/dist/todo-store.d.ts

@@ -27,6 +27,7 @@ export interface TodoDocument {
  * 并发安全：同一 TodoStore 实例的写操作通过 Promise 链串行化，
  * 避免同一 agentId 的并发 todo_write 互相覆盖。
  * 写入采用 tmp + rename 原子替换，防止半写损坏。
+ * （rename 在 Windows 上目标被打开时会 EPERM，使用 renameWithRetry 短退避重试）
  */
 export declare class TodoStore {
     private readonly todosDir;

package/package/acode/dist/todo-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"todo-store.d.ts","sourceRoot":"","sources":["../src/todo-store.ts"],"names":[],"mappings":"AAIA,gBAAgB;AAChB,MAAM,WAAW,QAAQ;IACvB,iBAAiB;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,WAAW,CAAC;IAC9D,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;CACrC;AAED,qBAAqB;AACrB,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,UAAU,CAAoC;;IAMtD,yBAAyB;IACzB,OAAO,CAAC,QAAQ;IAMhB,4CAA4C;IACtC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAmBlD,8DAA8D;IACxD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAkBnF"}
+{"version":3,"file":"todo-store.d.ts","sourceRoot":"","sources":["../src/todo-store.ts"],"names":[],"mappings":"AAKA,gBAAgB;AAChB,MAAM,WAAW,QAAQ;IACvB,iBAAiB;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,WAAW,CAAC;IAC9D,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;CACrC;AAED,qBAAqB;AACrB,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,UAAU,CAAoC;;IAMtD,yBAAyB;IACzB,OAAO,CAAC,QAAQ;IAMhB,4CAA4C;IACtC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAmBlD,8DAA8D;IACxD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAqBnF"}

package/package/acode/dist/todo-store.js

@@ -1,6 +1,7 @@
 import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { renameWithRetry } from "./fs-utils.js";
 /**
  * Todo JSON 文件存储，按 agentId 隔离。
  * 文件路径：{homedir}/.acode/todos/{agentId}.json
@@ -12,6 +13,7 @@ import path from "node:path";
  * 并发安全：同一 TodoStore 实例的写操作通过 Promise 链串行化，
  * 避免同一 agentId 的并发 todo_write 互相覆盖。
  * 写入采用 tmp + rename 原子替换，防止半写损坏。
+ * （rename 在 Windows 上目标被打开时会 EPERM，使用 renameWithRetry 短退避重试）
  */
 export class TodoStore {
     constructor() {
@@ -59,7 +61,10 @@ export class TodoStore {
             };
             const tmp = `${target}.tmp`;
             await fs.writeFile(tmp, JSON.stringify(doc, null, 2), "utf-8");
-            await fs.rename(tmp, target);
+            // ★ Windows 上 fs.rename 目标被 reader 打开时会 EPERM/EBUSY/EACCES，
+            //   瞬时错误，短退避后重试通常即可成功（reader 已释放 fd）。
+            //   POSIX 上 rename 原子，不会触发此类错误。
+            await renameWithRetry(tmp, target);
         });
         // 维持链式串行，但不让单次失败阻断后续写
         this.writeChain = run.catch(() => { });

package/package/acode/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { SubAgentManager } from "./sub-agent-manager.js";
+import type { SubAgentType } from "./sub-agent-types.js";
 import type { ACodeMcpConnection } from "./runtime.js";
 export interface ACodeMcpServerSpec {
     type?: "stdio" | "sse" | "http";
@@ -132,6 +133,16 @@ export interface ACodeRuntimeConfig {
     subAgentModel?: string;
     /** Sub Agent 思考强度覆盖（空值=继承主 Agent 强度） */
     subAgentEffort?: string;
+    /**
+     * Sub Agent 类型（general | explore）。
+     * - general：完整工具权限（可读写工作区文件）
+     * - explore：只读模式，过滤掉会修改工作区文件的内建工具
+     *   （write_file/edit_file/delete_file/Bash），仅保留 read_file/grep/symbols
+     *   等只读工具 + memory MCP 工具。MCP 工具白名单由
+     *   SUB_AGENT_ALLOWED_MCP_TOOLS 独立施加，此处不重复。
+     *   未设置时视为 general（向后兼容）。
+     */
+    subagentType?: SubAgentType;
     /**
      * 可选：Agent 文件操作变更回调。
      * 当 Agent 调用 write_file/edit_file/delete_file 工具时，