dsh-retrace 0.4.19 → 0.4.25

package/README.md

@@ -77,6 +77,21 @@ Full steps in [📦 Installation](#-installation).
 | 🧭 | **Jump-to-conversation** | one click from a version to that point in the conversation (auto-loads history, anchor highlight) |
 | 🧹 | **Bounded storage** | snapshots keep the most recent N versions (default 50); throttled background sweep prunes truncated ones |
 
+**Close guard (don't lose work by accident)** — before you exit or reload, know what is still running:
+
+| | What | |
+|---|---|---|
+| 🛡️ | **Running-work detection** | every session is scanned for live work: agent running, queued inbox items, background jobs, unclosed turns |
+| 📋 | **Running banner** | sessions with live work show a persistent in-page banner (short session code + reasons), so you can see it before quitting |
+| ⚠️ | **Exit prompt** | on plugin dispose (app exit / reload) a Chinese notice lists each running session and why it is considered busy — it only warns, it never cancels your running agent |
+| 🔒 | **Page-close interception (Web)** | `beforeunload` interception: a strong confirm when work is running (details modal, `[仍关闭]` = confirm-and-go), a light confirm otherwise |
+| 🔎 | **Query surface** | `retrace.runningState` (host RPC) + `GET|POST /api/plugins/retrace/runningState` (HTTP) — same shape on both transports |
+
+> Desktop note: the Electron shell destroys the window on quit, so the page-level
+> `beforeunload` hook cannot fire there and the host exposes no plugin quit-veto seam —
+> Desktop is covered by the running banner plus the dispose notice; Web gets the full
+> interception.
+
 **Why it's different** (the interaction layer — the guarantees above are the storage layer):
 
 - 🎯 **Whole-round recall** — removes the input *and* its output (tool rows included), not just a single bubble.

package/README.zh.md

@@ -233,6 +233,21 @@ Client 半区会依据包内 `dsh.client` 元数据被自动打包进 Web 客户
 
 ---
 
+**关闭守卫（防误关丢进度）** —— 退出/重载前先看清还有什么在跑：
+
+| | 是什么 | |
+|---|---|---|
+| 🛡️ | **运行中检测** | 逐会话扫描运行中工作：agent 正在跑 / inbox 排队 / 后台 jobs / 未闭合轮 |
+| 📋 | **运行中横幅** | 有运行中工作的会话显示页面常驻横幅（会话短码 + 原因），退出前可见 |
+| ⚠️ | **退出提示** | 插件 dispose（应用退出/重载）时中文提示列出每个运行中会话与原因——只提示，绝不代你取消 agent |
+| 🔒 | **页面关闭拦截（Web）** | `beforeunload` 拦截：有运行中任务强确认（明细模态，`[仍关闭]` 即确认离开），无任务轻确认 |
+| 🔎 | **查询面** | `retrace.runningState`（host RPC）+ `GET|POST /api/plugins/retrace/runningState`（HTTP），两入口同形状 |
+
+> 桌面说明：Electron 宿主退出时销毁窗口，页面 `beforeunload` 不会触发，宿主也未暴露
+> 插件可用的退出否决点——桌面侧由运行中横幅 + dispose 提示覆盖；Web 端拦截完整生效。
+
+---
+
 ## 🗺️ 路线图
 
 **当前已具备（0.4.x）：**

package/lib/adapter/dsh.js

@@ -12,6 +12,10 @@
 import { readdirSync, accessSync } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
+// 官方 foldSurface:重放得与写入端完全一致的 surface nodes(replace 插 marker、
+// 遮蔽移除节点 → nodes 非 seq 单调;span 计算必须用它,否则 start/end indexOf
+// 会 not found/倒置 → S4/S8 拒 → 撤回死锁,ISSUE-20260907113201)。peerDep 提供。
+import { foldSurface } from '@deepseek-ai/dsh-session'
 
 /** 找 DSH 会话文件路径(遍历 ~/.dsh/sessions 各工作区)。 */
 export function sessionFilePath(sessionId) {
@@ -37,24 +41,58 @@ async function readEvents(sessionId) {
   return readEventsFromFile(filePath)
 }
 
-/** 从指定文件路径读全量事件(测试可注入路径;生产走 readEvents 找 ~/.dsh)。 */
+/** 从指定文件路径读全量事件(测试可注入路径;生产走 readEvents 找 ~/.dsh)。
+ *  P0-6(代码 M-5):单次编辑/查询操作会连读多次(span+文件快照事实),每次全量
+ *  zstd 解压+JSON+foldSurface(1.37M 事件秒级)→ 加**进程级短缓存**(同批次
+ *  内共享一次读取;以 mtime+size 校验文件未变,变了即失效,防与写入撕裂)。
+ *  TTL 很短(300ms)只覆盖单次命令的连续读取,不缓存跨命令的陈旧数据。 */
+const readCache = new Map() // filePath → { sig, events, at }
+const READ_CACHE_TTL_MS = 300
 async function readEventsFromFile(filePath) {
   try {
     if (!filePath) return null
+    const { statSync } = await import('node:fs')
+    // 文件签名(mtimeMs+size):写入会改 mtime/size → 缓存自动失效
+    let sig = null
+    try {
+      const st = statSync(filePath)
+      sig = `${st.mtimeMs}:${st.size}`
+    } catch { sig = 'unreadable' }
+    const hit = readCache.get(filePath)
+    if (hit && hit.sig === sig && Date.now() - hit.at < READ_CACHE_TTL_MS) {
+      return hit.events
+    }
     const { loadSessionLog } = await import('dsh-log-contract')
     const log = loadSessionLog(filePath)
-    return log.events.map((r) => r.event)
+    const events = log.events.map((r) => r.event)
+    // 只缓存有效读取(失败不缓存,下次重试)
+    if (Array.isArray(events) && events.length > 0) {
+      readCache.set(filePath, { sig, events, at: Date.now() })
+      // 防膨胀:超过 32 个文件清空(单命令最多几个会话文件)
+      if (readCache.size > 32) readCache.clear()
+    }
+    return events
   } catch { return null }
 }
 
 /**
  * 从全量事件计算遮蔽范围(业务逻辑,基于通用事件,与 DSH 无关)。
+ *
+ * 2026-09-07 修复(ISSUE-20260907113201-3f9e4f12):nodes 不再从 events 顺序收集
+ * (seq 递增的虚拟 nodes),改为**官方 foldSurface 重放得真实 surface nodes**——
+ * 官方 replace 会把 marker(新 seq)插入遮蔽范围开头、移除被遮蔽节点 → nodes 非
+ * seq 单调。旧算法按 seq 递增假设算 span,写入时官方 nodes 里 indexOf(start/end)
+ * 可能 not found(目标已被遮蔽)或倒置(startIdx>endIdx,marker 插入) → S4/S8 拒 →
+ * 撤回死锁(evidence 快照实测:target 710693 span[710693..711448] → index 442>441)。
+ * 新算法 nodes = 官方 foldSurface 结果 → span 的 start/end 与写入端完全一致,
+ * not found/倒置不可能;target 已被遮蔽(不在 nodes)= 返回 null(target-shadowed)。
+ *
  * @param {Array} events - 全量事件(通用格式)。
  * @param {number|string} target - seq 或 messageId。
- * @param {'round'|'tail'} [mode] - round=遮蔽目标轮;tail=遮蔽目标之后(编辑 fromScratch)。
+ * @param {'round'|'tail'} [mode] - round=遮蔽目标轮;tail=遮蔽目标位置之后全部(recall/fromScratch)。
  */
 export function computeSpan(events, target, mode = 'round') {
-  if (!Array.isArray(events)) return null
+  if (!Array.isArray(events) || events.length === 0) return null
   let seq = typeof target === 'number' ? target : -1
   if (seq === -1) {
     for (let i = events.length - 1; i >= 0; i--) {
@@ -64,18 +102,27 @@ export function computeSpan(events, target, mode = 'round') {
     }
   }
   if (seq === -1 || !events[seq]) return null
-  // surface 节点 = user/assistant/tool 消息(近似 surface 节点,与官方 foldSurface 一致)
-  const nodes = []
-  for (const ev of events) {
-    if (ev && (ev.type === 'user/message' || ev.type === 'assistant/message' || ev.type === 'tool/result')) nodes.push(ev.seq)
+  // 官方 foldSurface 重放 = 与写入端一致的当前 surface(含 marker 插入效应、排除被遮蔽节点)
+  let nodes
+  try {
+    const folded = foldSurface(events)
+    nodes = folded?.nodes
+  } catch {
+    return null
   }
+  if (!Array.isArray(nodes) || nodes.length === 0) return null
+  const index = nodes.indexOf(seq)
+  if (index === -1) return null // 目标已被遮蔽/不在 surface → 调用方报 target-shadowed
   if (mode === 'tail') {
-    const shadowedSeqs = nodes.filter((s) => s >= seq)
+    // tail:从目标所在轮首遮蔽到 surface 尾(撤回 = 移除整轮 input+output + 其后全部,
+    // R2 语义;目标若是轮内 assistant/tool 则回退到轮首 user,防孤立输入)。
+    let startPos = index
+    for (let i = index; i >= 0; i--) { if (isRoundBoundary(events[nodes[i]])) { startPos = i; break } }
+    const shadowedSeqs = nodes.slice(startPos)
     if (shadowedSeqs.length === 0) return null
     return { start: shadowedSeqs[0], end: shadowedSeqs[shadowedSeqs.length - 1], shadowedSeqs }
   }
-  const index = nodes.indexOf(seq)
-  if (index === -1) return null
+  // round:目标轮(在官方 nodes 位置序上找轮边界;marker 是 assistant/message 非轮边界)
   let startIdx = index
   for (let i = index; i >= 0; i--) { if (isRoundBoundary(events[nodes[i]])) { startIdx = i; break } }
   let endIdx = nodes.length - 1
@@ -85,6 +132,67 @@ export function computeSpan(events, target, mode = 'round') {
   return { start: span[0], end: span[span.length - 1], shadowedSeqs: span }
 }
 
+/**
+ * 文件侧「目标同一轮的前置 user 原文」(M-1,独立审查 74e580d 后续)——regenerate
+ * 重发文本的唯一可靠来源。
+ *
+ * 为什么必须算在文件侧:host 内存 session.events 是窗口化/稀疏视图(带 undefined 洞),
+ * regenerate 在内存里「向前找最近的前置 user」会越过洞(洞里正是该轮 user)或越过被
+ * 遮蔽区间,选到**更早轮**的 user → 重发错文本 + marker targetSeq 指向错轮。round span
+ * 的起点在文件全量 events + 官方 foldSurface nodes 上就是目标同一轮的轮首 user
+ * (computeSpan round 模式向前找 isRoundBoundary 的落点),从该点单点取原文不可能跨轮。
+ *
+ * 纯函数(零平台 import)。
+ * @returns {{seq: number, text: string}|null} span 起点非轮边界 user(孤儿回复:向前
+ *   找不到 user;或非 round 模式)→ null(调用方保守处理:绝不重发更早轮的文本)。
+ */
+export function roundPromptOf(events, span, mode = 'round') {
+  if (mode !== 'round' || !span || !Array.isArray(events)) return null
+  const seq = span.start
+  if (typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < 0) return null
+  const event = events[seq]
+  if (!isRoundBoundary(event)) return null
+  const content = event.data?.content
+  const text = Array.isArray(content)
+    ? content.filter((b) => b && b.type === 'text' && typeof b.text === 'string').map((b) => b.text).join('')
+    : ''
+  return { seq, text }
+}
+
+/**
+ * computeSpan + 文件快照事实(comm-200):一次遍历同时给出遮蔽 span 与
+ * 「文件快照已知最大 seq / 目标在快照里的 seq」。span 为 null 时,调用方
+ * (withFileSpan/http.js)把这些事实注入 args.spanFacts,host-core 据此区分:
+ *  - 目标 seq > 文件快照最大 seq → 文件尚未 flush 该消息(提交中)→ message-pending;
+ *  - 快照已覆盖目标位置却不在其 surface(span null)→ 真被遮蔽 → target-shadowed。
+ * 纯函数(与 computeSpan 同构,平台无关;零平台 import)。
+ *
+ * M-1(独立审查 74e580d 后续):同时带回 prompt = round span 起点 user 的原文
+ * (roundPromptOf)。span 命中时调用方把它注入 args.regeneratePrompt —— regenerate
+ * 的重发文本/ marker targetSeq 一律取自文件侧,不再直扫 host 稀疏 events
+ * (直扫会越过洞选中更早轮 user,重发错文本)。
+ *
+ * @returns {{span: object|null, facts: {fileMaxSeq: number, targetSeq: number},
+ *   prompt: {seq: number, text: string}|null}}
+ */
+export function computeSpanProbe(events, target, mode = 'round', opts = {}) {
+  const span = computeSpan(events, target, mode, opts)
+  let targetSeq = typeof target === 'number' ? target : -1
+  let fileMaxSeq = -1
+  if (Array.isArray(events)) {
+    for (let i = events.length - 1; i >= 0; i--) {
+      const ev = events[i]
+      if (!ev) continue
+      if (typeof ev.seq === 'number' && ev.seq > fileMaxSeq) fileMaxSeq = ev.seq
+      if (targetSeq === -1) {
+        const id = ev?.type === 'user/message' ? ev.data?.id : ev?.type === 'assistant/message' ? ev.data?.message?.id : undefined
+        if (typeof id === 'string' && id === target) targetSeq = ev.seq
+      }
+    }
+  }
+  return { span, facts: { fileMaxSeq, targetSeq: targetSeq >= 0 ? targetSeq : -1 }, prompt: roundPromptOf(events, span, mode) }
+}
+
 /**
  * DSH 适配器:EventReader 实现。
  * 从文件读全量事件(可靠事实),并提供基于它的遮蔽计算。
@@ -96,6 +204,17 @@ export const dshAdapter = {
     const events = await readEvents(sessionId)
     return computeSpan(events, target, mode)
   },
+  /**
+   * 便捷:读事件一次,同时给出 span 与文件快照事实(comm-200)。span 为 null 时
+   * 调用方(withFileSpan/http.js)注入 facts → host-core 区分「提交中(message-pending)」
+   * 与「真被遮蔽(target-shadowed)」——文件 flush 滞后不再误报「已不在活跃对话」。
+   * M-1(独立审查 74e580d 后续):probe.prompt = round span 起点 user 的**文件侧原文**
+   * ——regenerate 的重发文本/ marker targetSeq 取自这里,不直扫 host 稀疏 events。
+   */
+  async spanProbeFromFile(sessionId, target, mode = 'round', opts = {}) {
+    const events = await readEvents(sessionId)
+    return computeSpanProbe(events, target, mode, opts)
+  },
   /**
    * 从文件全量事件算某 turn 内的最大 step 号(情形② marker step 分配用)。
    * 绕开 host 窗口化 session.events(稀疏内存视图可能看不到 turn 内全部 step,