dsh-rewind-plugin 0.2.5 → 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.5) 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)
@@ -85,20 +85,26 @@ conversation**: the marker's turn number collided with the next real turn's
 `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):
+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 script (scans every session under ~/.dsh/sessions,
+# 2. Run the offline repair (scans every session under ~/.dsh/sessions,
 #    rewriting each marker's turn back to the last started turn)
-node scripts/repair-markers.mjs            # default: scan ~/.dsh/sessions
-node scripts/repair-markers.mjs --dry-run  # report only, no writes
-node scripts/repair-markers.mjs --dir <sessions root>  # custom data dir
+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
 ```
 
-The script only rewrites the `data.turn` of `dsh-rewind` empty-marker events
+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.

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.5），经 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)
@@ -83,18 +83,22 @@
 与下一条真实回合的 `turn/start` 编号冲突，重新打开会话时界面报
 `历史加载失败：conversation Context …:turn-tail… received an update before its start Match（internal）`，
 历史整段消失。0.2.5 起新的回退不再产生该冲突；但**已损坏的会话需要离线修复**（日志是
-append-only 的，不能在内存中改写）：
+append-only 的，不能在内存中改写）。
+
+修复工具**已随 npm 包发布**（`dsh-rewind-repair`）——无需下载源码：
 
 ```sh
 # 1. 先完全退出 dsh web / host（会话处于驻留内存时，磁盘修复会被下次 checkpoint 覆盖）
-# 2. 运行离线修复脚本（扫描 ~/.dsh/sessions 下所有会话，把标记 turn 改回最后一个已开始的回合）
-node scripts/repair-markers.mjs            # 默认扫描 ~/.dsh/sessions
-node scripts/repair-markers.mjs --dry-run  # 只报告不写盘
-node scripts/repair-markers.mjs --dir <sessions 根目录>  # 指定数据目录
+# 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，损坏的会话即可正常加载历史
 ```
 
-脚本只改写 `dsh-rewind` 空标记事件的 `data.turn` 字段（保持 seq / 顺序 / 帧结构不变），
+也可以全局安装一次（`npm i -g dsh-rewind-plugin`）后直接运行 `dsh-rewind-repair`；
+源码方式为 `node scripts/repair-markers.mjs`（参数相同）。
+
+工具只改写 `dsh-rewind` 空标记事件的 `data.turn` 字段（保持 seq / 顺序 / zstd 帧结构不变），
 改前自动备份原文件为 `session.jsonl.zstd.bak-<时间戳>`；不改动任何其它事件，可安全重复运行。
 
 ## 📦 安装

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-rewind-plugin",
-  "version": "0.2.5",
+  "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.'}`)