dsh-rewind-plugin 0.2.4 → 0.2.6

package/README.md

@@ -4,7 +4,7 @@
 
 In-place conversation rewind for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): the Claude Code `/rewind` semantics inside the **same session window** — cut the model context back to an earlier user message, and optionally restore workspace files from **disk-persisted before-backups**.
 
-> **Status:** published to npm (`dsh-rewind-plugin`, v0.2.4) via GitHub Actions Trusted Publishing + Sigstore provenance. Targets the web profile (`dsh --profile web`). Interaction mirrors Claude Code's rewind, adapted to dsh's real web UI.
+> **Status:** published to npm (`dsh-rewind-plugin`, v0.2.6) via GitHub Actions Trusted Publishing + Sigstore provenance. Targets the web profile (`dsh --profile web`). Interaction mirrors Claude Code's rewind, adapted to dsh's real web UI.
 
 [![npm version](https://img.shields.io/npm/v/dsh-rewind-plugin.svg)](https://www.npmjs.com/package/dsh-rewind-plugin)
 [![npm license](https://img.shields.io/npm/l/dsh-rewind-plugin.svg)](https://github.com/SiriLee/dsh-rewind/blob/main/LICENSE)
@@ -61,6 +61,7 @@ The plugin appends an **empty-content marker** `assistant/message` into the sess
 
 - The marker carries `sourceEventSeqs` covering every shadowed node, and the `Session.append` surface rules validate the cut (only a contiguous range on the current surface).
 - Because the marker is **empty**, the harness derives it to `null` — it never enters the model context and never renders as conversation content. The agent and the user both see the conversation exactly as it was at the target.
+- The marker's **turn number reuses the LAST STARTED turn** (`markerTurnOf`), never `lastTurn + 1`: the harness's agent loop numbers its next real turn exactly `last turn/start + 1`, so a marker numbered the same way would leave an `assistant/message` BEFORE the `turn/start` of the same turn — the client conversation-context builder rejects that ordering with `conversation Context …:turn-tail… received an update before its start Match`, history load fails, and the whole conversation disappears from the UI (the real defect in ≤ 0.2.4, fixed in 0.2.5). Reusing an already-consumed turn makes the marker a harmless trailing update on the previous completed turn's tail — it can never collide with a future turn.
 - The append-only log is **untouched** — the audit trail keeps every withdrawn event; only the model-visible surface is cut, so the next request derives its context from the target onward.
 
 A running turn (LLM thinking / streaming) is force-stopped first (`cancel({ kind: 'user' })`) and the rewind waits for quiescence; if it can't stop, the rewind is aborted with an error.
@@ -76,6 +77,38 @@ The plugin tracks the write-class tools — `write`, `edit`, `str_replace_editor
 
 Backups persist across host restarts, bounded to the newest 100 anchor groups per session.
 
+## 🔧 Troubleshooting: history load failure (`…turn-tail… received an update before its start Match`)
+
+Versions ≤ 0.2.4 corrupted client replay when a rewind was **followed by further
+conversation**: the marker's turn number collided with the next real turn's
+`turn/start`, so reopening the session showed
+`Failed to load history: conversation Context …:turn-tail… received an update before its start Match (internal)`
+and the history vanished. Rewinds created from 0.2.5 on no longer produce the
+collision, but **already-corrupted sessions need an offline repair** (the log is
+append-only — it cannot be rewritten in memory).
+
+The repair tool ships **inside the npm package** (`dsh-rewind-repair`) — no
+source checkout needed:
+
+```sh
+# 1. Fully quit dsh web / host first (while a session is resident in memory,
+#    a disk repair is overwritten by the next checkpoint)
+# 2. Run the offline repair (scans every session under ~/.dsh/sessions,
+#    rewriting each marker's turn back to the last started turn)
+npm exec --yes --package=dsh-rewind-plugin -- dsh-rewind-repair
+npm exec --yes --package=dsh-rewind-plugin -- dsh-rewind-repair -- --dry-run  # preview only
+# 3. Restart dsh web — the repaired sessions load their history again
+```
+
+Or install it globally once (`npm i -g dsh-rewind-plugin`) and run
+`dsh-rewind-repair` directly; from a source checkout the same tool is
+`node scripts/repair-markers.mjs` (identical flags).
+
+The tool only rewrites the `data.turn` of `dsh-rewind` empty-marker events
+(keeping seqs, order, and the zstd frame structure intact), backs up the original
+file to `session.jsonl.zstd.bak-<timestamp>` before writing, and never touches
+any other event — safe to run repeatedly.
+
 ## 📦 Install
 
 Published to npm — the registry path is the recommended one. **Restart dsh web (`--profile web`) after installing.**

package/README.zh.md

@@ -4,7 +4,7 @@
 
 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件：**同一会话窗口的 in-place 对话回退**（Claude Code `/rewind` 语义）——把模型上下文剪回更早的一条用户消息，并可基于**落盘的写前备份**还原工作区文件。
 
-> **状态**：已发布 npm（`dsh-rewind-plugin`，v0.2.4），经 GitHub Actions Trusted Publishing + Sigstore provenance 构建发布。目标为 web 配置档（`dsh --profile web`）。交互以 Claude Code 的 rewind 为参考，并贴合 dsh Web 实际 UI。
+> **状态**：已发布 npm（`dsh-rewind-plugin`，v0.2.6），经 GitHub Actions Trusted Publishing + Sigstore provenance 构建发布。目标为 web 配置档（`dsh --profile web`）。交互以 Claude Code 的 rewind 为参考，并贴合 dsh Web 实际 UI。
 
 [![npm version](https://img.shields.io/npm/v/dsh-rewind-plugin.svg)](https://www.npmjs.com/package/dsh-rewind-plugin)
 [![npm license](https://img.shields.io/npm/l/dsh-rewind-plugin.svg)](https://github.com/SiriLee/dsh-rewind/blob/main/LICENSE)
@@ -61,6 +61,7 @@
 
 - 标记携带 `sourceEventSeqs` 覆盖所有被遮蔽节点，`Session.append` 的 surface 规则校验切割合法性（仅限当前 surface 上的连续区间）。
 - 因为标记**内容为空**，harness 会将其派生为 `null`——永不进入模型上下文、也永不渲染成对话内容。agent 与用户看到的对话都回到目标消息当时的样子。
+- 标记的 **turn 号复用最后一个已开始的回合**（`markerTurnOf`），而不是「最后回合 + 1」：harness 的 agent loop 恰好用 `最后 turn/start + 1` 编号下一条真实回合。若标记也取这个数，日志里就会出现同一 turn 的 `assistant/message` 先于 `turn/start` 的乱序，客户端 conversation 构建器会以 `conversation Context …:turn-tail… received an update before its start Match` 拒绝重放——历史加载失败、整个对话从界面消失（0.2.4 及之前的真实缺陷，已在 0.2.5 修复）。复用已消费的 turn 号则标记只是上一个已完成回合尾部的一次无害追加，永不与新回合冲突。
 - append-only 日志**不被改写**——审计轨迹完整保留每条被撤回的事件，只有模型可见的 surface 被剪掉，下一条请求从目标消息起派生上下文。
 
 若 agent 正在运行（LLM 思考/流式输出），会先强制停止（`cancel({ kind: 'user' })`）并等待 quiescence 再回退；停不下来则中止并报错。
@@ -76,6 +77,30 @@
 
 备份跨 host 重启持久化，每会话有界保留最近 100 组锚点。
 
+## 🔧 故障修复：历史加载失败（`…turn-tail… received an update before its start Match`）
+
+0.2.4 及之前版本在回退**之后继续对话**的场景下会损坏会话的客户端重放：标记的 turn 号
+与下一条真实回合的 `turn/start` 编号冲突，重新打开会话时界面报
+`历史加载失败：conversation Context …:turn-tail… received an update before its start Match（internal）`，
+历史整段消失。0.2.5 起新的回退不再产生该冲突；但**已损坏的会话需要离线修复**（日志是
+append-only 的，不能在内存中改写）。
+
+修复工具**已随 npm 包发布**（`dsh-rewind-repair`）——无需下载源码：
+
+```sh
+# 1. 先完全退出 dsh web / host（会话处于驻留内存时，磁盘修复会被下次 checkpoint 覆盖）
+# 2. 运行离线修复（扫描 ~/.dsh/sessions 下所有会话，把标记 turn 改回最后一个已开始的回合）
+npm exec --yes --package=dsh-rewind-plugin -- dsh-rewind-repair
+npm exec --yes --package=dsh-rewind-plugin -- dsh-rewind-repair -- --dry-run  # 只预览不写盘
+# 3. 重启 dsh web，损坏的会话即可正常加载历史
+```
+
+也可以全局安装一次（`npm i -g dsh-rewind-plugin`）后直接运行 `dsh-rewind-repair`；
+源码方式为 `node scripts/repair-markers.mjs`（参数相同）。
+
+工具只改写 `dsh-rewind` 空标记事件的 `data.turn` 字段（保持 seq / 顺序 / zstd 帧结构不变），
+改前自动备份原文件为 `session.jsonl.zstd.bak-<时间戳>`；不改动任何其它事件，可安全重复运行。
+
 ## 📦 安装
 
 已发布 npm——推荐走 registry 路径。**装完重启 dsh web（`--profile web`）。**

package/lib/client.js

@@ -586,7 +586,20 @@ function apply(ctx) {
           hidden.delete(seat);
         }
       }
-      if (session !== void 0) fillComposerForRewind(session, filledTargets);
+      if (session !== void 0) {
+        const snap = session.getSnapshot();
+        if (!fillBaselineTaken && snap.chat.order.length > 0) {
+          fillBaselineTaken = true;
+          for (const key of snap.chat.order) {
+            const node = snap.chat.nodes.get(key);
+            if (node?.kind === "command") {
+              const command = node.data;
+              if (command.seq > fillBaselineSeq) fillBaselineSeq = command.seq;
+            }
+          }
+        }
+        fillComposerForRewind(session, filledTargets);
+      }
       if (hiddenSeqs.size > 0 || hiddenCount > 0) {
         console.info(
           `[dsh-rewind] hiding: ${hiddenCount} rows, seqs [${[...hiddenSeqs].slice(0, 20).join(", ")}${hiddenSeqs.size > 20 ? "\u2026" : ""}]`
@@ -597,6 +610,8 @@ function apply(ctx) {
       }
     };
     const filledTargets = /* @__PURE__ */ new Set();
+    let fillBaselineSeq = -1;
+    let fillBaselineTaken = false;
     const fillComposerForRewind = (session, filled) => {
       const snap = session.getSnapshot();
       for (const key of snap.chat.order) {
@@ -604,6 +619,7 @@ function apply(ctx) {
         if (node === void 0 || node.kind !== "command") continue;
         const command = node.data;
         if (command.name !== "rewind" || command.outcome?.kind !== "success") continue;
+        if (command.seq <= fillBaselineSeq) continue;
         if (command.outcome.sourceEventSeq === void 0) continue;
         const target = targetOfOutcome(command.outcome.text);
         if (target === void 0 || filled.has(target)) continue;

package/lib/index.js

@@ -12,6 +12,15 @@ var RewindError = class extends Error {
   code;
 };
 var CANDIDATE_PREVIEW_CHARS = 80;
+function markerTurnOf(events) {
+  let lastStarted = 0;
+  for (const event of events) {
+    if (event.type === "turn/start" && event.data.turn > lastStarted) {
+      lastStarted = event.data.turn;
+    }
+  }
+  return lastStarted;
+}
 function isUserMessageEvent(event) {
   return event.type === "user/message";
 }
@@ -364,15 +373,6 @@ function buildMarker() {
     source: { provider: "dsh-rewind", model: "rewind-marker" }
   });
 }
-function nextTurnOf(session) {
-  let max = -1;
-  for (const event of session.events) {
-    if (event.type === "turn/start" || event.type === "turn/end" || event.type === "assistant/message") {
-      if (event.data.turn > max) max = event.data.turn;
-    }
-  }
-  return max + 1;
-}
 function describeTarget(target) {
   return target.kind === "seq" ? `seq ${target.seq}` : `\u7B2C ${target.index} \u6761\u6D88\u606F`;
 }
@@ -427,7 +427,7 @@ async function executeRewind(ctx, store, invocation, rawTarget, mode) {
   const marker = buildMarker();
   let event;
   try {
-    event = agent.session.append("assistant/message", { turn: nextTurnOf(agent.session), step: 0, message: marker }, {
+    event = agent.session.append("assistant/message", { turn: markerTurnOf(agent.session.events), step: 0, message: marker }, {
       surfaceOp: { op: "replace", start: plan.surfaceStart, end: plan.surfaceEnd },
       sourceEventSeqs: [...plan.shadowedSeqs]
     });

package/lib/types/rewind.d.ts

@@ -60,6 +60,29 @@ export interface RewindPlan {
 }
 /** Preview length cap for candidate listings. */
 export declare const CANDIDATE_PREVIEW_CHARS = 80;
+/**
+ * Turn number for the rewind marker.
+ *
+ * The marker MUST NOT reuse the harness's next-turn number. The agent loop
+ * numbers its next real turn `lastTurn/start + 1` (dsh-agent-loop), so a
+ * marker numbered `maxTurn + 1` collides: the log then holds an
+ * `assistant/message` (the marker) BEFORE the `turn/start` of the same turn,
+ * and the client conversation-context builder rejects that ordering with
+ * `conversation Context …:turn-tail… received an update before its start
+ * Match` — history load fails and the whole conversation disappears from the
+ * UI (reproduced across real sessions).
+ *
+ * The marker therefore reuses the LAST STARTED turn's number: the harness has
+ * already consumed it (its next turn is strictly larger), so it can never be
+ * reused by a future `turn/start`, and the marker lands as a harmless
+ * trailing update on that turn's already-closed tail context (its `turn/end`
+ * is already matched) — no new context, no reordering, nothing rendered, and
+ * the empty content still derives to `null` in the model context.
+ *
+ * @param events - the full session event log.
+ * @returns a turn number the harness can never reuse for a future `turn/start`.
+ */
+export declare function markerTurnOf(events: readonly SessionEvent[]): number;
 /** Narrow an event to a user message. */
 export declare function isUserMessageEvent(event: SessionEvent): event is SessionEvent<'user/message'>;
 /** Join the text blocks of a message into one plain string. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-rewind-plugin",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "DeepSeek Harness plugin: in-place conversation rewind in the same session window (Claude Code /rewind semantics) with optional workspace file restore",
   "keywords": [
     "deepseek-harness",
@@ -23,6 +23,9 @@
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
+  "bin": {
+    "dsh-rewind-repair": "scripts/repair-markers.mjs"
+  },
   "exports": {
     ".": {
       "types": "./lib/types/index.d.ts",
@@ -41,7 +44,8 @@
     "README.zh.md",
     "docs",
     "assets",
-    "LICENSE"
+    "LICENSE",
+    "scripts/repair-markers.mjs"
   ],
   "dsh": {
     "bundle": {

package/scripts/repair-markers.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * Offline repair for sessions corrupted by the ≤ 0.2.4 marker turn-number bug.
+ *
+ * Symptom: reopening a session shows
+ *   Failed to load history: conversation Context …:turn-tail… received an
+ *   update before its start Match (internal)
+ * and the history disappears. Root cause: the rewind marker was numbered
+ * `lastTurn + 1`, which is exactly how the harness numbers its NEXT real turn —
+ * so the log holds an `assistant/message` (the marker) BEFORE the `turn/start`
+ * of the same turn, and the client conversation-context builder rejects that
+ * ordering.
+ *
+ * This script rewrites ONLY the `data.turn` of `dsh-rewind` empty-marker events
+ * to the last turn/start that precedes them (a turn the harness has already
+ * consumed and can never reuse). It preserves:
+ *   - every other event byte-for-byte (seqs, times, surface metadata, …),
+ *   - the JSONL record order and line structure,
+ *   - the zstd multi-frame structure the persistence backend expects
+ *     (each frame is decoded, fixed, and re-compressed independently, with the
+ *     "last started turn" state threaded across frames).
+ *
+ * The original file is backed up to `session.jsonl.zstd.bak-<timestamp>` before
+ * the first write. Run with the host fully stopped (a resident session would
+ * overwrite the repaired file at its next checkpoint), then restart dsh web.
+ *
+ * Usage:
+ *   node scripts/repair-markers.mjs            # scan ~/.dsh/sessions
+ *   node scripts/repair-markers.mjs --dry-run  # report only, no writes
+ *   node scripts/repair-markers.mjs --dir <sessions root>
+ */
+
+import { readdirSync, readFileSync, writeFileSync, copyFileSync, statSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { zstdCompressSync, zstdDecompressSync } from 'node:zlib'
+
+const ZSTD_MAGIC = 0xfd2fb528
+const MARKER_SOURCE = { provider: 'dsh-rewind', model: 'rewind-marker' }
+const DEFAULT_ROOT = join(homedir(), '.dsh', 'sessions')
+
+/** @param {Buffer} buffer @returns {{start:number,end:number}[]} */
+function scanFrames(buffer) {
+  const frames = []
+  let offset = 0
+  while (offset < buffer.length) {
+    const start = offset
+    if (buffer.length - offset < 4 || buffer.readUInt32LE(offset) !== ZSTD_MAGIC) break
+    offset += 4
+    const next = buffer.indexOf(Buffer.from([0x28, 0xb5, 0x2f, 0xfd]), offset)
+    frames.push(next === -1 ? { start, end: buffer.length } : { start, end: next })
+    offset = next === -1 ? buffer.length : next
+  }
+  return frames
+}
+
+/**
+ * Rewrite marker turn numbers in ONE frame's JSONL text. Line-preserving: the
+ * fix never adds or removes lines, only rewrites a marker line's turn. State
+ * (`lastStarted`) is threaded across frames, because a marker in a later frame
+ * must know the turn/start events of earlier frames.
+ * @param {string} text - this frame's JSONL text.
+ * @param {{lastStarted:number}} state - running "last started turn" state.
+ * @returns {{text:string, changed:number}} the fixed text (identical when
+ *   nothing changed) and the number of rewritten markers in this frame.
+ */
+function fixMarkerTurns(text, state) {
+  const lines = text.split('\n')
+  let changed = 0
+  const out = []
+  for (const line of lines) {
+    if (line.trim() === '') {
+      out.push(line)
+      continue
+    }
+    let record
+    try {
+      record = JSON.parse(line)
+    } catch {
+      out.push(line) // keep unknown/torn lines verbatim
+      continue
+    }
+    if (record && record.type === 'turn/start' && Number.isSafeInteger(record.data?.turn)) {
+      if (record.data.turn > state.lastStarted) state.lastStarted = record.data.turn
+      out.push(line)
+      continue
+    }
+    const isMarker =
+      record?.type === 'assistant/message' &&
+      record.data?.message?.source?.provider === MARKER_SOURCE.provider &&
+      record.data?.message?.source?.model === MARKER_SOURCE.model
+    if (!isMarker) {
+      out.push(line)
+      continue
+    }
+    const badTurn = record.data.turn
+    if (badTurn === state.lastStarted) {
+      out.push(line) // already safe (post-0.2.5 marker) — idempotent
+      continue
+    }
+    changed += 1
+    out.push(JSON.stringify({ ...record, data: { ...record.data, turn: state.lastStarted } }))
+  }
+  return { text: out.join('\n'), changed }
+}
+
+/** Repair one session artifact file. @returns {string} a human summary line. */
+function repairFile(file, dryRun) {
+  const original = readFileSync(file)
+  const frames = scanFrames(original)
+  const state = { lastStarted: 0 }
+  const fixedTexts = []
+  let changed = 0
+  for (const frame of frames) {
+    const frameText = zstdDecompressSync(original.subarray(frame.start, frame.end)).toString('utf8')
+    const result = fixMarkerTurns(frameText, state)
+    changed += result.changed
+    fixedTexts.push(result.text)
+  }
+  if (changed === 0) return `  ok (no marker fix needed): ${file}`
+  if (dryRun) return `  would fix ${changed} marker(s): ${file}`
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+  copyFileSync(file, `${file}.bak-${stamp}`)
+  // Preserve the zstd frame structure: one re-compressed frame per original
+  // frame, in order.
+  writeFileSync(file, Buffer.concat(fixedTexts.map(text => zstdCompressSync(Buffer.from(text)))))
+  return `  fixed ${changed} marker(s): ${file} (backup: ${file}.bak-${stamp})`
+}
+
+function collectSessions(root) {
+  const files = []
+  for (const project of readdirSync(root)) {
+    const projectDir = join(root, project)
+    let stat
+    try {
+      stat = statSync(projectDir)
+    } catch {
+      continue
+    }
+    if (!stat.isDirectory()) continue
+    for (const entry of readdirSync(projectDir)) {
+      const file = join(projectDir, entry, 'session.jsonl.zstd')
+      if (existsSync(file)) files.push(file)
+    }
+  }
+  return files
+}
+
+const args = process.argv.slice(2)
+const dryRun = args.includes('--dry-run')
+const dirIndex = args.indexOf('--dir')
+const root = dirIndex !== -1 && args[dirIndex + 1] !== undefined ? args[dirIndex + 1] : DEFAULT_ROOT
+
+if (!existsSync(root)) {
+  console.error(`sessions root not found: ${root}`)
+  process.exit(1)
+}
+
+console.log(`${dryRun ? '[dry-run] ' : ''}scanning ${root}`)
+const files = collectSessions(root)
+console.log(`${files.length} session artifact(s) found`)
+let fixedCount = 0
+for (const file of files) {
+  try {
+    const line = repairFile(file, dryRun)
+    if (!line.includes('no marker fix needed')) {
+      console.log(line)
+      fixedCount += 1
+    }
+  } catch (error) {
+    console.error(`  ERROR ${file}: ${error instanceof Error ? error.message : String(error)}`)
+  }
+}
+console.log(fixedCount === 0
+  ? 'no corrupted sessions found — nothing to do'
+  : `${dryRun ? 'would repair' : 'repaired'} ${fixedCount} session(s). ${dryRun ? '' : 'Restart dsh web to reload the repaired histories.'}`)