@240xu/dsh-message-ops 0.5.2 → 0.5.8

package/README.md

@@ -262,3 +262,55 @@ MIT
   同步抛出也落进 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.2",
+  "version": "0.5.8",
   "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

@@ -415,6 +415,11 @@ window.__ModuleLoader__.load({
             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('')

package/src/index.js

@@ -20,9 +20,11 @@
  * @module dsh-message-ops
  */
 
+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);
+      }
     }
-  } catch { /* registry absent: treat as idle */ }
-  return false;
+    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;
+    }
+  } 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,39 @@ 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 baseTime = Date.now();
+  const batch = [buildRestoreNoticeEvent({
+    seq: cursor++, time: baseTime, turnStep: plan.turnStep,
+    text: restoreNoticeText(plan), restoreSeq: plan.restoreSeq,
+  })];
+  let offset = 0;
+  for (const item of plan.replayable) {
+    batch.push(buildReplayEvent({ seq: cursor++, time: baseTime + (++offset), 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) {
@@ -332,6 +511,15 @@ 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({
@@ -382,7 +570,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 被调用', () => {
@@ -251,3 +253,109 @@ test('工具 execute：async ops 被 await（list/branch/restore/export 全路
   })()
   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');
+});