@240xu/dsh-message-ops 0.5.1 → 0.5.7

package/README.md

@@ -243,3 +243,74 @@ MIT
 - 0.4.2 的 dock 重写误删了 `INPUT_DOCK_SLOT/ID` 常量声明——apply() 引用未定义
   标识符导致**整个客户端激活失败**（页面横幅 Failed to load plugins）。
   已恢复常量；新增 vm 冒烟自测路径（见 .e2e/）。
+
+## 0.5.2 · Bug 猎场第一轮修复（P0×1 + P1×3 + P2×6）
+
+- **[P0] activeMarkers 被 0.5.0 误删**（与 INPUT_DOCK 同一 commit，0.5.1 只找回常量）：
+  dock 100% 静默失效（ReferenceError 被 .catch 吞掉）。已恢复函数 + vm 冒烟守卫。
+- **[P1] 工具层未 await async ops**（0.2.1 改 async 后漏同步化）：list/restore 必抛
+  TypeError、export 渲出空 text。switch 全部 await + 回归测试（异步桩）。
+- **[P1] 引用空块**：assistant 消息 fullText 恒 null，回退 `''` 通过 null 检查 →
+  插入空 `> ` 块并报成功。改为按 seq 走新端点 `GET /text` 取单条全文，空串按不可用处理。
+- **[P1] 侧栏菜单卡死**：dispatch 缺 sessionId → 对话框永久「正在读取…」。
+  从 data-row-key 提取 sessionId 一并派发。
+- **[P2] seq 索引缓存投毒**：失败必须 `delete`，否则该会话按钮/dock 到刷新前全失效。
+- **[P2] 索引口径**：同 id 取最早 seq（对齐服务端 buildSeqIndex，不再内联取最大）。
+- **[P2] branch 工具渲染**：读 keptEvents/parentSession（原读不存在的 kept/parentId）。
+- **[P2] dock 标题口径**：改报标记 range 内被遮蔽消息数（原报标记数，严重低报）。
+- **[P2] busy 卡死**：runRevert/restoreRow/对话框 run 全部 `Promise.resolve()` 包裹——
+  同步抛出也落进 finally；restoreRow 补 finally 双保险。
+- **[P2] dock 陈旧**：新增 `dsh-message-ops:changed` 广播，回滚/恢复成功后 dock 自动重拉。
+- **[P3] 删 en 独有死键 dock.shadowedN；GET 端点补 405 方法校验。**
+
+### 0.5.3 · 「打开即 Running」误报修复（实机 P0 级）
+
+- isRunning 原查 agents 注册表——会话**在视图中打开**即有条目 → 打开即报
+  running → 回撤/删除/分支全部 409 锁死（「按钮没有用」的又一层根因，Playwright
+  闭环 e2e 实机抓到：curl 未打开时 false、UI 打开后恒 true）。
+- 改读 `sessions.list.getSnapshot().byId[].running`（host-asserted，与官方侧栏
+  spinner、官方分支按钮 disabled 同源）；老宿主回退 agents 注册表。
+
+### 0.5.4 · 「点回撤打死整个 dsh」P0 修复（包装实测 exit=1 定位）
+
+- **根因**：dsh 0.2.0 收紧 v4 行准入（`assertV4SystemMessageFields`）——每个
+  `system/message` 的 `data` 必须带**正整数 `turn`/`step`**。回滚/删除/恢复的通知
+  事件没带 → 持久层 `encodeEventBatch` 抛出的 SessionFormatError **没有任何层捕获
+  → 整个 dsh 进程退出**（浏览器端表现为「Failed to fetch」，一切 revert 都静默失败；
+  此前多次「实例无故死亡」全部是它）。
+- **修复**：新增 `deriveTurnStep(events)`（尾部回溯最近正坐标，兜底 1/1）；
+  revert/delete 通知与 restore 通知全部附带坐标；`opsCommit` 改 async 读日志派生，
+  HTTP/tool 调用点已 await。回归测试断言三处 append 的 data.turn/step 均为正整数。
+- 教训：宿主持久层对未知字段的编码失败会杀进程（记录于 hub——上游应给
+  encodeEventBatch 加错误边界），插件侧必须严格遵守 v4 行结构。
+
+### 0.5.5 · v4 准入第 3 关：`message.id` 非空字符串
+
+- 0.5.4 补 turn/step 后实机复测仍崩：`assertV4SystemMessageFields` 继续要求
+  `message.id` 为非空 string（`string(x, name, nonempty=true)`）。两处 notice
+  append 的 message.id 现用 `randomUUID()`；回归测试断言三段（turn/step/id）。
+- 行准入全貌（本轮实测三连击）：① `data.turn/step` 正整数 → ② `message.id`
+  非空字符串 → ③ role=system + content 数组 + block 文本串。
+
+### 0.5.6 · dock 死按钮修复：空可重放区间改优雅停用
+
+- 实机闭环：dock 上标记若遮蔽区间只含 tool/system 事件（或遮蔽了另一个标记），
+  恢复请求恒 409「no replayable user/assistant messages」——按钮永久死、dock
+  计数永远清不掉（Playwright 8 连 409 复现）。
+- 改为：planRestore 对空可重放返回空计划；applyRestore 追加**停用 notice**
+  （含 restoresSeq → dock 移除该行）+ 如实文案「区间无可重放内容」。
+  非标记/越界/非法 seq 仍按原语义 404/409/400。
+
+### 0.5.7 · 第四层根因：store-miss 会话的磁盘追加路径
+
+- **实机链**：lazy-view 让会话只在磁盘渲染、不进对象层（视图开着 dock 已渲染，
+  但 `sessions.get(id)` 双变体 miss、`list()` 里只有别的会话）→ 变更操作 404。
+  官方服务端**没有** retain/using 面（那是浏览器侧 ClientSessions 的）。
+- **修复**：store-miss 时改为**直接向日志追加 zstd 帧**（等价持久层
+  `appendLines`：encode → open('a') → write+sync+按 size 回滚），事件字段逐项
+  镜像引擎金标准（根键序 `type/seq/time/data/sourceEventSeqs/surfaceOp`；
+  restore notice `restoresSeq` + `surfaceOp:"append"`；重放无 id）。
+  磁盘会话的视图/搜索/dock 全部按帧重读 → 追加即可见；成功后客户端
+  openSession 强制重建视图（磁盘追加无 live 投影事件）。
+- live 会话（对象层在册）仍走引擎路径；两条路径共用 turn/step/id 派生与
+  空区间停用语义。新回归测试断言可见节点/计划语义/字段镜像（44/44）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@240xu/dsh-message-ops",
-  "version": "0.5.1",
+  "version": "0.5.7",
   "description": "Roll back, branch, and export any DSH conversation — from the UI or straight from the agent via a message_ops tool. Non-destructive: logs stay append-only and recoverable. 消息回滚/删除/分支/导出四合一，内置 message_ops agent 工具；非破坏语义，日志只追加可恢复。",
   "type": "module",
   "license": "MIT",

package/src/client.js

@@ -26,6 +26,9 @@ window.__ModuleLoader__.load({
     const INPUT_DOCK_ID = 'message-ops-revert-dock'
     const DIALOG_ID = 'message-ops-dialog'
     const EVENT = 'dsh-message-ops:open'
+    // 0.5.2（P2）：回滚/恢复成功后广播 → RevertDock 重拉标记（否则 dock 只在切会话时刷新）
+    const CHANGED_EVENT = 'dsh-message-ops:changed'
+    const emitChanged = () => { try { window.dispatchEvent(new CustomEvent(CHANGED_EVENT)) } catch { /* noop */ } }
     const NS = 'dsh-message-ops'
 
     const zhDict = {
@@ -386,11 +389,12 @@ window.__ModuleLoader__.load({
         }
         const path = mode === 'restore' ? 'restore' : mode
         const body = { sessionId: target.sessionId, seq: picked }
-        fetch('/api/message-ops/' + path, {
-          method: 'POST',
-          headers: { 'content-type': 'application/json' },
-          body: JSON.stringify(body),
-        })
+        Promise.resolve()
+          .then(() => fetch('/api/message-ops/' + path, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+          }))
           .then(async (res) => {
             let data = {}
             try { data = await res.json() } catch { /* keep {} */ }
@@ -410,6 +414,12 @@ window.__ModuleLoader__.load({
             setBusyMsg('')
             setState('done')
             notifyDone(okMsg)
+            emitChanged()
+            // 0.5.7：store-miss 的磁盘追加没有 live 投影事件 —— 成功后强制
+            // 重建视图（与 restoreRow 同款 openSession 模式），遮蔽即刻可见。
+            try {
+              if (__uiWorkspace && typeof __uiWorkspace.openSession === 'function') __uiWorkspace.openSession(target.sessionId)
+            } catch { /* 视图重建失败不阻断成功反馈 */ }
           })
           .catch((reason) => {
             setBusyMsg('')
@@ -641,12 +651,14 @@ window.__ModuleLoader__.load({
         else if (cached) resolve(cached)
         else {
           const p = fetch('/api/message-ops/messages?sessionId=' + encodeURIComponent(sessionId))
-            .then((r) => (r.ok ? r.json() : { messages: [] }))
+            .then((r) => (r.ok ? r.json() : Promise.reject(new Error('HTTP ' + r.status))))
             .then((data) => {
               const index = new Map()
               const full = new Map()
               for (const m of (data && data.messages) || []) {
-                if (m && m.id != null) index.set(String(m.id), m.seq)
+                // 0.5.2（P2）：同 id 取**最早** seq——与服务端 buildSeqIndex 口径一致
+                // （重试链取最早可见节点；此前内联 set 覆盖=取最大，双实现分裂）
+                if (m && m.id != null && !index.has(String(m.id))) index.set(String(m.id), m.seq)
                 if (m && m.id != null && m.fullText) full.set(String(m.id), m.fullText)
               }
               __seqIndexCache.set(sessionId, index)
@@ -654,7 +666,9 @@ window.__ModuleLoader__.load({
               return index
             })
           __seqIndexCache.set(sessionId, p)
-          p.then(resolve).catch(() => {})
+          // 0.5.2（P2）：失败必须清缓存——否则 rejected promise 被永久缓存，
+          // 该会话按钮/dock 到刷新页面为止全部失效
+          p.then(resolve).catch(() => { __seqIndexCache.delete(sessionId) })
         }
         return () => { alive = false }
       }, [messageId, sessionId])
@@ -689,16 +703,20 @@ window.__ModuleLoader__.load({
       const runRevert = () => {
         if (busy || seq == null || running) return
         setBusy('revert')
-        fetch('/api/message-ops/revert', {
-          method: 'POST', headers: { 'content-type': 'application/json' },
-          body: JSON.stringify({ sessionId, seq }),
-        })
+        // 0.5.2（P2）：Promise.resolve 包裹——fetch/stringify 同步抛出也转为
+        // rejection 落进 finally，busy 永不卡死
+        Promise.resolve()
+          .then(() => fetch('/api/message-ops/revert', {
+            method: 'POST', headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ sessionId, seq }),
+          }))
           .then(async (res) => {
             let data = {}
             try { data = await res.json() } catch { /* keep {} */ }
             if (!res.ok || !data.ok) throw new Error(data.error || ('HTTP ' + res.status))
             notifyDone(t('done.revert'))
             revealSession()
+            emitChanged()
           })
           .catch((reason) => {
             notifyDone(t('errorPrefix') + (reason && reason.message ? reason.message : String(reason)), 'error')
@@ -714,11 +732,18 @@ window.__ModuleLoader__.load({
             return
           }
           const span = inputActions.captureInsertion()
-          const text = fullText != null ? fullText : (summary && summary.title ? '' : null)
-          if (text == null) { notifyDone(t('quote.unavailable'), 'warn'); return }
-          const quoted = text.split('\n').map((l) => '> ' + l).join('\n') + '\n\n'
-          const ok = inputActions.insertText(quoted, span)
-          notifyDone(ok ? t('quote.done') : t('quote.unavailable'), ok ? 'ok' : 'warn')
+          const insertQuote = (text) => {
+            if (text == null || text === '') { notifyDone(t('quote.unavailable'), 'warn'); return }
+            const quoted = text.split('\n').map((l) => '> ' + l).join('\n') + '\n\n'
+            const ok = inputActions.insertText(quoted, span)
+            notifyDone(ok ? t('quote.done') : t('quote.unavailable'), ok ? 'ok' : 'warn')
+          }
+          // assistant 消息 fullText 恒 null（列表不携带）→ 按 seq 向服务端取单条全文
+          if (fullText != null && fullText !== '') { insertQuote(fullText); return }
+          fetch('/api/message-ops/text?sessionId=' + encodeURIComponent(sessionId) + '&seq=' + encodeURIComponent(seq))
+            .then((r) => (r.ok ? r.json() : null))
+            .then((d) => insertQuote(d && d.ok && typeof d.text === 'string' ? d.text : null))
+            .catch(() => insertQuote(null))
         } catch (e) {
           notifyDone(t('errorPrefix') + (e && e.message ? e.message : String(e)), 'error')
         }
@@ -740,6 +765,16 @@ window.__ModuleLoader__.load({
       )
     }
 
+    // 0.4.2 引入（恢复的标记自动离开活跃列表 = opencode clear 语义）。
+    // 0.5.0 脚本化编辑曾误删本函数 → dock 100% 静默失效（P0，0.5.2 恢复）。
+    function activeMarkers(msgs) {
+      const restored = new Set()
+      for (const m of msgs || []) {
+        if (m && typeof m.restoresSeq === 'number') restored.add(m.restoresSeq)
+      }
+      return (msgs || []).filter((m) => m.marker && m.sourceKind !== 'compact-checkpoint' && !restored.has(m.seq))
+    }
+
     function RevertDock(props) {
       const { sessionId, useSessions, inputActions } = props
       const t = (props && props.t) || __t
@@ -750,6 +785,7 @@ window.__ModuleLoader__.load({
       const running = summary ? summary.running === true : false
       const [open, setOpen] = useState(false)
       const [markers, setMarkers] = useState(null) // 活跃回撤标记（已恢复的自动消失）
+      const [shadowCount, setShadowCount] = useState(0) // 标记 range 内被遮蔽消息数（标题口径）
       const [restoring, setRestoring] = useState(null)
       const [styleInjected, setStyleInjected] = useState(false)
 
@@ -784,15 +820,28 @@ window.__ModuleLoader__.load({
 
       useEffect(() => {
         let alive = true
+        const onChange = () => load()
+        window.addEventListener(CHANGED_EVENT, onChange)
         const load = () => fetch('/api/message-ops/messages?sessionId=' + encodeURIComponent(sessionId))
           .then((r) => (r.ok ? r.json() : null))
           .then((data) => {
             if (!alive || !data || !data.ok) return
-            setMarkers(activeMarkers(data.messages || []))
+            const msgs = data.messages || []
+            setMarkers(activeMarkers(msgs))
+            // 0.5.2（P2）：标题口径 = 标记 range 内 visible=false 的去重 seq 数
+            const seen = new Set()
+            for (const mk of activeMarkers(msgs)) {
+              const start = mk.range && typeof mk.range.start === 'number' ? mk.range.start : mk.seq
+              const end = mk.range && typeof mk.range.end === 'number' ? mk.range.end : start
+              for (const m of msgs) {
+                if (m && m.visible === false && typeof m.seq === 'number' && m.seq >= start && m.seq <= end) seen.add(m.seq)
+              }
+            }
+            setShadowCount(seen.size)
           })
           .catch(() => {})
         load()
-        return () => { alive = false }
+        return () => { alive = false; window.removeEventListener(CHANGED_EVENT, onChange) }
       }, [sessionId])
 
       // items 变化自动折叠（opencode createEffect 同款；必须在早退之前——Hooks 规则）
@@ -802,10 +851,11 @@ window.__ModuleLoader__.load({
       const restoreRow = (row) => {
         if (restoring != null || running) return
         setRestoring(row.seq)
-        fetch('/api/message-ops/restore', {
-          method: 'POST', headers: { 'content-type': 'application/json' },
-          body: JSON.stringify({ sessionId, seq: row.seq }),
-        })
+        Promise.resolve()
+          .then(() => fetch('/api/message-ops/restore', {
+            method: 'POST', headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ sessionId, seq: row.seq }),
+          }))
           .then(async (res) => {
             let data = {}
             try { data = await res.json() } catch { /* keep {} */ }
@@ -821,13 +871,15 @@ window.__ModuleLoader__.load({
           })
           .catch((reason) => {
             notifyDone(t('errorPrefix') + (reason && reason.message ? reason.message : String(reason)), 'error')
-            setRestoring(null)
           })
+          .finally(() => setRestoring(null))
       }
 
 
       const headerKbd = (e) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); setOpen((v) => !v) } }
-      const label = t('dock.title', { n: String(markers.length) })
+      // 0.5.2（P2）：标题报「被遮蔽消息数」而非标记数——一个 revert 可遮蔽数百条，
+      // 用标记数会严重低报（0.4.2 文案引入的错口径）；无 range 数据时回退标记数
+      const label = t('dock.title', { n: String(shadowCount || markers.length) })
       const preview = markers[0] && markers[0].snippet ? markers[0].snippet : ''
 
       const rowEl = (row) => React.createElement('div', { key: row.seq, className: 'mopsRdRow' },
@@ -899,7 +951,11 @@ window.__ModuleLoader__.load({
         var titleEl = row.querySelector('[class*=title]')
         var title = titleEl ? String(titleEl.innerText || '').trim() : ''
         if (!title) return
-        window.dispatchEvent(new CustomEvent(EVENT, { detail: { title: title } }))
+        // 0.5.2（P1）：必须带 sessionId——否则对话框加载 effect 早退，永久卡「正在读取…」
+        var sid = ''
+        var rk = row.getAttribute && row.getAttribute('data-row-key')
+        if (rk && rk.indexOf('session:') === 0) sid = rk.slice(8)
+        window.dispatchEvent(new CustomEvent(EVENT, { detail: { title: title, sessionId: sid || undefined } }))
       })
       var sep = document.createElement('div')
       sep.style.cssText = 'height:1px;margin:4px 8px;background:var(--dsw-alias-border-l1,rgba(128,128,128,.2))'

package/src/index.js

@@ -20,9 +20,11 @@
  * @module dsh-message-ops
  */
 
-import { isSessionId, sessionIdVariants, findSessionDirs, readSessionFile, readSessionFileAsync, listMessages, computeShadowed } from "./session-file.js";
+import { zstdCompressSync } from "node:zlib";
+import { open as openFile, truncate as truncateFile, stat as statFile } from "node:fs/promises";
+import { isSessionId, sessionIdVariants, findSessionDirs, readSessionFile, readSessionFileAsync, listMessages, computeShadowed, messageText } from "./session-file.js";
 import { applyBranch } from "./branch.js";
-import {
+import { restoreNoticeText, planRevertFromEvents, planDeleteFromEvents, nextSeqFrom, buildMarkerEvent, buildRestoreNoticeEvent, buildReplayEvent, deriveTurnStep,
   OpsError, planRevert, planDelete, planRestore, applyRestore, applySurfaceReplace, exportMarkdown,
   isTrustedApiRequest, isJsonContentType,
 } from "./ops-core.js";
@@ -83,26 +85,151 @@ async function readFencedBody(req, res) {
 }
 
 /** 从 sessions 注册表解析（两种 id 拼写都试）。 */
+let __resolveSource = null; // 诊断：最近一次 resolveSession 的失败原因
 function resolveSession(ctx, sessionId) {
-  const sessions = ctx.get("sessions");
-  if (!sessions || typeof sessions.get !== "function") return undefined;
-  for (const variant of sessionIdVariants(sessionId)) {
-    const s = sessions.get(variant);
-    if (s !== undefined) return s;
+  // 宿主自己的取法是 `this.ctx.sessions.get(id)`（api-session-controller 同款）；
+  // 实测 `ctx.get("sessions")` 在 inject 子 fiber 下解析到的注册表**查不到视图已
+  // 加载的会话**（dock 已渲染但 get 双变体 miss —— agents.get 同 ctx 却命中），
+  // 故属性优先、ctx.get 兜底，两处都试全变体。
+  const candidates = [];
+  try { if (ctx && ctx.sessions) candidates.push(["prop", ctx.sessions]); } catch { /* no proxy */ }
+  try { const svc = ctx.get("sessions"); if (svc) candidates.push(["get", svc]); } catch { /* absent */ }
+  if (candidates.length === 0) { __resolveSource = "no-sessions-service"; return undefined; }
+  const variants = sessionIdVariants(sessionId);
+  const tried = [];
+  for (const [src, svc] of candidates) {
+    if (typeof svc.get !== "function") { tried.push(src + ":no-get"); continue; }
+    for (const variant of variants) {
+      const s = svc.get(variant);
+      if (s !== undefined) { __resolveSource = "hit via " + src + ".get " + String(variant).slice(0, 24); return s; }
+    }
+    // get 键错位兜底：list() 扫描（集群 face 的 list() 返回 live 实例数组，
+    // 实测 get 双变体 miss 时 list 里可能有 —— 按 id/sessionId 匹配）
+    if (typeof svc.list === "function") {
+      try {
+        const arr = svc.list();
+        if (Array.isArray(arr)) {
+          const hit = arr.find((x) => x && (variants.includes(x.id) || variants.includes(x.sessionId)));
+          if (hit) { __resolveSource = "hit via " + src + ".list() n=" + arr.length; return hit; }
+          tried.push(src + ":list-n=" + arr.length + " ids=" + arr.slice(0, 3).map((x) => String(x && (x.id || x.sessionId) || "?").slice(0, 18)).join("|"));
+        } else {
+          tried.push(src + ":list-" + typeof arr);
+        }
+      } catch (e) { tried.push(src + ":list-threw " + String(e && e.message).slice(0, 30)); }
+      continue;
+    }
+    tried.push(src + ":miss");
   }
+  __resolveSource = tried.join(",") + " tried=" + variants.length + " first=" + String(variants[0]).slice(0, 30);
   return undefined;
 }
 
 /** 是否有 live agent 正占用该会话。 */
+/**
+ * acquireSession：拿到 live SessionFace（带 .surface/.append）并在用完后释放。
+ *
+ * 0.5.6（实机第四层根因）：lazy-view 让会话**只在磁盘渲染、不进对象层**——
+ * 视图开着（dock 已渲染）但 sessions.get(id) 双变体全 miss、list() 里只有别的
+ * 会话 → 所有变更操作 404「not found in registry」。官方越界获取通道是
+ * retain(target, {source}) → await ready → binding.session（ISessions 契约）；
+ * 引用在 mutation 完成后 release（final reference 触发 teardown，须先 flush）。
+ */
+async function acquireSession(ctx, sessionId) {
+  const direct = resolveSession(ctx, sessionId);
+  if (direct !== undefined) return { session: direct, release() {} };
+  const owners = [];
+  // reflect 层：api-session-controller 把 ISessions（ClientSessions，带 retain）经
+  // `rootCtx.reflect.provide("sessions", this)` 挂在根上；普通 ctx.get 取到的是
+  // 近端同名对象层（get/list 有、retain 无）——必须走 reflect.get 才是契约面。
+  try { if (ctx && ctx.reflect && typeof ctx.reflect.get === "function") owners.push(["reflect", ctx.reflect.get("sessions", false)]); } catch { /* not provided */ }
+  try { if (ctx && ctx.sessions) owners.push(["prop", ctx.sessions]); } catch { /* getter threw */ }
+  try { const svc = ctx.get("sessions"); if (svc) owners.push(["get", svc]); } catch { /* absent */ }
+  const holders = owners.filter(([, o]) => o && typeof o.retain === "function");
+  if (holders.length === 0) {
+    const why = owners.length === 0
+      ? "no-owner (prop-absent && get-absent)"
+      : owners.map(([src, o]) => src + ":no-retain(" + (o == null ? "null" : typeof o) + ")").join(",");
+    __resolveSource = (__resolveSource || "") + " | ISessions:" + why;
+    return null;
+  }
+  const isess = holders[0][1];
+  let ref = null;
+  try {
+    ref = isess.retain(sessionId, { source: "controllerOperation" });
+    const binding = await ref.ready;
+    const face = binding && binding.session;
+    if (!face) { __resolveSource = "retain-ready-no-session-face"; try { ref.release(); } catch { /* */ } return null; }
+    __resolveSource = "acquired via ISessions.retain";
+    return { session: face, release: () => { try { ref.release(); } catch { /* already released */ } } };
+  } catch (e) {
+    __resolveSource = "retain-failed: " + String(e && e.message).slice(0, 80);
+    if (ref) { try { ref.release(); } catch { /* */ } }
+    return null;
+  }
+}
+
+let __runningSource = null; // 诊断：最近一次 isRunning 的判定来源
 function isRunning(ctx, sessionId) {
-  const agents = ctx.get("agents");
-  if (!agents || typeof agents.get !== "function") return false;
+  // 0.5.4（实机三层根因第 3 层的最终修）：与宿主**官方同源**——
+  // dsh-api-session-controller/lib/index.js ApiSessionList.summaryFor():
+  //   running: this.ctx.agents.get(session.id)?.status === "running"
+  // 原实现把「agents 注册表有条目」直接当 running —— 会话仅在视图中打开
+  // 就有条目 → 打开即 409 锁死所有变更操作。必须再比对 status。
   try {
-    for (const variant of sessionIdVariants(sessionId)) {
-      if (agents.get(variant)) return true;
+    const candidates = [];
+    try { if (ctx && ctx.agents) candidates.push(ctx.agents); } catch { /* no proxy */ }
+    try { const svc = ctx.get("agents"); if (svc) candidates.push(svc); } catch { /* absent */ }
+    if (candidates.length === 0) { __runningSource = "no-agents-service"; return false; }
+    for (const svc of candidates) {
+      if (typeof svc.get !== "function") continue;
+      for (const variant of sessionIdVariants(sessionId)) {
+        const agent = svc.get(variant);
+        if (agent && agent.status === "running") {
+          __runningSource = "agent-status-running";
+          return true;
+        }
+        if (agent) __runningSource = "agent-status:" + String(agent.status);
+      }
+    }
+    if (!__runningSource) __runningSource = "no-agent-entry";
+    return false;
+  } catch (e) {
+    __runningSource = "threw:" + String(e && e.message).slice(0, 50);
+    return false;
+  }
+}
+
+
+
+/**
+ * diskAppend：把新事件作为一个 zstd 帧追加到会话日志（等价持久层 appendLines：
+ * encode → open('a') → write+sync，失败按持久层同款按 size 回滚）。
+ * 仅用于 store-miss 的 lazy-view 会话——无并发生命周期游标可竞争。
+ */
+async function diskAppend(logPath, newEvents) {
+  if (!Array.isArray(newEvents) || newEvents.length === 0) throw new OpsError("diskAppend: empty batch", 400);
+  const jsonl = newEvents.map((e) => JSON.stringify(e)).join("\n") + "\n";
+  const frame = zstdCompressSync(Buffer.from(jsonl, "utf8"));
+  const handle = await openFile(logPath, "a");
+  let closed = false;
+  const closeHandle = async () => { if (closed) return; closed = true; await handle.close(); };
+  try {
+    const { size: before } = await statFile(logPath);
+    try {
+      await handle.writeFile(frame);
+      await handle.sync();
+    } catch (error) {
+      try {
+        await closeHandle();
+        await truncateFile(logPath, before);
+      } catch (rollbackError) {
+        throw new AggregateError([error, rollbackError], `failed to roll back append to "${logPath}"`);
+      }
+      throw error;
     }
-  } catch { /* registry absent: treat as idle */ }
-  return false;
+  } finally {
+    await closeHandle();
+  }
 }
 
 function flushSessions(ctx, session) {
@@ -143,28 +270,56 @@ async function opsList(targetCtx, sessionId) {
     ok: true,
     session: { id: header.id, createdAt: header.createdAt, parentSession: header.parentSession ?? null },
     running: isRunning(targetCtx, sessionId),
+    runningSource: __runningSource,
     total: messages.length,
     visibleCount,
     messages,
   };
 }
 
-function opsCommit(targetCtx, mode, sessionId, seq) {
+async function opsCommit(targetCtx, mode, sessionId, seq) {
   if (!isSessionId(sessionId)) throw new OpsError("invalid sessionId", 400);
   if (!Number.isSafeInteger(seq) || seq < 0) throw new OpsError("invalid seq", 400);
   if (isRunning(targetCtx, sessionId)) throw new OpsError("session is running; stop it first", 409);
-  const session = resolveSession(targetCtx, sessionId);
-  if (session === undefined) throw new OpsError("session not found in registry (is it loaded?)", 404);
-  const plan = mode === "delete" ? planDelete(session.surface, seq) : planRevert(session.surface, seq);
+  const { logPath } = pickSessionDir(sessionId);
+  const { events } = await readSessionFileAsync(logPath);
+  const turnStep = deriveTurnStep(events);
   const notice = mode === "delete"
     ? `[消息删除] 已遮蔽 seq ${seq}`
+    : null; // revert 文案含 shadowed 数量，规划后拼
+  const acq = await acquireSession(targetCtx, sessionId);
+  if (acq !== null && acq.session !== undefined) {
+    try {
+      const session = acq.session;
+      // 0.5.4（P0）：v4 准入要求 system/message 带正 turn/step——缺字段时持久层
+      // encodeEventBatch 的 SessionFormatError 未捕获会**打死整个 dsh 进程**。
+      const plan = mode === "delete" ? planDelete(session.surface, seq) : planRevert(session.surface, seq);
+      const text = mode === "delete" ? notice
+        : `[消息回滚] 已回滚到 seq ${seq}（含）之后的 ${plan.shadowedSeqs.length} 个节点`;
+      const event = applySurfaceReplace(session, plan.startSeq, plan.endSeq, plan.shadowedSeqs, text, turnStep);
+      flushSessions(targetCtx, session);
+      return {
+        ok: true, mode, seq,
+        shadowedCount: plan.shadowedSeqs.length,
+        eventSeq: event && event.seq != null ? event.seq : null,
+      };
+    } finally {
+      acq.release();
+    }
+  }
+  // store-miss（lazy-view 只读盘会话）→ 磁盘路径：镜像引擎字段直接追加 zstd 帧
+  const plan = mode === "delete" ? planDeleteFromEvents(events, seq) : planRevertFromEvents(events, seq);
+  const text = mode === "delete" ? notice
     : `[消息回滚] 已回滚到 seq ${seq}（含）之后的 ${plan.shadowedSeqs.length} 个节点`;
-  const event = applySurfaceReplace(session, plan.startSeq, plan.endSeq, plan.shadowedSeqs, notice);
-  flushSessions(targetCtx, session);
+  const marker = buildMarkerEvent({
+    seq: nextSeqFrom(events), time: Date.now(), turnStep, text,
+    startSeq: plan.startSeq, endSeq: plan.endSeq, shadowedSeqs: plan.shadowedSeqs,
+  });
+  await diskAppend(logPath, [marker]);
   return {
-    ok: true, mode, seq,
+    ok: true, mode, seq, disk: true,
     shadowedCount: plan.shadowedSeqs.length,
-    eventSeq: event && event.seq != null ? event.seq : null,
+    eventSeq: marker.seq,
   };
 }
 
@@ -182,15 +337,38 @@ async function opsRestore(targetCtx, sessionId, restoreSeq) {
   if (!isSessionId(sessionId)) throw new OpsError("invalid sessionId", 400);
   if (!Number.isSafeInteger(restoreSeq) || restoreSeq < 0) throw new OpsError("invalid seq", 400);
   if (isRunning(targetCtx, sessionId)) throw new OpsError("session is running; stop it first", 409);
-  const session = resolveSession(targetCtx, sessionId);
-  if (session === undefined) throw new OpsError("session not found in registry (is it loaded?)", 404);
   const { logPath } = pickSessionDir(sessionId);
   const { events } = await readSessionFileAsync(logPath);
   const plan = planRestore(events, restoreSeq);
-  const result = applyRestore(session, plan, {
-    flush: () => { flushSessions(targetCtx, session); },
-  });
-  return { ok: true, ...result, range: { startSeq: plan.startSeq, endSeq: plan.endSeq } };
+  const acq = await acquireSession(targetCtx, sessionId);
+  if (acq !== null && acq.session !== undefined) {
+    try {
+      const result = applyRestore(acq.session, plan, {
+        flush: () => { flushSessions(targetCtx, acq.session); },
+      });
+      return { ok: true, ...result, range: { startSeq: plan.startSeq, endSeq: plan.endSeq } };
+    } finally {
+      acq.release();
+    }
+  }
+  // store-miss → 磁盘路径：说明事件 + 重放事件批量追加（一个帧）
+  let cursor = nextSeqFrom(events);
+  const now = Date.now();
+  const batch = [buildRestoreNoticeEvent({
+    seq: cursor++, time: now, turnStep: plan.turnStep,
+    text: restoreNoticeText(plan), restoreSeq: plan.restoreSeq,
+  })];
+  for (const item of plan.replayable) {
+    batch.push(buildReplayEvent({ seq: cursor++, time: ++now, item }));
+  }
+  await diskAppend(logPath, batch);
+  return {
+    ok: true, disk: true,
+    restoredCount: plan.replayable.length,
+    skipped: plan.skipped,
+    eventSeqs: batch.map((e) => e.seq),
+    range: { startSeq: plan.startSeq, endSeq: plan.endSeq },
+  };
 }
 
 async function opsExport(targetCtx, sessionId, seq) {
@@ -250,15 +428,20 @@ export function createMessageOpsTool({ defineTool, ops, ctx }) {
       const sessionId = String(args.sessionId || "").trim();
       try {
         let result;
+        // 0.5.2（P1）：ops 自 0.2.1 起为 async——不 await 会把 Promise 直接送进 renderResult，
+        // list/restore 必抛 TypeError、export 渲出空 text（测试桩曾是同步的故漏检）。
         switch (action) {
-          case "list": result = ops.list(ctx, sessionId); break;
-          case "revert": result = ops.revert(ctx, sessionId, args.seq); break;
-          case "delete": result = ops.delete(ctx, sessionId, args.seq); break;
-          case "branch": result = ops.branch(ctx, sessionId, args.upToSeq); break;
-          case "restore": result = ops.restore(ctx, sessionId, args.seq); break;
-          case "export": result = ops.export(ctx, sessionId, args.seq); break;
+          case "list": result = await ops.list(ctx, sessionId); break;
+          case "revert": result = await ops.revert(ctx, sessionId, args.seq); break;
+          case "delete": result = await ops.delete(ctx, sessionId, args.seq); break;
+          case "branch": result = await ops.branch(ctx, sessionId, args.upToSeq); break;
+          case "restore": result = await ops.restore(ctx, sessionId, args.seq); break;
+          case "export": result = await ops.export(ctx, sessionId, args.seq); break;
           default: throw new OpsError(`unknown action: ${action}`, 400);
         }
+        if (action === "branch" && result && typeof result === "object" && result.parentSession == null) {
+          result.parentSession = sessionId; // renderResult 需要原始会话 id（branch 返回值不含/可为 undefined）
+        }
         return renderResult(action, result);
       } catch (e) {
         return `${action} failed: ${e && e.message ? e.message : e}`;
@@ -284,7 +467,7 @@ function renderResult(action, r) {
     case "delete":
       return `${r.mode} ok: shadowed ${r.shadowedCount} node(s) from seq ${r.seq}; marker event seq ${r.eventSeq}`;
     case "branch":
-      return `branch ok: new session ${r.newId} (parent ${r.parentId ?? "n/a"}), kept ${r.kept ?? "?"} event(s)`;
+      return `branch ok: new session ${r.newId} (parent ${r.parentSession ?? "n/a"}), kept ${r.keptEvents ?? "?"} event(s)`;
     case "restore":
       return `restore ok: replayed ${r.restoredCount} message(s) from range ${r.range.startSeq}..${r.range.endSeq} (${r.skipped} skipped); appended event seqs ${r.eventSeqs.join(", ")}`;
     case "export":
@@ -327,12 +510,22 @@ function registerToolTolerantly(ctx) {
 // ---------------------------------------------------------------------------
 
 export function apply(ctx) {
+  // 诊断（0.5.4 调试）：会话状态服务解析情况
+  try {
+    const names = ["sessions", "agents", "sessionController", "sessionList", "session-manager"];
+    const parts = names.map((n) => { const v = ctx.get(n); return n + "=" + (v == null ? String(v) : typeof v); });
+    const ses = ctx.get("sessions");
+    const hasList = ses && ses.list != null;
+    const hasSnap = hasList && typeof ses.list.getSnapshot === "function";
+    console.log("[message-ops] session services: " + parts.join(" ") + " | sessions.list=" + hasList + " getSnapshot=" + hasSnap + (ses ? " keys=" + Object.keys(ses).slice(0, 12).join("|") : ""));
+  } catch (e) { console.log("[message-ops] probe failed: " + e); }
   function registerHttp(host, targetCtx) {
     // --- GET /api/message-ops/messages：消息列表（只读） ---------------------
     targetCtx.effect(() => host.register({
       kind: "exact",
       path: "/api/message-ops/messages",
       handler: async (req, res) => {
+        if (req.method !== "GET") return sendJson(res, 405, { ok: false, error: "method not allowed" });
         if (!fence(req, res)) return;
         try {
           const url = new URL(req.url, "http://localhost");
@@ -343,6 +536,31 @@ export function apply(ctx) {
       },
     }), "dsh-message-ops: messages route");
 
+    // --- GET /api/message-ops/text：单条消息全文（0.5.2 引用按钮按需取） ----------
+    // assistant 消息的 fullText 不在 messages 列表里（载荷控制），quote 点击时单取。
+    targetCtx.effect(() => host.register({
+      kind: "exact",
+      path: "/api/message-ops/text",
+      handler: async (req, res) => {
+        if (req.method !== "GET") return sendJson(res, 405, { ok: false, error: "method not allowed" });
+        if (!fence(req, res)) return;
+        try {
+          const url = new URL(req.url, "http://localhost");
+          const sessionId = url.searchParams.get("sessionId") || "";
+          const seq = Number.parseInt(url.searchParams.get("seq") || "", 10);
+          if (!isSessionId(sessionId)) throw new OpsError("invalid sessionId", 400);
+          if (!Number.isSafeInteger(seq) || seq < 0) throw new OpsError("invalid seq", 400);
+          const { logPath } = pickSessionDir(sessionId);
+          const { events } = await readSessionFileAsync(logPath);
+          const ev = events.find((e) => e && e.seq === seq);
+          if (!ev) throw new OpsError("seq not found", 404);
+          return sendJson(res, 200, { ok: true, seq, text: messageText(ev) });
+        } catch (err) {
+          return sendJson(res, err instanceof OpsError ? err.status : 500, { ok: false, error: String(err && err.message ? err.message : err) });
+        }
+      },
+    }), "dsh-message-ops: text route");
+
     // --- POST revert / delete：live-session surface replace ------------------
     const commitHandler = (mode) => async (req, res) => {
       if (req.method !== "POST") return sendJson(res, 405, { ok: false, error: "method not allowed" });
@@ -351,7 +569,7 @@ export function apply(ctx) {
       if (body === undefined) return;
       if (!body || typeof body !== "object") return sendJson(res, 400, { ok: false, error: "invalid json" });
       try {
-        return sendJson(res, 200, opsCommit(targetCtx, mode, body.sessionId, body.seq));
+        return sendJson(res, 200, await opsCommit(targetCtx, mode, body.sessionId, body.seq));
       } catch (err) {
         return sendJson(res, err instanceof OpsError ? err.status : 500, { ok: false, error: String(err && err.message ? err.message : err) });
       }

package/src/ops-core.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 /**
  * dsh-message-ops — 可复用操作核心（纯逻辑，无 HTTP、无 dsh-tools 依赖）。
  *
@@ -16,7 +17,7 @@
  * @module dsh-message-ops/ops-core
  */
 
-import { readReplaceOp, messageText } from "./session-file.js";
+import { readReplaceOp, messageText, computeShadowed } from "./session-file.js";
 
 // messageText 的单点实现在 session-file.js（listMessages 同用）；此处转出保持
 // 既有导入面兼容（ops-core 的 messageText/exportMarkdown 调用方不受影响）。
@@ -75,8 +76,32 @@ export function _resetReplaceShape() { replaceShape = null; }
  * sourceEventSeqs 必须覆盖被遮蔽的全部 surface 节点（引擎
  * assertProvenance 强校验，缺失即抛错）。
  */
-export function applySurfaceReplace(session, startSeq, endSeq, sourceEventSeqs, noticeText) {
-  const data = { message: { role: "system", content: [{ type: "text", text: noticeText }] } };
+/**
+ * deriveTurnStep：从事件流尾部回溯最近的正整数 turn/step 坐标。
+ *
+ * 0.5.4（实机 P0）：dsh 0.2.0 收紧 v4 准入（assertV4SystemMessageFields）——
+ * 每个 system/message 的 data 必须带正整数 turn/step。缺失时持久层
+ * encodeEventBatch 抛出的 SessionFormatError **未被任何层捕获 → 打死整个 dsh
+ * 进程**（包装实测 exit=1，栈：assertV4SystemMessageFields ← encodeEventBatch
+ * ← cordis apply）。通知事件复用最近一次活动的坐标（row-admission 只做
+ * positive 校验，无状态机匹配要求）；空/旧日志兜底 1/1。
+ */
+export function deriveTurnStep(events) {
+  if (Array.isArray(events)) {
+    for (let i = events.length - 1; i >= 0; i--) {
+      const d = events[i] && events[i].data;
+      if (d && Number.isSafeInteger(d.turn) && d.turn > 0 && Number.isSafeInteger(d.step) && d.step > 0) {
+        return { turn: d.turn, step: d.step };
+      }
+    }
+  }
+  return { turn: 1, step: 1 };
+}
+
+export function applySurfaceReplace(session, startSeq, endSeq, sourceEventSeqs, noticeText, turnStep) {
+  const ts = turnStep && Number.isSafeInteger(turnStep.turn) && turnStep.turn > 0
+    ? turnStep : { turn: 1, step: 1 };
+  const data = { turn: ts.turn, step: ts.step, message: { id: randomUUID(), role: "system", content: [{ type: "text", text: noticeText }] } };
   if (replaceShape) {
     return session.append("system/message", data, { surfaceOp: replaceOpFor(replaceShape, startSeq, endSeq), sourceEventSeqs });
   }
@@ -127,10 +152,11 @@ export function planRestore(events, restoreSeq) {
       skipped++; // tool/call 等不可安全重放的事件：跳过并在结果里计数
     }
   }
-  if (replayable.length === 0) {
-    throw new OpsError(`restore: no replayable user/assistant messages in shadowed range ${startSeq}..${endSeq}`, 409);
-  }
-  return { restoreSeq, startSeq, endSeq, replayable, skipped };
+  // 0.5.6：区间无可重放消息（如只遮蔽了 tool/system 事件）不再 409 ——
+  // dock 会为这类标记常驻显示恢复按钮，409 死按钮 = 永远清不掉（实测 8 连 409）。
+  // 改为返回空计划：applyRestore 仍追加说明 notice（含 restoresSeq）→ 标记停用、
+  // dock 计数递减；语义如实：0 条重放 + 文案说明区间无 user/assistant 内容。
+  return { restoreSeq, startSeq, endSeq, replayable, skipped, turnStep: deriveTurnStep(events) };
 }
 
 /**
@@ -138,16 +164,26 @@ export function planRestore(events, restoreSeq) {
  * 引擎不支持取消遮蔽（SurfaceOp 无该变体），故实现为重放：
  * 每条消息以原类型 append、文本加 [恢复] 前缀；先 append 一条 system 说明。
  */
+/** 恢复说明文案（live append 与磁盘路径共用；空可重放 = 停用语义）。 */
+export function restoreNoticeText(plan) {
+  return plan.replayable.length === 0
+    ? `[消息恢复] seq ${plan.startSeq}..${plan.endSeq} 区间无可重放的 user/assistant 消息（` +
+      `内容为 tool/system 事件或空文本）——该回撤标记就此停用，区间保持遮蔽`
+    : `[消息恢复] 重放 seq ${plan.startSeq}..${plan.endSeq} 的 ${plan.replayable.length} 条消息` +
+      (plan.skipped > 0 ? `（另有 ${plan.skipped} 条不可重放事件已跳过）` : "") +
+      `；原区间仍处于遮蔽状态，恢复为重放而非解除遮蔽`;
+}
+
 export function applyRestore(session, plan, { flush } = {}) {
   const eventSeqs = [];
-  const notice = `[消息恢复] 重放 seq ${plan.startSeq}..${plan.endSeq} 的 ${plan.replayable.length} 条消息` +
-    (plan.skipped > 0 ? `（另有 ${plan.skipped} 条不可重放事件已跳过）` : "") +
-    `；原区间仍处于遮蔽状态，恢复为重放而非解除遮蔽`;
+  const notice = restoreNoticeText(plan);
   // 0.4.2：notice 事件携带 restoresSeq —— dock 据此把被恢复的标记从「活跃回撤」
   // 中移除（对齐 opencode clear 语义：恢复后不再显示为待恢复项）。
+  const ts = plan.turnStep && Number.isSafeInteger(plan.turnStep.turn) && plan.turnStep.turn > 0
+    ? plan.turnStep : { turn: 1, step: 1 };
   const noticeEvent = session.append(
     "system/message",
-    { message: { role: "system", content: [{ type: "text", text: notice }] }, restoresSeq: plan.restoreSeq },
+    { turn: ts.turn, step: ts.step, message: { id: randomUUID(), role: "system", content: [{ type: "text", text: notice }] }, restoresSeq: plan.restoreSeq },
     { surfaceOp: "append" },
   );
   if (noticeEvent && noticeEvent.seq != null) eventSeqs.push(noticeEvent.seq);
@@ -296,3 +332,98 @@ export function buildSeqIndex(messages) {
   }
   return map;
 }
+
+// ---------------------------------------------------------------------------
+// 0.5.7 · 磁盘路径（lazy-view 会话不进对象层时的回退）
+// ---------------------------------------------------------------------------
+// 实机第四层根因：视图打开 ≠ 对象层有会话（lazy-view 只读盘渲染）。官方服务端
+// 没有 retain/using 面，故 store-miss 时改为**直接向日志追加 zstd 帧**——与
+// 持久层 JsonlSessionPersistence.appendLines 等价（encode → open('a') →
+// write+sync+失败回滚），事件字段逐项镜像引擎写出的金标准（见 README0.5.7）。
+// 磁盘会话的视图本来就按帧重读，追加即可见；live 会话仍走引擎路径。
+
+/** 事件类型是否为 surface 节点（message 类；step/end、turn/end 等结构性事件不是）。 */
+export function isSurfaceMessageType(type) {
+  return type === "user/message" || type === "assistant/message"
+    || type === "system/message" || type === "developer/message";
+}
+
+/** 磁盘可见节点：按事件流推导的 message 类 seq（剔除既有遮蔽）。 */
+export function diskVisibleNodes(events) {
+  const shadowed = computeShadowed(events);
+  const nodes = [];
+  for (const e of events) {
+    if (!e || !Number.isSafeInteger(e.seq)) continue;
+    if (shadowed.has(e.seq)) continue;
+    if (isSurfaceMessageType(e.type)) nodes.push(e.seq);
+  }
+  return nodes;
+}
+
+/** 磁盘版 planRevert：target 必须可见，遮蔽 target 之后（含）全部可见节点。 */
+export function planRevertFromEvents(events, targetSeq) {
+  const nodes = diskVisibleNodes(events);
+  const startIdx = nodes.indexOf(targetSeq);
+  if (startIdx === -1) throw new OpsError(`surface replace: start seq ${targetSeq} not found in surface`, 409);
+  const shadowedSeqs = nodes.slice(startIdx);
+  if (shadowedSeqs.length === 0) throw new OpsError("nothing to revert", 409);
+  return { startSeq: targetSeq, endSeq: shadowedSeqs[shadowedSeqs.length - 1], shadowedSeqs };
+}
+
+/** 磁盘版 planDelete：单条可见遮蔽。 */
+export function planDeleteFromEvents(events, seq) {
+  if (!diskVisibleNodes(events).includes(seq)) {
+    throw new OpsError(`seq ${seq} not visible on current surface`, 409);
+  }
+  return { startSeq: seq, endSeq: seq, shadowedSeqs: [seq] };
+}
+
+/** 下一个可用 seq（全量事件 max+1；结构性事件也占 seq）。 */
+export function nextSeqFrom(events) {
+  let max = -1;
+  for (const e of events) if (e && Number.isSafeInteger(e.seq) && e.seq > max) max = e.seq;
+  return max + 1;
+}
+
+/** 磁盘回撤/删除标记事件（字段镜像引擎金标准：type/seq/time/data/sourceEventSeqs/surfaceOp）。 */
+export function buildMarkerEvent({ seq, time, turnStep, text, startSeq, endSeq, shadowedSeqs }) {
+  return {
+    type: "system/message",
+    seq,
+    time,
+    data: {
+      turn: turnStep.turn,
+      step: turnStep.step,
+      message: { id: randomUUID(), role: "system", content: [{ type: "text", text }] },
+    },
+    sourceEventSeqs: [...shadowedSeqs],
+    surfaceOp: { op: "replace", startSeq, endSeq },
+  };
+}
+
+/** 磁盘恢复说明事件（restoresSeq → dock 移除该行；surfaceOp 恒 "append"）。 */
+export function buildRestoreNoticeEvent({ seq, time, turnStep, text, restoreSeq }) {
+  return {
+    type: "system/message",
+    seq,
+    time,
+    data: {
+      turn: turnStep.turn,
+      step: turnStep.step,
+      message: { id: randomUUID(), role: "system", content: [{ type: "text", text }] },
+      restoresSeq: restoreSeq,
+    },
+    surfaceOp: "append",
+  };
+}
+
+/** 磁盘重放事件（镜像引擎：无 id、[恢复] 前缀、surfaceOp "append"）。 */
+export function buildReplayEvent({ seq, time, item }) {
+  return {
+    type: item.type,
+    seq,
+    time,
+    data: { message: { role: item.role, content: [{ type: "text", text: `[恢复] ${item.text}` }] } },
+    surfaceOp: "append",
+  };
+}

package/test/ops-core.test.js

@@ -89,17 +89,19 @@ test('planRestore：兼容 start/end 拼写（dsh-src 较新引擎形状）', ()
   assert.equal(plan.replayable[0].text, 'a')
 })
 
-test('planRestore：非标记事件 / 越界 seq / 无可重放消息 均拒绝', () => {
+test('planRestore：非标记事件 / 越界 seq 拒绝；空可重放区间改为接受（0.5.6 停用语义）', () => {
   const events = sampleEvents()
   assert.throws(() => planRestore(events, 99), (e) => e instanceof OpsError && e.status === 404)
   assert.throws(() => planRestore(events, 0), (e) => e instanceof OpsError && e.status === 409) // 普通消息非标记
   assert.throws(() => planRestore(events, -1), (e) => e instanceof OpsError && e.status === 400)
-  // 区间内只有 tool 事件 → 无可重放
+  // 0.5.6：区间内只有 tool 事件 → 不再 409，返回空可重放计划（停用语义）
   const onlyTool = [
     { type: 'tool/call', seq: 0, data: { name: 'bash' } },
     { type: 'system/message', seq: 1, surfaceOp: { op: 'replace', startSeq: 0, endSeq: 0 }, sourceEventSeqs: [0] },
   ]
-  assert.throws(() => planRestore(onlyTool, 1), (e) => e instanceof OpsError && e.status === 409)
+  const plan = planRestore(onlyTool, 1)
+  assert.equal(plan.replayable.length, 0, '空可重放 = 接受为停用计划')
+  assert.equal(plan.startSeq, 0)
 })
 
 test('applyRestore：重放 append 带 [恢复] 前缀 + system 说明，flush 被调用', () => {
@@ -190,7 +192,7 @@ test('apply：无 webServer、无 tools 时走 inject 等待，不抛错', () =>
   assert.equal(ctx.registrations.length, 0)
 })
 
-test('apply：webServer 存在时注册全部 6 条路由；tools 缺失走 inject 等待', () => {
+test('apply：webServer 存在时注册全部 7 条路由；tools 缺失走 inject 等待', () => {
   const ctx = mockCtx({ webServer: { register: (route) => ctx.registrations.push(route) } })
   assert.doesNotThrow(() => apply(ctx))
   const paths = ctx.registrations.map((r) => r.path).sort()
@@ -201,6 +203,7 @@ test('apply：webServer 存在时注册全部 6 条路由；tools 缺失走 inje
     '/api/message-ops/messages',
     '/api/message-ops/restore',
     '/api/message-ops/revert',
+    '/api/message-ops/text',
   ])
   // tools 缺失 → 容错等待而非 fatal
   assert.ok(ctx.injects.some(([deps]) => deps[0] === 'tools'))
@@ -214,3 +217,145 @@ test('apply：tools 服务存在时直接进入注册路径（包缺失时 catch
   // 但绝不能让插件 apply 抛错；异步分支也不能产生未处理拒绝。
   assert.equal(registered.length, 0)
 })
+
+// ── 0.5.2 回归：工具层必须 await async ops（0.2.1 改 async 后曾漏同步化，
+//    list/restore 抛 TypeError、export 渲出空 text；旧桩是同步的故漏检）──────
+test('工具 execute：async ops 被 await（list/branch/restore/export 全路径）', async () => {
+  let def
+  const defineTool = (d) => { def = d; return d }
+  const asyncOps = {
+    list: async () => ({ session: { id: 'session-abc', parentSession: null }, running: false, total: 1, visibleCount: 1,
+      messages: [{ seq: 10, role: 'user', visible: true, snippet: 'hello' }] }),
+    revert: async () => ({ mode: 'revert', shadowedCount: 2, seq: 10, eventSeq: 99 }),
+    delete: async () => ({ mode: 'delete', shadowedCount: 1, seq: 10, eventSeq: 98 }),
+    branch: async () => ({ newId: 'session-child', keptEvents: 42, parentSession: undefined }),
+    restore: async () => ({ restoredCount: 1, skipped: 0, range: { startSeq: 5, endSeq: 6 }, eventSeqs: [7, 8] }),
+    export: async () => ({ markdown: '# md' }),
+  }
+  createMessageOpsTool({ defineTool, ops: asyncOps, ctx: {} })
+  assert.ok(def, 'tool defined')
+  const outList = await def.execute({ action: 'list', sessionId: 'session-abc' })
+  assert.match(String(outList), /session session-abc/)
+  assert.doesNotMatch(String(outList), /failed:/)
+  const outBranch = await def.execute({ action: 'branch', sessionId: 'session-abc', upToSeq: 10 })
+  // 0.5.2 P2：branch 渲染读 keptEvents + parentSession（注入自入参），不再读不存在的 kept/parentId
+  assert.match(String(outBranch), /kept 42 event/)
+  assert.match(String(outBranch), /parent session-abc/)
+  const outRestore = await def.execute({ action: 'restore', sessionId: 'session-abc', seq: 6 })
+  assert.match(String(outRestore), /replayed 1 message/)
+  const outExport = await def.execute({ action: 'export', sessionId: 'session-abc' })
+  assert.equal(String(outExport), '# md')
+  // 同步抛出的 ops 仍走错误文案路径
+  const errTool = await (async () => {
+    let d2
+    createMessageOpsTool({ defineTool: (x) => { d2 = x }, ops: { list: () => { throw new Error('boom') } }, ctx: {} })
+    return d2.execute({ action: 'list', sessionId: 'session-abc' })
+  })()
+  assert.match(String(errTool), /list failed: boom/)
+})
+
+// ── 0.5.4 P0 回归：system/message 必须带正 turn/step（0.2.0 v4 准入收紧，
+//    缺字段 → 持久层 encodeEventBatch 未捕获 → **整个 dsh 进程 exit=1**）────
+test('applySurfaceReplace/applyRestore 附带正整数 turn/step（v4 准入）', async () => {
+  const { applySurfaceReplace, applyRestore, deriveTurnStep } = await import('../src/ops-core.js');
+  const appended = [];
+  const fakeSession = { append: (type, data, opts) => { appended.push({ type, data, opts }); return { seq: 999 }; } };
+  // 1) deriveTurnStep：尾部回溯 / 兜底
+  assert.deepEqual(deriveTurnStep([{ data: { turn: 7, step: 3 } }]), { turn: 7, step: 3 });
+  assert.deepEqual(deriveTurnStep([{ data: {} }, { data: { turn: 2, step: 5 } }]), { turn: 2, step: 5 });
+  assert.deepEqual(deriveTurnStep([]), { turn: 1, step: 1 });
+  assert.deepEqual(deriveTurnStep(undefined), { turn: 1, step: 1 });
+  // 2) revert/delete 通知
+  applySurfaceReplace(fakeSession, 10, 20, [10], '[消息回滚] x', { turn: 9, step: 4 });
+  assert.equal(appended[0].type, 'system/message');
+  assert.ok(appended[0].data.turn > 0 && Number.isInteger(appended[0].data.turn), 'data.turn 正整数');
+  assert.ok(appended[0].data.step > 0 && Number.isInteger(appended[0].data.step), 'data.step 正整数');
+  assert.ok(typeof appended[0].data.message.id === 'string' && appended[0].data.message.id.length > 0, 'message.id 非空字符串（v4 准入第 3 关）');
+  // 无坐标参数时兜底 1/1（调用方漏传不致崩）
+  applySurfaceReplace(fakeSession, 10, 20, [10], 'x2');
+  assert.ok(appended[1].data.turn >= 1 && appended[1].data.step >= 1);
+  // 3) restore 通知（plan.turnStep）
+  applyRestore(fakeSession, {
+    restoreSeq: 5, startSeq: 1, endSeq: 3, skipped: 0, turnStep: { turn: 12, step: 6 },
+    replayable: [{ type: 'user/message', role: 'user', text: 'hi' }],
+  });
+  const notice = appended[2];
+  assert.equal(notice.type, 'system/message');
+  assert.equal(notice.data.turn, 12);
+  assert.equal(notice.data.step, 6);
+});
+
+// 0.5.6 回归：空可重放区间 → 优雅停用而非 409（dock 死按钮修复）
+test('planRestore 空可重放区间返回空计划；applyRestore 发停用 notice', async () => {
+  const { planRestore, applyRestore } = await import('../src/ops-core.js');
+  // 事件流：startSeq..endSeq 内只有一条 tool 事件（非 user/assistant）
+  const events = [
+    { seq: 1, type: 'system/message', data: { turn: 1, step: 1, message: {} } },
+    { seq: 8, type: 'tool/result', data: { message: {} } },
+    { seq: 9, type: 'system/message', data: { turn: 1, step: 2, message: {} },
+      surfaceOp: { op: 'replace', startSeq: 8, endSeq: 8 } },
+  ];
+  const plan = planRestore(events, 9);
+  assert.equal(plan.replayable.length, 0, '无可重放');
+  assert.equal(plan.startSeq, 8);
+  const appended = [];
+  const fakeSession = { append: (type, data, opts) => { appended.push({ type, data, opts }); return { seq: 42 }; } };
+  const out = applyRestore(fakeSession, plan);
+  assert.equal(out.restoredCount, 0);
+  // notice 停用 + restoresSeq 指向标记（dock 由此移除该行）
+  assert.equal(appended.length, 1, '只发 notice');
+  assert.equal(appended[0].data.restoresSeq, 9);
+  assert.match(appended[0].data.message.content[0].text, /无可重放/);
+  assert.ok(appended[0].data.turn > 0 && appended[0].data.message.id, 'v4 准入字段齐');
+});
+
+// ── 0.5.7 磁盘路径回归：字段镜像引擎金标准 + 计划语义一致 ──────────────────
+test('磁盘计划/构建器：可见节点剔除遮蔽、marker 字段逐项镜像金标准', async () => {
+  const core = await import('../src/ops-core.js');
+  // 事件流：user10 → assistant11 → step/end12（非节点）→ 既有标记 13 遮蔽 11
+  const events = [
+    { type: 'user/message', seq: 10, data: { message: { role: 'user', content: [] } } },
+    { type: 'assistant/message', seq: 11, data: { message: { role: 'assistant', content: [] } } },
+    { type: 'step/end', seq: 12, data: {} },
+    { type: 'system/message', seq: 13, data: { turn: 1, step: 1, message: {} },
+      surfaceOp: { op: 'replace', startSeq: 11, endSeq: 11 }, sourceEventSeqs: [11] },
+    { type: 'user/message', seq: 14, data: { message: { role: 'user', content: [] } } },
+  ];
+  // 可见节点 = [10, 14]（11 已遮蔽；12 非 message；13 是标记本身也是 system 可见）
+  const nodes = core.diskVisibleNodes(events);
+  assert.deepEqual(nodes, [10, 13, 14], '剔除遮蔽 + 只取 message 类: ' + JSON.stringify(nodes));
+  // revert at 14 → 遮蔽 [14]（末尾）
+  const plan = core.planRevertFromEvents(events, 14);
+  assert.deepEqual(plan.shadowedSeqs, [14]);
+  assert.equal(plan.endSeq, 14);
+  // revert at 10 → 遮蔽 [10, 13, 14]
+  const plan2 = core.planRevertFromEvents(events, 10);
+  assert.deepEqual(plan2.shadowedSeqs, [10, 13, 14]);
+  // 不可见 seq → 409
+  assert.throws(() => core.planRevertFromEvents(events, 11), (e) => e.status === 409);
+  // nextSeq
+  assert.equal(core.nextSeqFrom(events), 15);
+  // marker 构建器字段镜像（对照引擎金标准形状）
+  const ev = core.buildMarkerEvent({
+    seq: 15, time: 1791105740958, turnStep: { turn: 9, step: 6 }, text: 'x',
+    startSeq: 14, endSeq: 14, shadowedSeqs: [14],
+  });
+  assert.deepEqual(Object.keys(ev), ['type', 'seq', 'time', 'data', 'sourceEventSeqs', 'surfaceOp'], '根键序镜像');
+  assert.equal(ev.type, 'system/message');
+  assert.equal(ev.data.turn, 9);
+  assert.equal(ev.data.step, 6);
+  assert.ok(ev.data.message.id.length > 0);
+  assert.equal(ev.data.message.role, 'system');
+  assert.deepEqual(ev.data.message.content[0], { type: 'text', text: 'x' });
+  assert.deepEqual(ev.sourceEventSeqs, [14]);
+  assert.deepEqual(ev.surfaceOp, { op: 'replace', startSeq: 14, endSeq: 14 });
+  assert.equal(Object.keys(ev.surfaceOp).length, 3, 'replace op 恰好 3 键（引擎 isReplaceOp）');
+  // restore notice + replay 镜像
+  const nt = core.buildRestoreNoticeEvent({ seq: 16, time: 2, turnStep: { turn: 9, step: 6 }, text: 'n', restoreSeq: 13 });
+  assert.equal(nt.surfaceOp, 'append');
+  assert.equal(nt.data.restoresSeq, 13);
+  const rp = core.buildReplayEvent({ seq: 17, time: 3, item: { type: 'user/message', role: 'user', text: 'hi' } });
+  assert.equal(rp.surfaceOp, 'append');
+  assert.deepEqual(rp.data.message, { role: 'user', content: [{ type: 'text', text: '[恢复] hi' }] });
+  assert.ok(!('id' in rp.data.message), '重放镜像引擎：不带 id');
+});