@zooique/memora 2.0.0 → 3.0.0

package/dist/agent/agent.js

@@ -1,82 +1,39 @@
 /**
  * Agent 门面类 — Memora 宿主项目接入入口
  *
- * 设计文档（ADR-010 · Agent 门面类）要求宿主项目通过 `import { Agent } from '@memora/core'`
- * 一行代码接入。本类负责组件组装和核心对话编排，
- * 领域专属操作委托给专职 Manager（PersonaManager / ToolExecutor / SkillManager / ConfigManager / InsightExtractor / MemoryInspector）。
- *
- * 使用方式（最简）：
- *   const agent = new Agent({ projectPath: './my-project', configDir: './agent-config' });
- *   await agent.init();
- *   for await (const chunk of agent.chat('你好')) {
- *     if (chunk.type === 'text') process.stdout.write(chunk.content);
- *   }
- *   await agent.close();
- *
- * 使用方式（高级）：
- *   const agent = new Agent({ projectPath: './my-project', provider: myProvider, configDir: './agent-config' });
- *
- * 2026-06-12 God Object 拆分：
- *   - Insight 提取 → InsightExtractor
- *   - 配置管理 → ConfigManager
- *   - 记忆查看 → MemoryInspector
- *   - 薄包装方法移除，调用方改为 agent.<manager>.xxx()
+ * 宿主通过 `import { Agent } from '@zooique/memora'` 一行接入。
+ * 负责组件组装和核心对话编排，领域专属操作委托给专职 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';
-import { recall } from '../memory/recall.js';
-import { assembleComponents } from '../agent/assembler.js';
-import { matchPersonaByLlm } from '../agent/personaMatcher.js';
-import { chatBusyError, configError } from '../utils/errors.js';
-import { clearSafeInterval } from '../utils/safeTimer.js';
-import { SessionManager } from '../agent/managers/sessionManager.js';
+import { DEFAULT_BEHAVIOR_STRATEGY } from '../role-pack/strategyResolver.js';
+import { isTemperature, MAX_OUTPUT_LIMIT } from '../role-pack/strategyKeys.js';
+import { resolveCapabilityTools } from '../role-pack/capabilityMap.js';
+import { SessionNamer } from '../agent/managers/sessionNamer.js';
+import { createDefaultGCService } from '../memory/gcService.js';
+import { assembleComponents, buildSystemPromptPrefix } from '../agent/assembler.js';
+import { estimateTokensMessages } from '../agent/contextManager.js';
+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 { MemoryDecayScheduler } from '../agent/managers/memoryDecayScheduler.js';
-import { ArchiveCoordinator } from '../agent/managers/archiveCoordinator.js';
-import { TypedEventEmitter } from '../utils/eventEmitter.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 { TRACE_SPANS, NOOP_TRACER } from '../agent/tracer.js';
+import { getBackgroundTaskStats as readBackgroundTaskStats, awaitBackgroundTasks, } from '../utils/backgroundTask.js';
 // ─── 模块级常量 ─────────────────────────────────────────
-/** Agent 事件名白名单，用于运行时校验 SessionManager 转发的事件类型 */
-// 必须与 utils/eventEmitter.ts 的 AgentEventMap 键集保持一致（10 个事件）
-const AGENT_EVENT_NAMES = new Set([
-    'memoryAdded', 'personaSwitched', 'decayCompleted',
-    'memoryRecalled', 'sessionForked', 'insightExtracted',
-    'conflictDetected', 'projectSwitched', 'skillMatched',
-    'archiveFailed',
-]);
 // ─── Agent 门面类 ───────────────────────────────────────
 /**
  * Memora Agent 门面类
  *
- * **设计哲学**：单 Agent，单配置，单记忆。每个 Agent 实例拥有独立的
- * 对话管线（AgentLoop）、独立的消息历史（MessageHistory）和独立的
- * 运行时状态（activeSkill、chatBusy）。
- *
- * **多实例**：宿主可通过 new Agent({ dataDir: './agent2' }) 创建
- * 独立实例。只要 dataDir 不同，它们拥有完全隔离的记忆库和会话。
- * 内核不负责多 Agent 编排——那是宿主层的职责。
- *
- * **fork vs 多实例**：
- * - forkSession() 分叉对话历史，但记忆索引全局共享
- * - new Agent() + 独立 dataDir 实现完全隔离的记忆空间
- *
- * @example
- * ```ts
- * const agent = new Agent({
- *   projectPath: '/path/to/project',
- *   provider: new OpenAIProvider({ apiKey: '...' }),
- *   configDir: '/path/to/config',
- *   dataDir: '/path/to/data',
- *   permission: 'owner',
- *   allowedPaths: ['/path/to/project'],
- * });
- * await agent.init();
- * const iter = agent.chat('你好');
- * for await (const chunk of iter) { ... }
- * ```
+ * 单 Agent，单配置，单记忆：每个实例拥有独立的对话管线、消息历史与运行时状态。
+ * 多实例只需 dataDir 不同即可彻底隔离记忆库与会话；forkSession() 分叉对话历史但记忆索引全局共享。
+ * skill 为当轮实时注入，不跨轮缓存。
  */
 export class Agent extends TypedEventEmitter {
     // 构造参数分组
@@ -85,108 +42,196 @@ export class Agent extends TypedEventEmitter {
     #provider;
     /** 后台 Provider（独立字段，因 setBackgroundProvider() 可变） */
     #backgroundProvider;
-    // 运行时组件（init 后填充）
+    /** Provider 路由选择器（多模型路由基础，可选） */
+    #providerRouter = null;
+    // 运行时组件（init 后填充）——宿主 getter 契约字段（projects/memory/works/polish/sessionManager 等）保持独立
     projectManager = null;
     history = null;
     loop = null;
     toolExec = null;
     // 新模块
-    personaManager = null;
-    #userProfile = null;
     skillManager = null;
+    /** 角色包管理器（角色+技能+规则的唯一真理源） */
+    _rolePackManager = null;
     // 拆分出的专职 Manager
-    insightExtractor = null;
-    configManager = null;
     memoryInspector = null;
-    workProjection = null;
-    /** AutoConfigRefiner（模式 3：Agent 智能总结） */
-    autoConfigRefiner = null;
-    /** SessionArchiver（会话内容归档器，content 类记忆） */
-    sessionArchiver = null;
+    /** 记忆治理统一门面（L0/L1/L2/L3 + 诊断） */
+    _governance = null;
     /** TextPolishManager（文本润色管理器，LLM 语法修正 + 表达优化） */
     textPolisher = null;
     /** 会话管理器（从 Agent 拆分出的会话管理职责） */
     _sessionManager = null;
-    /** 当前激活的技能名（上一轮匹配，本轮注入） */
-    activeSkill = null;
+    /** WorkProjectionManager（作品投影极简 JSON 索引，宿主经 works getter 消费） */
+    workProjection = null;
+    // ─── 纯内部组件聚合（无宿主 getter 契约，init 后填充、close 统一清空） ───
+    /**
+     * 内部组件聚合对象——收敛 12 个「仅门面内部消费、不对宿主暴露」的专职组件，
+     * 减少门面扁平字段数；宿主 getter 契约字段（memory/works/polish 等）不在此列。
+     */
+    internals = {
+        dedupManager: null,
+        memoryAdvisor: null,
+        sessionArchiver: null,
+        sessionNamer: null,
+        roundSummaryGenerator: null,
+        contextPreparer: null,
+        chatLockManager: null,
+        archiveCoordinator: null,
+        seedOrchestrator: null,
+        gcService: null,
+    };
     _initialized = false;
     // 项目上下文（AgentContext 与 ProjectContext 等价，直接使用后者避免重复字段）
     pctx = null;
-    /**
-     * chat() 并发锁管理器（init 时创建，close 时销毁）
-     *
-     * 职责：chat() 并发锁 + token 校验（race condition 防护）+ 超时保护 + 外部 signal 合并。
-     * 详见 ChatLockManager 类注释。
-     */
-    chatLockManager = null;
-    /** 记忆衰减定时器（已迁移至 MemoryDecayScheduler，此字段保留用于 close 时引用判断） */
-    decayTimer = null;
     /** 最近一次 chat() 调用的时间戳 */
     _lastInteractionAt = null;
-    // ─── 衰减职责已拆分至 MemoryDecayScheduler ──────────
-    // metricDecayRunCount / metricTotalDecayedCount / metricLastDecayAt 字段
-    // 位于 MemoryDecayScheduler 内部，Agent 通过 memoryDecayScheduler.getMetrics() 读取
-    /** 记忆衰减调度器（init 时创建，close 时销毁） */
-    memoryDecayScheduler = null;
-    /** 归档协调器（归档操作委托给 ArchiveCoordinator） */
-    archiveCoordinator = null;
+    /**
+     * 流活跃标志：chat()/resumeExecution() 的 AsyncGenerator 生命周期内置 true、finally 置 false。
+     * 与 chatLock.isBusy（并发锁，180s 超时后自动释放但**不中断生成流**）语义解耦——
+     * requestPause 空闲守卫必须用「流是否在产出」而非「锁是否持有」判任务是否结束，
+     * 否则长任务运行超锁期后点暂停会被误判为「任务已结束」——锁超时会自动释放但生成流仍在跑，
+     * 故判据只能是流活跃，不能是锁持有。
+     */
+    _flowActive = false;
+    /**
+     * 对话中因 chatLock 冲突暂存的配置重载请求（锁释放后补执行，兑现"对话后自动加载"）；
+     * 用 Set 去重——同一 source 只需补执行一次。
+     */
+    pendingConfigReload = new Set();
     constructor(opts) {
         super();
         this.#config = {
             projectPath: opts.projectPath,
-            dataDir: opts.dataDir ?? '~/.memora',
+            dataDir: opts.dataDir,
             registryDir: opts.registryDir,
             maxContextTokens: opts.maxContextTokens ?? AGENT_CONSTANTS.DEFAULT_MAX_CONTEXT_TOKENS,
-            personaName: opts.persona,
+            // per-LLM 输出预算默认值（token）：宿主 per-LLM 配置透传；undefined = 不传 max_tokens
+            //（回服务端默认）。与角色包策略 act.outputLimit 的最终关系由 buildChatOptions 取更小值。
+            maxTokens: opts.maxTokens,
             permission: opts.permission ?? 'owner',
             allowedPaths: opts.allowedPaths ?? [],
             confirmWrites: opts.confirmWrites ?? false,
-            vectorStore: opts.vectorStore,
-            recallExcludeSources: opts.recallExcludeSources ?? [
-                ...AGENT_CONSTANTS.DEFAULT_RECALL_EXCLUDE_SOURCES,
-            ],
+            confirmScripts: opts.confirmScripts ?? false,
             storage: opts.storage,
-            relationStore: opts.relationStore,
             sessionStore: opts.sessionStore,
+            roundStore: opts.roundStore,
             configDir: opts.configDir,
+            // 启动时激活的角色包名（宿主注入持久化值，init 时优先激活——§4.1 单链第一层）
+            activeRolePack: opts.activeRolePack,
+            // 组（宿主装配级）：组长角色包 + 组员名单（会议名单容器，非选择对象；组员仅会议参与）
+            // 内部运行态归一化必选（外部未配 = 无团队），保证装配链必传
+            rolePackTeams: opts.rolePackTeams ?? [],
+            // 程序级内置兜底角色（可选）：覆盖内核常量 BUILTIN_FALLBACK_PACK；须指向存在的包，否则回退内核常量
+            builtinFallbackRole: opts.builtinFallbackRole,
             tracer: opts.tracer,
             messages: opts.messages,
             enableContextSummary: opts.enableContextSummary ?? true,
             archiveMode: opts.archiveMode ?? 'full',
+            webSearchProvider: opts.webSearchProvider,
+            fetchProvider: opts.fetchProvider,
+            codeExecutionProvider: opts.codeExecutionProvider,
+            projectSearchProvider: opts.projectSearchProvider,
+            // 脚本执行 node 路径（可选）：宿主注入真实 node 路径，避免无独立 node 时 ENOENT
+            scriptNodePath: opts.scriptNodePath,
+            // 禁用技能清单（配置形态启停）：透传装配 → SkillManager 过滤 L1/L2/L3
+            disabledSkills: opts.disabledSkills ?? [],
+            // 宿主审批/审计/参数改写通道，透传供装配阶段与内部幂等检查组合为一处执行前检查点
+            preExecutionCheck: opts.preExecutionCheck,
+            // 宿主装配级策略覆盖（能力边界）：透传 #config → 装入策略解析链（resolveActiveStrategy），
+            // 压过角色包声明（v0.13 后无宿主注入默认值；机制保留供宿主产品能力边界使用）
+            strategyOverride: opts.strategyOverride,
         };
         this.#provider = opts.provider;
         this.#backgroundProvider = opts.backgroundProvider ?? null;
-        // 如需自定义日志，请在创建 Agent 前调用 `import { setLogger } from '@memora/core'` 全局设置
+        this.#providerRouter = opts.providerRouter ?? null;
+        // 如需自定义日志，请在创建 Agent 前调用 `import { setLogger } from '@zooique/memora'` 全局设置
     }
     // ─── 生命周期 ─────────────────────────────────────────
     /**
      * 初始化 Agent：加载索引、组装内部组件
      */
     async init(projectPathOverride) {
-        if (this._initialized) {
-            // close() 失败不应阻塞 init() 重建
-            // 原 close() 异常（如 awaitPendingArchives 超时）会传播到 init() 调用方，
-            // 导致 Agent 处于不可用状态。此处捕获后继续重建。
-            try {
-                await this.close();
-            }
-            catch (err) {
-                logger.warn({ err }, 'init() 中 close() 旧实例失败，继续重建');
-            }
-        }
+        await this.disposePreviousInstance();
         if (projectPathOverride) {
             this.#config.projectPath = projectPathOverride;
         }
+        const pctx = await this.initializeProject();
+        await this.assembleComponents(pctx);
+        this.pctx = pctx;
+        this.validateCoreComponents();
+        this.createPostInitComponents(pctx);
+        // 标记初始化完成
+        this._initialized = true;
+        // 注册暂停超时归档（同进程暂停超时：30min 无心跳则归档清理）
+        this.registerPauseTimeoutArchiver();
+        this.registerWorkProjectionRefresh();
+        // 注：不加载持久化检查点——中止/断电一律走
+        // 「中断轮补全为完整 turn 身份 → 参与下一轮」，不存在跨重启恢复；
+        // 运行时暂停是同 turn 内续跑（内存态），无需磁盘载体。
+        return pctx;
+    }
+    /**
+     * 登记作品投影实时刷新处理器：register_work 工具 / 右键登记成功后，
+     * 内核 WorkProjectionManager 触发 workProjectionGenerated 事件（携带已写入内存 entries 的投影），
+     * 立即重建 AgentLoop 的 systemPromptPrefix，使 AI 在下一轮对话即可感知新索引——
+     * 否则需切角色包 / reloadConfig / 开新会话才生效。
+     * 与 registerPauseTimeoutArchiver 同生命周期（init 内注册，close 的 removeAllListeners 兜底）。
+     */
+    registerWorkProjectionRefresh() {
+        this.on(AGENT_EVENTS.workProjectionGenerated, () => {
+            this.refreshRolePackPrefixOnLoop();
+        });
+    }
+    /**
+     * 注册暂停超时归档处理器（SessionManager 两条超时路径——启动加载与运行时定时器——统一在此消费）
+     * 注册在 init() 内（close() 的 removeAllListeners + init 起始的 disposePreviousInstance 保证实例周期内恰好一个监听器），
+     * 挂在生命周期稳定的 Agent 上，rebuildComponents() 重建管理器后仍有效。
+     */
+    registerPauseTimeoutArchiver() {
+        this.on(AGENT_EVENTS.sessionPauseTimedOut, (payload) => {
+            // pendingPauseReason 由 resetToRunning() 内部统一清理
+            //（checkPauseTimeout 经 sessionManager resetToRunning 已覆盖，此处无需再补 cancelPendingPause）。
+            const { sessionId, date, session } = payload;
+            if (!date || !session)
+                return;
+            // fire-and-forget：归档失败不阻塞主流程，仅记录
+            this.internals.archiveCoordinator
+                ?.archiveSession(date, session, { autoTriggered: true })
+                .catch((err) => {
+                logger.warn({ err, sessionId }, '暂停超时会话自动归档失败');
+            });
+        });
+    }
+    /**
+     * 关闭旧实例（如果已初始化），失败不阻塞重建
+     */
+    async disposePreviousInstance() {
+        if (!this._initialized)
+            return;
+        try {
+            await this.close();
+        }
+        catch (err) {
+            logger.warn({ err }, 'init() 中 close() 旧实例失败，继续重建');
+        }
+    }
+    /**
+     * 创建 ProjectManager 并初始化项目上下文
+     */
+    async initializeProject() {
         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, configDir ?? this.#config.configDir, agentDataDir ?? this.#config.dataDir),
+            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),
         });
-        const pctx = await this.projectManager.initProject(this.#config.projectPath, undefined, this.#config.configDir);
-        await this.assembleComponents(pctx);
-        this.pctx = pctx;
+        return this.projectManager.initProject(this.#config.projectPath, undefined, this.#config.configDir);
+    }
+    /**
+     * 校验核心组件（loop / history）非空
+     */
+    validateCoreComponents() {
         if (!this.loop || !this.history) {
             throw configError('Agent 初始化失败', '组件组装后 loop 或 history 为空（可能 assembleComponents 抛异常被静默吞掉）', [
                 '检查 assembleComponents() 是否有未捕获的异常',
@@ -194,406 +239,753 @@ export class Agent extends TypedEventEmitter {
                 '确认 API Key 已配置（环境变量或配置文件）',
             ]);
         }
+    }
+    /**
+     * 创建 init() 后期组件（初始化完成后才需要的组件）
+     */
+    createPostInitComponents(_pctx) {
         // chat() 并发锁管理器（生命周期与 Agent 实例一致）
-        this.chatLockManager = new ChatLockManager();
-        this._initialized = true;
-        // 归档操作委托给 ArchiveCoordinator
-        // 使用 getter 回调注入依赖，close 时 null 化字段后 getter 自然返回 null
-        this.archiveCoordinator = new ArchiveCoordinator({
-            getUserProfile: () => this.#userProfile,
-            getInsightExtractor: () => this.insightExtractor,
-            getSessionArchiver: () => this.sessionArchiver,
+        this.internals.chatLockManager = new ChatLockManager();
+        // 孤儿 Round 垃圾回收服务：roundStore+storage 均为构造期稳定注入（不随 rebuildComponents 变化），
+        // 每日周期清理 refCount=0 且超龄的孤立问答闭环（崩溃残留 pending / 已删会话遗留），防止存储膨胀。
+        // shouldSkip：对话进行中跳过本次（minAgeMs 判龄对长任务不可靠，防进行中轮被误清）
+        if (this.#config.roundStore && this.#config.storage) {
+            this.internals.gcService = createDefaultGCService(this.#config.roundStore, this.#config.storage, 
+            // 忙碌检查：chatLock busy = 对话/长任务进行中，跳过本次 GC
+            () => this.internals.chatLockManager?.isBusy ?? false);
+            this.internals.gcService.startPeriodic(AGENT_CONSTANTS.GC_INTERVAL_MS);
+        }
+        // 归档操作委托给 ArchiveCoordinator（content 会话归档）
+        this.internals.archiveCoordinator = new ArchiveCoordinator({
+            getSessionArchiver: () => this.internals.sessionArchiver,
+            getArchiveMode: () => this.#config.archiveMode,
             emit: (event, payload) => this.emit(event, payload),
         });
-        // 记忆衰减职责委托给 MemoryDecayScheduler
-        // L2 时效性评估：注入 backgroundProvider + index（可选，未注入时 evaluateTimeliness 静默跳过）
-        this.memoryDecayScheduler = new MemoryDecayScheduler({
-            tracer: this.#config.tracer,
-            onDecayCompleted: (payload) => {
-                this.emit('decayCompleted', payload);
-                // G2 自动触发 L2 时效性评估：衰减完成后 fire-and-forget 调用 evaluateTimeliness。
-                // 不 await：衰减循环不应被 LLM 调用阻塞（LLM 可能 5-15 秒）。
-                // 失败静默降级：evaluateTimeliness 内部已捕获 LLM 异常并返回降级报告。
-                // 触发频次：每小时 1 次（DECAY_INTERVAL_MS=3_600_000），无频次压力。
-                void this.evaluateTimeliness().catch((err) => {
-                    // 仅记录日志，不抛错（与 onDecayCompleted 回调语义一致：不阻塞衰减循环）
-                    logger.warn({ err }, 'L2 时效性评估自动触发失败（已降级，不影响衰减循环）');
-                });
+        // 会话命名器：新建会话首次问答自动命名标题；惰性获取当前 provider（切换后仍命中最新模型）
+        // 注入 onTitleUpdated 回调：标题生成后发射 sessionTitleUpdated 事件，宿主据此刷新 UI
+        this.internals.sessionNamer = new SessionNamer({
+            getProvider: () => this.#provider,
+            sessionStore: this.#config.sessionStore,
+            onTitleUpdated: (sessionId, title) => {
+                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）更换组件后仍取到最新引用。
+        this.internals.seedOrchestrator = this.createSeedOrchestrator();
+    }
+    /**
+     * 构造种子闭环编排器，注入门面稳定能力（getParts 快照 + 工具暴露 + 流收口协议）
+     *
+     * 构造偏好在 agent.ts 而非 assembler.ts（方案的"assembler 构造"）：seed 依赖
+     * sessionNamer（post-init 才创建）与 consumeExecutionStream（门面私有流收口协议），
+     * 二者均无法在 assembler 阶段就绪，故收敛到 post-init 门面组装处。
+     *
+     * @returns 已接线门面能力的 SeedOrchestrator
+     */
+    createSeedOrchestrator() {
+        return new SeedOrchestrator({
+            // 组件快照经 getter 惰性取当前引用：rebuildComponents 更换组件后仍读到最新（关键）
+            getParts: () => ({
+                loop: this.loop,
+                history: this.history,
+                sessionManager: this._sessionManager,
+                rolePackManager: this._rolePackManager,
+                contextPreparer: this.internals.contextPreparer,
+                sessionNamer: this.internals.sessionNamer,
+                roundSummaryGenerator: this.internals.roundSummaryGenerator,
+            }),
+            tracer: this.#config.tracer ?? null,
+            archiveMode: this.#config.archiveMode,
+            messages: this.#config.messages,
+            // 门面私有能力经回调注入 seed（物理实现仍在门面）
+            applyRolePackToolExposure: () => this.applyRolePackToolExposure(),
+            // 会议机制：按本轮表层装配视角刷新 loop 前缀（roundRole=null 回落 activePack）
+            refreshRolePackPrefixForRound: (roundRole) => this.refreshRolePackPrefixForRound(roundRole),
+            consumeExecutionStream: (source, signal) => this.consumeExecutionStream(source, signal),
+            getBackgroundProvider: () => this.#backgroundProvider,
+            // 宿主装配级策略覆盖（能力边界）：传给策略解析链，压过角色包声明（单一语义键不变）
+            strategyOverride: this.#config.strategyOverride,
+            // 事件发射回调：orchestrator.runSummary 完成后 emit roundSummaryGenerated，
+            // 让宿主感知后台摘要收口 → 解锁 UI 生命周期（删除/分叉按钮解禁，防孤儿记忆）
+            emit: (event, payload) => {
+                if (AGENT_EVENT_SET.has(event)) {
+                    this.emit(event, payload);
+                }
             },
-            backgroundProvider: this.#backgroundProvider,
-            index: pctx.index,
         });
-        this.memoryDecayScheduler.start(pctx.index, AGENT_CONSTANTS.DECAY_INTERVAL_MS);
-        // 保留 decayTimer 引用用于 close 时序兼容（实际定时器由 MemoryDecayScheduler 管理）
-        this.decayTimer = null;
-        return pctx;
     }
     /**
      * 流式对话（核心 API）
      */
     async *chat(input, signal) {
         this.assertInitialized('chat');
+        this.validateChatInput(input);
+        const lockCtx = this.acquireChatLock(signal);
+        const { myToken, combinedSignal, cleanupExternalSignal } = lockCtx;
+        try {
+            // 流活跃置位：requestPause 空闲守卫据此判「任务进行中」——锁 180s 超时释放后
+            // isBusy=false 但流仍在产出，必须以流生命周期（而非锁持有）为准（09-03 锁语义变更回归修补）
+            this._flowActive = true;
+            // 状态机翻转是副作用，必须在并发闸门内执行——PAUSED 态收到 chat = 自动恢复 + 继续（作为补充注入）；ERROR 态仍拒绝
+            if (!this.autoResumeIfPaused()) {
+                yield {
+                    type: 'error',
+                    message: '会话已超时，无法自动恢复，请重新开始新对话',
+                    category: 'timeout',
+                };
+                return;
+            }
+            this._lastInteractionAt = new Date();
+            // 委托种子编排器：对话路径完整闭环（prepare → act → reflect）
+            yield* this.internals.seedOrchestrator.runChat(input, combinedSignal);
+        }
+        finally {
+            // 流已退出：清除活跃标志（与置位对称；无论正常/异常退出都复位）
+            this._flowActive = false;
+            // 仅当本调用仍是当前锁持有者时才清理资源（token 校验）
+            this.internals.chatLockManager?.release(myToken);
+            cleanupExternalSignal();
+            // turn 结束自动收尾：非暂停态无条件清理任务表（turn 内能力，不跨 turn 残留）
+            this.clearPlanOnTurnEnd();
+            await this.flushPendingConfigReload();
+        }
+    }
+    /**
+     * 校验 chat 输入
+     */
+    validateChatInput(input) {
         if (input.length > AGENT_CONSTANTS.CHAT_INPUT_MAX_LENGTH) {
             throw configError('输入过长', `输入超过最大长度限制（${AGENT_CONSTANTS.CHAT_INPUT_MAX_LENGTH / 1024}KB）`, ['缩短输入内容', '分多次对话发送']);
         }
-        if (this.chatLockManager?.isBusy) {
+    }
+    /**
+     * 获取对话锁 — 返回锁上下文
+     */
+    acquireChatLock(signal) {
+        const chatLock = this.internals.chatLockManager;
+        if (!chatLock)
+            throw configError('ChatLockManager', 'ChatLockManager 未初始化', []);
+        if (chatLock.isBusy) {
             throw chatBusyError('发起新对话');
         }
-        // 获取锁 + 分配 token + 创建内部 AbortController + 启动超时定时器
-        // token 用于 finally 校验，避免 race condition：超时释放后新调用获取锁，旧 finally 误清新调用者的资源
-        // assertInitialized 已保证 chatLockManager/loop/history 非 null，此处用 ! 窄化类型
-        const chatLock = this.chatLockManager;
         const { token: myToken, internalAbort } = chatLock.acquire(AGENT_CONSTANTS.CHAT_LOCK_TIMEOUT_MS);
-        // 合并外部 signal：外部 abort 时也触发内部
         const cleanupExternalSignal = chatLock.attachExternalSignal(signal, internalAbort);
-        const combinedSignal = internalAbort.signal;
-        try {
-            this._lastInteractionAt = new Date();
-            // 清理上一轮注入的临时 system 消息（recentConversation/skill/recall/truncation）
-            // 防止多轮累积：每轮 chat() 开始前，只保留 messages[0] 和非 system 消息
-            const loop = this.loop;
-            loop.cleanTemporarySystemMessages();
-            // 基元驱动召回（双通道：语义 + 关键词）
-            yield { type: 'thinking', phase: 'recalling' };
-            const recalledMemories = await this.recallAndInject(input);
-            if (combinedSignal.aborted) {
-                yield {
-                    type: 'aborted',
-                    reason: this.#config.messages?.abortedByUser ?? 'User cancelled the conversation',
-                };
-                return;
-            }
-            // 注入上一轮匹配的技能 prompt
-            yield { type: 'thinking', phase: 'processing' };
-            this.injectActiveSkill();
-            const history = this.history;
-            await history.appendUser(input);
-            let assistantContent = '';
-            let wasAborted = false;
-            // 把 provider 异常转为 yield error chunk，让宿主能优雅展示并清理 UI
-            // （裸 throw 会导致未处理 rejection，UI 收不到错误展示机会）
-            try {
-                for await (const chunk of loop.processUserInput(input, recalledMemories, combinedSignal)) {
-                    yield chunk;
-                    if (chunk.type === 'text') {
-                        assistantContent += chunk.content;
-                    }
-                    else if (chunk.type === 'aborted') {
-                        wasAborted = true;
-                    }
-                }
-            }
-            catch (err) {
-                // aborted 已由 loop.ts 内部 yield chunk 处理，此处只捕获真正的异常
-                // （如 LLM 超时、连接断开、AbortError 未被 loop 拦截等）
-                // 转为 error chunk 通知宿主，避免裸 throw 导致 UI 卡死
-                if (err instanceof DOMException && err.name === 'AbortError') {
-                    // 必须 yield aborted chunk 让宿主能展示中断标记
-                    // （仅设置 wasAborted 会导致 chatHandlers catch 不触发，渲染层收不到 ABORTED）
-                    yield { type: 'aborted', reason: 'User cancelled the conversation' };
-                    return;
-                }
-                else {
-                    yield { type: 'error', message: err instanceof Error ? err.message : String(err) };
-                    return;
-                }
-            }
-            if (wasAborted) {
-                // 流式中断时仍保留已生成的部分文本到历史，避免下一轮上下文丢失
-                // 追加 interrupted 标记让下一轮 LLM 和历史归档能识别这是中断响应（非完整回复）
-                // 与下方正常路径一致采用 best-effort 写入（失败不影响中断流程）
-                if (assistantContent.trim()) {
-                    const interruptedMark = this.#config.messages?.interrupted ?? '\n\n[已中断]';
-                    try {
-                        await history.appendAssistant(assistantContent + interruptedMark);
-                    }
-                    catch (err) {
-                        logger.warn({ err }, '中断消息历史写入失败');
-                    }
-                }
-                return;
-            }
-            // 追加助手消息到历史（best-effort：失败不影响用户已收到的回答）
+        return { myToken, internalAbort, cleanupExternalSignal, combinedSignal: internalAbort.signal };
+    }
+    /**
+     * 补执行对话期间暂存的配置重载请求
+     */
+    async flushPendingConfigReload() {
+        if (this.pendingConfigReload.size === 0)
+            return;
+        const pending = Array.from(this.pendingConfigReload);
+        this.pendingConfigReload.clear();
+        for (const src of pending) {
             try {
-                await history.appendAssistant(assistantContent);
+                await this.reloadConfig(src);
+                this.emit(AGENT_EVENTS.configReloaded, { source: src });
             }
             catch (err) {
-                logger.warn({ err }, '助手消息历史写入失败');
+                logger.warn({ err, source: src }, '补执行配置重载失败');
             }
-            // 后处理阶段
-            yield { type: 'thinking', phase: 'archiving' };
-            await this.postProcess(input, assistantContent);
-        }
-        finally {
-            // 仅当本调用仍是当前锁持有者时才清理资源（token 校验）
-            // 若 token 已变（超时释放后被新调用者获取），跳过清理避免误清新调用者的状态
-            this.chatLockManager?.release(myToken);
-            cleanupExternalSignal();
         }
     }
     /**
      * 强制释放对话锁
      *
-     * 场景：宿主主进程"无进展超时"兜底后，generator 可能仍卡在不可中断的 await 点
-     *   （executeToolCalls 和 generateContextSummary 已覆盖 signal 响应，但其他
-     *   第三方库或未来新增的 await 点仍可能不响应 signal）。
-     *   此时 _chatBusy 锁未释放，用户再发消息会被 chat() 的竞态保护拒绝，
-     *   表现为"UI 能操作但发不出消息"，需等到 3 分钟锁超时才能恢复。
-     *
-     * 本方法让宿主在确认 generator 挂起后强制释放锁，让用户能立即发起新对话。
+     * 宿主在"无进展超时"确认 generator 挂起后调用，使用户能立即发起新对话（否则需等锁超时）。
+     * 安全机制委托 ChatLockManager.forceRelease：递增 token 让原 chat() 的 finally 跳过清理、abort signal 让响应点退出；
+     * 原 generator 仍可能后台运行但不影响新调用。幂等（未忙时 no-op）。
+     */
+    forceReleaseChatLock() {
+        this.internals.chatLockManager?.forceRelease();
+    }
+    /**
+     * 发送用户消息，非流式返回完整回复
+     */
+    async chatSync(input, signal) {
+        let result = '';
+        for await (const chunk of this.chat(input, signal)) {
+            if (chunk.type === 'text') {
+                result += chunk.content;
+            }
+        }
+        return result;
+    }
+    // ─── 不中断工作模型 v2.0：公开 API ──────────────────────
+    /**
+     * 软暂停后续跑（不中断工作模型 v2.1）
      *
-     * 安全机制（委托至 ChatLockManager.forceRelease）：
-     *   - 递增 _chatLockToken，让原 chat() 的 finally 块检测到 token 不匹配后
-     *     跳过资源清理（避免误清新调用者的 _chatBusy/chatAbortController）
-     *   - abort chatAbortController，让响应 signal 的 await 点（如 fetch）退出
-     *   - 原 generator 仍可能在后台运行（无法真正中断不响应 signal 的 await），
-     *     但其 finally 块的 token 校验会阻止它影响新调用
+     * 翻状态机为 RUNNING（触发 sessionResumed → 宿主转发 STATUS{running}），
+     * 驱动 loop.continueAfterPause 续跑并转发 chunk，完成后追加历史 + 后处理（同 chat 尾处理）。
+     * 硬停止（signal.abort）仍是唯一霸道中止路径，与软暂停严格区分。
      *
-     * 幂等性：_chatBusy 已 false 时 no-op（多次调用安全）
+     * 归属：补充输入归属当前问答闭环（复用 prepare 分配的闭环节点 roundId，不分裂新轮），
+     * 以 kind 区分交互类型（question-answer=主动提问回答 / supplement=暂停/流中补充）。
      *
-     * 使用约束：
-     *   - 仅在宿主确认 generator 挂起（如无进展超时）后调用
-     *   - 不应在常规 abort 路径调用（常规 abort 走 signal，generator 自然退出）
-     *   - 调用后不应再消费原 chat() generator 的后续 chunk（token 已变，chunk 无意义）
+     * @param input - 可选补充输入（空=续跑原路径；有=注入修正后续轮）
+     * @param signal - 可选 AbortSignal（硬停止仍走此路径）
+     * @param kind - 交互输入类型（默认 supplement；对主动提问的回答传 'question-answer'）
      */
-    forceReleaseChatLock() {
-        this.chatLockManager?.forceRelease();
+    async *resumeExecution(input, signal, kind = 'supplement') {
+        const resumeStatus = this._sessionManager?.status;
+        // 错误态续跑须明确失败而非静默吞没：error 态由检查点恢复回填进入，运行时异常走
+        // yield { type: 'error' } 不翻状态机，生产链路不会自然离开，必须显式提示重新开始
+        if (resumeStatus === 'error') {
+            this.emit(AGENT_EVENTS.sessionResumeFailed, {
+                sessionId: this._sessionManager?.getCheckpoint()?.sessionId,
+                reason: '会话处于错误态，无法续跑',
+            });
+            yield {
+                type: 'error',
+                message: '当前会话处于错误态，无法续跑，请重新开始',
+                category: 'unknown',
+            };
+            return;
+        }
+        if (resumeStatus !== 'paused')
+            return;
+        // resumeExecution 与 chat() 同构，必须加并发锁
+        const lockCtx = this.acquireChatLock(signal);
+        const { myToken, combinedSignal, cleanupExternalSignal } = lockCtx;
+        try {
+            // 流活跃置位：与 chat() 同构（requestPause 空闲守卫判据——续跑也是活跃流）
+            this._flowActive = true;
+            // 翻状态机为 RUNNING（触发 sessionResumed）
+            if (!this.resume()) {
+                // resume() 返回 false 时 yield error + 发事件，让宿主感知失败原因而非静默吞没
+                this.emit(AGENT_EVENTS.sessionResumeFailed, {
+                    sessionId: this._sessionManager?.getCheckpoint()?.sessionId,
+                    reason: 'resume() 返回 false，可能因暂停超时或状态机拒绝',
+                });
+                yield {
+                    type: 'error',
+                    message: '会话已超时，无法自动恢复，请重新开始新对话',
+                    category: 'timeout',
+                };
+                return;
+            }
+            // 预判短路（收窄）：仅「计划全部 blocked」才拦——blocked=真停滞，继续调 LLM
+            // 只会复读卡住状态、白烧 token。全 done / 无计划不再拦：用户主动点「继续」就是要 AI 产出
+            // （可能收尾总结、补建计划、继续语境），且短问答暂停续跑本就无计划，拦了就没法继续聊。
+            // 判定下沉 sessionManager.isPlanAllBlocked()（仅全 blocked 拦；全 done/空计划放行）。
+            if (!input &&
+                this._sessionManager?.isPlanAllBlocked() &&
+                !this.requireLoop.isInAutonomousStep) {
+                yield {
+                    type: 'text',
+                    content: '计划任务项当前全部处于阻塞状态，无法自动推进。请提供新指令或修改计划',
+                };
+                yield { type: 'done' };
+                return;
+            }
+            // 委托种子编排器：续跑路径闭环（act(continueAfterPause) → reflect；无回答前），
+            // 预判短路与锁/状态机守卫留在门面，执行语义收在编排器内。
+            yield* this.internals.seedOrchestrator.runResume(input, combinedSignal, kind);
+        }
+        finally {
+            // 流已退出：清除活跃标志（与置位对称；无论正常/异常退出都复位）
+            this._flowActive = false;
+            // 与 chat() 同构：释放锁 + 清理外部 signal
+            this.internals.chatLockManager?.release(myToken);
+            cleanupExternalSignal();
+            // 续跑轮（resumeExecution）是同一 turn 的收尾半程：turn 真正结束 → 与 chat() 同构，
+            // 无条件清空任务表（除非再次暂停——pauseMeta 由 loop 在边界重新挂起，guard 保留）。
+            // 必须无条件清：若仅全 done 才清，resume 以非 done 且未重暂停结束（如某任务项标 blocked
+            // 后收尾）时 plan 残留 → 跨 turn 污染下一个 chat()。
+            // 两处 turn-end 清理统一为 clearPlanOnTurnEnd（单一收口点），plan 严格 turn 内、不跨 turn 残留。
+            this.clearPlanOnTurnEnd();
+        }
     }
     /**
-     * 召回记忆 + 注入最近对话上下文
+     * 消费执行流的单一真理源
      *
-     * 从 chat() 中提取，职责：
-     *   1. 双通道召回（语义 + 关键词）
-     *   2. Layer 5: 最近对话注入
+     * chat() 与续跑（continueAfterPause）必须共用同一份消费逻辑——两份同构实现会漂移
+     * （实证：续跑漏 paused 分支导致三方分叉）；收口于此，新增 chunk 类型只需改一处。
+     * 暂停幂等锁的释放放 finally——清理是"退出本作用域的不变式"而非某分支动作，新增 return 分支无遗漏。
      *
-     * @param input 用户输入
-     * @returns 召回的记忆列表
-     */
-    async recallAndInject(input) {
-        // 实际 recall() 函数耗时 span（区别于 loop.ts 的 RECALL 注入 span）
-        const tracer = this.#config.tracer ?? NOOP_TRACER;
-        const recallSpan = tracer.startSpan(TRACE_SPANS.RECALL_ACTUAL, {
-            queryLength: input.length,
-            hasVectorStore: !!this.#config.vectorStore,
-        });
-        let recalledMemories = [];
+     * @returns 消费结果；failed 为 true 时调用方应立即 return（错误 chunk 已 yield）
+     */
+    async *consumeExecutionStream(source, signal) {
+        let content = '';
+        let aborted = false;
+        // 软暂停标记：loop 在 step 边界挂起（用户 requestPause / ask_user 主动提问）时置真，
+        // 供编排器据此推迟摘要——回合未完成不产摘要，保摘要与外部输入 1:1
+        let paused = false;
         try {
-            recalledMemories = await recall(this.pctx.index, input, {
-                limit: 5,
-                vectorStore: this.#config.vectorStore,
-                excludeSources: this.#config.recallExcludeSources,
-            });
+            for await (const chunk of source) {
+                // 内核事实驱动：loop 在 step 边界真正挂起时状态机才翻 PAUSED，非申请即翻转；
+                // 与 requestPause 空闲分支同源，须传 lowRisk=true 保持同一暂停事件契约（否则流中暂停计入连续暂停配额）
+                if (chunk.type === 'paused') {
+                    const pendingInfo = this._sessionManager?.consumePendingPause();
+                    // 暂停收口统一写 pauseMeta：reason/source 取自 pendingPause（与状态机一致）。
+                    // ask_user 主动提问等"直接暂停路径"不走 loop.onPaused，在此自然补齐，
+                    // 重启后宿主可展示"为什么暂停 + 问了什么"
+                    const pauseReason = pendingInfo?.reason ?? '用户主动暂停';
+                    const pauseSource = pendingInfo?.source ?? 'user';
+                    this.pause(pauseReason, pauseSource, true);
+                    this._sessionManager?.setPauseMeta({ reason: pauseReason, source: pauseSource });
+                    paused = true;
+                }
+                yield chunk;
+                // 累积 assistantContent 用于持久化到 history：只累积正常回答（stage≠self_review）。
+                // 自审查文本是内部思考过程——宿主渲染进 round-block § 自审查输出折叠区（不进正文流），
+                // 也不应持久化到会话历史（重启后不应在对话记录里看到自审查内容）。
+                // 注：loop.messages 里自审查 assistant 仍保留（LLM 下一轮迭代可能需参考），过滤只在持久化出口。
+                if (chunk.type === 'text' && chunk.stage !== 'self_review') {
+                    content += chunk.content;
+                }
+                else if (chunk.type === 'narrate' && chunk.withdrawn) {
+                    // 回抽：首轮工具步的叙述文本先作为 text 流式累积进正文（上面分支），
+                    // 确认工具轮后从**持久化正文**扣除——与宿主正文撤回同源（同一 withdrawn 字段，SSOT）。
+                    // 契约：该段为最近追加的正文文本（后缀）；不符（多 turn 复用流/异常序）则忽略并告警，
+                    // 宁可正文多一段叙述也不误删真实答案。
+                    if (content.endsWith(chunk.withdrawn)) {
+                        content = content.slice(0, content.length - chunk.withdrawn.length);
+                    }
+                    else {
+                        logger.warn({ withdrawnLen: chunk.withdrawn.length, contentLen: content.length }, 'narrate 回抽：持久化正文不含该段（后缀契约不符），已忽略');
+                    }
+                }
+                else if (chunk.type === 'aborted') {
+                    aborted = true;
+                }
+            }
         }
         catch (err) {
-            recallSpan.recordException(err instanceof Error ? err : new Error(String(err)));
-            throw err;
+            if (isAbortError(err)) {
+                // signal 已 abort（宿主/插话合并信号）→ 真用户取消：非失败——置 aborted 供 act() 走
+                // 「中断保留已产出文本」分支，半截回答落盘。
+                if (signal?.aborted) {
+                    // 锁超时中断（signal.reason=TimeoutError）≠ 用户取消：stopReason 区分，宿主映射超时文案
+                    yield {
+                        type: 'aborted',
+                        reason: isTimeoutAbortSignal(signal)
+                            ? 'LLM request timed out (no response)'
+                            : 'User cancelled the conversation',
+                        stopReason: isTimeoutAbortSignal(signal) ? 'timeout' : 'user',
+                    };
+                    return { content, aborted: true, paused, failed: false };
+                }
+                // signal 未 abort 却抛 AbortError → provider/网络内部中断（连接被抽断/代理异常）：
+                // 非用户取消，判为「连接中断」——与普通错误同归 error 分支，用结构化 category
+                // 标记连接中断（宿主按 category 映射友好文案），避免谎报为用户取消。
+                logger.warn({ err }, 'LLM 请求非用户取消原因中断，判为连接中断');
+                const raw = err instanceof Error ? err.message : String(err);
+                yield {
+                    type: 'error',
+                    // 连接中断分类：语义走 category 字段，不携带裸前缀；message 保留原始细节（调试/报错可追溯）
+                    category: 'connection',
+                    message: raw,
+                };
+                return { content, aborted, paused, failed: true };
+            }
+            // 超时（典型 = SSE 停摆看门狗 reject 的 DOMException TimeoutError）补结构化分类：
+            // 不补 → 宿主 `friendlyByCategory` 无键可映射 → 用户只能读到原始技术文案。
+            // 判据 SSOT = isTimeoutError（与上方 isTimeoutAbortSignal 同族，同一 name 判据、不同载体）。
+            // 注：非 abort 路径故不入 aborted 分支，它属「失败」并由本 catch 收口。
+            yield {
+                type: 'error',
+                ...(isTimeoutError(err) ? { category: 'timeout' } : {}),
+                message: err instanceof Error ? err.message : String(err),
+            };
+            return { content, aborted, paused, failed: true };
         }
         finally {
-            recallSpan.setAttribute('resultCount', recalledMemories.length);
-            recallSpan.end();
-        }
-        if (recalledMemories.length > 0) {
-            this.emit('memoryRecalled', { count: recalledMemories.length, query: input });
+            // 释放暂停幂等锁覆盖三路——残留会让 requestPause 的幂等检查永久拒绝后续暂停请求
+            this._sessionManager?.cancelPendingPause();
+            // 同步清理 loop 的 pause 申请（clearPauseRequest 委托 interruptQueue 过滤 kind='pause' 条目）
+            this.requireLoop.clearPauseRequest();
         }
-        // Layer 5: 最近对话注入
-        const loop = this.loop;
-        const recentHistory = loop.getRecentHistory(3);
-        if (recentHistory.length > 0) {
-            const msgs = this.#config.messages;
-            const label = msgs?.recentConversationLabel ?? '[Recent conversation]';
-            const userLabel = msgs?.userLabel ?? 'User';
-            const assistantLabel = msgs?.assistantLabel ?? 'Assistant';
-            const recentPrompt = `${label}\n` +
-                recentHistory
-                    .map((m) => `${m.role === 'user' ? userLabel : assistantLabel}：${m.content}`)
-                    .join('\n');
-            loop.injectSystemMessage(recentPrompt);
-            logger.debug({ turns: recentHistory.length / 2 }, '最近对话已注入');
-        }
-        return recalledMemories;
+        return { content, aborted, paused, failed: false };
     }
     /**
-     * 注入上一轮匹配的技能 prompt
+     * 暂停会话（用户/Agent/系统均可触发，暂停前自动创建检查点）
+     * @param lowRisk 低风险暂停不计入连续暂停计数（默认 false）
      */
-    injectActiveSkill() {
-        if (this.activeSkill && this.skillManager && this.loop) {
-            const skillPrompt = this.skillManager.buildSystemPrompt(this.activeSkill);
-            if (skillPrompt) {
-                this.loop.injectSystemMessage(skillPrompt);
-                logger.debug({ skill: this.activeSkill }, '技能 prompt 已注入');
-            }
-            this.activeSkill = null;
-        }
+    pause(reason, source = 'user', lowRisk = false) {
+        this.assertInitialized('pause');
+        return this.requireSessionManager.pause(reason, source, lowRisk);
     }
     /**
-     * 对话后处理：用户画像归档、角色匹配、技能匹配、Insight 提取
-     *
-     * 所有归档/匹配操作均为 best-effort：任何子步骤失败不应影响用户已收到的回答，
-     * 失败仅记录日志，不向上抛出异常。
+     * 恢复会话（从 PAUSED 恢复到 RUNNING）
+     */
+    resume() {
+        this.assertInitialized('resume');
+        return this.requireSessionManager.resume();
+    }
+    /**
+     * 自动恢复暂停状态（chat() 与续跑共用）：
+     * ERROR 态直接 throw（拒绝，须先 recover 保持状态一致）；PAUSED 态尝试自动恢复。
+     * 续跑（continueAfterPause）不走自动恢复，由独立的暂停恢复短路逻辑处理。
      *
-     * ADR-015 归档模式控制：
-     * - 角色匹配 + 技能匹配不受 archiveMode 影响（每轮都执行，非归档行为）
-     * - `manual` 模式跳过所有自动归档（profile + insight），需用户手动调用
-     *   archiveProfileFacts() / archiveInsight() 触发
-     * - `full` / `insights-only` 模式下 profile + insight 都自动归档
-     *   （会话归档实现后，`insights-only` 将跳过对话原始内容自动归档）
-     */
-    async postProcess(input, assistantContent) {
-        // postProcess 全流程 span（角色匹配 + 技能匹配 + 归档 + AutoConfigRefiner）
-        const tracer = this.#config.tracer ?? NOOP_TRACER;
-        const span = tracer.startSpan(TRACE_SPANS.POST_PROCESS, {
-            archiveMode: this.#config.archiveMode,
-        });
-        try {
-            await this.postProcessInner(input, assistantContent);
+     * @returns true=恢复成功或无需恢复；false=恢复失败（暂停超时等）
+     */
+    autoResumeIfPaused() {
+        const sm = this._sessionManager;
+        if (!sm)
+            return true;
+        const status = sm.status;
+        if (status === 'error') {
+            throw configError('会话异常', '会话处于异常状态，无法接收新消息', [
+                '先标记 error.recovered=true 并调用 agent.recover()',
+            ]);
         }
-        finally {
-            span.end();
+        if (status === 'paused') {
+            return this.resume();
         }
+        return true;
     }
     /**
-     * postProcess 内部实现（为 span 埋点提供 try/finally 包裹边界）
+     * 请求软暂停（不中断工作模型 v2.1）
+     *
+     * 经 sm.requestPause 暂存 pending（SessionStateMachine 是 pending 真理源）+ loop.pauseRequested
+     * 入 interruptQueue（在下一 step 边界挂起，不 abort）。
+     * 状态机翻 PAUSED 延后到 loop 边界真正挂起时——内核事实驱动而非申请即翻转；与硬停止（abort）严格区分，
+     * 软暂停保留历史、可经 resumeExecution 续跑。
      *
-     * 原 postProcess 逻辑完整保留于此，由外层 postProcess 负责 span 生命周期管理。
+     * @returns true=请求已注册（下一 step 边界生效）；false=无法暂停
      */
-    async postProcessInner(input, assistantContent) {
-        // 角色自动匹配（best-effort：失败不阻塞对话结束，非归档行为不受 archiveMode 影响）
-        // 两层匹配策略：关键词高置信度 → LLM 辅助（低置信度且 backgroundProvider 已注入时）
-        // LLM 辅助匹配在 agent 层执行，遵循 backend_layers_rules §分层职责（persona/ 不直接调 LLM）
-        if (this.personaManager) {
-            try {
-                let matchedPersona = null;
-                if (this.personaManager.canAutoMatch()) {
-                    matchedPersona = await this.personaManager.autoMatch(input);
-                    // 关键词低置信度且 backgroundProvider 已注入 → LLM 辅助语义匹配
-                    const bgProvider = this.#backgroundProvider;
-                    if (!matchedPersona && bgProvider) {
-                        matchedPersona = await matchPersonaByLlm(bgProvider, this.personaManager.list, this.personaManager.activeName, input);
-                    }
-                }
-                if (matchedPersona) {
-                    const prevName = this.personaManager.activeName;
-                    this.personaManager.switchPersona(matchedPersona);
-                    this.emit('personaSwitched', { from: prevName, to: matchedPersona });
-                    if (this.loop) {
-                        const profilePrompt = this.userProfile?.buildSystemPrompt() ?? '';
-                        const personaPrompt = this.personaManager.buildSystemPrompt();
-                        const newPrefix = [personaPrompt, profilePrompt].filter(Boolean).join('\n\n') +
-                            ([personaPrompt, profilePrompt].some(Boolean) ? '\n\n---\n\n' : '');
-                        this.loop.refreshPersonaPrefix(newPrefix);
-                    }
-                    logger.info({ persona: matchedPersona }, '角色自动切换');
-                }
-            }
-            catch (err) {
-                logger.warn({ err }, '角色自动匹配失败');
-            }
+    requestPause(reason, source = 'user') {
+        this.assertInitialized('requestPause');
+        const sm = this._sessionManager;
+        if (!sm)
+            return false;
+        // 状态机阻止：已暂停/已异常时禁止再申请暂停
+        const status = sm.status;
+        if (status === 'paused') {
+            logger.debug('requestPause 忽略：会话已处于暂停状态');
+            return false;
         }
-        // 技能关键词匹配（best-effort：失败不阻塞对话结束，非归档行为不受 archiveMode 影响）
-        if (this.skillManager) {
-            try {
-                const match = this.skillManager.match(input);
-                if (match) {
-                    this.activeSkill = match.skill.name;
-                    // 发射 skillMatched 事件：宿主 UI 可据此展示当前激活技能
-                    this.emit('skillMatched', { skill: match.skill.name, score: match.score });
-                    logger.debug({ skill: match.skill.name, score: match.score }, '技能匹配，下一轮注入');
-                }
-            }
-            catch (err) {
-                logger.warn({ err }, '技能匹配失败');
-            }
+        if (status === 'error') {
+            logger.debug('requestPause 忽略：会话处于异常状态，无法暂停');
+            return false;
         }
-        // ADR-015: manual 模式跳过所有自动归档（profile + insight），
-        // 需用户手动调用 archiveProfileFacts/archiveInsight 触发。
-        // 角色匹配/技能匹配/AutoConfigRefiner 属"配置学习"行为，非归档，每轮都执行。
-        const skipAutoArchive = this.#config.archiveMode === 'manual';
-        if (skipAutoArchive) {
-            logger.debug({ mode: 'manual' }, '归档模式为 manual，跳过自动归档');
+        // 空闲守卫：无活跃流时暂停无消费方——若此时同步翻状态机并落盘 checkpoint，
+        // 「turn 已完成后的暂停」会把会话钉在 paused，后续新输入被宿主路由成
+        // supplement（新意图被吞成"上一个回答的补充"，毒化闭环节点；loop 无流消费的延迟翻转亦无意义）。
+        // 任务已结束 = 暂停申请作废，返回 false 供宿主明确反馈；系统/Agent 触发（ask_user/drift）均在
+        // 流中（_flowActive=true）不经过此分支，不受影响。
+        // ⚠ 判据必须用 _flowActive（流活跃）而非 chatLock.isBusy（锁持有）——chatLock 锁
+        // 180s 超时后自动释放（不中断生成流），长任务运行超锁期后 isBusy=false 但流
+        // 仍在产出，用锁判据会把「进行中的暂停申请」误作废成「任务已结束」；_flowActive 由 chat()/resumeExecution()
+        // 的流生命周期显式维护，与锁超时无关，是「任务是否仍在运行」的准确判据。
+        if (!this._flowActive) {
+            logger.debug({ reason, source }, 'requestPause 空闲守卫：任务已结束，暂停申请作废');
+            return false;
         }
-        // 用户画像实时归档（委托 ArchiveCoordinator，与手动归档路径统一，消除 DRY 违反）
-        // ADR-015: full / insights-only 模式下 profile facts 自动归档
-        const history = this.history;
-        if (!skipAutoArchive) {
-            try {
-                // fire-and-forget 包装：registerPendingArchive 确保 close() 时等待后台归档完成
-                // 失败时发射 archiveFailed 事件，让宿主 UI 可通知用户（而非静默吞没）
-                const archiveFactsPromise = this.archiveCoordinator.archiveProfileFacts(input).then(() => { }, (err) => {
-                    const message = err instanceof Error ? err.message : String(err);
-                    logger.warn({ err, stage: 'profile' }, '归档失败');
-                    this.emit('archiveFailed', { stage: 'profile', message: message.slice(0, 200) });
-                });
-                history.registerPendingArchive(archiveFactsPromise);
-            }
-            catch (err) {
-                logger.warn({ err }, '用户画像归档初始化失败');
-            }
+        // 委托 SessionStateMachine 管理 pending 暂停状态（含幂等检查）
+        if (!sm.requestPause(reason, source)) {
+            logger.debug('requestPause 忽略：已有待处理的暂停请求');
+            return false;
         }
-        // 输入分类 → Insight 提取（委托 ArchiveCoordinator，与手动归档路径统一）
-        // ADR-015: full / insights-only 模式下 insight 自动归档
-        if (!skipAutoArchive) {
-            try {
-                // fire-and-forget 包装：classify 判断由 ArchiveCoordinator 内部完成
-                // 失败时发射 archiveFailed 事件，让宿主 UI 可通知用户（而非静默吞没）
-                const archiveInsightPromise = this.archiveCoordinator.archiveInsight(input, assistantContent).then(() => { }, (err) => {
-                    const message = err instanceof Error ? err.message : String(err);
-                    logger.warn({ err, stage: 'insight' }, '归档失败');
-                    this.emit('archiveFailed', { stage: 'insight', message: message.slice(0, 200) });
-                });
-                history.registerPendingArchive(archiveInsightPromise);
-            }
-            catch (err) {
-                logger.warn({ err }, 'Insight 提取初始化失败');
-            }
+        this.requireLoop.requestPause();
+        return true;
+    }
+    /**
+     * 取消待处理的软暂停请求：清空 loop 的 pauseRequested 标志（与 requestPause 对称），
+     * 并同步清理 SessionStateMachine 的 pending 暂停状态。
+     */
+    cancelPauseRequest() {
+        this.assertInitialized('cancelPauseRequest');
+        this.requireLoop.clearPauseRequest();
+        this._sessionManager?.cancelPendingPause();
+    }
+    /**
+     * 是否存在待处理的暂停申请（申请已发、尚未在 loop 边界挂起）
+     *
+     * 供宿主 UI 区分三态：无申请（暂停）/ 申请在途（取消暂停）/ 已暂停（继续）。
+     * 状态真理源 SessionStateMachine.isPausePending()：流中 requestPause 置位、边界挂起后 consumePendingPause 消费、
+     * cancelPauseRequest 主动清理；空闲态由 requestPause 空闲守卫作废（见上，return false 不触达状态机）——
+     * isPausePending 仅在流中「申请在途」时为 true（空闲态不翻 PAUSED）。
+     */
+    isPausePending() {
+        return this._sessionManager?.isPausePending() ?? false;
+    }
+    /**
+     * 放弃当前暂停检查点（宿主 stop 语义的内核出口）
+     *
+     * 与 pause() 对称：pause 创建检查点；discardCurrentCheckpoint 销毁检查点。
+     * 宿主 handleStop 在 paused 态调用——用户决定彻底放弃暂停执行，不再 resume。
+     *
+     * 除转发 SessionManager.discardCheckpoint（清内存 + 状态机 resetToRunning——检查点不落盘，无存储清理动作），
+     *  还须协同 loop.clearPendingInterjections() 清排队插话——pause 生效时 step 边界优先返回不消费 queue，
+     *  只清 checkpoint 会留孤儿 queue，下次 chat() 首个 step 误消费残留（坑）。
+     *  返回值以 checkpoint 清理为主（queue 有残留不判失败）。
+     * @returns true=成功清理；false=无暂停检查点（空闲态调了个空）
+     */
+    discardCurrentCheckpoint() {
+        this.assertInitialized('discardCurrentCheckpoint');
+        // 协同清理暂停上下文的两个组成部分：checkpoint（内存态暂停点，不落盘）+ pendingInterjections（排队插话）
+        //  暂停上下文 = checkpoint + queue，stop 语义下两者必须同清，不留孤儿
+        const checkpointCleared = this._sessionManager?.discardCheckpoint() ?? false;
+        // queue 清理独立：即使 checkpoint 已不存在（空闲态调），残留 queue 也应顺手清掉
+        const queueCleared = this.loop?.clearPendingInterjections() ?? 0;
+        if (queueCleared > 0) {
+            logger.info({ count: queueCleared }, 'discardCheckpoint 协同清理残留 pendingInterjections');
         }
-        // AutoConfigRefiner（模式 3：Agent 智能总结）
-        if (this.autoConfigRefiner) {
-            try {
-                // 注册到 pendingArchives，确保 close() 时等待后台分析完成，避免写入已关闭的存储
-                const analyzePromise = this.autoConfigRefiner.analyze(input, assistantContent).catch((err) => {
-                    logger.warn({ err }, 'AutoConfigRefiner 分析失败');
-                });
-                history.registerPendingArchive(analyzePromise);
-            }
-            catch (err) {
-                logger.warn({ err }, 'AutoConfigRefiner 初始化失败');
-            }
+        return checkpointCleared;
+    }
+    /**
+     * 执行中插话（申请）：把用户补充输入排队，当前 step 完成后在 step 边界统一注入为 user 消息。
+     *
+     * 与 requestPause（step 边界挂起待续跑）同为「申请 → 气口生效」——不中断当前 LLM/工具执行，
+     * 只在边界拿到补充输入后开始下一轮 step。插话是唯一写入口（interject → pendingInterjections 排队），
+     * 无「立即中断」模式：只有单一申请模式（无 inputInterrupt 立即中断通道）。
+     *
+     * 归属：插话同时以「补充」交互输入持久化到当前闭环节点（interactiveInputs），
+     * 保证跨重启重放时插话内容不丢失、不分裂新轮。持久化 fire-and-forget（appendUser 内部
+     * 已 catch 写入失败，仅记日志），不阻塞插话本身。
+     */
+    interject(content) {
+        this.assertInitialized('interject');
+        // 持久化插话为闭环节点交互补充输入（roundId 非空时才写；空=无在途闭环，跳过）
+        const closureRoundId = this.loop?.getCurrentRoundId();
+        if (closureRoundId) {
+            void this.history?.appendUser(content, closureRoundId, {
+                interactive: true,
+                kind: 'supplement',
+            });
         }
+        this.requireLoop.interject(content);
+    }
+    /**
+     * 删除待注入的插话（宿主 UI 层用户后悔）。与 interject 对称。
+     * 注意：interject 时已持久化到 history（交互输入归属），此处只从内核队列移除，不删除已落盘记录——
+     * 未来若需完整"撤回"需额外方案（如软删标记），当前先保证 step 边界不会注入已删除的补充。
+     * @param index 要删除的插话在队列中的位置（宿主镜像数组与内核队列同序同长度）
+     * @returns true=成功删除；false=index 越界或队列为空
+     */
+    removePendingInterject(index) {
+        this.assertInitialized('removePendingInterject');
+        return this.requireLoop.removePendingInterject(index);
+    }
+    /**
+     * 清空全部待注入插话（宿主「全部清空」按钮触发，或 stop→discard 协同清理）。
+     *
+     * 逻辑下沉 loop.clearPendingInterjections 原子方法——清队列唯一入口在内核，
+     *  宿主不维护队列镜像，避免镜像与内核双写不一致；discardCurrentCheckpoint 经同一方法协同清理。
+     *  @returns 被清除的条目数（宿主可用于 notice 反馈；无队列时返回 0）
+     */
+    clearPendingInterjections() {
+        this.assertInitialized('clearPendingInterjections');
+        return this.requireLoop.clearPendingInterjections();
+    }
+    /**
+     * 读取当前待注入插话队列快照（宿主渲染层只读镜像，不修改内核状态）。
+     * 返回副本，宿主无法暗改内核 queue；宿主渲染直接读本快照，不另维护队列镜像。
+     */
+    getPendingInterjections() {
+        this.assertInitialized('getPendingInterjections');
+        return this.requireLoop.getPendingInterjections();
+    }
+    /**
+     * 放弃在途主动提问（ask_user 工具挂起后，宿主「跳过/取消提问」时调用）：
+     * 委托 loop.cancelAsk 补占位 tool 结果（防 assistant.tool_calls 无配对 → 400），
+     * 随后 resumeExecution() 续跑。与 answerQuestion 二选一消费在途提问。
+     */
+    cancelAsk() {
+        this.assertInitialized('cancelAsk');
+        this.requireLoop.cancelAsk();
+    }
+    /**
+     * 回答在途主动提问（ask_user 工具）：
+     * 答案以 ask_user 的 tool result 回填（与 assistant.tool_calls 配对，结构合法）。
+     * 调用后宿主以 resumeExecution(回答文本, undefined, 'question-answer') 续跑——
+     * 回答文本同时作为新 user 输入注入并记录为闭环节点交互输入（round 不分裂），
+     * 与既有续跑主流程一致（本方法只负责结构化回填，不做历史记录，避免双写）。
+     * 返回 false 表示无在途提问（提供方未调用 / 已消费）。
+     */
+    answerQuestion(answers) {
+        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);
+    }
+    /**
+     * 卸载运行态挂载物：清空检查点计划与任务项推进日志（宿主任务流结束/停止/异常广播 idle 前调用），
+     * 回到"空闲 = 无挂载物"的资源层常态；会话历史与记忆等资源层内容不受影响。
+     */
+    clearPlan() {
+        this.assertInitialized('clearPlan');
+        this.requireSessionManager.clearPlan();
+    }
+    /**
+     * turn 结束自动收尾：非暂停态 → 无条件 clearPlan（任务表收紧为 turn 内能力，不跨 turn 残留）。
+     *
+     * 任务表生命周期 = 单个 turn：LLM 在 turn 内编排并完成任务表；chat() 流退出（turn 真正结束）
+     * 时，无论任务项是否全部标记完成，都清空运行时挂载物（checkpoint.plan 与 planItemLog）。这样：
+     * ① 宏任务一个 turn 完不成 → 本 turn 结束兜底丢弃，下个 turn 由 LLM 重新规划全新任务表；
+     * ② 续跑轮（resumeExecution = ask_user 问答/暂停补充）是同一 turn 的闭环收尾，与 chat() 同构
+     * 走本方法——turn 真正结束即无条件清空，chat() 与续跑轮共用本收口点。
+     *
+     * 唯一例外是暂停态（pauseMeta）：turn 尚未真正结束，暂停恢复后要继续用 plan 推进，
+     * 故保留不清；恢复完成后该 turn 最终退出时仍会走本方法无条件清空。
+     *
+     * 运行时状态（plan/planItemLog）清空，但对话记录里的 round-block 折叠块已沉淀为历史（不落盘删除）。
+     * 挂点：chat() 与 resumeExecution 的 finally 块（generator close 时触发，确保所有 yield 已被宿主消费）
+     */
+    clearPlanOnTurnEnd() {
+        const sm = this._sessionManager;
+        if (!sm)
+            return;
+        const cp = sm.getCheckpoint();
+        if (!cp?.plan || cp.plan.length === 0)
+            return;
+        if (cp.pauseMeta)
+            return; // 暂停态：turn 未真正结束，恢复时需继续用 plan，保留不清
+        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 已解除）
      */
-    async chatSync(input, signal) {
-        let result = '';
-        for await (const chunk of this.chat(input, signal)) {
-            if (chunk.type === 'text') {
-                result += chunk.content;
-            }
+    recover() {
+        this.assertInitialized('recover');
+        return this.requireSessionManager.recover();
+    }
+    /**
+     * 创建会话检查点：快照当前运行时状态（热记忆等），生成纯内存态快照
+     * （不落盘、无序列化/恢复路径——中止/断电走「中断轮补全为完整 turn」）。
+     * 无 role/standard 会话能力位，createCheckpoint 仅收 mainGoal。
+     */
+    createCheckpoint(mainGoal) {
+        this.assertInitialized('createCheckpoint');
+        return this.requireSessionManager.createCheckpoint(mainGoal);
+    }
+    /**
+     * 获取当前检查点
+     */
+    getCheckpoint() {
+        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 }));
+    }
+    /**
+     * 向 loop 注入 system 消息
+     */
+    injectSystemMessage(message) {
+        this.requireLoop.injectSystemMessage(message);
+    }
+    /**
+     * 从指定 Round 位置分叉当前会话（委托至 SessionManager）：
+     * round-based 模式唯一分叉方式——创建新会话，复制 Round ID 列表（指针复制），
+     * 新会话是完全平等的普通会话。记忆索引全局共享不受影响。
+     *
+     * 自动命名场景（未传 targetSession）：分叉后异步触发 SessionNamer 为新会话生成标题
+     * （best-effort，不阻塞分叉返回）；用户显式指定会话名时尊重用户命名，不触发 LLM 覆盖。
+     *
+     * @param roundId - 分叉点的 Round ID（可选；不传默认使用最后一个 Round）
+     * @param targetSession - 可选，自定义新会话名
+     */
+    forkSession(roundId, targetSession) {
+        this.assertInitialized('forkSession');
+        const result = this.requireSessionManager.forkSession(roundId, targetSession);
+        // 分叉会话首轮命名：仅自动命名（未传 targetSession）时触发，
+        // 以分叉点首轮用户消息为标题依据（与新会话首次问答命名同源语义）
+        if (!targetSession) {
+            void this.ensureForkSessionTitle(result).catch((err) => {
+                logger.debug({ err, session: result.newSession }, '分叉会话首轮命名失败（best-effort，不影响分叉结果）');
+            });
         }
         return result;
     }
     /**
-     * 分叉当前会话（委托至 SessionManager）
+     * 分叉会话首轮命名（best-effort，fire-and-forget）
      *
-     * 分叉后原会话完整保留，新分支拥有独立消息历史。
-     * 记忆索引（IMemoryStorage）全局共享，不受分叉影响。
+     * 分叉新会话是平等普通会话，自动命名（未提供 targetSession）时应拥有 LLM 生成的语义标题。
+     * 取新会话第一个 Round 的用户消息作为命名输入（分叉点即新会话起点，语义=首轮问答）；
+     * SessionNamer 内部已有 autoName 存在即跳过（幂等），LLM 失败/无价值降级占位标题。
+     *
+     * @param result - 分叉结果（含新会话名/日期/Round 列表）
      */
-    forkSession(targetSession) {
-        this.assertInitialized('forkSession');
-        return this._sessionManager.forkSession(targetSession);
+    async ensureForkSessionTitle(result) {
+        const namer = this.internals.sessionNamer;
+        if (!namer) {
+            logger.debug('ensureForkSessionTitle: sessionNamer 未创建，跳过分叉会话命名');
+            return;
+        }
+        const roundStore = this.#config.roundStore;
+        const firstRoundId = result.roundIds[0];
+        if (!roundStore || !firstRoundId) {
+            logger.debug({ hasRoundStore: !!roundStore }, 'ensureForkSessionTitle: 无 RoundStore/新会话为空，跳过');
+            return;
+        }
+        // 分叉点首轮用户消息 = 新会话的"首条消息"，作为标题生成输入
+        const firstRound = roundStore.getById(firstRoundId);
+        const firstUserContent = firstRound?.userMessage?.content;
+        if (!firstUserContent) {
+            logger.debug({ roundId: firstRoundId }, 'ensureForkSessionTitle: 首轮无用户消息，跳过');
+            return;
+        }
+        await namer.ensureSessionTitle(result.date, result.newSession, firstUserContent);
     }
     /**
-     * 切换到指定项目
+     * 切换到指定项目：切换后自动 rebuildComponents()；Agent 级记忆存储（宿主注入，实例不随项目切换重建）保留，项目级配置（.memora/）重新加载
      *
-     * 切换后自动 rebuildComponents()，无需手动调用。
-     * Agent 级记忆（memora.db）保留，项目级配置（.memora/）重新加载。
+     * `nameOrPath` 只接受两种输入：① 项目注册表中的项目名（依赖注册表跨项目共享，见 dataDir/registryDir）；
+     * ② 项目根目录的**绝对路径**。二者都不满足时抛 configError——否则相对串会以 process.cwd()
+     * 为基准解析，静默造出非预期的项目目录并占用其锁。
      */
     async switchProject(nameOrPath) {
         this.assertInitialized('switchProject', ['projectManager', 'provider']);
         // 对话进行中切换项目会导致 loop/history 引用被替换，工作记忆与持久化状态不一致
-        if (this.chatLockManager?.isBusy) {
-            throw chatBusyError('切换项目');
-        }
+        this.assertNotBusy('切换项目');
         const pm = this.projectManager;
         const projects = pm.list;
         let target = projects.find((p) => p.name === nameOrPath || p.path === nameOrPath);
@@ -601,15 +993,34 @@ export class Agent extends TypedEventEmitter {
             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;
-        this.pctx = newPctx;
-        await this.rebuildComponentsWithCurrentCtx();
+        // 先尝试重建组件，失败时回滚 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('projectSwitched', {
+        this.emit(AGENT_EVENTS.projectSwitched, {
             from: fromProjectPath,
             to: projectPath,
             projectName,
@@ -618,246 +1029,384 @@ export class Agent extends TypedEventEmitter {
     }
     // ─── 组件组装 ─────────────────────────────────────────
     /**
-     * 组装所有运行时组件（委托给 assembler 工厂）
+     * 组装所有运行时组件（一行委托给 assembler 工厂）
+     *
+     * 接线回调（工具幂等 outbox / 任务表 / loop 回调 / createSessionManager）与装配私有状态
+     * （暂存队列 / 停滞计数器）全部由 assembler 组装收口——Agent 只注入稳定能力（hooks）。
      */
     async assembleComponents(pctx) {
         const result = await assembleComponents(pctx, {
             provider: this.provider,
             backgroundProvider: this.#backgroundProvider,
+            providerRouter: this.#providerRouter,
             projectPath: this.#config.projectPath,
             configDir: this.#config.configDir,
-            personaName: this.#config.personaName,
+            activeRolePack: this.#config.activeRolePack,
+            // 组数据（宿主装配级）：组长角色包 + 组员名单（会议名单容器）
+            rolePackTeams: this.#config.rolePackTeams,
             maxContextTokens: this.#config.maxContextTokens,
+            // per-LLM 输出预算默认值：透传组装器 → AgentLoop.defaultMaxTokens（buildChatOptions 填底座）
+            maxTokens: this.#config.maxTokens,
             sessionStore: this.#config.sessionStore,
-            relationStore: this.#config.relationStore,
+            roundStore: this.#config.roundStore,
             tracer: this.#config.tracer,
             messages: this.#config.messages,
             enableContextSummary: this.#config.enableContextSummary,
+            webSearchProvider: this.#config.webSearchProvider,
+            fetchProvider: this.#config.fetchProvider,
+            codeExecutionProvider: this.#config.codeExecutionProvider,
+            projectSearchProvider: this.#config.projectSearchProvider,
+            // 脚本执行 node 路径（可选）：透传装配 → toolExecutor/assembler 脚本执行回调
+            scriptNodePath: this.#config.scriptNodePath,
+            // 禁用技能清单：透传装配 → SkillManager.setDisabledSkills
+            disabledSkills: this.#config.disabledSkills,
             existingSkillManager: this.skillManager,
+            // 策略覆盖不经组装器：AssembleInput 零消费，真实消费链 = 本类
+            // 构造 SeedOrchestrator deps 时直传（见 #createSeedOrchestrator 的 strategyOverride），
+            // 经 resolveActiveStrategy 压过角色包声明——策略解析唯一链在 seed 侧。
+            // Agent 稳定能力（emit/守卫/暂停/角色切换）：接线下沉后仅传能力，接线语义在组装器唯一实现
+            hooks: {
+                // 桥接 SessionManager 宽类型事件到 Agent 强类型 emit（校验事件名在 AgentEventMap 内，避免不安全断言）
+                emit: (event, data) => {
+                    if (AGENT_EVENT_SET.has(event)) {
+                        this.emit(event, data);
+                    }
+                },
+                isChatBusy: () => this.internals.chatLockManager?.isBusy ?? false,
+                requestPause: (reason, source) => {
+                    this.requestPause(reason, source);
+                },
+                preExecutionCheck: this.#config.preExecutionCheck,
+                // 检查点恢复协议角色契约重注入 → Agent 生命周期（工具暴露面 / loop 前缀刷新）
+                applyRolePackToolExposure: () => this.applyRolePackToolExposure(),
+                refreshRolePackPrefixOnLoop: () => this.refreshRolePackPrefixOnLoop(),
+                // 会议逐项切换：随 active 任务项刷新本轮装配视角
+                applyActivePlanItemAssembly: () => this.applyActivePlanItemAssemblyIfChanged(),
+            },
         });
         this.history = result.history;
         this.loop = result.loop;
+        // 有效窗口变更 → 同步 ContextPreparer。有效窗口的**唯一计算点在 loop**
+        // （min(provider 窗口, 角色包 contextLimit)），此处只做分发；用闭包读最新
+        // internals.contextPreparer，避免与装配顺序耦合。
+        this.loop.onContextWindowChanged = (effectiveTokens) => {
+            this.internals.contextPreparer?.setMaxContextTokens(effectiveTokens);
+        };
         this.toolExec = result.toolExec;
-        this.personaManager = result.personaManager;
-        this.#userProfile = result.userProfile;
         this.skillManager = result.skillManager;
-        this.insightExtractor = result.insightExtractor;
-        this.configManager = result.configManager;
+        this._rolePackManager = result.rolePackManager;
+        // 角色包切换锁定事件：rolePackManager 触发锁定时，Agent 向宿主发射 rolePackSwitchLocked 事件
+        this._rolePackManager.onRolePackSwitchLocked((reason, lockedSeconds) => {
+            this.emit(AGENT_EVENTS.rolePackSwitchLocked, { reason, lockedSeconds });
+        });
         this.memoryInspector = result.memoryInspector;
-        this.autoConfigRefiner = result.autoConfigRefiner;
+        this.internals.dedupManager = result.dedupManager;
+        this.internals.memoryAdvisor = result.memoryAdvisor;
         this.workProjection = result.workProjection;
-        this.sessionArchiver = result.sessionArchiver;
+        this.internals.sessionArchiver = result.sessionArchiver;
         this.textPolisher = result.textPolisher;
-        // 绑定冲突检测回调，InsightExtractor 检测到 contradicts 时 emit('conflictDetected')
-        // 与 bindGetRecentHistory 同模式：解决 Agent 晚于 InsightExtractor 创建的时序循环依赖
-        this.insightExtractor.bindOnConflict((info) => {
-            this.emit('conflictDetected', info);
-        });
-        // 注入 VectorStore 到 MemoryInspector，启用混合搜索
-        if (this.memoryInspector && this.#config.vectorStore) {
-            this.memoryInspector.setVectorStore(this.#config.vectorStore);
+        this.internals.roundSummaryGenerator = result.roundSummaryGenerator;
+        // 会话管理器由组装器创建（先于 loop），Agent 直接持有
+        this._sessionManager = result.sessionManager;
+        // 输入增强管线由组装器创建，Agent 只保留编排调用点
+        this.internals.contextPreparer = result.contextPreparer;
+    }
+    // ─── Provider 管理 ────────────────────────────────────
+    setProvider(provider) {
+        // 对话中切换会导致同循环内前后两次 LLM 调用命中不同 Provider（上下文窗口假设/工具格式不一致）
+        this.assertNotBusy('切换 Provider');
+        this.#provider = provider;
+        if (this.loop) {
+            this.loop.setProvider(provider);
         }
-        // 创建会话管理器（提取 createSessionManager 辅助方法，消除重复）
-        this._sessionManager = this.createSessionManager();
+        logger.info({ provider: this.#provider.name }, 'Provider 已切换');
     }
     /**
-     * 用当前 pctx 重建 history / loop
+     * 运行时更新上下文窗口上限（token）
+     *
+     * 模型热切换配套：同步三处装配期值拷贝（loop 截断/软上限、ContextManager 阈值、
+     * ContextPreparer 预算与占用快照），全部对新窗口即刻生效。对话进行中禁止更新
+     * （与 setProvider 同守卫）。
+     *
+     * @param tokens 新窗口 token 数
      */
-    async rebuildComponentsWithCurrentCtx() {
-        if (!this.pctx)
-            return;
-        await this.assembleComponents(this.pctx);
-        // 重建会话管理器：assembleComponents 创建了新的 history/loop 实例（复用 createSessionManager）
-        this._sessionManager = this.createSessionManager();
+    setContextWindow(tokens) {
+        this.assertNotBusy('切换上下文窗口');
+        this.#config.maxContextTokens = tokens;
+        if (this.loop) {
+            // loop 内部按 min(provider 窗口, 角色包 contextLimit) 重算**有效窗口**，并经
+            // onContextWindowChanged 回调把有效值同步到 contextPreparer —— 计算点唯一（在 loop）。
+            this.loop.setContextWindow(tokens);
+        }
+        else if (this.internals.contextPreparer) {
+            // loop 尚未装配（早期阶段）：无角色策略可叠加，直接用 provider 窗口
+            this.internals.contextPreparer.setMaxContextTokens(tokens);
+        }
+        logger.info({ providerWindow: tokens }, 'provider 上下文窗口已更新');
     }
     /**
-     * 创建会话管理器（提取重复的 forwardEvent + SessionManager 构造逻辑）
+     * 运行时更新 per-LLM 输出预算默认值（token）
      *
-     * assembleComponents 和 rebuildComponentsWithCurrentCtx 共享同一套构造逻辑：
-     * - 通过回调访问当前组件（支持 rebuild 后自动获取最新引用）
-     * - 事件转发桥接：SessionManager 使用宽类型 (string, Record<string,unknown>)，
-     *   Agent 内部桥接到 TypedEventEmitter 的强类型 emit
-     * - 运行时校验事件名是否在 AgentEventMap 中，避免不安全的类型断言
+     * Provider 热切换配套（与 setContextWindow 同链路）：同步 #config 拷贝并即时生效于 loop——
+     * 切换 Provider 后新配置的 maxTokens 无需重装 Agent。undefined = 清除（回服务端默认）。
+     * 不设 assertNotBusy：maxTokens 是请求参数（非上下文结构），轮内下一迭代即用新值，无一致性风险。
      *
-     * @returns 新的 SessionManager 实例
+     * @param tokens 新输出预算（token）；undefined 清除
      */
-    createSessionManager() {
-        const forwardEvent = (event, data) => {
-            if (AGENT_EVENT_NAMES.has(event)) {
-                this.emit(event, data);
-            }
-        };
-        return new SessionManager(
-        // 惰性 getter：SessionManager 内部调用时 Agent 已 init，用 ! 窄化
-        () => this.history, () => this.loop, this.#config.sessionStore, () => this.chatLockManager?.isBusy ?? false, forwardEvent);
-    }
-    // ─── Provider 管理 ────────────────────────────────────
-    setProvider(provider) {
-        // 对话进行中切换 Provider 会导致同一 processUserInput 循环内前后两次 LLM 调用命中不同 Provider
-        // （模型上下文窗口假设不一致 → 可能导致上下文截断逻辑误判或 tool_call 格式不兼容）
-        if (this.chatLockManager?.isBusy) {
-            throw chatBusyError('切换 Provider');
-        }
-        this.#provider = provider;
+    setMaxTokens(tokens) {
+        this.#config.maxTokens = tokens;
         if (this.loop) {
-            this.loop.setProvider(provider);
+            this.loop.setDefaultMaxTokens(tokens);
         }
-        logger.info({ provider: this.#provider.name }, 'Provider 已切换');
+        logger.info({ maxTokens: tokens }, 'per-LLM 输出预算已更新');
+    }
+    /**
+     * 读取本轮请求体**实际**携带的 max_tokens（生效值），供宿主取证面写 meta。
+     *
+     * 薄委托：优先级裁决收敛在 AgentLoop.buildChatOptions（见其注释），此处不复制规则——
+     * 否则「谁压过谁」会在宿主侧长出第二真理源。loop 未装配时返回 undefined。
+     */
+    getEffectiveMaxTokens() {
+        return this.loop?.getEffectiveMaxTokens();
     }
     setBackgroundProvider(provider) {
         // 与 setProvider 一致，对话进行中禁止切换后台 Provider
-        if (this.chatLockManager?.isBusy) {
-            throw chatBusyError('切换后台 Provider');
-        }
+        this.assertNotBusy('切换后台 Provider');
         this.#backgroundProvider = provider;
-        // 同步更新 AutoConfigRefiner 的后台 Provider
-        if (this.autoConfigRefiner) {
-            this.autoConfigRefiner.setBackgroundProvider(provider);
+        // 同步更新所有后台组件（统一消费 backgroundProvider）
+        if (this.internals.roundSummaryGenerator) {
+            this.internals.roundSummaryGenerator.setBackgroundProvider(provider);
+        }
+        if (this.internals.sessionArchiver) {
+            this.internals.sessionArchiver.setBackgroundProvider(provider);
         }
         logger.info({ hasBackground: !!provider }, '后台 Provider 已切换');
     }
-    // ─── 归档模式管理（ADR-015） ───────────────────────────
+    // ─── 归档模式管理 ───────────────────────────
     /**
-     * 运行时切换归档模式
-     *
-     * 与 setProvider 一致，对话进行中禁止切换（避免本轮 postProcess 行为不一致）。
-     *
-     * @param mode 目标模式
+     * 运行时切换归档模式：对话进行中禁止切换（避免本轮 postProcess 行为不一致），无变更幂等返回
      */
     setArchiveMode(mode) {
-        if (this.chatLockManager?.isBusy) {
-            throw chatBusyError('切换归档模式');
-        }
+        this.assertNotBusy('切换归档模式');
         const prev = this.#config.archiveMode;
         if (prev === mode)
             return; // 幂等：无变更直接返回
         this.#config.archiveMode = mode;
+        this.emit(AGENT_EVENTS.archiveModeChanged, { from: prev, to: mode });
         logger.info({ from: prev, to: mode }, '归档模式已切换');
     }
     /**
-     * 查询当前归档模式
-     *
-     * 宿主 UI（如设置面板）可据此同步显示当前模式。
+     * 查询当前归档模式（宿主 UI 可据此同步显示）
      */
     getArchiveMode() {
         return this.#config.archiveMode;
     }
     /**
-     * 手动触发 profile facts 归档（manual 模式下使用）
-     *
-     * manual 模式下 postProcess 跳过自动归档，用户需通过此 API 主动归档。
-     * full / insights-only 模式下也可调用（会重复归档，但不推荐）。
-     *
-     * 归档逻辑已委托给 ArchiveCoordinator
-     *
-     * @param input 本轮用户输入
-     * @returns 写入/更新的 UserProfileEntry 列表
+     * 获取角色包切换锁定状态（透传 RolePackManager，宿主 IPC 层据此区分"切换失败"原因）
+     * @returns locked 是否锁定；unlockAt 锁定自动恢复时间戳（ms epoch），未锁定时为 null
      */
-    async archiveProfileFacts(input) {
-        this.assertInitialized('archiveProfileFacts');
-        return this.archiveCoordinator.archiveProfileFacts(input);
+    getRolePackSwitchLockStatus() {
+        this.assertInitialized('getRolePackSwitchLockStatus');
+        if (!this._rolePackManager)
+            return { locked: false, unlockAt: null };
+        return this._rolePackManager.getSwitchLockStatus();
     }
     /**
-     * 手动触发 insight 提取（manual 模式下使用）
+     * 获取当前激活角色包的 traits（宿主情感计算 API）
      *
-     * manual 模式下 postProcess 跳过自动归档，用户需通过此 API 主动归档。
-     * 内部仍走 classify 判断（避免无价值输入浪费 LLM 调用）。
+     * @returns traits 键值对，无激活角色包或无 traits 时返回 undefined
+     */
+    getActiveTraits() {
+        return this._rolePackManager?.getActiveTraits();
+    }
+    /**
+     * 刷新 AgentLoop 的 systemPromptPrefix（SSOT：buildSystemPromptPrefix）
      *
-     * 归档逻辑已委托给 ArchiveCoordinator
+     * 角色包是 system prompt 的唯一注入源。调用时机：手动切换成功后、reloadConfig 重载后；
+     * loop 为 null 时静默跳过（init 前或 close 后边界）。统一走 buildSystemPromptPrefix 真理源，
+     * 全局技能清单也在该前缀内（不能只拼 rolePackPrompt）。等价于「按 activePack 视角刷新」（roundRole=null）。
+     */
+    refreshRolePackPrefixOnLoop() {
+        this.refreshRolePackPrefixForRound(null);
+    }
+    /**
+     * 会议阶梯推进：按当前 active 任务项的 rolePack 派生本轮装配视角。
      *
-     * @param input 本轮用户输入
-     * @param assistantContent 本轮助手回复内容
-     * @returns 写入/更新的 Memory 列表
+     * 由 assembler.getTaskTable 每轮注入时驱动（hooks.applyActivePlanItemAssembly），与任务表渲染同源，
+     * 保证后继 step 换角色即时生效（装配视角不能只在 prepare.run 设一次，否则展示层正确/装配层冻结）。
+     * roundRole=candidate（可能为 null，无有效覆盖时回落 activePack 组长），调 refreshRolePackPrefixForRound 重建前缀。
+     * 防重：candidate 与 rolePackManager 当前 roundAssemblyPerspective 一致则跳过，避免每轮迭代重复重建。
      */
-    async archiveInsight(input, assistantContent) {
-        this.assertInitialized('archiveInsight');
-        return this.archiveCoordinator.archiveInsight(input, assistantContent);
+    applyActivePlanItemAssemblyIfChanged() {
+        const plan = this._sessionManager?.getCheckpoint()?.plan ?? [];
+        const active = plan.find((s) => s.status === 'active');
+        const candidate = this._rolePackManager?.resolveRoundAssemblyRole(active?.rolePack) ?? null;
+        if (candidate === this._rolePackManager?.roundAssemblyPerspective)
+            return;
+        this._rolePackManager?.setRoundAssemblyRole(candidate);
+        this.refreshRolePackPrefixForRound(candidate);
+        logger.debug({ roundAssemblyRole: candidate }, '会议装配视角随 active 任务项切换');
     }
     /**
-     * 手动归档会话内容（content 类记忆）
+     * 按本轮表层装配视角刷新 AgentLoop 前缀（会议机制）
      *
-     * 适用于 `insights-only` / `manual` 模式下用户手动触发会话内容归档。
-     * `full` 模式下由宿主在会话切换前自动调用，无需用户干预。
+     * roundRole=null（日常态）→ 回落 activePack 前缀；roundRole 为任务项角色 → 该角色
+     * persona/rules/skills 全量表层装配（buildSystemPrompt(name)）。策略键恒为 activePack：
+     * ChatOptions（temperature/outputLimit）由 activePack 策略构建，不随视角变（键不换防抖动）。
+     * 由 seed prepare 每轮调用（`refreshRolePackPrefixForRound` 契约），保证前缀始终匹配本轮装配角色。
+     */
+    refreshRolePackPrefixForRound(roundRole) {
+        if (!this.loop)
+            return;
+        const assemblyName = roundRole ?? this._rolePackManager?.activeName ?? undefined;
+        const rolePackPrompt = this._rolePackManager?.buildSystemPrompt(assemblyName) ?? '';
+        const globalSkillList = this.skillManager?.buildSkillList() ?? '';
+        // 作品投影装配块：缓存于 manager（装配时刷新 + register_work 更新），同步读取即可
+        const workProjectionContext = this.workProjection?.contextBlock() ?? '';
+        const newPrefix = buildSystemPromptPrefix(rolePackPrompt, globalSkillList, undefined, workProjectionContext);
+        this.loop.refreshRolePackPrefix(newPrefix);
+        // 角色包底盘占用随切换实时更新（不依赖跑 prepare）：装配此刻即确定的真值
+        this.loop.setRolePackBaseTokens(estimateTokensMessages([{ content: newPrefix }]));
+        // 同步注入角色包策略的 ChatOptions 覆盖项（temperature / outputLimit）
+        // 键恒为 activePack：buildChatOptionsFromStrategy 读激活包策略，不随本轮装配视角变
+        this.loop.setChatOptions(this.buildChatOptionsFromStrategy());
+    }
+    /**
+     * 从当前激活的角色包策略构建 ChatOptions 覆盖项
+     * 将 act.temperature / act.outputLimit 映射到 ChatOptions 字段；输出上限最终与 per-LLM 默认值
+     * 取**更小值**（两者皆为「上限」，须同时满足）——收敛在 `buildChatOptions`，此处不裁决大小。
+     */
+    buildChatOptionsFromStrategy() {
+        const strategy = this.getActiveStrategy();
+        if (!strategy)
+            return undefined;
+        const chatOptions = {};
+        const act = strategy.act;
+        // act.temperature → ChatOptions.temperature（限 0-2；边界 SSOT = strategyKeys.isTemperature，不重复字面量）
+        const temperature = act?.temperature;
+        if (isTemperature(temperature)) {
+            chatOptions.temperature = temperature;
+        }
+        // act.outputLimit → ChatOptions.maxTokens（需 ∈ [1, MAX_OUTPUT_LIMIT]，越界忽略防资源失控）
+        const outputLimit = act?.outputLimit;
+        if (typeof outputLimit === 'number' && outputLimit > 0 && outputLimit <= MAX_OUTPUT_LIMIT) {
+            chatOptions.maxTokens = outputLimit;
+        }
+        return Object.keys(chatOptions).length > 0 ? chatOptions : undefined;
+    }
+    /**
+     * 角色包系统的唯一切换入口（自动匹配 + 手动切换共用）：activate 更新激活态 → 发射 rolePackSwitched 事件
+     * → 刷新 AgentLoop 前缀 → 同步工具白名单。
+     * @returns 是否切换成功。false 有两种成因（**均不发射切换事件**）：角色包不存在、
+     * 切换锁已激活（30s 内超 5 次限流）；调用方须以 getRolePackSwitchLockStatus() 区分，
+     * 不可由「返回 false + 未收到 rolePackSwitchLocked」推断为"不存在"（被锁时该事件不发射，
+     * 仅在**触发锁定**的那一次切换中发射，而那一次返回 true）。同名切换幂等返回 true。
+     */
+    switchRolePack(name) {
+        this.assertInitialized('switchRolePack');
+        const rpm = this._rolePackManager;
+        if (!rpm)
+            return false;
+        const prevName = rpm.activeName;
+        if (prevName === name)
+            return true;
+        const ok = rpm.activate(name);
+        if (!ok) {
+            logger.warn({ name }, '切换角色包失败（不存在或切换锁已激活）');
+            return false;
+        }
+        this.emit(AGENT_EVENTS.rolePackSwitched, { from: prevName ?? '', to: name });
+        this.refreshRolePackPrefixOnLoop();
+        this.applyRolePackToolExposure();
+        logger.info({ rolePack: name }, '角色包切换');
+        return true;
+    }
+    /**
+     * 手动归档会话（更新 SessionMeta，委托 ArchiveCoordinator）
      *
-     * 归档逻辑已委托给 ArchiveCoordinator
+     * 适用于 manual 模式（用户手动触发；full 模式由宿主切换前自动调用）。
+     * options 透传给 ArchiveCoordinator：宿主自动触发传 { autoTriggered: true }（按其模式判断），
+     * 用户手动触发省略 options（默认 autoTriggered=false，无条件执行）。
      *
-     * @param date 会话日期 YYYY-MM-DD
-     * @param session 会话标识（不含日期前缀）
-     * @returns 归档结果（memories 可能为空，表示无归档价值或 LLM 失败）
+     * @returns 归档结果（updatedFields 可能为空，表示无归档价值或 LLM 失败）
      */
-    async archiveSessionContent(date, session) {
-        this.assertInitialized('archiveSessionContent');
-        return this.archiveCoordinator.archiveSessionContent(date, session);
+    async archiveSession(date, session, options) {
+        this.assertInitialized('archiveSession');
+        return this.requireArchiveCoordinator.archiveSession(date, session, options);
     }
     // ─── 配置重载（事件驱动） ───────────────────────
     /**
-     * 重载配置类记忆：从 configDir 重新扫描指定 source 的配置文件并更新内存缓存 + SQLite 索引
-     *
-     * 解决方案：installSkill 写入文件后或 confirmConfigSuggestion 写入配置文件后，
-     * 调用此方法使当前会话立即生效，无需重启 Agent。
-     *
-     * 支持的 source：
-     * - 'skill' → SkillManager.reload() 清空缓存重新扫描 skills/ 目录
-     * - 'persona' → PersonaManager.reload() 清空缓存重新扫描 personas/ 目录（保持激活角色）
-     * - 'rule' → 无操作（rule 类型已由 ConfigManager.addRule() 即时注入 system prompt）
-     * - 'guardrail' → 抛错（guardrail 是 AgentLoop 的 readonly 数组，需 rebuildComponents 才能重载）
-     * - undefined → 重载 skill + persona（全量重载，不含 guardrail）
-     *
-     * @param source 配置类型，缺省时重载全部可热更新的配置
-     * @returns 重载结果统计
+     * 重载配置类记忆：从 configDir 重新扫描指定 source 并更新内存缓存（设定记忆纯文件装载，不写记忆库），使当前会话立即生效（无需重启）。
+     * - 'skill' → SkillManager.reload() 重扫 skills/
+     * - 'rolePack' → RolePackManager.reload() 重扫 role-packs/（保持激活角色，刷新 AgentLoop 前缀）
+     * - 'rule' → 经角色包管理机制热更新（即 rolePack）
+     * - undefined → 全量重载 skill + rolePack
      */
     async reloadConfig(source) {
         this.assertInitialized('reloadConfig');
-        if (this.chatLockManager?.isBusy) {
+        if (this.internals.chatLockManager?.isBusy) {
+            // 对话中无法热重载：暂存 source 待锁释放后补执行；undefined（全量）不暂存——无具体来源，补执行语义不明
+            if (source) {
+                this.pendingConfigReload.add(source);
+                logger.info({ source }, '对话进行中，配置重载已暂存，将在对话结束后补执行');
+            }
             throw chatBusyError('重载配置');
         }
-        // guardrail 需重建 AgentLoop，不属于热重载范畴
-        if (source === 'guardrail') {
-            throw configError('guardrail 不支持热重载', 'guardrail 规则是 AgentLoop 的 readonly 数组，需调用 rebuildComponents() 重建', ['使用 rebuildComponents() 重建组件（代价较高）']);
-        }
-        // rule 类型已由 ConfigManager.addRule() 即时注入，无需重载
+        // rule 是角色包的一部分，重载走 rolePack 路径
         if (source === 'rule') {
-            logger.info('rule 类型已由 addRule() 即时注入，reloadConfig 跳过');
-            return { skill: 0, persona: 0 };
+            logger.info('rule 类型重载：触发角色包重新扫描');
+            return this.reloadConfig('rolePack');
         }
-        const result = { skill: 0, persona: 0 };
+        const result = { skill: 0, rolePack: 0 };
+        const errors = [];
         // 按需重载：source 缺省时全量重载，否则只重载指定类型
         const shouldReloadSkill = !source || source === 'skill';
-        const shouldReloadPersona = !source || source === 'persona';
+        const shouldReloadRolePack = !source || source === 'rolePack';
         if (shouldReloadSkill && this.skillManager) {
-            result.skill = await this.skillManager.reload();
+            try {
+                result.skill = await this.skillManager.reload();
+            }
+            catch (err) {
+                errors.push(toError(err));
+                logger.warn({ err: toError(err) }, 'reloadConfig: skillManager.reload 失败');
+            }
         }
-        if (shouldReloadPersona && this.personaManager) {
-            result.persona = await this.personaManager.reload();
-            // 角色重载后，刷新 AgentLoop 的角色前缀（使新角色内容立即注入 system prompt）
-            if (this.loop) {
-                const newPrefix = this.personaManager.buildSystemPrompt();
-                this.loop.refreshPersonaPrefix(newPrefix);
+        if (shouldReloadRolePack && this._rolePackManager) {
+            try {
+                result.rolePack = await this._rolePackManager.reload();
+                // 角色重载后刷新 AgentLoop 前缀
+                if (this.loop) {
+                    this.refreshRolePackPrefixOnLoop();
+                }
+            }
+            catch (err) {
+                errors.push(toError(err));
+                logger.warn({ err: toError(err) }, 'reloadConfig: rolePackManager.reload 失败');
             }
         }
-        logger.info({ source, ...result }, '配置已热重载');
+        if (errors.length > 0) {
+            logger.warn({ source, ...result, errorCount: errors.length }, '配置热重载部分失败');
+        }
+        else {
+            logger.info({ source, ...result }, '配置已热重载');
+        }
         return result;
     }
     // ─── 组件访问 ─────────────────────────────────────────
     /**
-     * 重建内部组件（history / loop / managers）
-     *
-     * 通常不需要手动调用——switchProject() 已自动执行 rebuild。
-     * 仅在宿主项目需要强制刷新组件时使用（如热更新配置后）。
+     * 重建内部组件（history / loop / managers）：通常由 switchProject() 自动触发，仅强制刷新时手动调用
      */
     async rebuildComponents() {
-        // 对话进行中重建组件会导致 loop/history 引用被替换，工作记忆与持久化状态不一致
-        if (this.chatLockManager?.isBusy) {
-            throw chatBusyError('重建组件');
-        }
-        await this.rebuildComponentsWithCurrentCtx();
+        // 对话进行中重建会导致 loop/history 引用被替换，工作记忆与持久化状态不一致
+        this.assertNotBusy('重建组件');
+        if (!this.pctx)
+            return;
+        // assembleComponents 内部重建 history/loop/managers，并返回新创建的 sessionManager
+        await this.assembleComponents(this.pctx);
     }
     // ─── 守卫方法 ───────────────────────────────────────────
     /**
-     * 检查 Agent 是否已初始化
-     *
-     * @param methodName 调用方法名（用于错误消息）
-     * @param requires 需要检查的组件列表
+     * 检查 Agent 是否已初始化（methodName 用于错误消息，requires 为需检查的组件列表）
      */
     assertInitialized(methodName, requires = ['history', 'loop']) {
         if (!this._initialized) {
@@ -879,78 +1428,186 @@ export class Agent extends TypedEventEmitter {
             }
         }
     }
+    /**
+     * 断言对话未进行中（统一守卫）：破坏状态一致性的入口统一在此做 isBusy 检查。
+     * reloadConfig 不使用本方法——它在 isBusy 时需暂存 source 而非直接抛错。
+     */
+    assertNotBusy(operation) {
+        if (this.internals.chatLockManager?.isBusy) {
+            throw chatBusyError(operation);
+        }
+    }
+    // 断言 getter：非空或抛明确错误，替代 this.loop!/history!/pctx! 非空断言
+    get requireLoop() {
+        if (!this.loop)
+            throw configError('AgentLoop 未初始化', undefined, ['在调用此方法前执行 await agent.init()']);
+        return this.loop;
+    }
+    get requireArchiveCoordinator() {
+        if (!this.internals.archiveCoordinator)
+            throw configError('ArchiveCoordinator 未初始化', undefined, [
+                '在调用此方法前执行 await agent.init()',
+            ]);
+        return this.internals.archiveCoordinator;
+    }
+    get requireSessionManager() {
+        if (!this._sessionManager)
+            throw configError('SessionManager 未初始化', undefined, [
+                '在调用此方法前执行 await agent.init()',
+            ]);
+        return this._sessionManager;
+    }
+    /**
+     * 获取角色包管理器（system prompt 的唯一注入源，返回 null 表示 Agent 未初始化）
+     */
+    get rolePackManager() {
+        return this._rolePackManager;
+    }
+    /**
+     * 获取当前激活的 L2 行为策略：从激活角色包读取，未激活时用全局默认值；供各阶段按策略调整行为
+     */
+    getActiveStrategy() {
+        return this._rolePackManager?.getActive()?.strategy ?? DEFAULT_BEHAVIOR_STRATEGY;
+    }
+    /**
+     * 应用当前角色包的工具暴露面（换角色 → 工具集切换）：声明 capabilities 时解析为工具白名单，未声明放行全部。
+     * 空数组（parseCapabilities 对 undefined 返回 []）同样视为"未声明能力"放行全部，避免误解释为"禁止所有"。
+     * toolMode=block 全禁与此正交；变更经 setToolWhitelist → onToolsChanged 链路同步 loop 快照与 system prompt。
+     */
+    applyRolePackToolExposure() {
+        if (!this.toolExec)
+            return;
+        const active = this._rolePackManager?.getActive();
+        const capabilities = active?.capabilities;
+        const whitelist = capabilities && capabilities.length > 0 ? resolveCapabilityTools(capabilities) : null;
+        this.toolExec.setToolWhitelist(whitelist);
+    }
     // ─── 记忆生命周期 ───────────────────────────────────────
-    // ─── runMemoryDecay 已迁移至 MemoryDecayScheduler.runOnce ─────
+    /**
+     * 立即执行一次孤儿 Round 垃圾回收（宿主手动触发入口）。
+     *
+     * roundStore+storage 未注入时返回空统计（降级不报错）；
+     * 对话进行中（chatLock busy）经 shouldSkip 跳过并返回空统计。
+     *
+     * @returns GC 结果统计（scanned/deleted/memoryCleaned 等）
+     */
+    gcNow() {
+        const gc = this.internals.gcService;
+        if (!gc) {
+            logger.debug('gcNow: roundStore/storage 未注入，GCService 未创建（降级为空转）');
+            return {
+                scanned: 0,
+                orphaned: 0,
+                deleted: 0,
+                failedDueToRefCount: 0,
+                memoryCleaned: 0,
+                elapsedMs: 0,
+            };
+        }
+        return gc.run();
+    }
     // ─── 关闭 ─────────────────────────────────────────────
     /**
-     * 关闭 Agent，释放 SQLite 连接等资源
+     * 关闭 Agent，释放存储连接等资源
      */
     async close() {
-        // 清理 chat 锁管理器（递增 token 使进行中的 chat() generator 的 finally 块
-        // 检测到 token 变化后跳过资源清理，close 已接管清理职责）
-        this.chatLockManager?.dispose();
-        this.chatLockManager = null;
-        // 清理 MemoryDecayScheduler（含定时器和 storage 引用）
-        if (this.memoryDecayScheduler) {
-            this.memoryDecayScheduler.stop();
-            this.memoryDecayScheduler = null;
+        // 清理 chat 锁管理器（递增 token 使进行中 chat() 的 finally 跳过清理，close 已接管）
+        this.internals.chatLockManager?.dispose();
+        this.internals.chatLockManager = null;
+        // 孤儿 Round GC 停止定时任务（须先于下方 projectManager.shutdown——其会关闭 storage）
+        this.internals.gcService?.stopPeriodic();
+        this.internals.gcService = null;
+        // 等待 WorkProjection 无 inflight 概念（作品投影改为用户主动触发同步写，无后台 LLM 任务）
+        // 背景任务统一由下方 awaitBackgroundTasks 兜底
+        // 关键约束：等待 backgroundTask 全局在途任务完成（如 touchScores）。
+        // 否则 close 后后台任务仍可能 upsert 已关闭的 storage，触发写失效或异常。
+        try {
+            const awaited = await awaitBackgroundTasks(AGENT_CONSTANTS.SHUTDOWN_ARCHIVE_TIMEOUT_MS);
+            if (awaited > 0) {
+                logger.debug({ awaited }, 'close: 背景任务等待结束（awaited = 初始在途数，超时放弃时非完成数）');
+            }
         }
-        // 清理 ArchiveCoordinator（无定时器，只需释放引用）
-        this.archiveCoordinator = null;
-        // 清理定时器
-        if (this.decayTimer) {
-            clearSafeInterval(this.decayTimer);
-            this.decayTimer = null;
+        catch (err) {
+            logger.warn({ err: toError(err) }, 'close: awaitBackgroundTasks 失败');
+        }
+        // 处理 pending 暂停残留：关闭前确保状态机与检查点一致
+        const sm = this._sessionManager;
+        if (sm?.isPausePending()) {
+            const pendingInfo = sm.pendingPauseInfo;
+            logger.warn({ reason: pendingInfo?.reason, source: pendingInfo?.source }, 'close() 时存在未消费的暂停请求，已自动清理');
+            // 若状态机仍 running，同步翻 paused 使检查点内存态一致（无需触发挂起，仅修正一致性）；
+            // 系统清理不消耗连续暂停配额 → lowRisk=true
+            if (sm.status === 'running') {
+                sm.pause('close 清理残留暂停', 'system', true);
+            }
+            sm.cancelPendingPause();
+        }
+        // 清理 SessionManager（须先于 nullifyAllComponents，destroy 需访问其内部状态）
+        if (this._sessionManager) {
+            // 清脏后再 destroy（纯内存，无落盘；检查点不落盘，本调用为保留语义边界的 no-op）
+            this._sessionManager.flushOnShutdown();
+            this._sessionManager.destroy();
         }
-        // 清理 PersonaManager 的角色切换防抖锁计时器，防止关闭后回调触发
-        if (this.personaManager) {
-            this.personaManager.close();
+        // ArchiveCoordinator 无定时器，仅释放引用
+        this.internals.archiveCoordinator = null;
+        // 清理 RolePackManager 切换防抖锁计时器，防止关闭后回调触发
+        if (this._rolePackManager) {
+            this._rolePackManager.close();
         }
-        // 先等待后台归档完成，再移除事件监听器
-        // 顺序敏感：若先 removeAllListeners，fire-and-forget 的归档 Promise 在 await 期间
-        // reject 时 emit 会变成 no-op（listeners 已清空），archiveFailed 事件丢失
+        // 顺序敏感：先等后台归档完成再移除监听器，否则 await 期间归档 reject 的 emit 变 no-op、事件丢失
         if (this.history) {
-            await this.history.awaitPendingArchives(AGENT_CONSTANTS.SHUTDOWN_ARCHIVE_TIMEOUT_MS);
+            try {
+                await this.history.awaitPendingArchives(AGENT_CONSTANTS.SHUTDOWN_ARCHIVE_TIMEOUT_MS);
+            }
+            catch (err) {
+                logger.warn({ err: toError(err) }, 'close: awaitPendingArchives 失败');
+            }
         }
-        // pending archives 完成后再移除监听器，确保归档失败的 emit 能送达
         this.removeAllListeners();
         if (this.projectManager) {
-            await this.projectManager.shutdown();
+            try {
+                await this.projectManager.shutdown();
+            }
+            catch (err) {
+                logger.warn({ err: toError(err) }, 'close: projectManager.shutdown 失败');
+            }
         }
         this._initialized = false;
         this.nullifyAllComponents();
         // 清理次要状态字段，防止 re-init 后残留上一会话状态
-        this.activeSkill = null;
         this._lastInteractionAt = null;
+        this.pendingConfigReload.clear();
     }
     /**
-     * 统一 null 化所有组件字段（新增 Manager 时在此处追加一行）
-     *
-     * 仅处理"纯 null 化"字段，带副作用的清理（dispose/stop/close/shutdown）
-     * 仍由 close() 显式调用，顺序敏感不可合并。
+     * 统一 null 化所有组件字段（新增 Manager 时在此追加一行）；带副作用的清理仍由 close() 显式调用，顺序敏感不可合并
      */
     nullifyAllComponents() {
-        // Provider
         this.#backgroundProvider = null;
-        // 核心组件
         this.history = null;
         this.loop = null;
         this.toolExec = null;
-        // 专职 Manager
-        this.personaManager = null;
-        this.#userProfile = null;
         this.skillManager = null;
-        this.insightExtractor = null;
-        this.configManager = null;
+        this._rolePackManager = null;
         this.memoryInspector = null;
+        this._governance = null;
         this.workProjection = null;
-        this.autoConfigRefiner = null;
-        this.sessionArchiver = null;
         this.textPolisher = null;
         this._sessionManager = null;
-        // 项目管理
         this.projectManager = null;
         this.pctx = null;
+        // 纯内部组件聚合整体置 null（新增内部组件只需在字段声明与 createPostInitComponents 登记）
+        this.internals = {
+            dedupManager: null,
+            memoryAdvisor: null,
+            sessionArchiver: null,
+            sessionNamer: null,
+            roundSummaryGenerator: null,
+            contextPreparer: null,
+            chatLockManager: null,
+            archiveCoordinator: null,
+            seedOrchestrator: null,
+            gcService: null,
+        };
     }
     // ─── 只读访问器 ───────────────────────────────────────
     get initialized() {
@@ -959,265 +1616,140 @@ export class Agent extends TypedEventEmitter {
     get context() {
         return this.pctx;
     }
+    /**
+     * 获取 AgentLoop 实例（宿主集成面，用于 restoreHistory 等底层操作；getMessages/getMessageCount 无法替代）
+     */
     get agentLoop() {
         return this.loop;
     }
     /**
-     * 注入情感基调到 system prompt（Phase 2.1：AffectController）
-     *
-     * 委托至 AgentLoop.injectAffect()，在角色前缀和 bootstrap 记忆之间插入情感描述。
-     * 与角色切换独立——切换角色不会清除情感注入。
-     *
-     * @param affectString 情感描述文本，传空字符串清除注入
+     * 获取当前消息列表（只读副本，不可绕过编排链路直接修改）
      */
-    injectAffect(affectString) {
-        this.loop?.injectAffect(affectString);
+    getMessages() {
+        return this.loop?.getMessages() ?? [];
+    }
+    /** 获取当前消息数量 */
+    getMessageCount() {
+        return this.loop?.getMessages().length ?? 0;
     }
+    /**
+     * 获取 MessageHistory 实例（宿主集成面，用于日期/会话判断等底层操作；
+     * currentDateValue/currentSessionValue 等只读属性无替代接口）
+     */
     get agentHistory() {
         return this.history;
     }
+    /**
+     * 注入情感基调到 system prompt：委托 AgentLoop.injectAffect()，在角色前缀与 bootstrap 记忆间插入情感描述；
+     * 与角色切换独立（切换角色不清除情感注入），传空串清除。
+     */
+    injectAffect(affectString) {
+        if (!this.loop)
+            throw configError('AgentLoop', 'AgentLoop 未初始化，无法注入 affect', []);
+        this.loop.injectAffect(affectString);
+    }
     get provider() {
         return this.#provider;
     }
     get isBusy() {
-        return this.chatLockManager?.isBusy ?? false;
+        return this.internals.chatLockManager?.isBusy ?? false;
     }
     get lastInteractionAt() {
         return this._lastInteractionAt;
     }
+    /** 记忆治理统一门面（语义去重 / 来源健康诊断 / 冲突检测 / 建议推荐），Agent 上的记忆管理方法统一收口于此（无显式衰减层面） */
+    get governance() {
+        return this._governance;
+    }
     // ─── 运行时指标 ────────────────────────────────
     /**
-     * 获取 Agent 运行时指标快照（可观测性增强）
-     *
-     * 聚合 AgentLoop 指标（LLM 调用、记忆召回、工具调用、上下文管理）
-     * 与 Agent 层指标（记忆衰减），返回完整的 AgentMetrics 快照。
-     *
-     * 未初始化时返回全零指标（合理的默认值，不抛异常）。
-     * 纯只读、同步、零副作用——适合宿主项目定期轮询构建监控面板。
-     *
-     * 使用方式：
-     *   const metrics = agent.getMetrics();
-     *   console.log(`LLM 调用 ${metrics.llm.callCount} 次，命中率 ${metrics.recall.hitRate}`);
-     *
-     * @returns AgentMetrics 完整快照（含衰减指标）
+     * 后台任务统计快照（宿主观测后台副作用健康度，纯只读转发 utils 单例）。
+     * @returns 在途 / 成功 / 失败计数
+     */
+    getBackgroundTaskStats() {
+        return readBackgroundTaskStats();
+    }
+    /**
+     * 获取 Agent 运行时指标快照（可观测性）：聚合 AgentLoop 指标与 Agent 层治理指标；
+     * 未初始化返回全零默认值（不抛异常），纯只读同步零副作用，适合宿主定期轮询监控面板。
      */
     getMetrics() {
-        // 衰减指标从 MemoryDecayScheduler 读取
-        const decayMetrics = this.memoryDecayScheduler?.getMetrics() ?? {
-            runCount: 0,
-            totalDecayedCount: 0,
-            lastRunAt: null,
-        };
-        // 未初始化时返回全零指标，避免调用方需要判空
+        // 未初始化时返回全零指标，避免调用方判空
         if (!this.loop) {
             return {
-                llm: { callCount: 0, totalInputTokens: 0, totalOutputTokens: 0 },
-                recall: { totalCount: 0, hitCount: 0, hitRate: 0 },
-                tools: { callCount: 0, failureCount: 0 },
+                llm: {
+                    callCount: 0,
+                    totalInputTokens: 0,
+                    totalOutputTokens: 0,
+                    actualInputTokens: 0,
+                    actualOutputTokens: 0,
+                    emptyResponseCount: 0,
+                    truncationRecoveryCount: 0,
+                    pairingGuardFires: 0,
+                },
+                tools: {
+                    callCount: 0,
+                    failureCount: 0,
+                    unparsedToolIntentCount: 0,
+                    ledgerStubEchoCount: 0,
+                    readDedupBlockCount: 0,
+                },
                 context: { truncationCount: 0, messageCount: 0, estimatedTokens: 0 },
-                decay: decayMetrics,
+                plan: { taskTableWriteCount: 0, planItemBoundaryCount: 0 },
+                tasks: {
+                    totalCount: 0,
+                    successCount: 0,
+                    failureCount: 0,
+                    successRate: 0,
+                    avgDurationMs: 0,
+                },
             };
         }
-        // 获取 AgentLoop 指标快照，填充衰减字段
         const loopMetrics = this.loop.getMetrics();
         return {
             ...loopMetrics,
-            decay: decayMetrics,
         };
     }
-    // ─── Manager 暴露（激进拆分：调用方直接操作 Manager）──
-    //
-    // 设计策略（ADR-010 §Manager 访问器）：访问器返回 null，门面方法抛错。
-    // - 访问器（getter）：返回 Manager | null，供宿主项目链式调用和优雅降级
-    //   （如 `agent.persona?.activeName`、`if (!agent.memory) return []`）
-    // - 门面方法（snapshot/inspect/stats/searchMemories 等）：通过
-    //   assertInitialized 抛 MemoraError，提供明确错误信息
-    // 宿主项目使用访问器时需自行判空，或使用门面方法获得自动错误处理。
-    /**
-     * 角色管理器（可能为 null）
-     *
-     * 返回 null 时表示 Agent 未初始化或角色系统未加载。
-     * 链式调用建议使用可选链：`agent.persona?.activeName`
-     */
-    get persona() {
-        return this.personaManager;
+    // ─── Manager 暴露（调用方直接操作 Manager）──
+    // 设计策略：访问器（getter）返回 Manager | null 供链式调用和优雅降级（如 `if (!agent.memory) return []`）；
+    // 门面方法经 assertInitialized 抛明确错误；宿主用访问器需自行判空，或用门面方法获得自动错误处理。
+    /** 角色包管理器（角色+技能+规则的唯一真理源，system prompt 的唯一注入源） */
+    get rolePack() {
+        return this._rolePackManager;
     }
-    /**
-     * 工具执行器（可能为 null）
-     *
-     * 返回 null 时表示 Agent 未初始化。
-     */
+    /** 工具执行器（返回 null 表示 Agent 未初始化） */
     get tools() {
         return this.toolExec;
     }
-    /**
-     * 技能管理器（可能为 null）
-     *
-     * 返回 null 时表示 Agent 未初始化或技能系统未加载。
-     */
+    /** 技能管理器（返回 null 表示未初始化或技能系统未加载） */
     get skills() {
         return this.skillManager;
     }
-    /**
-     * 配置管理器（可能为 null）—— 规则/技能注入 + 配置建议
-     *
-     * 返回 null 时表示 Agent 未初始化。
-     */
-    get config() {
-        return this.configManager;
-    }
-    /**
-     * Insight 提取器（可能为 null）—— 输入分类 + 记忆提取
-     *
-     * 返回 null 时表示 Agent 未初始化或 LLM Provider 未配置。
-     */
-    get insight() {
-        return this.insightExtractor;
+    /** 角色包管理器（返回 null 表示未初始化或角色包系统未加载） */
+    get rolePacks() {
+        return this._rolePackManager;
     }
-    /**
-     * 记忆查看器（可能为 null）—— 快照 + 搜索 + 统计
-     *
-     * 返回 null 时表示 Agent 未初始化或存储层未就绪。
-     * 宿主项目常用模式：`const mem = agent.memory; if (!mem) return [];`
-     */
+    /** 记忆查看器（快照 + 搜索 + 统计；宿主常用 `const mem = agent.memory; if (!mem) return []`） */
     get memory() {
         return this.memoryInspector;
     }
-    // ─── LLM 记忆治理委托方法（G1：暴露能力但不暴露 manager 实例） ──
-    // 这三个方法是 sprite 层接入 L1~L3 治理能力的唯一入口。
-    // 委托内部 manager（memoryInspector / memoryDecayScheduler / memoryAdvisor），
-    // 不返回 manager 实例本身，保持封装（sprite 层不感知 manager 内部结构）。
-    // manager 未初始化时返回 skippedReason 报告，与 manager 内部"backgroundProvider
-    // 未注入时静默跳过"语义一致（向后兼容）。
-    /**
-     * L1 语义去重（委托 MemoryInspector.deduplicateMemories）
-     *
-     * 扫描名称相似的记忆对，调用 LLM 判断语义等价，降级低分记忆（score→0.1，不物理删除）。
-     * backgroundProvider 未注入或 Agent 未初始化时返回 skippedReason 报告，不抛错。
-     *
-     * @param signal 可选的 AbortSignal（取消进行中的 LLM 判断）
-     * @returns 去重报告（扫描数 / 降级 ID 列表 / 跳过原因）
-     */
-    async deduplicateMemories(signal) {
-        const inspector = this.memoryInspector;
-        if (!inspector) {
-            return {
-                scannedCount: 0,
-                pairCount: 0,
-                deduplicatedCount: 0,
-                demotedIds: [],
-                skippedReason: 'Agent 未初始化',
-            };
-        }
-        return inspector.deduplicateMemories(signal);
-    }
-    /**
-     * L2 时效性评估（委托 MemoryDecayScheduler.evaluateTimeliness）
-     *
-     * 扫描低分记忆（score<0.3），调用 LLM 判断是否过时，降级过时记忆（score→0.05）。
-     * backgroundProvider 未注入或 Agent 未初始化时返回 skippedReason 报告，不抛错。
-     *
-     * 使用场景：
-     *   - G2 自动触发：onDecayCompleted 钩子内 fire-and-forget 调用
-     *   - 手动触发：宿主 UI 健康度面板"时效性评估"按钮
-     *
-     * @param signal 可选的 AbortSignal
-     * @returns 评估报告（扫描数 / 过时数 / 降级 ID 列表 / 跳过原因）
-     */
-    async evaluateTimeliness(signal) {
-        const scheduler = this.memoryDecayScheduler;
-        if (!scheduler) {
-            return {
-                scannedCount: 0,
-                outdatedCount: 0,
-                demotedIds: [],
-                skippedReason: 'Agent 未初始化',
-            };
-        }
-        return scheduler.evaluateTimeliness(signal);
-    }
-    /**
-     * 手动触发一次 L0 记忆衰减（委托 MemoryDecayScheduler.runOnce）
-     *
-     * 执行纯 score 递减（无 LLM 调用），衰减完成后触发 decayCompleted 事件。
-     * 供宿主 UI 手动触发（如仪表盘"立即衰减"按钮），与定时器自动触发路径一致。
-     */
-    runMemoryDecayOnce() {
-        this.memoryDecayScheduler?.runOnce();
-    }
-    /**
-     * L3 冲突检测（委托 MemoryAdvisor.detectConflicts）
-     *
-     * 同 source 内配对，调用 LLM 判断语义冲突，仅检测不修复（需用户决策）。
-     * backgroundProvider 未注入或 Agent 未初始化时返回 skippedReason 报告，不抛错。
-     *
-     * @param signal 可选的 AbortSignal
-     * @returns 冲突报告（扫描数 / 冲突数 / 冲突详情列表 / 跳过原因）
-     */
-    async detectConflicts(signal) {
-        // MemoryAdvisor 实例由 MemoryInspector 持有（组合根装配时注入），
-        // 通过 inspector.detectConflicts 转发，避免 agent 直接持有 advisor 引用
-        const inspector = this.memoryInspector;
-        if (!inspector) {
-            return {
-                scannedCount: 0,
-                pairCount: 0,
-                conflictCount: 0,
-                conflicts: [],
-                skippedReason: 'Agent 未初始化',
-            };
-        }
-        return inspector.detectConflicts(signal);
-    }
-    /**
-     * 项目管理器（可能为 null）
-     *
-     * 返回 null 时表示 Agent 未初始化。
-     */
+    /** 项目管理器（返回 null 表示 Agent 未初始化） */
     get projects() {
         return this.projectManager;
     }
-    /**
-     * 用户画像管理器（可能为 null）—— 实时归档 + 确认/拒绝
-     *
-     * 返回 null 时表示 Agent 未初始化。
-     * 宿主常用模式：
-     *   - `agent.userProfile?.getPending()` 查询待确认条目
-     *   - `await agent.userProfile?.confirm(id)` 确认条目
-     *   - `await agent.userProfile?.reject(id)` 拒绝条目
-     */
-    get userProfile() {
-        return this.#userProfile;
-    }
-    /**
-     * 安全守卫（可能为 null）—— 写入确认回调注册
-     *
-     * 返回 null 时表示 Agent 未初始化或 projectPath 未设置。
-     * 宿主常用模式：
-     *   - `agent.security?.onWriteConfirmation(callback)` 注册写入确认回调
-     *   - 回调返回 true 允许写入，返回 false 拒绝写入
-     *
-     * 详见 M1 写入确认 UI 闭环
-     */
+    /** 安全守卫（写入确认回调注册：`onWriteConfirmation` 返回 true 放行、false 拒绝；未初始化/projectPath 未设为 null） */
     get security() {
         return this.pctx?.security ?? null;
     }
-    /**
-     * 作品投影管理器（可能为 null）—— 文件内容 → 概要+结构+决策
-     *
-     * 返回 null 时表示 Agent 未初始化。
-     * 宿主常用模式：
-     *   - `agent.works?.ensureProjection(filePath, content)` 读取文件后触发生成
-     *   - `agent.works?.loadAll()` 获取所有投影
-     */
+    /** 作品投影管理器（用户主动登记的 JSON 极简索引；`registerWork`/`listWorks`/`loadAndGetContextBlock`/`isFileMalformed`） */
     get works() {
         return this.workProjection;
     }
-    /** 会话管理器（宿主可通过此 getter 访问会话恢复/切换/分叉功能） */
+    /** 会话管理器（会话恢复/切换/分叉功能） */
     get sessionManager() {
         return this._sessionManager;
     }
-    /** 文本润色管理器（宿主可通过此 getter 调用 polish 方法） */
+    /** 文本润色管理器（polish 方法） */
     get polish() {
         return this.textPolisher;
     }