dsh-rewind-plugin 0.2.7 → 0.2.8

package/README.md

@@ -1,46 +1,26 @@
 # dsh-rewind
 
-[简体中文](README.zh.md)
-
-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.7) 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.
->
-> **v0.2.7 highlights:** composer refill is event-driven (reopening a session never resurrects withdrawn text); subagent edits are not tracked (Claude Code alignment); concurrent rewinds are guarded; the code-restore option appears only when tracked changes exist (mixed host/client versions safe).
+In-place conversation rewind for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): Claude Code's `/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.
 
 [![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)
 
-## Table of contents
-
-- [✨ Features](#-features)
-- [📸 Screenshots](#-screenshots)
-- [How it works](#how-it-works)
-- [📦 Install](#-install)
-- [Usage](#usage)
-- [Behavior details & limitations](#behavior-details--limitations)
-- [Not included](#not-included)
-- [Compatibility](#compatibility)
-- [Development](#development)
-- [Publishing](#publishing)
-- [Directory layout](#directory-layout)
-- [License](#license)
-
-## ✨ Features
-
-| Feature | Description |
-| --- | --- |
-| In-place rewind | Rewind to **any** user message from a per-message ↶ button: the target message and everything after it (agent replies, tool calls) are withdrawn from the model context *and* the rendered transcript — no new session, no window switch |
-| Time-travel semantics | Rewinding to a message withdraws **that message too**; its text is offered back in the composer so you can edit and re-send it |
-| Claude-Code-style file restore | Write-class edits are backed up **before** they happen and persisted on disk; "conversation and code" restores files to their pre-edit content and deletes files created after the target |
-| Impact preview | "Conversation and code" first shows the exact restore / delete list for confirmation (the option is hidden when there are no tracked changes — like Claude Code's code-restore visibility) |
-| Approval-plugin coexistence | Capture runs at the `tools/execute` around-dispatch stage, so another plugin's pre-execute approval short-circuit (e.g. dsh-edit-approval) cannot skip the backup, and a denied call never records |
-| Paths resolved by session cwd | Relative paths are backed up and restored against the **real** file using the fs-tools session-cwd rule; the resolved display path is what gets recorded |
-| Restores write real files | Restore goes through plain `node:fs` directly to the filesystem; symbolic and hard links are skipped with a warning (no clobber through a shared inode) |
-| Survives host restart | Backups live on disk under `~/.dsh/rewind-snapshots/<session>/<anchor seq>/`, newest 100 message groups per session |
-| Localized | `zh` / `en` copy registered into the dsh locale system |
-
-## 📸 Screenshots
+> English | [中文](README.zh.md)
+
+A deliberately focused plugin with one job: rewind to any earlier user message, in place.
+
+| Mode | Conversation | Workspace files |
+| --- | --- | --- |
+| **Rewind conversation only** | Cut back to the target message | Untouched |
+| **Rewind conversation and code** | Cut back to the target message | Restored to their state before it (modified files written back, later-created files deleted) |
+
+Rewinding is time-travel: the target message and everything after it (agent replies, tool calls) are withdrawn from the model context *and* the rendered transcript — no new session, no window switch — and the target's text is offered back in the composer so you can edit and re-send it.
+
+The plugin never rewrites the append-only session log and never touches your git repository.
+
+## Preview
+
+Each user message gains a compact **↶ rewind** action in its action row. Clicking it opens a mode-selection popover; "conversation and code" first shows the exact restore / delete list for confirmation (the option is hidden when there are no tracked changes — like Claude Code's code-restore visibility).
 
 <table>
   <tr>
@@ -53,132 +33,78 @@ In-place conversation rewind for [DeepSeek Harness](https://github.com/deepseek-
   </tr>
 </table>
 
-## How it works
-
-Two halves work together: the **conversation rewind** (in-place, same window) and the **checkpoint file restore** (Claude-Code-style before-backups).
+Manual `/rewind` input in the composer is intercepted — submitting shows a transient hint pointing at the ↶ button.
 
-### 1. Conversation rewind
-
-The plugin appends an **empty-content marker** `assistant/message` into the session log whose `surfaceOp: { op: 'replace', start, end }` replaces every surface node after the target message with the marker:
-
-- 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.
-
-### 2. Checkpoint file restore
-
-The plugin tracks the write-class tools — `write`, `edit`, `str_replace_editor` (mutating commands `create` / `str_replace` / `insert`):
-
-1. **Before-capture** at `tools/execute` (the around-dispatch stage): the target file is read and the resolved path + content are held in a pending map. This stage only runs after any pre-execute approval gate let the call through — so an `ask` short-circuit (dsh-edit-approval) **cannot skip** the backup, and a denied call never records.
-2. **Disk commit** at `tools/post-execute`: the before-backup is written under the turn's **anchor message seq** (`~/.dsh/rewind-snapshots/<session>/<anchor seq>/<callId>.json`).
-3. **Restore** (`/rewind @<seq> both`): every backup anchored at or after the target applies — modified files are written back to their **earliest** captured before-state, files created after the target are deleted, symbolic / hard links are skipped. Writes go through plain `node:fs`, independent of the fs service.
-4. A failed tool body that **throws** skips `tools/post-execute`; a `tools/result` safety net clears the pending capture so nothing leaks in memory.
-
-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:
+## Install
 
 ```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
+dsh plugin --profile web add dsh-rewind-plugin
 ```
 
-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).
+Restart `dsh web` (`--profile web`) after installing.
 
-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.
+> ⚠️ The npm name `dsh-rewind` belongs to another author's package — install with `dsh-rewind-plugin`.
 
-## 📦 Install
+From a local checkout or a pinned GitHub commit:
 
-Published to npm — the registry path is the recommended one. **Restart dsh web (`--profile web`) after installing.**
+```sh
+dsh plugin --profile web add /path/to/dsh-rewind              # local checkout
+dsh plugin --profile web add github:SiriLee/dsh-rewind#<sha>  # pinned commit
+```
 
-> ⚠️ Note: the npm name `dsh-rewind` belongs to another author's package — install with `dsh-rewind-plugin`.
+A git install fails on first run: pnpm blocks git dependencies from running build scripts. Follow the CLI hint to add an `allowBuilds` key to the profile's `pnpm-workspace.yaml`, then retry — pnpm runs the plugin's `prepare` (full build) and installs it.
 
-### Option A: registry (recommended)
+## Usage
 
-```sh
-dsh plugin --profile web add dsh-rewind-plugin
-```
+1. **Hover** any user message you sent — a **↶ rewind** button appears in its action row.
+2. **Click it.** The target is that message; a small popover offers the two modes ("conversation and code" is hidden when no tracked file changes exist after the target).
+3. The rewind executes as an in-session command; a result message confirms, and the withdrawn message's text is filled back into the composer for editing and re-sending.
 
-### Option B: local checkout (authors / contributors)
+The ↶ button appears on user messages rendered in the **current session view** — switch to another session before rewinding it. A rewind can itself be rewound (its marker enters the log), but the file-restore action is not re-backed up.
 
-```sh
-cd dsh-rewind
-npm install      # devDeps come from the npm registry; no harness checkout needed
-npm run build    # full build: lib/ (host ESM + client bundle + .d.ts)
-dsh plugin --profile web add /path/to/dsh-rewind   # link install
-```
+## How it works
 
-### Option C: GitHub (pin a commit for reproducibility)
+### 1. Conversation rewind (in-place)
 
-```sh
-dsh plugin --profile web add github:SiriLee/dsh-rewind#<commit-sha>
-```
+The plugin appends an **empty-content marker** `assistant/message` into the session log whose `surfaceOp: { op: 'replace', start, end }` replaces every surface node after the target message with the marker:
 
-First run fails: pnpm blocks git dependencies from running build scripts. Follow
-the CLI hint to add an `allowBuilds` key to the profile's `pnpm-workspace.yaml`
-(e.g. `$DSH_HOME/profiles/web/pnpm-workspace.yaml`), then retry. pnpm then runs
-the plugin's `prepare` (full build) and installs it into the profile.
+- The marker carries `sourceEventSeqs` covering every shadowed node, and `Session.append`'s surface rules validate the cut (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. Agent and 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 numbers its next real turn exactly `last turn/start + 1`, so a `maxTurn + 1` marker would sit *before* that `turn/start` — the client conversation builder rejects the ordering (`…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** — every withdrawn event stays in the audit trail; only the model-visible surface is cut, so the next request derives its context from the target onward.
 
-## Usage
+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.
 
-### Rewind via the per-message button
+### 2. Checkpoint file restore
 
-1. **Hover** any user message you sent — a **↶ rewind** button appears in its action row.
-2. **Click it.** The target is that message (step one is done). A small popover opens (step two):
-   - **Rewind conversation only** — cut the model context back to before the message; workspace files stay untouched.
-   - **Rewind conversation and code** — same context cut, plus workspace files restored to their state before the message. An impact list (files to restore / delete) is shown first, then you confirm.
-   - The "conversation and code" option is **hidden** when no tracked file changes exist after the target (matching Claude Code's behavior).
-3. The rewind executes as an in-session command; a result message confirms (e.g. "已撤回 seq N 及之后内容；还原 M 个文件"), and the withdrawn message's text is filled back into the composer for editing and re-sending.
+The plugin tracks the write-class tools — `write`, `edit`, `str_replace_editor` (mutating commands `create` / `str_replace` / `insert`):
 
-### Rewinds are time-travel
+1. **Before-capture** at `tools/execute` (the around-dispatch stage): the target file is read; the resolved path + content are held in a pending map. This stage runs only after any pre-execute approval gate let the call through — an `ask` short-circuit (dsh-edit-approval) **cannot skip** the backup, and a denied call never records. If the read fails (e.g. a permission error), the change is simply not backed up — the plugin warns in the log but **does not block the write**.
+2. **Disk commit** at `tools/post-execute`: the before-backup is written under the turn's anchor message seq (`~/.dsh/rewind-snapshots/<session>/<anchor seq>/<callId>.json`).
+3. **Restore** (`/rewind @<seq> both`): every backup anchored at or after the target applies — modified files are written back to their **earliest** captured before-state, files created after the target are deleted, symbolic / hard links are skipped (they share an inode with another name; restoring through one would clobber both). Writes go through plain `node:fs`, independent of the fs service — under sandbox / remote backends, path resolution may be restricted.
+4. A tool body that **throws** skips `tools/post-execute`; a `tools/result` safety net clears the pending capture so nothing leaks in memory.
 
-Rewinding to a message **withdraws** it and everything after it — the transcript and the agent's context both return to before the message. The command result says so, and the message's text is offered back in the composer.
+Backups persist across host restarts, bounded to the newest 100 anchor groups per session.
 
-### Manual `/rewind` is blocked
+## What it deliberately does NOT do
 
-`/rewind` exists only as the button's internal channel. Typing `/rewind` (bare or with arguments) into the composer is **intercepted** — submitting shows a transient hint pointing at the ↶ button.
+- **Whole-tree / git-first snapshots** — only write-class tool edits are backed up. `bash`, other tools, and external edits are not tracked and cannot be restored: the same limitation as Claude Code, which defers such rollbacks to the user's git.
+- **Subagent edits** — not tracked (same as Claude Code): a subagent runs its own session, so its backups could never be restored by a rewind of the parent session.
+- **Fork / branch rewind and `/compact`** — the harness already provides these ("branch in new chat", compact).
+- **Keyboard shortcuts** (esc+esc rewind menu) — planned as a follow-up.
 
-## Behavior details & limitations
+## Comparison with similar projects
 
-- Only **write-class tools** running while the plugin is active are tracked (`write` / `edit` / `str_replace_editor`). Changes made by `bash`, other tools, or external programs are not backed up and cannot be restored — the same limitation as Claude Code, which also defers such rollbacks to the user's git.
-- **Subagent edits are not tracked** — same as Claude Code. A subagent runs its own session, so its backups could never be restored by a rewind of the parent session; the capture is skipped instead of recording to an unreachable store.
-- If a before-capture read fails (e.g. a permission error), that change is simply not backed up and a `both` rewind cannot restore it — the plugin logs a warning but **does not block the write**.
-- File restore/delete writes through the **real local filesystem**; under sandbox / remote backends path resolution may be restricted.
-- Symbolic links and hard links are not written through (they share the inode with another name; a restore would clobber both) — they are skipped and reported.
-- A rewind can itself be rewound (its marker enters the log), but the file-restore action is not re-backed up.
-- The ↶ button is injected on user messages rendered in the **current session view**; switch to another session before rewinding it.
-- When no tracked file changes exist after the target, the mode popover offers only "conversation only" (Claude Code hides code-restore options the same way).
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) also has [Anionex/dsh-turn-rewind](https://github.com/Anionex/dsh-turn-rewind) — a rewind plugin with the same user-facing idea (a per-message action that rolls the conversation back and restores workspace files), but a different approach:
 
-## Not included
+| Dimension | dsh-rewind (this plugin) | Anionex dsh-turn-rewind |
+| --- | --- | --- |
+| Conversation rollback | **In-place, same session/window** — the model-visible surface is cut back to the target; the append-only log is untouched | **Forks a new Session** at the previous `turn/end`; the original session is always retained |
+| File-restore engine | **Lightweight before-backups** of write-class tools only, restored via plain `node:fs` | **Change Ledger** — a durable restore-point engine with Git fences, an approval gate, rescue points and crash reconciliation |
+| Tracked-change scope | Only write-class tool edits (like Claude Code) | Any Git-managed file (Git worktree required) |
+| Public service API | No — a focused single-purpose plugin | Yes — `ctx.changeLedger` service + `/turn-rewind` HTTP endpoint |
 
-- Keyboard shortcuts (esc+esc to open the rewind menu) — planned as a follow-up.
-- `/compact` — provided by the harness.
-- Fork / branch rewind — the harness's built-in "branch in new chat".
-- Whole-tree / git-first snapshots covering bash and external edits — **deliberately not implemented**, in line with Claude Code's native rewind (which also defers such rollbacks to the user's git).
+The essential difference: dsh-turn-rewind keeps the log immutable and therefore forks a new session; this plugin cuts the model-visible surface in place with an empty marker, so the original conversation continues in the same window — the non-trivial part (see [Known issues](#known-issues)) that dsh-turn-rewind sidesteps.
 
 ## Compatibility
 
@@ -189,6 +115,16 @@ Rewinding to a message **withdraws** it and everything after it — the transcri
 > This project and DeepSeek Harness are both in developer preview. Pin exact
 > versions in reproducible environments and review the behavior notes above.
 
+## Known issues
+
+Rewinds created with versions `≤ v0.2.4` could corrupt client replay when followed by more conversation (a marker turn collides with the next `turn/start`). The offline repair tool ships **inside the npm package** (`dsh-rewind-repair`). This only affects sessions you already had before upgrading — a fresh install never hits it.
+
+Full instructions: [docs/troubleshooting.md](docs/troubleshooting.md)
+
+## Security
+
+This plugin only appends rewind-marker events to the session log; it never deletes or rewrites logged history. File writes happen only when you choose "conversation and code" — before-backups and restores stay under `~/.dsh/rewind-snapshots/`. It never touches your git repository, makes no network requests, and accesses no credentials.
+
 ## Development
 
 ```sh
@@ -199,55 +135,19 @@ npm run build          # esbuild: lib/index.js (host ESM) + lib/client.js (loade
 node scripts/verify-host.mjs   # boot the BUILT host artifact end-to-end (18 checks)
 ```
 
-`prepare` runs the full build, so git installs and `npm pack` / `npm publish`
-always produce a complete `lib/` and the `LICENSE`.
+`prepare` runs the full build, so git installs and `npm pack` / `npm publish` always produce a complete `lib/` and the `LICENSE`.
 
-Maintainers: see [docs/harness-reference.md](docs/harness-reference.md) for the
-DeepSeek Harness interface reference (subsystem docs + key source index).
+Maintainers: the module map and harness interface reference live in [docs/harness-reference.md](docs/harness-reference.md); publishing steps in [docs/release.md](docs/release.md).
 
-## Publishing
+## Release
 
-Releases go out through GitHub Actions Trusted Publishing (OIDC, no stored
-`NPM_TOKEN`):
+Releases go out through GitHub Actions Trusted Publishing (OIDC, no stored `NPM_TOKEN`): push a `v<version>` tag and CI publishes with Sigstore provenance.
 
 ```sh
-npm version patch && git push origin main --tags   # triggers .github/workflows/publish.yml
+npm version patch && git push origin main --tags
 ```
 
-- The workflow verifies the tag matches `package.json`, runs typecheck + tests +
-  a full build + artifact verification, publishes with `--provenance`
-  (Sigstore), and creates a GitHub Release. It is **idempotent** — an already
-  published version is skipped. CI (`.github/workflows/ci.yml`) runs the same
-  checks on every push / PR, plus a `npm pack --dry-run` sanity check that the
-  tarball carries `lib/` and `LICENSE`.
-- One-time npm-side configuration (cannot be done from this repo): open
-  [dsh-rewind-plugin](https://www.npmjs.com/package/dsh-rewind-plugin) →
-  **settings → Trusted Publisher → Add**, with Provider **GitHub Actions** ·
-  Organization or user **`SiriLee`** · Repository **`dsh-rewind`** (the GitHub
-  repo, not the npm name) · Workflow filename **`publish.yml`** · Environment
-  **empty** · Allowed actions **`npm publish`**. Once configured, pushes of
-  `v<version>` tags publish automatically.
-
-## Directory layout
-
-```
-src/index.ts            host plugin: /rewind command + checkpoint pipeline (tools/execute|post-execute)
-src/rewind.ts           pure planning: target resolution, surface range, candidate listing
-src/snapshot.ts         checkpoint store (disk before-backups, restore/preview, bounded prune)
-src/session-cwd.ts      session-cwd resolution (fs-tools rule)
-src/client/index.ts     client plugin: per-message ↶ button + manual /rewind guard
-src/client/popover.ts   mode-selection popover (both-mode impact confirm)
-src/client/hidden.ts    withdrawn-span computation (hiddenSeqsOf), pure
-src/client/locales.ts   zh / en copy (LocaleNamespaceMap)
-src/client/styles.ts    injected styles (dsh design tokens)
-scripts/build.mjs       esbuild: lib/index.js (host ESM) + lib/client.js (loader closure) + .d.ts
-scripts/verify-host.mjs end-to-end host verification (18 checks)
-tests/                  vitest suites (rewind / snapshot / hidden / session-cwd / integration, 46 cases)
-docs/harness-reference.md   maintainer docs: DeepSeek Harness interface reference
-assets/screenshots/     UI screenshots
-cordis.patch.yml        bundle patch (mounts the dual-face plugin row)
-package.json            dsh.bundle + dsh.client manifests, optional peerDependencies
-```
+One-time npm-side setup and the full workflow details: [docs/release.md](docs/release.md).
 
 ## License