@zooique/memora 3.0.1 → 5.0.0

package/dist/agent/managers/sessionManager.js

@@ -8,7 +8,6 @@ import { chatBusyError, configError } from '../../utils/errors.js';
 // 会话标识格式契约（SSOT）：恢复最近会话时把 sessionId 拆成 (date, session) 供 loadMessages
 import { isValidSessionId, splitSessionId } from '../../utils/time.js';
 import { AGENT_CONSTANTS } from '../../agent/constants.js';
-import { GoalConsistencyChecker } from '../../agent/managers/goalConsistencyChecker.js';
 import { SessionStateMachine } from '../../agent/sessionStateMachine.js';
 /** 会话管理器：经回调访问 Agent 当前组件状态，支持 Agent 重建后自动取最新引用 */
 export class SessionManager {
@@ -24,17 +23,10 @@ export class SessionManager {
     stateMachine;
     /** 当前会话检查点（运行时状态快照） */
     checkpoint = null;
-    /** 检查点脏标记（内存态收口）：touchCheckpoint 置位、settleCheckpoint 清理（纯内存态，不落盘） */
-    checkpointDirty = false;
-    /** 目标一致性校验器（目标版本一致性校验） */
-    consistencyChecker;
-    /**
-     * 连续暂停时间戳数组（防滥用窗口）：每次高风险暂停记录时间戳，窗口（1 小时）内连续 2 次则强制降为低风险暂停。
-     * ⚠ 进程内状态，不入 SessionCheckpoint——重启归零是设计（反滥用卫生状态，非执行状态）；1h 窗口自愈防线，勿引入持久化。
-     */
-    consecutivePauseTimestamps = [];
-    /** 连续暂停时间窗口（毫秒），1 小时前的暂停不计入连续计数 */
-    static CONSECUTIVE_PAUSE_WINDOW_MS = 3_600_000;
+    // 删后注记（2026-10-16 · 5.0.0）：曾有「连续暂停防滥用」计数器（consecutivePauseTimestamps +
+    // CONSECUTIVE_PAUSE_WINDOW_MS）——整条机制从未通电：判据 isPauseLimitReached 零生产消费、
+    // 生产路径 pause() 恒传 lowRisk=true 使计数数组恒空，注释却谎称「≥2 次强制降级」。
+    // 按 SSOT/不带伤裁决拆除（见 CHANGELOG 5.0.0）。勿加回。
     // ── 运行时暂停超时检测 ────────────────────────────────
     /** 暂停超时检测定时器（只在 paused 状态时运行） */
     _pauseTimeoutTimer = null;
@@ -47,7 +39,6 @@ export class SessionManager {
         this.isChatBusy = isChatBusy;
         this.emitEvent = emitEvent;
         this.stateMachine = new SessionStateMachine('running');
-        this.consistencyChecker = new GoalConsistencyChecker();
     }
     // ─── SSOT 状态机代理（封装 stateMachine，暴露有界接口） ───
     /** 会话状态（状态机状态） */
@@ -66,14 +57,9 @@ export class SessionManager {
     get pendingPauseInfo() {
         return this.stateMachine.pendingPauseInfo;
     }
-    /** 检查是否处于暂停态 */
-    isPaused() {
-        return this.stateMachine.status === 'paused';
-    }
-    /** 检查是否处于运行态 */
-    isRunning() {
-        return this.stateMachine.status === 'running';
-    }
+    // 删后注记（2026-10-16 · 5.0.0，按 SSOT/不带伤裁决提前于 DEPRECATE-1 计划删除）：曾有
+    // isPaused()/isRunning() 两个便捷布尔查询——判据与 status getter 重复（三态两布尔还吞掉 error 态），
+    // 内核+宿主+手册零消费的冗余别名。替代物 = `status`（`session.status === 'paused'`）。勿加回（§3.2.1）。
     /** 待处理暂停请求是否在等待中 */
     isPausePending() {
         return this.stateMachine.isPausePending();
@@ -97,29 +83,38 @@ export class SessionManager {
     }
     /**
      * 会话替换 chokepoint：作废所有会话级派生缓存。
-     * 任何替换 loop 工作记忆（switch/fork/restore）入口都必须经此，新增派生缓存在此注册一处避免"对称的另一半没写完"。
+     * 任何替换 loop 工作记忆（switch/fork/load）入口都必须经此，新增派生缓存在此注册一处避免"对称的另一半没写完"。
      */
     invalidateSessionDerivedState() {
         // 真实 loop 必有 resetContextSummary；测试 mock 可能未实现，缺失时 no-op
         this.getLoop()?.resetContextSummary?.();
     }
-    /** 切换当前会话。底层 MessageHistory.switchSession 为纯同步操作，不引入无意义 async 包装。 */
-    switchSession(newSession) {
-        // 对话进行中切换会导致消息持久化分散
+    /**
+     * 会话替换前置闸（SSOT 收口）：任何替换 loop 工作记忆（switch/fork/load）的入口都必须经此。
+     * 合并「对话进行中」繁忙闸 + 「非 running 态拒绝」状态闸，消除 switch 有状态闸而
+     * fork/restore/load 漏闸的对称性缺口（原 switchSession 注释谎称「与 fork/restore 繁忙守卫同构」，
+     * 实际 fork/restore/load 无状态闸——属注释与实现不符的带伤，本次修复）。
+     * 暂停/错误态替换语义未定义，保守拒绝；宿主未就绪/暂停态触发由宿主 try/catch 兜底转错误通知。
+     */
+    assertSessionReplaceable(operation) {
+        // 对话进行中替换会导致消息持久化分散 / loop 工作记忆被替换
         if (this.isChatBusy()) {
-            throw chatBusyError('切换会话');
+            throw chatBusyError(operation);
         }
-        // 暂停/错误态切换语义未定义，保守拒绝（与 fork/restore 繁忙守卫同构）
+        // 暂停/错误态替换语义未定义，保守拒绝（所有替换入口共用此闸，避免状态闸不对称）
         if (this.stateMachine.status !== 'running') {
-            throw configError('切换会话', `会话处于 ${this.stateMachine.status} 态，无法切换`, [
-                '仅 running 态允许 switchSession',
+            throw configError(operation, `会话处于 ${this.stateMachine.status} 态，无法替换`, [
+                '仅 running 态允许替换工作记忆',
             ]);
         }
+    }
+    /** 切换当前会话。底层 MessageHistory.switchSession 为纯同步操作，不引入无意义 async 包装。 */
+    switchSession(newSession) {
+        // 替换工作记忆前置闸（SSOT：与 fork/load 共用断言，消除状态闸不对称）
+        this.assertSessionReplaceable('切换会话');
         // 检查点是当前会话的工作状态，切换时清空内存态（检查点纯内存态，不落盘）
         if (this.checkpoint && this.checkpoint.sessionId !== newSession) {
-            this.settleCheckpoint(true);
             this.checkpoint = null;
-            this.checkpointDirty = false;
         }
         const result = this.getHistory().switchSession(newSession);
         // 会话已替换：作废上下文摘要等派生缓存，避免陈旧摘要注入新会话
@@ -144,11 +139,28 @@ export class SessionManager {
             ]);
         }
         const { date, session } = splitSessionId(sessionId);
+        // 切换前记录旧会话身份（getCurrentSessionInfo 的唯一消费方）：
+        // 旧会话真实存在（history 已初始化）且 ≠ 目标会话时，切换完成后对旧会话触发归档事件——
+        // 旧会话由此进入历史列表，其 summary/keyTopics 归档必须在此发生（fire-and-forget，消费方在 Agent 层）
+        const previous = this.getCurrentSessionInfo();
+        // date/session 任一缺失（history 未初始化/测试 mock 未实现）视为无旧会话，不触发归档事件
+        const prevDate = previous?.date;
+        const prevSession = previous?.session;
+        const previousSessionId = prevDate && prevSession ? `${prevDate}-${prevSession}` : null;
         // 切换会话身份（内部含 busy/状态守卫 + 作废派生缓存）
         this.switchSession(session);
         // 加载/清空工作记忆：空会话 → restoreHistory([]) 清空（缓存已作废，无陈旧注入）
         const messages = await this.getHistory().loadSessionMessages(date, session);
         this.applySessionToLoop(messages);
+        // 切换成功才广播（失败路径已提前抛出）；重复打开同一会话无「切走」语义，不广播
+        if (prevDate && prevSession && previousSessionId !== sessionId) {
+            this.emitEvent('sessionSwitched', {
+                date: prevDate,
+                session: prevSession,
+                fromSessionId: previousSessionId,
+                toSessionId: sessionId,
+            });
+        }
         return messages.length;
     }
     /** 获取当前会话的日期和会话名（供 switchSession 前触发 content 类归档）；history 未初始化返回 null */
@@ -185,9 +197,8 @@ export class SessionManager {
      * @param targetSession - 可选，自定义新会话名；不传则自动生成
      */
     forkSession(roundId, targetSession) {
-        if (this.isChatBusy()) {
-            throw chatBusyError('分叉');
-        }
+        // 替换工作记忆前置闸（SSOT：与 switch/load 共用断言）
+        this.assertSessionReplaceable('分叉');
         const history = this.getHistory();
         // 记录源会话名（含日期前缀完整名，用于事件）
         const sourceSessionName = history.currentSessionName;
@@ -197,11 +208,10 @@ export class SessionManager {
         // round-based 模式：通过 roundIds 加载消息并应用到 loop
         const sessionMessages = history.loadRoundBasedMessages(result.roundIds);
         this.applySessionToLoop(sessionMessages);
-        // 关键约束：分叉后清空 checkpoint，防止新分支的 plan/goal 写入源会话检查点。
+        // 关键约束：分叉后清空 checkpoint，防止新分支的 plan 等快照内容写入源会话检查点
+        // （曾连写 plan/goal，goal 三字段已随 5.0.0 GOAL-DRIFT-1 退役删除）。
         if (this.checkpoint) {
-            this.settleCheckpoint(true);
             this.checkpoint = null;
-            this.checkpointDirty = false;
         }
         this.emitEvent('sessionForked', {
             from: sourceSessionName,
@@ -216,66 +226,21 @@ export class SessionManager {
             roundIds: result.roundIds,
         };
     }
-    /**
-     * 恢复最近活跃会话：经 ISessionStore 加载最近消息到工作记忆；宿主未注入则返回 0。
-     *
-     * 会话管理纯度：会话一律手动创建（宿主标题条「＋」唯一入口），
-     * 本方法只做「恢复」、绝不隐式创建会话——无按天归档隐式语义
-     * （「今天-main 优先」类规则），也无 preferredSession 参数。最近活跃的唯一时间序真理源 = listSessionMetas[0]（updatedAt 降序）。
-     *
-     * @returns 恢复的消息条数（0 = 无可恢复会话）
-     */
-    async restoreMostRecentSession() {
-        // 对话进行中恢复会导致 loop 工作记忆被替换
-        if (this.isChatBusy()) {
-            throw chatBusyError('恢复会话');
-        }
-        if (!this.sessionStore) {
-            logger.debug({ hasSessionStore: false }, '未注入 ISessionStore，无法恢复会话');
-            return 0;
-        }
-        // SSOT：listSessionMetas 依 updatedAt 降序，[0] 即最近活跃会话（唯一时间序真理源）
-        const metas = this.sessionStore.listSessionMetas();
-        const target = metas[0]?.sessionId;
-        if (!target) {
-            logger.debug({ sessionCount: metas.length }, '没有可恢复的历史会话');
-            return 0;
-        }
-        // 解析 "YYYY-MM-DD-session"（sessionId 格式契约真理源 = splitSessionId，session 名可含连字符）
-        const parsed = splitSessionId(target);
-        if (!parsed.session) {
-            logger.debug({ session: target }, '会话标识格式不匹配');
-            return 0;
-        }
-        const sessionMessages = this.sessionStore.loadMessages(parsed.date, parsed.session);
-        if (sessionMessages.length === 0) {
-            logger.debug({ messageCount: 0 }, '没有找到可恢复的历史会话');
-            return 0;
-        }
-        this.applySessionToLoop(sessionMessages);
-        return sessionMessages.length;
-    }
-    /** 恢复指定会话的对话 */
-    async restoreSession(date, session) {
-        // 对话进行中恢复会导致 loop 工作记忆被替换
-        if (this.isChatBusy()) {
-            throw chatBusyError('恢复会话');
-        }
-        const sessionMessages = await this.getHistory().loadSessionMessages(date, session);
-        if (sessionMessages.length === 0) {
-            return 0;
-        }
-        this.applySessionToLoop(sessionMessages);
-        return sessionMessages.length;
-    }
-    /** 对外暴露的 loadSessionMessages 委托。⚠ 会切换当前会话（更新 currentDate/currentSession），加载后下一条 chat 写入被加载会话 */
-    async loadSessionMessages(date, session) {
-        // 对话进行中加载会切换 currentDate/currentSession，导致消息持久化分散
-        if (this.isChatBusy()) {
-            throw chatBusyError('加载会话');
-        }
-        return this.getHistory().loadSessionMessages(date, session);
-    }
+    // 删后注记（2026-10-16 · 5.0.0，按 SSOT/不带伤裁决提前于 DEPRECATE-1 周期删除）：曾有公开
+    // restoreMostRecentSession() / restoreSession(date, session) 两个「从 ISessionStore 恢复会话到
+    // 工作记忆」入口——宿主零消费（宿主「打开最近/指定会话」走 chatPanel 读自家 HostSessionStore.
+    // listSessionMetas + switchToSession 对齐，不经内核恢复入口），且 listSessionMetas 降序契约的
+    // 真实消费者在宿主侧。恢复能力仍由 switchToSession（切换+加载，生产路径）与 forkSession 承担。
+    // 勿加回；若宿主将来要「重启后恢复内核 session 状态」，应基于 switchToSession 接线而非新开恢复面。
+    //
+    // 删后注记（2026-10-17 · 5.0.0，用户拍板不走 DEPRECATE-1 周期直删）：曾有公开委托
+    // loadSessionMessages(date, session)——仅薄委托 MessageHistory.loadSessionMessages（设 currentDate/
+    // currentSession + 经 ISessionStore.loadMessages 读消息），是「半个 switchToSession」：改了会话锚点
+    // 却不 restore 到 AgentLoop 工作记忆，调用后下一条 chat 写入被加载会话而上下文仍属旧会话 =
+    // 语义不完整的陷阱入口（JSDoc ⚠ 即防此）。替代 = switchToSession（切换+加载+应用 loop 的生产路径）；
+    // 「按 date/session 读消息」的能力真源 = ISessionStore.loadMessages 接口契约（宿主自家 store 已实现
+    // 并直读，chatPanel loadMessagesHistory 路径），不随本出口删除而消失。MessageHistory.
+    // loadSessionMessages 内部方法保留（switchToSession 内部消费，非公开面）。
     /** 将会话消息恢复到 AgentLoop 工作记忆 */
     applySessionToLoop(sessionMessages) {
         const messages = sessionMessages.map((tm) => ({
@@ -287,25 +252,11 @@ export class SessionManager {
         this.invalidateSessionDerivedState();
     }
     // ─── 不中断工作模型：检查点 + 状态机 ──────────────────
-    /**
-     * 检查点必需字段默认值工厂（默认值单一真理源）。
-     * 仅 createCheckpoint 新建/合并时使用——反序列化采用严格模式，不做静默补齐。
-     * 必须返回新实例：数组/对象默认值共享引用会让不同检查点互相污染（一个 push 计划任务项另一凭空多出）。
-     */
-    static checkpointDefaults() {
-        return {
-            mainGoal: '',
-            currentGoal: '',
-            goalChangeSeq: 0,
-            plan: [],
-        };
-    }
     /** 从当前运行时状态创建检查点：快照消息历史与会话标识生成 SessionCheckpoint（纯内存态，
      *  不落盘——中止/断电走中断轮补全，运行时暂停同 turn 内存续跑） */
-    createCheckpoint(mainGoal) {
+    createCheckpoint() {
         const history = this.getHistory();
         const prev = this.checkpoint;
-        const defaults = SessionManager.checkpointDefaults();
         // 合并语义：以已有检查点为基底展开，仅覆写本次重算的字段。
         // 【禁止改回对象字面量整体重建】——整体重建≈隐式字段白名单，任何未显式列出的字段每次 pause 被静默丢弃
         // （整体重建会使 planItemLog/completedToolCalls/pauseMeta 静默归零，非幂等工具恢复后重复执行）
@@ -323,50 +274,29 @@ export class SessionManager {
                     recovered: false,
                 }
                 : undefined,
-            mainGoal: mainGoal ?? prev?.mainGoal ?? defaults.mainGoal,
-            // 不传 mainGoal 时保留已有 currentGoal（防 pause() 内调用覆盖 updateGoal 的更新）
-            currentGoal: mainGoal ?? prev?.currentGoal ?? prev?.mainGoal ?? defaults.currentGoal,
-            goalChangeSeq: prev?.goalChangeSeq ?? defaults.goalChangeSeq,
-            plan: prev?.plan ?? defaults.plan,
+            // plan 缺省必须是新数组实例：默认值共享引用会让不同检查点互相污染（一个 push 计划任务项另一凭空多出）
+            plan: prev?.plan ?? [],
             lastHeartbeat: Date.now(),
         };
-        // 检查点内容已整体重算，强制清脏（纯内存，无落盘）
-        this.settleCheckpoint(true);
         return this.checkpoint;
     }
     /**
-     * 标记检查点已变更（内存写点统一入口）。刷新心跳并置脏标记。
-     * 所有修改 this.checkpoint 的方法都必须调用本方法，不得直接赋值 lastHeartbeat——否则变更不被后续清脏感知，内存与清脏链路静默分叉。
+     * 刷新检查点心跳（内存写点统一入口）。所有修改 `this.checkpoint` 的方法都必须调用本方法，
+     * 不得直接赋值 `lastHeartbeat`——心跳是暂停超时判定的兜底依据，绕过本方法会让超时判定读到陈旧值。
+     * ⚠️ 检查点不落盘：本方法**只刷心跳，无脏标记**（脏标记随 2026-10-14 CHKPT-3 减法删除——
+     * 曾经的 `checkpointDirty` 无外部消费者，属纯内耗）。
      */
     touchCheckpoint() {
         if (!this.checkpoint)
             return;
         this.checkpoint.lastHeartbeat = Date.now(); // 心跳唯一写点
-        this.checkpointDirty = true;
-    }
-    /**
-     * 检查点脏标记清理（**纯内存态**）：
-     * `SessionCheckpoint` 不落盘——中止/断电走「中断轮补全为完整 turn」而非跨重启恢复，
-     * 运行时暂停是同 turn 内续跑（内存态），无跨进程载体需求。故本方法仅清理脏标记，
-     * 不再写存储层（保留方法语义边界，避免为纯净化波及 40+ 处调用点）。
-     */
-    settleCheckpoint(force = false) {
-        if (!this.checkpoint)
-            return;
-        if (!force && !this.checkpointDirty)
-            return;
-        // 纯内存：无落盘动作，仅清脏
-        this.checkpointDirty = false;
     }
     /** 获取当前检查点快照；未创建返回 null */
     getCheckpoint() {
         return this.checkpoint;
     }
-    /**
-     * 暂停会话（用户/Agent/系统均可触发）。暂停前自动创建检查点；高风险暂停计入连续计数（防滥用），低风险不计。
-     * @param lowRisk 低风险暂停不计连续计数（默认 false）
-     */
-    pause(reason, source = 'user', lowRisk = false) {
+    /** 暂停会话（用户/Agent/系统均可触发）。暂停前自动创建检查点。 */
+    pause(reason, source = 'user') {
         const result = this.stateMachine.pause(reason, source);
         if (result.allowed) {
             // 先在 createCheckpoint 前记 pausedAt，检查点经 spread 继承，省去 pause() 内的二次补设分支
@@ -374,19 +304,16 @@ export class SessionManager {
                 this.checkpoint.pausedAt = Date.now();
             }
             this.createCheckpoint();
-            // 首轮暂停无现有检查点，pausedAt 未被 spread 继承，补设并标脏
+            // 首轮暂停无现有检查点，pausedAt 未被 spread 继承，补设并刷心跳
             if (this.checkpoint && !this.checkpoint.pausedAt) {
                 this.checkpoint.pausedAt = Date.now();
                 this.touchCheckpoint();
             }
-            // 仅高风险暂停记录时间戳（低风险由 Agent 自动兜底不累积）
-            if (!lowRisk) {
-                this.consecutivePauseTimestamps.push(Date.now());
-                logger.debug({ consecutivePauseCount: this.consecutivePauseTimestamps.length, reason }, '高风险暂停已记录时间戳');
-            }
-            else {
-                logger.debug({ reason }, '低风险暂停不记录时间戳（Agent 自动兜底）');
-            }
+            // pauseMeta 唯一写入点（SSOT）：两路暂停——用户 requestPause / ask_user 提问挂起——
+            // 全部经本方法翻状态机，故收敛到此处即可全覆盖，各调用方不再各自补写。
+            // ⚠ 消费方是**判据**不是展示：clearPlanOnTurnEnd 以 `cp.pauseMeta` 有无决定
+            //   「turn 是否真正结束、任务表该不该清」。任一暂停路径漏写，恢复后任务表会被误清。
+            this.setPauseMeta({ reason, source });
             // 启动暂停超时检测，防暂停会话长时间占用资源
             this.startPauseTimeoutTimer();
             this.emitEvent('sessionPaused', {
@@ -394,7 +321,7 @@ export class SessionManager {
                 source,
                 sessionId: this.checkpoint?.sessionId,
             });
-            logger.info({ reason, source, lowRisk }, '会话已暂停');
+            logger.info({ reason, source }, '会话已暂停');
         }
         return result.allowed;
     }
@@ -423,8 +350,6 @@ export class SessionManager {
                 // 走 setPauseMeta 唯一写入口而非内联赋值，避免绕过其兜底链路（其内部已含 touch+settle，此处不再重复调用）
                 this.setPauseMeta(undefined);
             }
-            // 连续暂停计数在暂停超时处理（checkPauseTimeout）对称重置，
-            // 不在 resume() 里清零——避免用户回答前过早清零导致防滥用机制无效
             this.emitEvent('sessionResumed', {
                 sessionId: this.checkpoint?.sessionId,
             });
@@ -445,38 +370,12 @@ export class SessionManager {
         }
         return result.allowed;
     }
-    // ── 防滥用：连续暂停计数 ───────────────────────────────
-    /** 清理过期暂停时间戳（窗口过滤）：移除超过窗口（1 小时）的旧时间戳，仅保留窗口内暂停；每次查询计数时自动调用 */
-    pruneStalePauseTimestamps() {
-        const cutoff = Date.now() - SessionManager.CONSECUTIVE_PAUSE_WINDOW_MS;
-        const before = this.consecutivePauseTimestamps.length;
-        this.consecutivePauseTimestamps = this.consecutivePauseTimestamps.filter((ts) => ts > cutoff);
-        const pruned = before - this.consecutivePauseTimestamps.length;
-        if (pruned > 0) {
-            logger.debug({ pruned, remaining: this.consecutivePauseTimestamps.length }, '过期暂停时间戳已清理');
-        }
-    }
-    /** 检查连续暂停是否已达上限（防滥用）：先清理窗口外时间戳，再查窗口内暂停≥2 次则强制降为低风险暂停。低风险不计数 */
-    isPauseLimitReached() {
-        this.pruneStalePauseTimestamps();
-        return this.consecutivePauseTimestamps.length >= 2;
-    }
-    /** 获取当前连续暂停计数：先清理窗口外时间戳，返回窗口内有效暂停数 */
-    getConsecutivePauseCount() {
-        this.pruneStalePauseTimestamps();
-        return this.consecutivePauseTimestamps.length;
-    }
-    /** 重置连续暂停计数（防滥用）：暂停超时处理后调用。与 resume() 分离，防回答前过早清零致防滥用失效 */
-    resetConsecutivePauseCount() {
-        this.consecutivePauseTimestamps = [];
-        logger.debug('连续暂停时间戳已清空');
-    }
     /**
      * 放弃当前暂停检查点（宿主 stop 语义的内核出口）
      *
      * 语义 = 用户决定**彻底放弃**暂停执行，不再 resume。清理内容：
      *   1. 停暂停超时定时器（防止已放弃的 checkpoint 继续被超时清理）
-     *   2. 清内存态 checkpoint + checkpointDirty + pauseMeta
+     *   2. 清内存态 checkpoint + pauseMeta
      *   3. 状态机 resetToRunning（回到 idle 之前的 running 基础态，下次 chat() 正常）
      *
      * 与 resume() 的区别：resume = 想继续跑暂停点；discardCheckpoint = 不想了，检查点作废。
@@ -494,7 +393,6 @@ export class SessionManager {
         this.stopPauseTimeoutTimer();
         // 2. 清内存态（检查点纯内存态不落盘，无存储清理动作）
         this.checkpoint = null;
-        this.checkpointDirty = false;
         this.setPauseMeta(undefined);
         // 3. 状态机回到 running
         this.stateMachine.resetToRunning();
@@ -515,8 +413,6 @@ export class SessionManager {
                 this.checkpoint.status = this.stateMachine.status;
                 this.touchCheckpoint();
             }
-            // 内存态收口（无落盘：recovered 只活内存，跨进程一律走中断补全）
-            this.settleCheckpoint();
             this.emitEvent('sessionRecovered', {
                 sessionId: this.checkpoint?.sessionId,
             });
@@ -524,52 +420,6 @@ export class SessionManager {
         }
         return result.allowed;
     }
-    /**
-     * 更新检查点目标版本：递增 goalChangeSeq 触发漂移检测。漂移处置由内核自兜底不依赖宿主：
-     * drift 级内核直接低风险暂停强制确认；minor 级仅发射事件+日志不打断执行。
-     * goalDriftDetected 事件为可观测性出口，宿主可选订阅，不订阅不影响正确性。
-     */
-    updateGoal(newGoal) {
-        if (!this.checkpoint) {
-            this.createCheckpoint(newGoal);
-            return null;
-        }
-        // 幂等短路：目标值未变直接返回（返回 level='same'），不递增 goalChangeSeq、不触发漂移。
-        // 续跑/补充输入每轮喂相同 currentGoal，若无短路 goalChangeSeq 会退化为轮次计数器
-        if (newGoal === this.checkpoint.currentGoal) {
-            return {
-                level: 'same',
-                similarity: 1,
-                constraints: this.consistencyChecker.extractConstraints(this.checkpoint.mainGoal),
-                constraintsConsistent: true,
-            };
-        }
-        // 执行一致性校验，与 mainGoal 对比
-        const mainGoal = this.checkpoint.mainGoal;
-        const consistencyResult = this.consistencyChecker.checkConsistency(mainGoal, newGoal);
-        this.checkpoint.currentGoal = newGoal;
-        this.checkpoint.goalChangeSeq++;
-        this.touchCheckpoint();
-        // 目标变更是会话的语义骨架，立即清脏（纯内存，无落盘）
-        this.settleCheckpoint();
-        // 检测到漂移则发射 goalDriftDetected 事件；drift 级自动低风险暂停强制用户确认（不计入连续计数）
-        if (consistencyResult.level !== 'same') {
-            this.emitEvent('goalDriftDetected', {
-                sessionId: this.checkpoint.sessionId,
-                mainGoal,
-                newGoal,
-                similarity: consistencyResult.similarity,
-                level: consistencyResult.level,
-                constraints: consistencyResult.constraints,
-                goalChangeSeq: this.checkpoint.goalChangeSeq,
-            });
-            if (consistencyResult.level === 'drift') {
-                const pauseReason = `目标漂移：新目标与原始目标不一致（相似度 ${consistencyResult.similarity.toFixed(2)}）`;
-                this.pause(pauseReason, 'system', true);
-            }
-        }
-        return consistencyResult;
-    }
     /** 全量替换计划任务项（与 appendPlanItem 仅追加正交；保留已有任务项 id/status）。唯一生产点：task_table_write mode='replace' */
     updatePlan(plan) {
         if (!this.checkpoint)
@@ -638,8 +488,7 @@ export class SessionManager {
         return cp.plan;
     }
     /**
-     * 更新计划任务项状态（plan 任务项状态的唯一写点）。必须经此写点置 checkpointDirty，
-     * 否则状态变更可能丢失标脏，计划变更与标脏在此原子完成。
+     * 更新计划任务项状态（plan 任务项状态的唯一写点）。
      *
      * 写完后自动 ensureActivePlanItem：如果变更导致 active 空缺（如把 active 标记为 done/blocked），
      * 则推进下一个 pending → active。这保证任何时刻 plan 中恰好有一个 active 任务项。
@@ -680,15 +529,14 @@ export class SessionManager {
         const firstPending = plan.find((s) => s.status === 'pending');
         if (firstPending) {
             firstPending.status = 'active';
-            // 不 touchCheckpoint——调用方（updatePlanItemStatus / writePlan）会统一标脏
+            // 不 touchCheckpoint——调用方（updatePlanItemStatus / writePlan）会统一刷心跳
         }
     }
     /**
      * 是否存在「在途计划」= 有未完成任务项（pending 或 active）。
      *
-     * SSOT：全库该命题唯一实现。消费方三处——会议骨架预置守卫（prepare，判断续会不重开）、
-     * 任务表 nudge 跳过（loop，已有在途表则不再诱导建表）、canContinueWithoutInput（agent，
-     * 可续跑信号）。禁任一消费方自行内联谓词。
+     * SSOT：全库该命题唯一实现。消费方两处——会议骨架预置守卫（prepare，判断续会不重开）、
+     * 任务表 nudge 跳过（loop，已有在途表则不再诱导建表）。禁任一消费方自行内联谓词。
      *
      * 口径取 pending||active（非仅 active）：与 ensureActivePlanItem 的补偿语义对齐——
      * plan 非空时恒有一个 active（见 :826 场景 1/2），全 done/blocked 时无 active（场景 3），
@@ -710,9 +558,8 @@ export class SessionManager {
             this.updatePlanItemStatus(planItemId, 'done');
         }
         this.appendPlanItemLog({ planItemId, summary });
-        // 心跳 + 清脏：step 边界即检查点语义边界（纯内存态；检查点不落盘，崩溃走中断轮补全）
+        // 心跳刷新：step 边界即检查点语义边界（纯内存态；检查点不落盘，崩溃走中断轮补全）
         this.touchCheckpoint();
-        this.settleCheckpoint();
     }
     /** 写 step 边界日志（时间轴投影，不改 plan 状态）。迭代边界
      *  onPlanItemBoundary 只做本写——plan 状态推进唯一写者 = LLM 的 task_table_update。 */
@@ -721,7 +568,6 @@ export class SessionManager {
             return;
         this.appendPlanItemLog(options);
         this.touchCheckpoint();
-        this.settleCheckpoint();
     }
     /**
      * 兜底收尾（「LLM 未显式 update 即收尾」）：turn 正常完成且计划已「全部到达」——
@@ -783,9 +629,8 @@ export class SessionManager {
         this.checkpoint.plan = [];
         this.checkpoint.planItemLog = undefined;
         this.touchCheckpoint();
-        this.settleCheckpoint();
     }
-    /** 设置暂停元数据；传 undefined 清除。写后必须清脏（清除也清脏，纯内存态无磁盘残留） */
+    /** 设置暂停元数据；传 undefined 清除。写后刷心跳（纯内存态无磁盘残留） */
     setPauseMeta(meta) {
         // 意图：pauseMeta 通常随 pause()（建检查点后）写入，但检查点不一定已存在（首轮/未知状态），
         // 故保留防御性守卫——无检查点时静默 no-op，不抛弃 pause/resume 链路的其余语义。
@@ -793,7 +638,6 @@ export class SessionManager {
             return;
         this.checkpoint.pauseMeta = meta;
         this.touchCheckpoint();
-        this.settleCheckpoint();
     }
     /**
      * 计划是否全部阻塞（预判短路收窄专用判定）：仅全 blocked 视为真停滞。
@@ -822,7 +666,6 @@ export class SessionManager {
     // ── 工具执行日志（outbox 模式）：补偿管线不启用，以下仅日志 ──
     /**
      * 记录工具执行：追加到检查点日志（append-only，内存态）。
-     * 标脏策略：仅标脏不即时清脏（completePlanItem step 边界统一清脏、createCheckpoint 暂停/异常强制清脏）。
      * 检查点纯内存态不落盘：completedToolCalls 仅内存态，回合中途崩溃即整体丢弃、走中断轮补全恢复；
      * 「工具重跑排重」仅在单进程存活期内有效，无跨重启持久化。
      */
@@ -842,28 +685,15 @@ export class SessionManager {
             }
         }
         this.touchCheckpoint();
-        // 依赖 completePlanItem / createCheckpoint 在 step 边界统一清脏
-    }
-    /** 记录非幂等工具执行（补偿降级后仅日志）：不再逐副作用执行补偿，仅记录事实供宿主/人工排查 */
-    compensateTool(record) {
-        const msg = `${record.name}(${record.argsSignature.slice(0, 50)})：非幂等工具，需人工确认是否需要补偿`;
-        logger.warn({ tool: record.name, argsSignature: record.argsSignature.slice(0, 80) }, msg);
-        return msg;
-    }
-    /** 记录所有非幂等工具执行（补偿降级后仅日志）：直接记录所有非幂等工具，每条生成一条日志 */
-    compensateAllNonIdempotent() {
-        if (!this.checkpoint?.completedToolCalls)
-            return [];
-        return this.checkpoint.completedToolCalls
-            .filter((r) => r.idempotent === 'non-idempotent')
-            .map((r) => this.compensateTool(r));
-    }
-    /** 发送心跳，防僵尸会话 */
-    heartbeat() {
-        if (this.checkpoint) {
-            this.touchCheckpoint();
-        }
     }
+    // 删后注记（2026-10-16 · 5.0.0，按 SSOT/不带伤裁决提前于 DEPRECATE-1 周期删除）：曾有公开
+    // compensateTool() / compensateAllNonIdempotent()——「非幂等工具补偿」降级后仅生成文案 +
+    // logger.warn，零状态变更、零返回值消费者、生产零调用（仅测试直测），属 no-op 型公开面。
+    // 勿加回；真要做人工确认面，应经 tool_start/tool_result 事件流在宿主侧渲染。
+    // 删后注记（2026-10-16 · 5.0.0，按 SSOT/不带伤裁决提前于 DEPRECATE-1 计划删除）：曾有公开
+    // heartbeat()——把私有 touchCheckpoint（心跳唯一写点）包成公开方法，暗示接入者需手动打卡；
+    // 实际心跳由每个修改检查点的方法自动刷新，且超时判定时钟钉在 pausedAt（设计已排除手动保活），
+    // 生产+宿主零调用。勿加回；真要「暂停保活」需求应开专用 API（见台账 DEPRECATE-1 销项记录）。
     /**
      * 标记会话暂停超时（超时事实唯一写点）。广播式：超时信息经事件载荷传递，多监听器并行消费互不干扰。
      * 由 checkPauseTimeout 调用（唯一调用点，启动路径无跨重启恢复）。
@@ -912,28 +742,14 @@ export class SessionManager {
         const sessionId = checkpoint.sessionId;
         const pauseDuration = Date.now() - (checkpoint.pausedAt ?? checkpoint.lastHeartbeat);
         logger.warn({ sessionId, pauseDuration }, '运行时检测到暂停超时，自动清理检查点');
-        // 清除检查点 + 状态机回到 running；残留脏标记无对应内存态一并清除
+        // 清除检查点 + 状态机回到 running
         this.checkpoint = null;
-        this.checkpointDirty = false;
         this.stateMachine.resetToRunning();
-        // 暂停超时意味着会话断裂，重置连续暂停计数（递增→衰减→重置闭合）
-        this.resetConsecutivePauseCount();
         // 记录超时会话 + 发射事件（唯一入口）
         this.markSessionTimedOut(sessionId, pauseDuration);
         // 超时后不再需要继续检测
         this.stopPauseTimeoutTimer();
     }
-    /** 关闭时清脏（纯内存，无落盘）：Agent 关闭、destroy 前调用。检查点不落盘，
-     *  本方法为保留语义边界的 no-op 清脏（无持久化动作） */
-    flushOnShutdown() {
-        this.settleCheckpoint(true);
-    }
-    /** 立即清脏（纯内存，无落盘）：非只读工具完成后调用。⚠️ 检查点不落盘，completedToolCalls 仅内存态——
-     *  「工具重跑排重」仅在单进程存活期内生效，进程崩溃/重启后失效（走中断轮补全）。无落盘设计，
-     *  本方法为保留语义边界的 no-op 清脏 */
-    flushNow() {
-        this.settleCheckpoint(true);
-    }
     /** 销毁 SessionManager，清理所有定时器（防阻止进程退出或悬空回调） */
     destroy() {
         this.stopPauseTimeoutTimer();