mingdao-harness 0.6.34 → 0.6.35

package/docs/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # MingDao-Harness 架构设计
 
-> 版本口径：v0.6.30。本文档覆盖 `src/` 全部 **93** 个模块（`find src -name '*.js' | wc -l` = 93），
+> 版本口径：v0.6.30（v0.7.0 §1.1 增量见下）。本文档覆盖 `src/` 全部 **94** 个模块（`find src -name '*.js' | wc -l` = 94），
 > 按层给出每个模块的职责与它守住的那条不变量；判定以文件头注释与实际实现为准，不做推断性描述。
 >
 > 阅读顺序建议：§2 模块索引（查「某件事归谁管」）→ §3 数据流（看一次回合怎么走）→ §4 已知边界（看它**保证不了**什么）。
@@ -93,9 +93,10 @@ MingDao 是一个「模型循环 + 工具 + 权限」内核，纯 Node.js ≥ 18
 - `net-policy.js` —— 出网白名单策略：纯函数，不碰 IO、不改全局状态，便于单测与文档化 —— 命中哪条规则、拦还是放，判定只此一份。
 - `net-guard.js` —— 出网闸门：在 `globalThis.fetch` 收口做出口判定 + 记账，`guardEgress()` 供 `node:http(s)` 路径（safe-fetch、sync 的 rawRequest）复用 —— **默认不安装**（未配置 `config.net` 时完全不介入）；只覆盖内核自己发起的请求，不代表整机不出网。
 
-### 2.4 会话 / 记忆 / 任务（10）
+### 2.4 会话 / 记忆 / 任务（11）
 
 - `session.js` —— 会话持久化：`<home>/sessions/<时间戳>-<随机>.jsonl` 每轮追加，`--continue` 载入最近一次，`--resume` 打开选择器 —— 会话文件是消息结构的唯一权威，检查点等旁挂状态另存侧车文件。
+- `session-events.js` —— 会话事件日志（v0.7.0 §1.1 切片 A）：`<session>.events.ndjson` 追加 12 类事件 `{seq,time,type,data}`（session/turn/step/tool/message/usage/compact/interrupt/checkpoint）—— **seq 是唯一关联键**：跨进程短临界区锁内「读尾行 last+1」、单次 append 后回读校验；读侧跳过 torn 行/未知 type 并返回 `skipped`；`replayToMessages()` 是纯函数（`message.append` 提供消息本体、`compact` 重置基线、`interrupt` 延迟补 tool 占位），由事件流重放的消息数组必须与原消息数组逐字节等价；事件文件是**旁路**，`loadSession`/`rewriteSession`/SSE/UI 都不读它，`cfg.eventLog=false` 或 `MINGDAO_EVENT_LOG=0` 可整体回滚。
 - `session-index.js` —— 会话检索索引：词表倒排 + 按 mtime/size 的增量同步，分片存 `<home>/sessions-index/<2位sha1前缀>.json`（256 片）—— 未变化直接用缓存词表，>8MB 文件跳过并移除条目；中文按 bigram + 单字、查询串同口径分词后 AND 匹配。
 - `memory.js` —— 长记忆与自主进化：用户记忆 `~/.mingdao/AGENTS.md`（手动 + 会话结束自动提取用户偏好并去重追加）、会话日志 `journal.jsonl`（默认不注入系统提示，`--journal` / WebUI 勾选才取最近 3 条）—— 自动提取用 executor 模型（约几十 token），`autoMemory: false` 可关。
 - `tasks.js` —— 多会话后台任务面板：`mingdao run` 拉起独立 worker 子进程，状态落 `<home>/tasks/<id>.json`，命令族 `run` / `tasks` / `tasks watch` / `tasks kill` —— taskId 用不可枚举随机值；kill 前必须过 PID 归属校验（见 `proc.js`）。
@@ -176,8 +177,8 @@ MingDao 是一个「模型循环 + 工具 + 权限」内核，纯 Node.js ≥ 18
 - `help.js` —— 帮助文本的唯一来源：CLI 与 REPL 各用 `variant` 声明自己多出来的那几行 —— 两个入口的差异必须是显式的，不允许各存一份正文。
 - `index.js` —— 库公共 API：导出 `@stable`（minor 内向后兼容）与 `@experimental` 两组能力，契约与示例见 DEVELOPER.md。
 
-模块计数核对：7 + 8 + 12 + 10 + 4 + 2 + 16 + 13 + 19 = **92** 个条目（含合并条目；`find src -name '*.js' | wc -l` = **93**），其中 §2.7 的
-`web/util.js` / `web/app.js` 一条覆盖 2 个文件、`web/viewmodel.js` 单列，故条目覆盖 **93** 个 `src/**/*.js`（每版本以 `find` 实测为准），
+模块计数核对：7 + 8 + 13 + 11 + 4 + 2 + 16 + 13 + 19 = **93** 个条目（含合并条目；`find src -name '*.js' | wc -l` = **94**），其中 §2.7 的
+`web/util.js` / `web/app.js` 一条覆盖 2 个文件、`web/viewmodel.js` 单列，故条目覆盖 **94** 个 `src/**/*.js`（每版本以 `find` 实测为准），
 与 `find src -name '*.js' | wc -l` 的结果一致。
 
 ## 3. 数据流：一次 `runTurn` 的关键路径

package/docs/CONFIG.md

@@ -27,7 +27,8 @@
 
 可选字段：`temperature`、`maxOutputTokens`、`includeUsage`（流式请求 usage 统计，个别网关不支持
 `stream_options` 时设 `false`）、`autoTitle`（自动生成会话标题，默认开）、`notify`（任务桌面通知，默认开）、
-`autoCompact`（上下文自动压缩，默认开，见下）、`audit`（工具调用审计，默认开，见下）。
+`autoCompact`（上下文自动压缩，默认开，见下）、`audit`（工具调用审计，默认开，见下）、
+`eventLog`（会话事件日志双写，默认开，见下）。
 
 ### WebUI 设置项的「默认值」列（只读，不落盘）
 
@@ -85,6 +86,26 @@ MingDao 先用 executor 模型（路由关闭时为当前模型）把被裁段
 中文按 bigram+单字、英文按词，多词 AND 匹配；只有内容变化（mtime/size）的会话才重新
 分词，删除的会话自动清出索引。索引目录可随时删除（下次搜索自动重建）。
 
+## 会话事件日志（v0.7.0 §1.1）
+
+每个会话在消息文件旁多一条 append-only 的事件流 `<session>.events.ndjson`（0600，与
+`<session>.jsonl` 同级）：每条 `{seq,time,type,data}`，seq 单调、是 turn/step/tool/message
+之间的唯一关联键。当前 12 类事件：`session.start` / `turn.start` / `turn.end` / `step.start` /
+`step.end` / `tool.start` / `tool.end` / `message.append` / `usage` / `compact` / `interrupt` /
+`checkpoint`。
+
+- **双写、旁路**：`appendMessages()` 在会话消息落盘**之后**追加 `message.append`；agent 在
+  turn/step/工具/用量/压缩/中断边界追加结构事件。事件日志写失败只 warn，**不影响会话写入**，
+  也不改变 `loadSession()` / `rewriteSession()` 的返回值。
+- **确定性重放**：`replayToMessages(events)` 由事件流派生消息数组（`compact` 重置基线、
+  `interrupt` 补 tool 占位），已对拍单轮 / 工具调用 / 压缩 / 中断四个场景与消息数组 deepEqual。
+- **回滚开关**：`"eventLog": false`（默认开）或环境变量 `MINGDAO_EVENT_LOG=0`。关闭后**完全**
+  停止事件写入（含 `message.append` 双写），会话文件照常写入。
+- **兼容**：旧会话没有 events 文件时读取返回空流；事件侧车不会出现在会话列表/最近会话中；
+  事件文件不参与云同步。SSE 帧与 UI 在本切片**未改**。
+- **已知边界**：手动 `/compact` 走 `rewriteSession` 时没有对应 `compact` 事件；自动标题重命名
+  会话文件不会搬迁事件侧车；这两类留待后续切片（事件日志目前是旁路，不参与既有读取）。
+
 ## 会话级工作空间（P3-4）
 
 WebUI 中每个会话记住自己的工作目录：新会话记录创建时的全局工作空间；继续该会话时任务

package/docs/DEVELOPER.md

@@ -411,3 +411,18 @@ CI 想"只卡新增盲区"就用当前存量数当基线（例如 `--fail-over 1
   三个套件都是零外部依赖、只用本机临时目录。
 - 盲区检查只回答"有没有变异"，不回答"变异质量"——`--fail-over` 只能挡住新增盲区，
   挡不住"给一个 600 行模块写 1 条无关变异"这种凑数。质量仍靠 review 与 `expect` 关键词约束。
+
+### 7.4 覆盖率当前**只报告不判失败**（v0.6.35 起）
+
+实测：同一棵树、同一套 34 个套件、连续三次跑 `npm run coverage`，code-lines 得到
+**73.7% / 72.5% / 69.7%**（覆盖行数差 760 行）。原因不是代码变了，而是套件会 spawn 大量子进程，
+**子进程的 V8 覆盖数据是否被聚合不稳定**。
+
+因此 `npm run coverage` 现在只输出趋势与"棘轮回落"提示，**不返回非零**。要恢复闸门：
+
+1. 让收集确定：固定套件顺序、等待所有子进程退出、校验每个套件都产出了覆盖目录；
+2. 连续 3 次同树测量差 ≤0.2pp（可作为一条套件断言）；
+3. 设 `COVERAGE_GATE=1` 即可恢复"低于基线即失败"（代码分支仍保留）。
+
+> 为什么宁可"只报告"也不留一个随机红的闸门：**被随机关掉的闸门等于没有闸门**，
+> 而且会训练大家忽略红灯。宁可先诚实地承认"现在量不准"。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mingdao-harness",
-  "version": "0.6.34",
+  "version": "0.6.35",
   "description": "MingDao Harness —— 开源智能体框架（Agent Harness）。零依赖、开箱即用，针对 DeepSeek-V4 系列优化，开放主流模型接入。",
   "type": "module",
   "bin": {

package/src/agent.js

@@ -5,6 +5,7 @@
 // v0.7.0 §1.5：**文案 / 预测层已迁至 ./messages.js**（逐字搬运、逻辑零变化）——
 // 本文件只保留循环与编排；导出面由下方 `export { … } from './messages.js'` 逐字保留。
 
+import path from 'node:path';
 import { trimMessages, messageTokens, approxTokens } from './context.js';
 import { compactConversation } from './compact.js';
 // 审计 M-1 §2.1 第 4 条（Pack 反向提权）：`makeToolCtx` 把内核 ctx 剪成"工具面向的 ctx"并冻结。
@@ -38,6 +39,8 @@ import { compileConstraints, checkPreTool, checkPostTool, checkOutput, blockedOu
 import { createLedger, newRunId } from './ledger.js';
 import { registerEgressSink } from './net-guard.js';
 import { getActivePackContext } from './packs.js';
+import { mingdaoHome } from './config.js';
+import { appendEvent, eventFileFor, eventLogEnabled, missingToolCallIds, setEventLogEnabled } from './session-events.js';
 // v0.6.11（审计 P1-1 拆分第三刀）：工具编排两端的判据单源在 tools-flow.js——
 // ① 本轮可见哪些工具（只读档 × 预设白名单 × 已用工具快照 × MCP 只读标注）；
 // ② 工具结果怎么回填（序列化 / 复用前缀 / 约束拒绝文案 / 按窗口截断）；
@@ -117,6 +120,24 @@ function resolveEndpointBaseUrl(/** @type {any} */ cfg, /** @type {any} */ model
   }
 }
 
+/**
+ * v0.7.0 §1.1：解析本会话的事件侧车。优先级：`cfg.eventFile`（测试/嵌入方显式指定）>
+ * `sessionRef.file` > `<MINGDAO_HOME>/sessions/<sessionRef.name>`。
+ * 任何异常都返回 null——事件日志是旁路，路径解析失败不得影响回合。
+ * @param {any} sessionRef
+ * @param {any} cfg
+ * @returns {string|null}
+ */
+function resolveAgentEventFile(sessionRef, cfg) {
+  try {
+    if (cfg?.eventFile) return eventFileFor(String(cfg.eventFile));
+    const ref = sessionRef || {};
+    if (ref.file) return eventFileFor(String(ref.file));
+    if (ref.name) return eventFileFor(path.join(mingdaoHome(), 'sessions', String(ref.name)));
+  } catch {}
+  return null;
+}
+
 /**
  * 创建 Agent 循环（调用方只需传 provider/permission/io/modelName/workingDir，其余可选）
  * @param {{ provider: any, permission: any, io: any, modelName: any, workingDir: any,
@@ -132,6 +153,53 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
   // v0.6.26 §3.91：子代理实例（spawnTask 传入 parentProgress / 子任务标记）。子代理的成功**不**计入
   // 端点"连续干净成功"——一个父回合里可能跑多个子代理，否则一次回合就能把 +25% 的上调门槛凑满。
   const isSubagent = Boolean(cfg?.parentProgress || cfg?.subagentLabel);
+  // v0.7.0 §1.1：事件双写的开关与出口（旁路：任何失败只 warn，绝不影响回合结果）。
+  // `cfg.eventLog === false` 时**同时**停掉 session.appendMessages 的 message.append 双写，
+  // 否则只会关掉 agent 事件、留下半份事件流。子代理不重复设置进程开关（父代理已设）。
+  const eventsOn = eventLogEnabled(cfg);
+  if (!isSubagent) setEventLogEnabled(eventsOn);
+  let eventFileKey = '';
+  let eventFileCache = /** @type {string|null} */ (null);
+  let eventWarned = false;
+  const sessionEventFile = () => {
+    const ref = /** @type {any} */ (sessionRef || {});
+    const key = `${String(cfg?.eventFile || '')}|${String(ref.file || '')}|${String(ref.name || '')}`;
+    if (key !== eventFileKey) {
+      eventFileKey = key;
+      eventFileCache = resolveAgentEventFile(sessionRef, cfg);
+    }
+    return eventFileCache;
+  };
+  /** @param {string} type @param {any} data */
+  const emitEvent = (type, data) => {
+    try {
+      if (!eventLogEnabled(cfg)) return;
+      const file = sessionEventFile();
+      if (!file) return;
+      const r = appendEvent(file, { type, data });
+      if (!r.ok && !eventWarned) {
+        eventWarned = true;
+        console.warn(`[MingDao] ⚠ 会话事件日志写入失败（${file}）：${r.error}——事件日志本次不完整，不影响会话与回合结果。`);
+      }
+    } catch {}
+  };
+  // step 边界：step.start 在本步开始时写；step.end 在**下一步开始前 / 回合收尾**补写，
+  // 因此即使某个出口提前 return，事件流里也不会留下永远不结束的 step。
+  /** @type {{step:number,round:number}|null} */
+  let openStep = null;
+  /** @param {string} status */
+  const closeStep = (status) => {
+    if (!openStep) return;
+    const s = openStep;
+    openStep = null;
+    emitEvent('step.end', { step: s.step, round: s.round, status });
+  };
+  /** @param {number} step @param {number} round */
+  const beginStep = (step, round) => {
+    closeStep('next');
+    openStep = { step, round };
+    emitEvent('step.start', { step, round });
+  };
   // safeBudget 恒用：即使用户显式 contextBudget 也套「窗口−输出−余量」上限与 75% 舒适区，
   // 防显式值撑爆窗口（本地模型窗口可能只有 32k/131k，用户却留了默认 128000）。
   const safeB = safeBudget(cfg, caps);
@@ -595,6 +663,14 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
       zeroToolCalls: ensureZeroToolCallNotice(),
     });
     let aborted = false;
+    // v0.7.0 §1.1：中断事件只写一次（SIGINT 可能在思考/工具/权限询问期间到达）。
+    // toolCallIds 交给 replay 延迟补占位：随后 message.append 若已含占位，不会重复。
+    let interruptEmitted = false;
+    const emitInterruptOnce = (/** @type {string} */ reason) => {
+      if (interruptEmitted) return;
+      interruptEmitted = true;
+      emitEvent('interrupt', { reason, toolCallIds: missingToolCallIds(messages) });
+    };
     // 连续空/截断输出计数（防止无限续写）。v0.6.28（M-10）：**必须真的复位**——
     // 有进展的工具轮（成功且不重复，与看门狗同判据）与有内容的模型轮都会清零，
     // 否则「3 次非连续空轮」会被误判成「连续 3 轮」而中止（文案与实现的判据必须一致）。
@@ -634,7 +710,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
     // A1：本回合的剥描述冻结快照（会话级 usedToolNames 的副本）——回合内 schema 字节不变
     const turnStrippedSet = new Set(usedToolNames);
     // 整个回合注册一次 SIGINT：思考、工具执行、权限询问期间都能中断
-    const offSigint = io.onSigint ? io.onSigint(() => { aborted = true; currentAc?.abort(); }) : () => {};
+    const offSigint = io.onSigint ? io.onSigint(() => { aborted = true; emitInterruptOnce('sigint'); currentAc?.abort(); }) : () => {};
     // ---- v0.6.13（A）：回合级进度快照 + 无进展看门狗 ----
     // 快照挂在 io 上：WebUI 服务端（src/web/server.js）每 5s 读它下发状态条、每 30s 落一行日志。
     // 这里不改 web-io.js 的接口（它不在本次改动面内），字段是"只读约定"。
@@ -937,6 +1013,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
       // recordUsage，长任务期间「今日费用」恒为 0 被误读为「无统计」；中断时已完成轮次费用也保留）。
       const roundUsageStart = { prompt_tokens: usage.prompt_tokens, completion_tokens: usage.completion_tokens, prompt_cache_hit_tokens: usage.prompt_cache_hit_tokens || 0, prompt_cache_miss_tokens: usage.prompt_cache_miss_tokens || 0 };
       while (steps < stepLimit) {
+      beginStep(steps + 1, round + 1);
       steps += 1;
       // v0.6.28（L-13）：`finish` 是**本次模型请求**的 finish_reason，不是回合级状态。
       // 每步开始重置，且只由本步的 res.finish 写入（见下方赋值）——否则上一轮 length/capped
@@ -1011,6 +1088,9 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
             try {
               onCompact?.(messages);
             } catch {}
+            // v0.7.0 §1.1：compact 事件携带压缩后的**完整基线**——重放据此整体替换，
+            // 与 onCompact 把同一份 messages 重写进 .jsonl 是同一事实。
+            emitEvent('compact', { droppedCount: compacted.droppedCount, droppedTokens: compacted.droppedTokens, messages });
           }
         } catch {}
       }
@@ -1505,6 +1585,8 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
           }
         }
       }
+      // v0.7.0 §1.1：本步模型用量（逐轮，便于与 message/tool 事件对齐）
+      if (res.usage) emitEvent('usage', { model: activeModel, round, step: steps, usage: res.usage, total: { ...usage } });
 
       if (res.toolCalls?.length) {
         // v0.6.13（A）：本回合 tool_call 计数（界面/日志/收尾提示的单一来源）
@@ -1661,6 +1743,8 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
         // 后续相同调用直接复用结果（仍逐个回填 tool 消息以保持 tool_call_id 配对）
         async function runTool(/** @type {any} */ prep) {
           io.renderToolStart?.(prep.name, prep.args);
+          // v0.7.0 §1.1：工具边界事件（只记 id/名字/是否命中缓存，不记参数正文）
+          emitEvent('tool.start', { callId: prep.tc?.id ?? null, name: String(prep.name || ''), cached: Boolean(prep.cached) });
           // v0.6.13（A）：登记"正在等待哪个工具"——`task` 子代理/长命令动辄几十分钟，
           // 界面与日志必须能显示"在等谁、等了多久"，否则与卡死无法区分。
           const prevPending = turnProgress.pendingTool;
@@ -1725,6 +1809,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
           else turnProgress.unproductive += 1;
           // v0.6.28（M-10）：有进展的工具轮复位空轮计数（失败/重复调用不算进展，与看门狗同判据）。
           if (toolOk && repeatedBefore === 0) emptyRounds = 0;
+          emitEvent('tool.end', { callId: prep.tc?.id ?? null, name: String(prep.name || ''), ok: toolOk, ms, cached: Boolean(prep.cached) });
           // 省钱 B3：逐工具调用/耗时累加（费用二级分账的 byTool 维度）
           const ts = toolStats.get(prep.name) || { calls: 0, ms: 0 };
           ts.calls += 1;
@@ -1799,6 +1884,12 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
 
         // 拒绝项（参数解析失败/钩子阻止/预设白名单/权限拒绝/领域约束）同样按原序入队。
         // 它们没有执行、没有耗时/账本结果，只回填一条 tool 消息——顺序必须与成功项一致。
+        function emitDeniedToolEvents(/** @type {any} */ prep) {
+          // 拒绝项没有执行/耗时，但同样是「一次工具调用」：补 start/end 让时间线成对。
+          emitEvent('tool.start', { callId: prep.tc?.id ?? null, name: String(prep.name || ''), denied: true });
+          emitEvent('tool.end', { callId: prep.tc?.id ?? null, name: String(prep.name || ''), ok: false, denied: true, ms: 0 });
+        }
+
         function finishDenied(/** @type {any} */ prep) {
           pendingToolMessages.push({
             idx: prep.idx,
@@ -1857,6 +1948,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
             for (let idx = 0; idx < prefix.length; idx += 1) await finishTool(prefix[idx].prep, results[idx].r, results[idx].t0);
             for (const b of batch.slice(prefix.length)) {
               if (b.prep.denied != null) {
+                emitDeniedToolEvents(b.prep);
                 finishDenied(b.prep);
                 continue;
               }
@@ -1866,6 +1958,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
           } else {
             for (const b of batch) {
               if (b.prep.denied != null) { // 拒绝/失败成员：只入队，不执行
+                emitDeniedToolEvents(b.prep);
                 finishDenied(b.prep);
                 continue;
               }
@@ -2239,13 +2332,29 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
       turnLearned = { ...freshLearned.record, appliedBudget: freshSafe };
     }
     let r = /** @type {any} */ (null);
+    // v0.7.0 §1.1：turn 边界（双写旁路；cfg.eventLog=false 时 emitEvent 内部直接 no-op）
+    emitEvent('turn.start', { model: modelName, session: sessionRef?.name ?? null, messages: Array.isArray(messages) ? messages.length : 0 });
     try {
       r = await runTurnInner(messages, startBudget);
+    } catch (err) {
+      closeStep('error');
+      emitEvent('turn.end', { status: 'error', error: String(/** @type {any} */ (err)?.message ?? err) });
+      throw err;
     } finally {
       turnLearned = null;
       currentTurnBudget = null;
       currentTurnMaxOutput = null;
     }
+    // 收尾：最后一个 step 也要有 step.end（事件流里不留下永远不结束的 step），再写 turn.end。
+    closeStep(r?.aborted ? 'aborted' : r?.stalled ? 'stalled' : 'completed');
+    emitEvent('turn.end', {
+      status: r?.stalled ? 'stalled' : r?.aborted ? 'aborted' : r?.capHit ? 'capped' : 'done',
+      steps: Number(r?.perf?.steps) || 0,
+      usage: r?.usage ?? null,
+      aborted: Boolean(r?.aborted),
+      capHit: Boolean(r?.capHit),
+      truncated: Boolean(r?.truncated),
+    });
     // v0.6.26 §3.91（端点级学习·上调）：**干净成功**（无内存压缩、无中断/无进展/截断）才计数，
     // 连续 3 次把学习值 +25%（上限 = 用户配置的预算）。上调后若再撞内存墙，
     // 两级压缩仍失败会把它重新学下来——降级与恢复都基于真实结果。

package/src/config.js

@@ -7,6 +7,7 @@ import os from 'node:os';
 import { PROVIDERS, modelPreset, providerPreset, pickFamilyModel, normalizeModelLabels, DEFAULT_MODEL, DEFAULT_PLANNER_MODEL, DEFAULT_EXECUTOR_MODEL } from './models.js';
 import { setStoredKey, resolveApiKey, maskKey } from './credentials.js';
 import { atomicWriteFileSync, withFileLock, withFileLockSync as withStateFileLockSync } from './atomic-write.js';
+import { setEventLogEnabled } from './session-events.js';
 
 export function mingdaoHome() {
   return process.env.MINGDAO_HOME || path.join(os.homedir(), '.mingdao');
@@ -357,6 +358,19 @@ function prepareConfigForWrite(cfg) {
   return base;
 }
 
+/**
+ * v0.7.0 §1.1：把 `config.eventLog` 同步到事件日志的进程级开关。
+ *
+ * 为什么必须在 config 层做一次：WebUI 的 /api/chat 会**先**把用户消息 appendMessages 落盘、
+ * **后**才 createAgent；只靠 createAgent 设置开关会让 config 里的 eventLog=false 漏掉这条
+ * 用户消息（半份事件流）。loadConfig/saveConfig 是配置进入进程的两个入口，在这里设一次，
+ * 任何「先写会话、后建 agent」的顺序都不会漏。缺省（字段不存在）按开启处理。
+ * @param {any} cfg
+ */
+function applyEventLogGate(cfg) {
+  setEventLogEnabled(!(cfg && cfg.eventLog === false));
+}
+
 /** 读取配置对象（不存在/损坏返回 null）；返回值为用户可编辑的任意 JSON 配置，类型不定
  *
  * 注意（v0.6.3 / H-7）：null **同时**表示「不存在」与「读不出来」。凡是要**写**配置的调用点，
@@ -367,6 +381,7 @@ export function loadConfig() {
   if (!r.ok) return null;
   const cfg = applyModelLabels(applyCachedModelDefaults(r.data));
   rememberConfig(cfg); // v0.7.0 §1.3：记下基线，saveConfig 只合并增量
+  applyEventLogGate(cfg); // v0.7.0 §1.1：config.eventLog=false 在「先落盘、后建 agent」路径也生效
   return cfg;
 }
 
@@ -388,11 +403,13 @@ export function loadConfigForWrite(why = '某个写配置的命令') {
   if (r.ok) {
     const cfg = r.data || {};
     rememberConfig(cfg);
+    applyEventLogGate(cfg);
     return cfg;
   }
   quarantineCorruptConfig(`${why} 需要写回配置，但读不出来：${r.error}`);
   const empty = {};
   rememberConfig(empty);
+  applyEventLogGate(empty);
   return empty;
 }
 
@@ -444,6 +461,7 @@ export function saveConfig(cfg) {
       writeConfigUnlocked(prepareConfigForWrite(cfg));
       rememberConfig(cfg); // 成功后把这版对象当作下次增量比较的基线
     });
+    applyEventLogGate(cfg);
     return { ok: true, error: null };
   } catch (err) {
     const msg = String(/** @type {any} */ (err)?.message ?? err);

package/src/session-events.js

@@ -0,0 +1,533 @@
+// 会话事件日志（v0.7.0 §1.1 切片 A）：append-only 的事件流，与消息数组**双写**。
+//
+// 为什么要有它：会话此前只存 `<home>/sessions/<name>.jsonl` 的消息数组——「这条消息属于哪个
+// turn/step、工具有没有结束、压缩发生在第几条之前」这些结构信息只能靠字段猜。本模块把会话状态
+// 增加一条**可重放**的事实源：每条 `{seq,time,type,data}` 追加一行，seq 单调且是唯一关联键。
+//
+// 本切片**不改既有读取路径**：
+//   · `loadSession` / `rewriteSession` 的返回值与 `.jsonl` 格式一字未动；
+//   · 事件文件是**并列的新侧车** `<session>.events.ndjson`，旧会话没有它照样可读；
+//     **为什么不是 .jsonl**：全仓（以及用户脚本/测试）有大量 `readdirSync(sessions).filter(f => f.endsWith('.jsonl'))`
+//     的写法，侧车若也叫 `.jsonl` 就会被当成会话——本版实测已挂掉 2 个 e2e（分享时把侧车当会话推给服务端，
+//     服务端回「你还没有这个会话」）。改成 `.ndjson`（同格式、不同扩展名）让这类碰撞在命名层就不存在。
+//   · SSE 帧、UI、账本、同步都不读事件文件。
+// 因此事件日志坏掉/写不进去，最多是「这条时间线不完整」，绝不影响会话本身。
+//
+// 可靠性约定：
+//   · 所有对外 API 一律返回 `{ok,error}` 形态，**任何失败都不许抛到调用方**；
+//   · seq 分配在跨进程文件锁内「读尾行 → last+1 → 单次 append」，同进程再用 Map 缓存上一条，
+//     避免 8 个子进程并发时重号；
+//   · 读取跳过 torn 行（半截 JSON）与未知 type，并返回 `skipped` 计数——**可见**，不静默丢；
+//   · `replayToMessages` 是纯函数：`message.append` 提供消息本体，`compact` 重置基线，
+//     `interrupt` 在最终消息数组里补齐尚未回填的 tool 占位（延迟到全部事件读完再补，避免与
+//     随后 message.append 的占位重复/错位）。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { appendFilePrivateSync } from './atomic-write.js';
+
+/** 本切片先定这 12 类事件；新增类型必须同时更新这里与 `test/session-events.js` 的清单。 */
+export const EVENT_TYPES = Object.freeze([
+  'session.start',
+  'turn.start',
+  'turn.end',
+  'step.start',
+  'step.end',
+  'tool.start',
+  'tool.end',
+  'message.append',
+  'usage',
+  'compact',
+  'interrupt',
+  'checkpoint',
+]);
+
+const EVENT_TYPE_SET = new Set(EVENT_TYPES);
+
+/** 回滚开关：`MINGDAO_EVENT_LOG=0`（或 false/off/no）时全局关闭双写。 */
+export const EVENT_LOG_ENV = 'MINGDAO_EVENT_LOG';
+
+/** 中断时补的 tool 占位文案——与 `agent.js#finishTurn` 的既有文案保持逐字一致。 */
+export const INTERRUPTED_TOOL_CONTENT = '（已中断，未执行）';
+
+/** 尾部读取窗口：足够覆盖若干条事件；只有读不到 seq 且文件更大时才回退整文件。 */
+const TAIL_BYTES = 64 * 1024;
+
+/** 同进程 seq 缓存：`事件文件绝对路径 → {seq, size}`。跨进程仍以文件尾为准。 */
+const seqCache = new Map();
+
+/** 追加锁的临界区只有「读尾行 + 一次 append」：超过这个年龄的锁视为崩溃残留。 */
+const APPEND_LOCK_STALE_MS = 10000;
+const APPEND_LOCK_TIMEOUT_MS = 10000;
+
+/** 同步小睡：临界区极短，用 Atomics.wait 让出 CPU（不引入异步传染）。 */
+function sleepSync(/** @type {number} */ ms) {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  } catch {}
+}
+
+/** 释放追加锁。返回是否真的删掉了（删除失败只影响下一次抢锁，不影响本次写入结果）。 */
+function releaseAppendLock(/** @type {string} */ lock) {
+  try {
+    fs.unlinkSync(lock);
+  } catch {
+    return false;
+  }
+  return true;
+}
+
+/** 回收崩溃残留锁：只回收「超过临界区阈值」的锁，避免误删刚建的新锁。 */
+function reclaimStaleAppendLock(/** @type {string} */ lock) {
+  try {
+    const st = fs.statSync(lock);
+    if (Date.now() - st.mtimeMs <= APPEND_LOCK_STALE_MS) return false;
+    try {
+      fs.unlinkSync(lock);
+    } catch {
+      return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 每文件一个极短临界区的追加锁（`<eventFile>.lock`，O_EXCL 创建）。
+ *
+ * 为什么不用 `atomic-write.js#withFileLockSync`：那套锁允许调用方按业务持锁数秒，
+ * 本模块的临界区只有「读尾行 → append → 回读校验」三步、毫秒级；这里用更小的超时/陈旧阈值，
+ * 且失败一律折成 `{ok:false}`（见 appendEvent 的 catch），不会让事件日志拖住会话。
+ * 也可以理解为：seq 的唯一性靠这把锁，锁外的任何路径都不写事件文件。
+ * @template T
+ * @param {string} file
+ * @param {() => T} fn
+ * @returns {T}
+ */
+function withAppendLock(file, fn) {
+  const lock = `${file}.lock`;
+  const deadline = Date.now() + APPEND_LOCK_TIMEOUT_MS;
+  for (;;) {
+    let fd = -1;
+    try {
+      fd = fs.openSync(lock, 'wx', 0o600);
+      try {
+        fs.writeSync(fd, JSON.stringify({ pid: process.pid, at: Date.now() }));
+      } finally {
+        fs.closeSync(fd);
+        fd = -1;
+      }
+      break;
+    } catch (err) {
+      if (fd >= 0) {
+        try {
+          fs.closeSync(fd);
+        } catch {}
+      }
+      const code = String(/** @type {any} */ (err)?.code || '');
+      if (code !== 'EEXIST') throw err;
+      // 崩溃残留：临界区毫秒级，超过 10s 的锁不可能是活写方；二次 stat 防误删刚建的新锁。
+      if (reclaimStaleAppendLock(lock)) continue;
+      if (Date.now() > deadline) throw new Error(`获取事件追加锁超时：${lock}`);
+      sleepSync(5);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    releaseAppendLock(lock);
+  }
+}
+
+/** 写失败告警去重（每个事件文件每次进程只提示一次，避免每条消息刷屏）。 */
+const warnedFiles = new Set();
+
+/** 进程级开关（`createAgent` 按 `cfg.eventLog` 设置；默认开）。 */
+let processEnabled = true;
+
+/**
+ * 事件日志是否启用。
+ * @param {any} [cfg] 传入 config 时额外尊重 `cfg.eventLog === false`
+ * @returns {boolean}
+ */
+export function eventLogEnabled(cfg) {
+  const env = String(process.env[EVENT_LOG_ENV] ?? '').toLowerCase();
+  if (env === '0' || env === 'false' || env === 'off' || env === 'no') return false;
+  if (cfg && cfg.eventLog === false) return false;
+  return processEnabled;
+}
+
+/**
+ * 进程级开关。`cfg.eventLog === false` 时由 `createAgent` 调用它，使**会话消息的**
+ * `message.append` 双写也一起停下（否则只停 agent 事件，仍会写一半）。
+ * @param {boolean} enabled
+ */
+export function setEventLogEnabled(enabled) {
+  processEnabled = enabled !== false;
+}
+
+/**
+ * 会话文件 → 事件文件：`<session>.jsonl` → `<session>.events.ndjson`。
+ * 已经是 `.events.ndjson` 的原样返回（方便调用方只写一个入口）。
+ * @param {string} sessionFile
+ * @returns {string}
+ */
+export function eventFileFor(sessionFile) {
+  const s = String(sessionFile || '');
+  if (!s) return '';
+  if (s.endsWith('.events.ndjson')) return s;
+  if (s.endsWith('.jsonl')) return `${s.slice(0, -'.jsonl'.length)}.events.ndjson`;
+  return `${s}.events.ndjson`;
+}
+
+/**
+ * 是否是事件侧车文件名。会话列表/同步必须排除它——否则事件文件会被当成一个「没有消息的
+ * 幽灵会话」，甚至因为 mtime 更新而抢走 `latestSession()`。
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isEventLogName(name) {
+  return String(name || '').endsWith('.events.ndjson');
+}
+
+/**
+ * @typedef {{seq: number, time: number, type: string, data: any}} SessionEvent
+ * @typedef {{ok: boolean, error: string|null, events: SessionEvent[], skipped: number}} ReadEventsResult
+ * @typedef {{ok: boolean, error: string|null, seq?: number|null, disabled?: boolean}} AppendEventResult
+ */
+
+/**
+ * 读文件尾（最多 TAIL_BYTES）。文件不存在按空文件处理；其余读失败上抛，由调用方转成 `{ok:false}`。
+ * @param {string} file
+ * @returns {{size: number, text: string, endsWithNewline: boolean}}
+ */
+function readTail(file) {
+  let fd = -1;
+  try {
+    fd = fs.openSync(file, 'r');
+    const size = fs.fstatSync(fd).size;
+    const len = Math.min(size, TAIL_BYTES);
+    const buf = Buffer.alloc(len);
+    if (len > 0) fs.readSync(fd, buf, 0, len, size - len);
+    const text = buf.toString('utf8');
+    return { size, text, endsWithNewline: size === 0 || text.endsWith('\n') };
+  } catch (err) {
+    if (String(/** @type {any} */ (err)?.code || '') === 'ENOENT') {
+      return { size: 0, text: '', endsWithNewline: true };
+    }
+    throw err;
+  } finally {
+    if (fd >= 0) {
+      try {
+        fs.closeSync(fd);
+      } catch {}
+    }
+  }
+}
+
+/**
+ * 从文本尾部找最后一条**可解析事件的 seq**；torn/非 JSON 行跳过。
+ * @param {string} text
+ * @returns {number}
+ */
+function lastSeqInText(text) {
+  const lines = String(text || '').split('\n');
+  while (lines.length && !lines[lines.length - 1].trim()) lines.pop();
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = lines[i].replace(/\r$/, '');
+    if (!line.trim()) continue;
+    try {
+      const ev = JSON.parse(line);
+      const seq = Number(ev?.seq);
+      if (Number.isInteger(seq) && seq > 0) return seq;
+    } catch {}
+  }
+  return 0;
+}
+
+/**
+ * 读文件尾的 last seq；尾窗读不到且文件更大时回退整文件（只发生在文件损坏/超长时）。
+ * @param {string} file
+ * @returns {{lastSeq: number, size: number, endsWithNewline: boolean}}
+ */
+function readLastEventSeq(file) {
+  const tail = readTail(file);
+  let lastSeq = lastSeqInText(tail.text);
+  if (!lastSeq && tail.size > Buffer.byteLength(tail.text, 'utf8')) {
+    lastSeq = lastSeqInText(fs.readFileSync(file, 'utf8'));
+  }
+  return { lastSeq, size: tail.size, endsWithNewline: tail.endsWithNewline };
+}
+
+/**
+ * 追加一条事件。返回 `{ok,error,seq}`；**绝不抛异常**。
+ *
+ * seq 分配：跨进程文件锁内读尾行 last seq + 1，单次 append 后立刻回读校验；同进程用 Map
+ * 缓存上一条作为「文件被外部截断/重建」时的保守下限（文件大小小于缓存值时以文件尾为准，
+ * 避免凭空跳号）。
+ * @param {string} eventFile
+ * @param {{type?: string, data?: any, at?: number|Date|null}} [event]
+ * @returns {AppendEventResult}
+ */
+export function appendEvent(eventFile, { type = '', data = {}, at = null } = {}) {
+  if (!eventLogEnabled()) return { ok: true, error: null, seq: null, disabled: true };
+  try {
+    const file = path.resolve(String(eventFile || ''));
+    if (!file) return { ok: false, error: '事件文件路径为空' };
+    if (!EVENT_TYPE_SET.has(type)) return { ok: false, error: `未知事件类型：${String(type)}` };
+    const payload = data && typeof data === 'object' ? data : {};
+    const time = Number(at instanceof Date ? at.getTime() : at);
+    const lineBody = () => {
+      const event = { seq: 0, time: Number.isFinite(time) && time > 0 ? time : Date.now(), type, data: payload };
+      return event;
+    };
+    const result = withAppendLock(
+      file,
+      () => {
+        const tail = readLastEventSeq(file);
+        const cached = seqCache.get(file);
+        let base = tail.lastSeq;
+        if (tail.size === 0) base = 0;
+        else if (cached && tail.size >= cached.size) base = Math.max(base, cached.seq);
+        const seq = base + 1;
+        const event = lineBody();
+        event.seq = seq;
+        const json = JSON.stringify(event);
+        // 文件尾部若没有换行（torn 行/手工写入），先补一个换行：新事件永远独占一行。
+        const prefix = tail.size > 0 && !tail.endsWithNewline ? '\n' : '';
+        appendFilePrivateSync(file, prefix + json + '\n');
+        const newSize = tail.size + Buffer.byteLength(prefix + json + '\n', 'utf8');
+        // 末尾校验：确认最后一行就是刚写下的事件（锁内不会有第二个写方）。
+        const verify = readTail(file);
+        const lines = verify.text.split('\n').filter((l) => l.trim());
+        const last = lines.length ? lines[lines.length - 1] : '';
+        let ok = false;
+        try {
+          const parsed = JSON.parse(last.replace(/\r$/, ''));
+          ok = parsed?.seq === seq && parsed?.type === type;
+        } catch {}
+        if (!ok) return { ok: false, error: `事件写入后校验失败（seq=${seq}）` };
+        seqCache.set(file, { seq, size: newSize });
+        return { ok: true, error: null, seq };
+      }
+    );
+    return result;
+  } catch (err) {
+    return { ok: false, error: String(/** @type {any} */ (err)?.message ?? err) };
+  }
+}
+
+/**
+ * 读取事件流。torn 行 / 未知 type / 缺 seq 的行跳过并计入 `skipped`；文件不存在返回空流
+ * （这是旧会话的正常形态，不是错误）。
+ * @param {string} eventFile
+ * @returns {ReadEventsResult}
+ */
+export function readEvents(eventFile) {
+  try {
+    const file = path.resolve(String(eventFile || ''));
+    let raw;
+    try {
+      raw = fs.readFileSync(file, 'utf8');
+    } catch (err) {
+      if (String(/** @type {any} */ (err)?.code || '') === 'ENOENT') {
+        return { ok: true, error: null, events: [], skipped: 0 };
+      }
+      return { ok: false, error: String(/** @type {any} */ (err)?.message ?? err), events: [], skipped: 0 };
+    }
+    /** @type {SessionEvent[]} */
+    const events = [];
+    let skipped = 0;
+    for (const rawLine of raw.split('\n')) {
+      const line = rawLine.replace(/\r$/, '').trim();
+      if (!line) continue;
+      let parsed;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        skipped += 1;
+        continue;
+      }
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        skipped += 1;
+        continue;
+      }
+      if (!EVENT_TYPE_SET.has(parsed.type)) {
+        skipped += 1;
+        continue;
+      }
+      const seq = Number(parsed.seq);
+      if (!Number.isInteger(seq) || seq < 1) {
+        skipped += 1;
+        continue;
+      }
+      const time = Number(parsed.time);
+      events.push({
+        seq,
+        time: Number.isFinite(time) ? time : 0,
+        type: String(parsed.type),
+        data: parsed.data && typeof parsed.data === 'object' ? parsed.data : {},
+      });
+    }
+    return { ok: true, error: null, events, skipped };
+  } catch (err) {
+    return { ok: false, error: String(/** @type {any} */ (err)?.message ?? err), events: [], skipped: 0 };
+  }
+}
+
+/** @param {any} value @returns {any} 深拷贝（事件里只会有 JSON 值）。 */
+function cloneJson(value) {
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * 事件按 seq 升序（seq 是唯一关联键）；缺 seq 的保持原序在后。
+ * @param {any[]} events
+ * @returns {SessionEvent[]}
+ */
+function ordered(events) {
+  const list = Array.isArray(events) ? events.filter((e) => e && typeof e === 'object') : [];
+  return list
+    .map((e, i) => ({ e, i }))
+    .sort((a, b) => {
+      const sa = Number(a.e?.seq);
+      const sb = Number(b.e?.seq);
+      const fa = Number.isFinite(sa) ? sa : Number.MAX_SAFE_INTEGER;
+      const fb = Number.isFinite(sb) ? sb : Number.MAX_SAFE_INTEGER;
+      return fa === fb ? a.i - b.i : fa - fb;
+    })
+    .map((x) => /** @type {SessionEvent} */ (x.e));
+}
+
+/**
+ * 找出中断时**尚未回填**的 tool_call_id（按 assistant.tool_calls 原序）。
+ * 与 `agent.js#finishTurn` 的判据同源：最后一条带 tool_calls 的 assistant 之后，
+ * 哪些 id 还没有对应的 tool 消息。
+ * @param {any[]} messages
+ * @returns {string[]}
+ */
+export function missingToolCallIds(messages) {
+  const list = Array.isArray(messages) ? messages : [];
+  /** @type {string[]} */
+  const ids = [];
+  try {
+    const assistant = [...list].reverse().find((m) => m?.role === 'assistant' && Array.isArray(m.tool_calls) && m.tool_calls.length);
+    if (!assistant) return ids;
+    const have = new Set(list.filter((m) => m?.role === 'tool' && m.tool_call_id).map((m) => String(m.tool_call_id)));
+    for (const tc of assistant.tool_calls) {
+      const id = tc?.id ? String(tc.id) : '';
+      if (id && !have.has(id)) ids.push(id);
+    }
+  } catch {}
+  return ids;
+}
+
+/**
+ * 由事件流确定性重放出消息数组（纯函数：不读写文件、不改入参）。
+ *
+ * 语义（与双写顺序一致）：
+ *   · `message.append`：`data.message` 追加到末尾；
+ *   · `compact`：`data.messages` 是压缩后的**新基线**，整体替换（后续 append 接在它后面）；
+ *   · `interrupt`：`data.toolCallIds` 里的 id 若在最终消息里仍没有 tool 回填，则在对应
+ *     assistant 之后补一条 `（已中断，未执行）` 占位——**延迟到所有事件处理完再补**，这样
+ *     随后到达的 message.append 若已含占位就不会重复，也不会插错位置。
+ * @param {any[]} events
+ * @returns {any[]}
+ */
+export function replayToMessages(events) {
+  /** @type {any[]} */
+  let messages = [];
+  /** @type {string[]} */
+  const pendingInterruptIds = [];
+  for (const ev of ordered(events)) {
+    if (ev.type === 'message.append') {
+      const m = ev.data?.message;
+      if (m && typeof m === 'object' && !Array.isArray(m)) messages.push(cloneJson(m));
+    } else if (ev.type === 'compact') {
+      const base = ev.data?.messages;
+      if (Array.isArray(base)) {
+        messages = base.filter((m) => m && typeof m === 'object' && !Array.isArray(m)).map(cloneJson);
+      }
+    } else if (ev.type === 'interrupt') {
+      const ids = Array.isArray(ev.data?.toolCallIds) ? ev.data.toolCallIds : Array.isArray(ev.data?.ids) ? ev.data.ids : [];
+      for (const raw of ids) {
+        const id = raw ? String(raw) : '';
+        if (id) pendingInterruptIds.push(id);
+      }
+    }
+  }
+  // 延迟补占位：只补「最终基线里确实缺 tool 回填」的 id，插在该 assistant 之后连续 tool 块末尾。
+  for (const id of [...new Set(pendingInterruptIds)]) {
+    if (messages.some((m) => m?.role === 'tool' && String(m.tool_call_id) === id)) continue;
+    let assistantAt = -1;
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+      const m = messages[i];
+      if (m?.role === 'assistant' && Array.isArray(m.tool_calls) && m.tool_calls.some((/** @type {any} */ tc) => String(tc?.id) === id)) {
+        assistantAt = i;
+        break;
+      }
+    }
+    const placeholder = { role: 'tool', tool_call_id: id, content: INTERRUPTED_TOOL_CONTENT };
+    if (assistantAt < 0) {
+      // 找不到对应的 assistant（可能已被 compact 压掉）：不凭空造消息，避免重放与真实消息数组分叉。
+      continue;
+    }
+    let insertAt = assistantAt + 1;
+    while (insertAt < messages.length && messages[insertAt]?.role === 'tool') insertAt += 1;
+    messages.splice(insertAt, 0, placeholder);
+  }
+  return messages;
+}
+
+/**
+ * 供后续 UI/诊断用的 turn 摘要（可选；纯函数）。只从事件自己推导，不读消息正文。
+ * @param {any[]} events
+ * @returns {{turn:number, startedAt:number, endedAt:number|null, status:string, steps:number, toolCalls:number, usage:any}[]}
+ */
+export function deriveTurnSummaries(events) {
+  /** @type {{turn:number, startedAt:number, endedAt:number|null, status:string, steps:number, toolCalls:number, usage:any}[]} */
+  const out = [];
+  /** @type {any} */
+  let cur = null;
+  for (const ev of ordered(events)) {
+    if (ev.type === 'turn.start') {
+      cur = { turn: out.length + 1, startedAt: ev.time, endedAt: null, status: 'running', steps: 0, toolCalls: 0, usage: null };
+      out.push(cur);
+    } else if (!cur) {
+      continue;
+    } else if (ev.type === 'step.start') {
+      cur.steps += 1;
+    } else if (ev.type === 'tool.start') {
+      cur.toolCalls += 1;
+    } else if (ev.type === 'usage') {
+      cur.usage = ev.data?.usage ?? null;
+    } else if (ev.type === 'turn.end') {
+      cur.endedAt = ev.time;
+      cur.status = String(ev.data?.status ?? 'done');
+      cur = null;
+    }
+  }
+  return out;
+}
+
+/**
+ * 写失败时打一条**可见** warn（每个文件每进程一次）。事件日志是旁路，绝不能反过来影响调用方。
+ * @param {string} eventFile
+ * @param {string|null} error
+ */
+export function warnEventFailure(eventFile, error) {
+  const file = String(eventFile || '');
+  if (warnedFiles.has(file)) return;
+  warnedFiles.add(file);
+  try {
+    console.warn(
+      `[MingDao] ⚠ 会话事件日志写入失败（${file}）：${error || '未知原因'}——会话消息已正常写入，` +
+        `事件日志本次不完整（可用 config.eventLog=false 或 MINGDAO_EVENT_LOG=0 关闭）。`
+    );
+  } catch {}
+}

package/src/session.js

@@ -3,6 +3,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { appendEvent, eventFileFor, eventLogEnabled, isEventLogName, warnEventFailure } from './session-events.js';
 
 // —— 冲突备份名（单一事实来源，v0.4.6）——
 // 同步冲突时写入的备份：<会话名>.server-<时间戳>[-<随机后缀>].jsonl（远端版本）与 .remote-（远端拉取版本）。
@@ -44,7 +45,9 @@ export function listSessionsDetailed(home) {
   }
   for (const f of entries) {
     // 冲突备份不是会话：排除后不再出现在会话列表/最近会话/搜索/云同步推送集合中
-    if (!f.endsWith('.jsonl') || isConflictBackupName(f)) continue;
+    // v0.7.0 §1.1：事件侧车 `<session>.events.ndjson` 不是会话——必须排除，否则它会变成
+    // 「没有消息的幽灵会话」，甚至因 mtime 更新而抢走 latestSession()。旧会话行为不变。
+    if (!f.endsWith('.jsonl') || isEventLogName(f) || isConflictBackupName(f)) continue;
     const file = path.join(dir, f);
     try {
       list.push({ file, name: f, mtime: fs.statSync(file).mtimeMs });
@@ -116,12 +119,46 @@ export function stampMessageTs(messages, now = new Date()) {
   return messages;
 }
 
+/**
+ * v0.7.0 §1.1：会话消息的**双写**（消息文件写完之后的旁路）。
+ *
+ * 纪律：会话文件已经落盘，这里任何失败都只 warn 并返回；**绝不改变 appendMessages 的结果**，
+ * 也绝不把异常抛给调用方。`cfg.eventLog=false` 由 agent 侧把进程开关关掉，这里自然一并停止。
+ * @param {any} file
+ * @param {any[]} messages
+ */
+function doubleWriteSessionEvents(file, messages) {
+  if (!eventLogEnabled()) return;
+  const eventFile = eventFileFor(file);
+  if (!eventFile) return;
+  try {
+    // 事件流的第一条：只在文件尚不存在时写一次（并发下最多重复一条 session.start，无害）。
+    if (!fs.existsSync(eventFile)) {
+      const start = appendEvent(eventFile, { type: 'session.start', data: { session: path.basename(String(file)) } });
+      if (!start.ok) {
+        warnEventFailure(eventFile, start.error ?? null);
+        return;
+      }
+    }
+    for (const m of messages) {
+      const r = appendEvent(eventFile, { type: 'message.append', data: { message: m } });
+      if (!r.ok) {
+        warnEventFailure(eventFile, r.error ?? null);
+        return; // 写不进去就停：后面的每一条都只会重复同一条告警
+      }
+    }
+  } catch (err) {
+    warnEventFailure(eventFile, String(/** @type {any} */ (err)?.message ?? err));
+  }
+}
+
 /** @param {any} file @param {any} messages */
 export function appendMessages(file, messages) {
   if (!messages?.length) return;
   stampMessageTs(messages); // 单一来源：所有写入路径在这里补 ts（已有 ts 不覆盖）
   const lines = messages.map((/** @type {any} */ m) => JSON.stringify(m)).join('\n') + '\n';
   appendFilePrivateSync(file, lines);
+  doubleWriteSessionEvents(file, messages); // 旁路：失败只 warn，不影响上面的会话写入
 }
 
 // 整文件原子重写：自动压缩后把会话文件同步为压缩形态（否则每次加载历史都会重新触发压缩）