@zooique/memora 4.0.0 → 5.0.0

package/dist/agent/agent.js

@@ -5,8 +5,6 @@
  * 负责组件组装和核心对话编排，领域专属操作委托给专职 Manager
  * （RolePackManager / ToolExecutor / SkillManager / MemoryInspector）。
  */
-import { isAbsolute } from 'node:path';
-import { getBaseName } from '../utils/path.js';
 import { AGENT_CONSTANTS } from '../agent/constants.js';
 import { ProjectManager } from '../memory/projectManager.js';
 import { SecurityGuard } from '../security/pathGuard.js';
@@ -21,12 +19,10 @@ import { SeedOrchestrator } from '../agent/seed/index.js';
 import { chatBusyError, configError, isAbortError, isTimeoutAbortSignal, isTimeoutError, } from '../utils/errors.js';
 import { toError } from '../utils/toError.js';
 import { ChatLockManager } from '../agent/managers/chatLockManager.js';
-import { MemoryGovernance } from '../agent/managers/memoryGovernance.js';
 import { ArchiveCoordinator, } from '../agent/managers/archiveCoordinator.js';
 import { TypedEventEmitter, AGENT_EVENTS, AGENT_EVENT_SET, } from '../utils/eventEmitter.js';
 import { logger } from '../logging/logger.js';
 import { isValidSessionId, splitSessionId } from '../utils/time.js';
-import { getBackgroundTaskStats as readBackgroundTaskStats, awaitBackgroundTasks, } from '../utils/backgroundTask.js';
 // ─── 模块级常量 ─────────────────────────────────────────
 // ─── Agent 门面类 ───────────────────────────────────────
 /**
@@ -45,7 +41,7 @@ export class Agent extends TypedEventEmitter {
     #backgroundProvider;
     /** Provider 路由选择器（多模型路由基础，可选） */
     #providerRouter = null;
-    // 运行时组件（init 后填充）——宿主 getter 契约字段（projects/memory/works/polish/sessionManager 等）保持独立
+    // 运行时组件（init 后填充）——宿主 getter 契约字段（memory/works/polish/sessionManager 等）保持独立
     projectManager = null;
     history = null;
     loop = null;
@@ -56,8 +52,6 @@ export class Agent extends TypedEventEmitter {
     _rolePackManager = null;
     // 拆分出的专职 Manager
     memoryInspector = null;
-    /** 记忆治理统一门面（L0/L1/L2/L3 + 诊断） */
-    _governance = null;
     /** TextPolishManager（文本润色管理器，LLM 语法修正 + 表达优化） */
     textPolisher = null;
     /** 会话管理器（从 Agent 拆分出的会话管理职责） */
@@ -70,12 +64,11 @@ export class Agent extends TypedEventEmitter {
      * 减少门面扁平字段数；宿主 getter 契约字段（memory/works/polish 等）不在此列。
      */
     internals = {
-        dedupManager: null,
-        memoryAdvisor: null,
         sessionArchiver: null,
         sessionNamer: null,
         roundSummaryGenerator: null,
         contextPreparer: null,
+        backgroundTasks: null,
         chatLockManager: null,
         archiveCoordinator: null,
         seedOrchestrator: null,
@@ -99,12 +92,18 @@ export class Agent extends TypedEventEmitter {
      * 用 Set 去重——同一 source 只需补执行一次。
      */
     pendingConfigReload = new Set();
+    /**
+     * 对话期间被 chatLock 拒掉的归档模式切换：**末次为准**（不排队——VS Code 设置本身也是后写覆盖）。
+     *
+     * 与 pendingConfigReload 同族：轮终（chat() / resumeExecution() 的 frame 退出）统一补执行，
+     * 语义见 flushPendingTurnEndTasks。null = 无待补执行的切换。
+     */
+    pendingArchiveMode = null;
     constructor(opts) {
         super();
         this.#config = {
             projectPath: opts.projectPath,
             dataDir: opts.dataDir,
-            registryDir: opts.registryDir,
             maxContextTokens: opts.maxContextTokens ?? AGENT_CONSTANTS.DEFAULT_MAX_CONTEXT_TOKENS,
             // per-LLM 输出预算默认值（token）：宿主 per-LLM 配置透传；undefined = 不传 max_tokens
             //（回服务端默认）。与角色包策略 act.outputLimit 的最终关系由 buildChatOptions 取更小值。
@@ -152,12 +151,13 @@ export class Agent extends TypedEventEmitter {
     // ─── 生命周期 ─────────────────────────────────────────
     /**
      * 初始化 Agent：加载索引、组装内部组件
+     *
+     * ⚠️ **项目在构造时钉死**（`AgentOptions.projectPath`），`init()` **不接受路径覆盖参数**——
+     * 形态定案「一个 Agent = 一个项目」：换项目请宿主新建一个 Agent 实例，不要在单实例内改绑
+     * （原 `init(projectPathOverride?)` 于 PR-SWITCH-2 删除：它与该原则直接冲突，且全仓零调用）。
      */
-    async init(projectPathOverride) {
+    async init() {
         await this.disposePreviousInstance();
-        if (projectPathOverride) {
-            this.#config.projectPath = projectPathOverride;
-        }
         const pctx = await this.initializeProject();
         await this.assembleComponents(pctx);
         this.pctx = pctx;
@@ -190,12 +190,25 @@ export class Agent extends TypedEventEmitter {
     /**
      * 注册暂停超时归档处理器（SessionManager 两条超时路径——启动加载与运行时定时器——统一在此消费）
      * 注册在 init() 内（close() 的 removeAllListeners + init 起始的 disposePreviousInstance 保证实例周期内恰好一个监听器），
-     * 挂在生命周期稳定的 Agent 上，rebuildComponents() 重建管理器后仍有效。
+     * 挂在生命周期稳定的 Agent 上，组件重装配后仍有效。
      */
     registerPauseTimeoutArchiver() {
         this.on(AGENT_EVENTS.sessionPauseTimedOut, (payload) => {
             // pendingPauseReason 由 resetToRunning() 内部统一清理
             //（checkPauseTimeout 经 sessionManager resetToRunning 已覆盖，此处无需再补 cancelPendingPause）。
+            //
+            // 在途提问清理（配对不变量守卫）：宿主侧 ASK_TIMEOUT 定时器活在 webview 里，
+            // 而本面板未启用 retainContextWhenHidden ⇒ 面板隐藏/销毁即失，提问超时只能由
+            // 内核 30min 暂停超时兜底。兜底路径若只清检查点、不清在途提问，messages 尾部会留下
+            // assistant(tool_calls) 而 ask_user 无配对 tool 消息——下一次 chat 装配即被
+            // OpenAI 兼容端以 400 拒绝。补此调用后与宿主超时路径同构（同一守卫，非新增判据）。
+            // cancelAsk 对「无在途提问」天然 no-op，无条件调用安全；失败不阻断归档（隔离而非吞没）。
+            try {
+                this.cancelAsk();
+            }
+            catch (err) {
+                logger.warn({ err }, '暂停超时清理在途提问失败（不阻断会话归档）');
+            }
             const { sessionId, date, session } = payload;
             if (!date || !session)
                 return;
@@ -257,7 +270,6 @@ export class Agent extends TypedEventEmitter {
         this.projectManager = new ProjectManager({
             dataDir: this.#config.dataDir,
             storage: this.#config.storage,
-            registryDir: this.#config.registryDir,
             // SecurityGuard 由 Agent 层创建，解除 memory→security 反向依赖
             createSecurityGuard: (projectPath, memoraDir, configDir, agentDataDir) => new SecurityGuard(projectPath, memoraDir, this.#config.allowedPaths, this.#config.confirmWrites, this.#config.permission, this.#config.confirmScripts, configDir ?? this.#config.configDir, agentDataDir ?? this.#config.dataDir),
         });
@@ -281,7 +293,7 @@ export class Agent extends TypedEventEmitter {
     createPostInitComponents(_pctx) {
         // chat() 并发锁管理器（生命周期与 Agent 实例一致）
         this.internals.chatLockManager = new ChatLockManager();
-        // 孤儿 Round 垃圾回收服务：roundStore+storage 均为构造期稳定注入（不随 rebuildComponents 变化），
+        // 孤儿 Round 垃圾回收服务：roundStore+storage 均为构造期稳定注入（不随组件重装配变化），
         // 每日周期清理 refCount=0 且超龄的孤立问答闭环（崩溃残留 pending / 已删会话遗留），防止存储膨胀。
         // shouldSkip：对话进行中跳过本次（minAgeMs 判龄对长任务不可靠，防进行中轮被误清）
         if (this.#config.roundStore && this.#config.storage) {
@@ -305,11 +317,9 @@ export class Agent extends TypedEventEmitter {
                 this.emit(AGENT_EVENTS.sessionTitleUpdated, { sessionId, title });
             },
         });
-        // 记忆治理统一门面（去重 / 冲突 / 诊断）
-        this._governance = new MemoryGovernance(this.internals.dedupManager, this.internals.memoryAdvisor);
         // 种子 turn 编排器（turn 唯一编排真理源）：依赖 sessionManager/loop/history 等
         // 均已就绪（assembleComponents 已完成 + sessionNamer 本方法前段创建），在此构造一次。
-        // getParts() 惰性取当前组件——rebuildComponents（switchProject）更换组件后仍取到最新引用。
+        // getParts() 惰性取当前组件——组件重装配后仍取到最新引用。
         this.internals.seedOrchestrator = this.createSeedOrchestrator();
     }
     /**
@@ -323,7 +333,7 @@ export class Agent extends TypedEventEmitter {
      */
     createSeedOrchestrator() {
         return new SeedOrchestrator({
-            // 组件快照经 getter 惰性取当前引用：rebuildComponents 更换组件后仍读到最新（关键）
+            // 组件快照经 getter 惰性取当前引用：组件重装配后仍读到最新（关键）
             getParts: () => ({
                 loop: this.loop,
                 history: this.history,
@@ -333,8 +343,11 @@ export class Agent extends TypedEventEmitter {
                 sessionNamer: this.internals.sessionNamer,
                 roundSummaryGenerator: this.internals.roundSummaryGenerator,
             }),
+            // 后台任务槽位调度器（实例级，装配期由 assembler 创建）：摘要/会话命名 fire-and-forget 经此
+            backgroundTasks: this.internals.backgroundTasks,
             tracer: this.#config.tracer ?? null,
-            archiveMode: this.#config.archiveMode,
+            // 归档模式经 getter 惰性取：setArchiveMode 轮内/轮终改值后 span 标注仍为真（同 getParts）
+            archiveMode: () => this.#config.archiveMode,
             messages: this.#config.messages,
             // 门面私有能力经回调注入 seed（物理实现仍在门面）
             applyRolePackToolExposure: () => this.applyRolePackToolExposure(),
@@ -387,7 +400,7 @@ export class Agent extends TypedEventEmitter {
             // turn 结束自动收尾：非暂停态无条件清理任务表（turn 内能力，不跨 turn 残留）；
             // 清空前产出 plan_snapshot 快照 chunk（任务项完成态落盘真源）
             yield* this.clearPlanOnTurnEnd();
-            await this.flushPendingConfigReload();
+            await this.flushPendingTurnEndTasks();
         }
     }
     /**
@@ -413,9 +426,32 @@ export class Agent extends TypedEventEmitter {
         return { myToken, internalAbort, cleanupExternalSignal, combinedSignal: internalAbort.signal };
     }
     /**
-     * 补执行对话期间暂存的配置重载请求
+     * 补执行对话期间暂存的**轮终任务**（当前两类：配置重载 source、归档模式切换）
+     *
+     * 挂载点 = **两处**都必须挂，缺一即同族缺陷（见 clearPlanOnTurnEnd 的「单一收口点」注释）：
+     *   - chat() 的 finally（本文件 chat() 生成器收尾块）
+     *   - resumeExecution() 的 finally——缺它则「暂停→续跑」期间暂存的项滞留到下一次 chat()，
+     *     用户若不再发问则**永久丢失**（2026-10-16 实证：此前仅 chat() 挂点存在，该缺陷为空头承诺）。
+     *
+     * 位置约束：必须在 release(myToken) **之后** ⇒ 到达时 chatLock 已释放，此处再申请不会撞 busy。
+     * 语义 = 「流退出」（generator frame exit）而非「turn 真正收场（非 paused）」：
+     *   暂停边界同样会执行本方法，这与「暂停期间直接改 = 即时生效」的现状一致（ADR-041 §2）。
+     *
+     * 失败策略：**成功才清槽**。失败保留暂存 + logger.warn，顺延下一个安全点（幂等保证重复应用无害）。
+     *   ⚠ 下方 reloadConfig 段仍是既有的「先 clear 再尝试」（失败即丢失）——同族债已登记，本批不动其行为。
      */
-    async flushPendingConfigReload() {
+    async flushPendingTurnEndTasks() {
+        if (this.pendingArchiveMode !== null) {
+            const mode = this.pendingArchiveMode;
+            try {
+                // 复用公开入口而非直改字段：幂等判定与 archiveModeChanged 回执走同一条路径
+                this.setArchiveMode(mode);
+                this.pendingArchiveMode = null; // 仅成功后清槽
+            }
+            catch (err) {
+                logger.warn({ err, mode }, '轮终补执行归档模式切换失败，保留暂存待下一个安全点');
+            }
+        }
         if (this.pendingConfigReload.size === 0)
             return;
         const pending = Array.from(this.pendingConfigReload);
@@ -430,16 +466,9 @@ export class Agent extends TypedEventEmitter {
             }
         }
     }
-    /**
-     * 强制释放对话锁
-     *
-     * 宿主在"无进展超时"确认 generator 挂起后调用，使用户能立即发起新对话（否则需等锁超时）。
-     * 安全机制委托 ChatLockManager.forceRelease：递增 token 让原 chat() 的 finally 跳过清理、abort signal 让响应点退出；
-     * 原 generator 仍可能后台运行但不影响新调用。幂等（未忙时 no-op）。
-     */
-    forceReleaseChatLock() {
-        this.internals.chatLockManager?.forceRelease();
-    }
+    // 删后注记（2026-10-16 · 5.0.0）：曾有公开 forceReleaseChatLock()——注释称宿主在「无进展超时」
+    // 后调用以强行释放对话锁，实际宿主全仓零真实调用（仅一句注释提及），承诺的兜底从未接线。
+    // 底层 ChatLockManager.forceRelease 随之无调用者，一并拆除（close 路径仍用 dispose 释放锁）。勿加回。
     /**
      * 发送用户消息，非流式返回完整回复
      */
@@ -536,6 +565,9 @@ export class Agent extends TypedEventEmitter {
             // 两处 turn-end 清理统一为 clearPlanOnTurnEnd（单一收口点），plan 严格 turn 内、不跨 turn 残留；
             // 清空前产出 plan_snapshot 快照 chunk（任务项完成态落盘真源）
             yield* this.clearPlanOnTurnEnd();
+            // 与 chat() 同构：补执行对话期间暂存的轮终任务（归档模式 / 配置重载）。
+            // 缺本行 ⇒ 「暂停→续跑」半程内被拒切的偏好滞留到下一次 chat()，用户不再发问则永久丢失。
+            await this.flushPendingTurnEndTasks();
         }
     }
     /**
@@ -555,17 +587,16 @@ export class Agent extends TypedEventEmitter {
         let paused = false;
         try {
             for await (const chunk of source) {
-                // 内核事实驱动：loop 在 step 边界真正挂起时状态机才翻 PAUSED，非申请即翻转；
-                // 与 requestPause 空闲分支同源，须传 lowRisk=true 保持同一暂停事件契约（否则流中暂停计入连续暂停配额）
+                // 内核事实驱动：loop 在 step 边界真正挂起时状态机才翻 PAUSED，非申请即翻转
                 if (chunk.type === 'paused') {
                     const pendingInfo = this._sessionManager?.consumePendingPause();
-                    // 暂停收口统一写 pauseMeta：reason/source 取自 pendingPause（与状态机一致）。
-                    // ask_user 主动提问等"直接暂停路径"不走 loop.onPaused，在此自然补齐，
-                    // 重启后宿主可展示"为什么暂停 + 问了什么"
+                    // 原因/来源唯一真源 = 状态机 pendingPause：用户暂停与提问挂起**同源**注册
+                    // （提问挂起经 assembler 的 onPendingQuestion → requestPause(reason,'agent')，
+                    //   见 assembler.ts）。此处不另设第二载体，否则同一事实两个真源即漂移。
                     const pauseReason = pendingInfo?.reason ?? '用户主动暂停';
                     const pauseSource = pendingInfo?.source ?? 'user';
-                    this.pause(pauseReason, pauseSource, true);
-                    this._sessionManager?.setPauseMeta({ reason: pauseReason, source: pauseSource });
+                    // pauseMeta 不在此写——唯一写入点已收口到 SessionManager.pause()（本方法转发调用）。
+                    this.pause(pauseReason, pauseSource);
                     paused = true;
                 }
                 yield chunk;
@@ -642,11 +673,10 @@ export class Agent extends TypedEventEmitter {
     }
     /**
      * 暂停会话（用户/Agent/系统均可触发，暂停前自动创建检查点）
-     * @param lowRisk 低风险暂停不计入连续暂停计数（默认 false）
      */
-    pause(reason, source = 'user', lowRisk = false) {
+    pause(reason, source = 'user') {
         this.assertInitialized('pause');
-        return this.requireSessionManager.pause(reason, source, lowRisk);
+        return this.requireSessionManager.pause(reason, source);
     }
     /**
      * 恢复会话（从 PAUSED 恢复到 RUNNING）
@@ -669,7 +699,7 @@ export class Agent extends TypedEventEmitter {
         const status = sm.status;
         if (status === 'error') {
             throw configError('会话异常', '会话处于异常状态，无法接收新消息', [
-                '先标记 error.recovered=true 并调用 agent.recover()',
+                '先标记 error.recovered=true 并调用 agent.sessionManager.recover()',
             ]);
         }
         if (status === 'paused') {
@@ -705,7 +735,7 @@ export class Agent extends TypedEventEmitter {
         // 空闲守卫：无活跃流时暂停无消费方——若此时同步翻状态机并落盘 checkpoint，
         // 「turn 已完成后的暂停」会把会话钉在 paused，后续新输入被宿主路由成
         // supplement（新意图被吞成"上一个回答的补充"，毒化闭环节点；loop 无流消费的延迟翻转亦无意义）。
-        // 任务已结束 = 暂停申请作废，返回 false 供宿主明确反馈；系统/Agent 触发（ask_user/drift）均在
+        // 任务已结束 = 暂停申请作废，返回 false 供宿主明确反馈；ask_user 提问挂起在
         // 流中（_flowActive=true）不经过此分支，不受影响。
         // ⚠ 判据必须用 _flowActive（流活跃）而非 chatLock.isBusy（锁持有）——chatLock 锁
         // 180s 超时后自动释放（不中断生成流），长任务运行超锁期后 isBusy=false 但流
@@ -850,14 +880,13 @@ export class Agent extends TypedEventEmitter {
         this.assertInitialized('answerQuestion');
         return this.requireLoop.answerQuestion(answers);
     }
-    /**
-     * 追加计划任务项（SESSION_APPEND_TASK 落点）：在现有 plan 末尾追加新任务项
-     */
-    appendPlanItem(description) {
-        this.assertInitialized('appendPlanItem');
-        const sm = this.requireSessionManager;
-        return sm.appendPlanItem(description);
-    }
+    // 删后注记（2026-10-17 · 5.0.0，PUB-API-PRUNE-2）：Agent 面类曾有 4 个纯转发门面——
+    // appendPlanItem / triggerError / recover / injectSystemMessage——均 3-13 行薄委托
+    // （sessionManager / loop 层实现），宿主零调用 + 手册零承诺 + 真身在对应类公开可用
+    // （sessionManager.appendPlanItem/triggerError/recover、loop.injectSystemMessage）。
+    // 与 loadSessionMessages 同型裁决：转门口不留。getActiveStrategy 经复核**保留**——
+    // 它不是转发门面（rolePackManager 无同名方法），是 Agent 级策略读取器且内部自用
+    // （buildChatOptionsFromStrategy），「读当前生效策略」属合理外部能力。
     /**
      * 卸载运行态挂载物：清空检查点计划与任务项推进日志（宿主任务流结束/停止/异常广播 idle 前调用），
      * 回到"空闲 = 无挂载物"的资源层常态；会话历史与记忆等资源层内容不受影响。
@@ -906,49 +935,15 @@ export class Agent extends TypedEventEmitter {
             sm.clearPlan();
         }
     }
-    /**
-     * 内核→宿主信号：当前会话是否可"无输入续跑"（决定暂停按钮显隐 + 暂停后继续 UI）
-     *
-     * 真值条件：① 状态机已 paused（已软暂停必可续跑，最高优先级——pauseRequested 在下一 step 边界才挂起，
-     * 彼时 inAutonomousStep 已重置为 false，仅看它会误报）；② loop 在自主工具步（可暴露暂停按钮在边界挂起）；
-     * ③ 存在未完成的计划任务项（多轮任务可续跑下一轮）。三者皆否（纯单轮、无待续目标）→ 隐藏暂停按钮（仅停止）。
-     */
-    canContinueWithoutInput() {
-        if (this._sessionManager?.status === 'paused')
-            return true;
-        // 错误态不展示"继续"：error 态由检查点恢复回填进入，须显式处理（重新开始或 recover），避免点了静默无反应
-        if (this._sessionManager?.status === 'error')
-            return false;
-        // 仅 pending/active（可推进）任务项计入"可续跑"——blocked 不续（全 blocked 由 isPlanAllBlocked 拦，
-        // 避免全 blocked 计划按钮可点但 resumeExecution 早退）。判定走 SessionManager.hasInflightPlan
-        // 单一真理源（禁内联谓词，SSOT 见 sessionManager.ts hasInflightPlan 注释），与 prepare/loop 同源。
-        const hasPendingPlan = this._sessionManager?.hasInflightPlan() ?? false;
-        return this.requireLoop.isInAutonomousStep || hasPendingPlan;
-    }
-    /**
-     * 触发会话异常（公开 API，宿主显式调用）：仅 RUNNING 状态可触发，异常时自动创建检查点保存状态。
-     * 生产内部无调用者——运行时异常（LLM 超时/工具失败）走 yield {type:'error'} 事件流不翻状态机；
-     * 本 API 供宿主在自定义异常（如外部服务故障）显式触发，或经检查点恢复回填进入 ERROR 态。
-     */
-    triggerError(cause) {
-        this.assertInitialized('triggerError');
-        return this.requireSessionManager.triggerError(cause);
-    }
-    /**
-     * 从异常恢复：校验恢复条件（error.recovered === true 且 cause 已解除）
-     */
-    recover() {
-        this.assertInitialized('recover');
-        return this.requireSessionManager.recover();
-    }
     /**
      * 创建会话检查点：快照当前运行时状态（热记忆等），生成纯内存态快照
      * （不落盘、无序列化/恢复路径——中止/断电走「中断轮补全为完整 turn」）。
-     * 无 role/standard 会话能力位，createCheckpoint 仅收 mainGoal。
+     * 返回值恒非空：未 init 时由 assertInitialized/requireSessionManager 抛错（configError），
+     * 不返回 null——null 仅属于 getCheckpoint()（首个检查点尚未创建）。
      */
-    createCheckpoint(mainGoal) {
+    createCheckpoint() {
         this.assertInitialized('createCheckpoint');
-        return this.requireSessionManager.createCheckpoint(mainGoal);
+        return this.requireSessionManager.createCheckpoint();
     }
     /**
      * 获取当前检查点
@@ -957,25 +952,10 @@ export class Agent extends TypedEventEmitter {
         this.assertInitialized('getCheckpoint');
         return this.requireSessionManager.getCheckpoint();
     }
-    /**
-     * 获取最近一次处理线程的工具执行历史（loop 域聚合出口，补待办 #3）
-     *
-     * 数据源自 sessionManager 检查点的 completedToolCalls（已由
-     * AGENT_CONSTANTS.COMPLETED_TOOL_CALLS_MAX 做 FIFO 封顶）。本方法剥离「恢复/幂等」内部
-     * 语义，提供稳定的 execute 域只读契约——宿主可在透明面板/观测面消费本轮及历史的工具调用
-     * 明细（工具名 / 成败 / 结果摘要），与累计 AgentMetrics.tools 互补。
-     *
-     * @param limit 返回条数上限（默认取封顶上限，超界由调用方控制，取最近 limit 条）
-     * @returns 工具执行记录（记录顺序：时间正序即旧→新；无记录返回空数组；返回浅拷贝防宿主改动检查点）
-     */
-    getRecentToolExecutions(limit = AGENT_CONSTANTS.COMPLETED_TOOL_CALLS_MAX) {
-        this.assertInitialized('getRecentToolExecutions');
-        const calls = this.requireSessionManager.getCheckpoint()?.completedToolCalls;
-        if (!calls || calls.length === 0)
-            return [];
-        // 取最近 limit 条并浅拷贝，避免宿主引用改动污染检查点（FIFO 封顶后 slice 安全）
-        return calls.slice(-limit).map((r) => ({ ...r }));
-    }
+    // 删后注记（2026-10-16 · 5.0.0，按 SSOT/不带伤裁决提前于 DEPRECATE-1 周期删除）：曾有公开
+    // getRecentToolExecutions()——聚合检查点 completedToolCalls 的「工具执行历史」出口，
+    // 内核+宿主+手册三面零消费（loop 域 tool_start/tool_result 事件流才是宿主可自聚合的真源，
+    // 本出口是多余中间层）。勿加回；观测需求经事件流自聚合。
     /**
      * 后台任务只读快照（宿主 UI 出口 · 见 `docs/方案-后台任务可见性与kill入口-20261004.md` §2.1）
      *
@@ -1005,12 +985,6 @@ export class Agent extends TypedEventEmitter {
         this.assertInitialized('killBackgroundTask');
         return this.requireLoop.killBackgroundTask(taskId);
     }
-    /**
-     * 向 loop 注入 system 消息
-     */
-    injectSystemMessage(message) {
-        this.requireLoop.injectSystemMessage(message);
-    }
     /**
      * 从指定 Round 位置分叉当前会话（委托至 SessionManager）：
      * round-based 模式唯一分叉方式——创建新会话，复制 Round ID 列表（指针复制），
@@ -1064,58 +1038,6 @@ export class Agent extends TypedEventEmitter {
         }
         await namer.ensureSessionTitle(result.date, result.newSession, firstUserContent);
     }
-    /**
-     * 切换到指定项目：切换后自动 rebuildComponents()；Agent 级记忆存储（宿主注入，实例不随项目切换重建）保留，项目级配置（.memora/）重新加载
-     *
-     * `nameOrPath` 只接受两种输入：① 项目注册表中的项目名（依赖注册表跨项目共享，见 dataDir/registryDir）；
-     * ② 项目根目录的**绝对路径**。二者都不满足时抛 configError——否则相对串会以 process.cwd()
-     * 为基准解析，静默造出非预期的项目目录并占用其锁。
-     */
-    async switchProject(nameOrPath) {
-        this.assertInitialized('switchProject', ['projectManager', 'provider']);
-        // 对话进行中切换项目会导致 loop/history 引用被替换，工作记忆与持久化状态不一致
-        this.assertNotBusy('切换项目');
-        const pm = this.projectManager;
-        const projects = pm.list;
-        let target = projects.find((p) => p.name === nameOrPath || p.path === nameOrPath);
-        if (!target) {
-            const nameOrPathLower = nameOrPath.toLowerCase();
-            target = projects.find((p) => p.name.toLowerCase() === nameOrPathLower || p.path.toLowerCase() === nameOrPathLower);
-        }
-        // 注册表未命中时按路径处理。相对路径会以 process.cwd() 为基准解析——宿主进程的 cwd
-        // 不具项目语义，会静默创建出非预期的项目目录并占用其锁，故只接受绝对路径。
-        if (!target && !isAbsolute(nameOrPath)) {
-            throw configError('项目切换失败', `「${nameOrPath}」既不是已注册的项目名，也不是绝对路径`, [
-                '按名切换：先经 agent.projects.registerProject(项目路径, 项目名) 注册，并保证注册表跨项目共享（多项目共用同一 dataDir 或 registryDir）',
-                '按路径切换：传入项目根目录的绝对路径',
-            ]);
-        }
-        const projectPath = target ? target.path : nameOrPath;
-        const projectName = target ? target.name : getBaseName(nameOrPath);
-        const newPctx = await pm.initProject(projectPath, projectName, this.#config.configDir);
-        // 记录源项目路径（用于事件），切换前 pctx 可能不存在（首次初始化）
-        const fromProjectPath = this.pctx?.projectPath ?? null;
-        // 先尝试重建组件，失败时回滚 pctx 防止状态不一致
-        try {
-            this.pctx = newPctx;
-            await this.rebuildComponents();
-        }
-        catch (err) {
-            // 回滚：恢复旧 pctx（若存在）
-            if (fromProjectPath) {
-                logger.warn({ err: toError(err) }, 'switchProject: 组件重建失败，回滚项目上下文');
-                this.pctx = { projectPath: fromProjectPath };
-            }
-            throw err;
-        }
-        // 发射项目切换事件（供宿主 UI 刷新项目相关界面）
-        this.emit(AGENT_EVENTS.projectSwitched, {
-            from: fromProjectPath,
-            to: projectPath,
-            projectName,
-        });
-        return newPctx;
-    }
     // ─── 组件组装 ─────────────────────────────────────────
     /**
      * 组装所有运行时组件（一行委托给 assembler 工厂）
@@ -1200,8 +1122,6 @@ export class Agent extends TypedEventEmitter {
             this.emit(AGENT_EVENTS.rolePackSwitchLocked, { reason, lockedSeconds });
         });
         this.memoryInspector = result.memoryInspector;
-        this.internals.dedupManager = result.dedupManager;
-        this.internals.memoryAdvisor = result.memoryAdvisor;
         this.workProjection = result.workProjection;
         this.internals.sessionArchiver = result.sessionArchiver;
         this.textPolisher = result.textPolisher;
@@ -1210,6 +1130,9 @@ export class Agent extends TypedEventEmitter {
         this._sessionManager = result.sessionManager;
         // 输入增强管线由组装器创建，Agent 只保留编排调用点
         this.internals.contextPreparer = result.contextPreparer;
+        // 后台任务槽位调度器（实例级）：assembler 创建时已注入 toolExec（命中 touch）；
+        // 此处持有 → 下方创建 seedOrchestrator 时注入 SeedDeps（摘要/命名）+ close() 单点等待。
+        this.internals.backgroundTasks = result.backgroundTasks;
     }
     // ─── Provider 管理 ────────────────────────────────────
     setProvider(provider) {
@@ -1284,10 +1207,29 @@ export class Agent extends TypedEventEmitter {
     }
     // ─── 归档模式管理 ───────────────────────────
     /**
-     * 运行时切换归档模式：对话进行中禁止切换（避免本轮 postProcess 行为不一致），无变更幂等返回
+     * 运行时切换归档模式：**对话进行中不即时生效** → 暂存期望值 + 抛错，由 flushPendingTurnEndTasks 补执行。
+     *
+     * 契约与 reloadConfig(source) 逐字同构：
+     *   - busy 时 **既暂存、又抛错**——抛错是「已排期到轮终」的传输方式，不是「静默接受」。
+     *     宿主据此走 catch 分支向用户如实说明「运行时将在当前对话结束后生效」（settingsPanel.setArchiveMode）。
+     *   - 补执行点：chat() / resumeExecution() 的 finally（流退出），见 flushPendingTurnEndTasks。
+     *
+     * ⚠ 守卫用 chatLock.isBusy（`assertNotBusy` 同源），而该锁 180s 超时会**自动释放且不中断生成流**
+     *   （见 ChatLockManager.acquire 计时器）⇒ 长轮跑过 180s 后本方法会即时生效而非暂存，
+     *   此时本轮的**后半程**即按新模式归档。这是既有判据的缺陷，非本方法引入；
+     *   判据统一问题已登记专项（本批不动判据），此处如实注明而非回避。
      */
     setArchiveMode(mode) {
-        this.assertNotBusy('切换归档模式');
+        if (this.internals.chatLockManager?.isBusy) {
+            // 先暂存后抛：任何一次拒切都排期到轮终，用户偏好既不会丢也不会被伪造为「已生效」
+            // （最坏情况还有「装配期读持久化配置注入」兜底，见 extension.ts getOrCreateAgent）。
+            this.pendingArchiveMode = mode;
+            logger.info({ mode }, '对话进行中，归档模式切换已暂存，将在流退出时补执行');
+            throw chatBusyError('切换归档模式');
+        }
+        // 清槽落点必须在幂等 return **之前**（三条出口全覆盖）：
+        // 否则「即时改成当前值」会命中幂等直接 return，旧暂存仍在轮终覆盖用户最后一次表态。
+        this.pendingArchiveMode = null;
         const prev = this.#config.archiveMode;
         if (prev === mode)
             return; // 幂等：无变更直接返回
@@ -1440,7 +1382,9 @@ export class Agent extends TypedEventEmitter {
     }
     // ─── 配置重载（事件驱动） ───────────────────────
     /**
-     * 重载配置类记忆：从 configDir 重新扫描指定 source 并更新内存缓存（设定记忆纯文件装载，不写记忆库），使当前会话立即生效（无需重启）。
+     * 从 configDir 重新扫描指定 source 并更新内存缓存（设定记忆纯文件装载，不写记忆库）。
+     * **空闲时**使当前会话立即生效（无需重启）；**对话进行中**则暂存 source 并抛错（见下方 busy 分支），
+     *   由 flushPendingTurnEndTasks 在流退出时补执行——故此处不宜读作「无条件立即生效」。
      * - 'skill' → SkillManager.reload() 重扫 skills/
      * - 'rolePack' → RolePackManager.reload() 重扫 role-packs/（保持激活角色，刷新 AgentLoop 前缀）
      * - 'rule' → 经角色包管理机制热更新（即 rolePack）
@@ -1497,17 +1441,6 @@ export class Agent extends TypedEventEmitter {
         return result;
     }
     // ─── 组件访问 ─────────────────────────────────────────
-    /**
-     * 重建内部组件（history / loop / managers）：通常由 switchProject() 自动触发，仅强制刷新时手动调用
-     */
-    async rebuildComponents() {
-        // 对话进行中重建会导致 loop/history 引用被替换，工作记忆与持久化状态不一致
-        this.assertNotBusy('重建组件');
-        if (!this.pctx)
-            return;
-        // assembleComponents 内部重建 history/loop/managers，并返回新创建的 sessionManager
-        await this.assembleComponents(this.pctx);
-    }
     // ─── 守卫方法 ───────────────────────────────────────────
     /**
      * 检查 Agent 是否已初始化（methodName 用于错误消息，requires 为需检查的组件列表）
@@ -1622,20 +1555,25 @@ export class Agent extends TypedEventEmitter {
         this.internals.gcService?.stopPeriodic();
         this.internals.gcService = null;
         // 等待 WorkProjection 无 inflight 概念（作品投影改为用户主动触发同步写，无后台 LLM 任务）
-        // 背景任务统一由下方 awaitBackgroundTasks 兜底
-        // 关键约束：等待 backgroundTask 全局在途任务完成（如 touchScores）。
+        // 背景任务统一由下方调度器等待兜底
+        // 关键约束：等待**本实例**后台任务在途任务完成（如 touchScores）。
         // 否则 close 后后台任务仍可能 upsert 已关闭的 storage，触发写失效或异常。
-        try {
-            const awaited = await awaitBackgroundTasks(AGENT_CONSTANTS.SHUTDOWN_ARCHIVE_TIMEOUT_MS);
-            if (awaited > 0) {
-                logger.debug({ awaited }, 'close: 背景任务等待结束（awaited = 初始在途数，超时放弃时非完成数）');
+        const backgroundTasks = this.internals.backgroundTasks;
+        if (backgroundTasks) {
+            try {
+                const awaited = await backgroundTasks.awaitPending(AGENT_CONSTANTS.SHUTDOWN_ARCHIVE_TIMEOUT_MS);
+                // 超时后丢弃**未启动**的排队任务（只清队列，不中断在途）——防关后从队列启动新任务写已关 storage
+                const discarded = backgroundTasks.cancelPending();
+                if (awaited > 0) {
+                    logger.debug({ awaited, discarded }, 'close: 背景任务等待结束（awaited = 初始在途数，超时放弃时非完成数）');
+                }
+            }
+            catch (err) {
+                logger.warn({ err: toError(err) }, 'close: 后台任务等待失败');
             }
         }
-        catch (err) {
-            logger.warn({ err: toError(err) }, 'close: awaitBackgroundTasks 失败');
-        }
-        // 后台「命令」任务实例终态收割——与上方 awaitBackgroundTasks 是同名异物：
-        // 上方等的是归档/打分类内存任务，此处杀的是注册表持有的 shell 子进程。
+        // 后台「命令」任务实例终态收割——与上方 BackgroundTaskScheduler 是同名异物：
+        // 上方等的是归档/打分/命名类内存副作用，此处杀的是注册表（BackgroundTaskRegistry）持有的 shell 子进程。
         // turn 终态刻意脱管不杀（跨轮存活），但注册表按 Agent 实例隔离，实例销毁后任务
         // 不可寻址，不杀就是 OS 层孤儿（观察点 ⑧ 真机实锤：父进程退出后 ping.exe 仍在）。
         // 本调用同时注销注册表的 exit 兜底钩子（close 内同步杀树若因关窗窗口赶不上，
@@ -1650,17 +1588,14 @@ export class Agent extends TypedEventEmitter {
         if (sm?.isPausePending()) {
             const pendingInfo = sm.pendingPauseInfo;
             logger.warn({ reason: pendingInfo?.reason, source: pendingInfo?.source }, 'close() 时存在未消费的暂停请求，已自动清理');
-            // 若状态机仍 running，同步翻 paused 使检查点内存态一致（无需触发挂起，仅修正一致性）；
-            // 系统清理不消耗连续暂停配额 → lowRisk=true
+            // 若状态机仍 running，同步翻 paused 使检查点内存态一致（无需触发挂起，仅修正一致性）
             if (sm.status === 'running') {
-                sm.pause('close 清理残留暂停', 'system', true);
+                sm.pause('close 清理残留暂停', 'system');
             }
             sm.cancelPendingPause();
         }
         // 清理 SessionManager（须先于 nullifyAllComponents，destroy 需访问其内部状态）
         if (this._sessionManager) {
-            // 清脏后再 destroy（纯内存，无落盘；检查点不落盘，本调用为保留语义边界的 no-op）
-            this._sessionManager.flushOnShutdown();
             this._sessionManager.destroy();
         }
         // ArchiveCoordinator 无定时器，仅释放引用
@@ -1692,6 +1627,7 @@ export class Agent extends TypedEventEmitter {
         // 清理次要状态字段，防止 re-init 后残留上一会话状态
         this._lastInteractionAt = null;
         this.pendingConfigReload.clear();
+        this.pendingArchiveMode = null;
     }
     /**
      * 统一 null 化所有组件字段（新增 Manager 时在此追加一行）；带副作用的清理仍由 close() 显式调用，顺序敏感不可合并
@@ -1704,7 +1640,6 @@ export class Agent extends TypedEventEmitter {
         this.skillManager = null;
         this._rolePackManager = null;
         this.memoryInspector = null;
-        this._governance = null;
         this.workProjection = null;
         this.textPolisher = null;
         this._sessionManager = null;
@@ -1712,12 +1647,11 @@ export class Agent extends TypedEventEmitter {
         this.pctx = null;
         // 纯内部组件聚合整体置 null（新增内部组件只需在字段声明与 createPostInitComponents 登记）
         this.internals = {
-            dedupManager: null,
-            memoryAdvisor: null,
             sessionArchiver: null,
             sessionNamer: null,
             roundSummaryGenerator: null,
             contextPreparer: null,
+            backgroundTasks: null,
             chatLockManager: null,
             archiveCoordinator: null,
             seedOrchestrator: null,
@@ -1772,18 +1706,21 @@ export class Agent extends TypedEventEmitter {
     get lastInteractionAt() {
         return this._lastInteractionAt;
     }
-    /** 记忆治理统一门面（语义去重 / 来源健康诊断 / 冲突检测 / 建议推荐），Agent 上的记忆管理方法统一收口于此（无显式衰减层面） */
-    get governance() {
-        return this._governance;
-    }
+    // 删后注记（2026-10-18 · 5.0.0，批次 GOVERNANCE-SRC-1 方案②「整链退役」，用户拍板）：
+    // 曾有公开 getter `governance`（MemoryGovernance 门面：deduplicate / detectConflicts /
+    // sourceHealth / suggest）。退役理由 = **结构性恒空**，非「暂时没人用」：四个方法里三个
+    // 逐 `GOVERNANCE_SOURCES` 取样，而该常量自「设定记忆归角色包」后固定为空数组 ⇒
+    // deduplicate 恒 0 条 / detectConflicts 恒 skippedReason / suggest(undefined) 恒 []；
+    // 仅 sourceHealth 走 getAllSources() 有效，而其信息已由 `memory.stats().bySource` 覆盖。
+    // 治理模型现为写时取代（roundSummaryGenerator 的 supersedeSimilar + supersededBy）。
+    // 连带拆除：MemoryAdvisor / DedupManager / GOVERNANCE_SOURCES / llmJudgeHelper /
+    // recallDefaults / dedupCompleted 事件 + 宿主 suggestions 通道。勿加回。
     // ─── 运行时指标 ────────────────────────────────
-    /**
-     * 后台任务统计快照（宿主观测后台副作用健康度，纯只读转发 utils 单例）。
-     * @returns 在途 / 成功 / 失败计数
-     */
-    getBackgroundTaskStats() {
-        return readBackgroundTaskStats();
-    }
+    // 删后注记（2026-10-16 · 5.0.0，按 SSOT/不带伤裁决提前于 DEPRECATE-1 周期删除）：曾有公开
+    // getBackgroundTaskStats()——转发 utils 后台任务统计快照（pending/completed/failed），
+    // 宿主零消费；连带 utils 层 getBackgroundTaskStats 函数、BackgroundTaskStats 接口与
+    // stats 的 completed/failed 只写字段一并拆除（pending 仍服务后台任务等待/收口）。
+    // 勿加回；后台健康度观测需求出现时经事件流或专用诊断面重建。
     /**
      * 获取 Agent 运行时指标快照（可观测性）：聚合 AgentLoop 指标与 Agent 层治理指标；
      * 未初始化返回全零默认值（不抛异常），纯只读同步零副作用，适合宿主定期轮询监控面板。
@@ -1851,10 +1788,6 @@ export class Agent extends TypedEventEmitter {
     get memory() {
         return this.memoryInspector;
     }
-    /** 项目管理器（返回 null 表示 Agent 未初始化） */
-    get projects() {
-        return this.projectManager;
-    }
     /** 安全守卫（写入确认回调注册：`onWriteConfirmation` 返回 true 放行、false 拒绝；未初始化/projectPath 未设为 null） */
     get security() {
         return this.pctx?.security ?? null;