dsh-rewind-branch
Rewind a turn of a DeepSeek Harness session and continue in a new branch — with the files that turn changed restored. The session you came from is left exactly as it was.
English | 中文
What it does
Every finished turn gets one action under the assistant reply: Rewind to before this prompt.
Clicking it:
- asks the Host for a plan — which files that turn changed, which were created, which now conflict, and what risks the turn carries;
- after you confirm, restores those files to their state before the prompt, backing up the current content first;
- forks the conversation at that message boundary into a new branch session and switches to it.
Nothing is deleted from the original session: its log, messages and continuation stay untouched. The new branch keeps the conversation up to the message before the rewind point.
Why branch instead of in-place rewind
An in-place rewind truncates the current conversation. Branching keeps the original as evidence and makes the rewind reversible: the old session is still there to compare against or to continue.
File restoration does not require Git. The Host captures the pre-write bytes of DSH's file-tool targets into a content-addressed store, so a workspace without a repository (or with unrelated uncommitted changes) is restored file by file instead of by resetting a repository.
Install
Requires DeepSeek Harness 0.2.1-rc.3 or newer (declared in dsh.engines). No dependencies, no build step, plain JavaScript.
Install from GitHub:
dsh plugin --profile <profile> add "git+https://github.com/shutongcao1-design/dsh-rewind-branch.git"
dsh plugin installs the package and selects the bundle in the same operation. Restart DSH after installing (a full quit, not just a page refresh) so the Host half starts and the turn-tail action reaches the client.
This plugin is not published to npm; install it from this repository.
Usage
- Let an agent turn finish — the session must be idle.
- Under that turn's reply, click Rewind to before this prompt.
- Review the plan: files to restore, files to delete, conflicts, warnings.
- Click Confirm — the files are restored and a new branch session opens.
Notes:
- The first turn of a session has no earlier checkpoint and cannot be rewound.
- A running turn refuses to rewind (
session-running); wait for it to finish.
- Turns that ran before the plugin was installed, or while it was disabled, have no snapshots.
What is captured
Captured (pre-write bytes and a post-write snapshot, per file):
write, edit, str_replace_editor, multi_edit — the tools that write files through DSH.
Not captured:
bash, pwsh, terminal tools, run_code and other shell/code executors. If such a tool ran in the selected turn, the preview shows a warning and the files it changed are not restored; captured files are still restored.- Symlinks, directories and files larger than 4 MiB are skipped.
- File mode bits, ACLs, hard links and submodule contents are not restored.
Conflicts and safety
- The Host compares the current file with the latest post-write snapshot. If they differ (you edited it by hand, or a shell changed it), the file is skipped and listed as a conflict — never overwritten.
- The current content is backed up to
<data>/safety/<timestamp>/ (manifest.json plus one .bin per file) before any write.
- The plan is re-validated right before writing (TOCTOU); a file changed while the confirmation dialog was open is skipped instead of overwritten.
- Writes go through a temporary file followed by rename, so a partially written file never replaces a good one.
Data
- Journal and content-addressed blobs live under
<DSH_HOME>/dsh-rewind-branch/ (journal.jsonl, blobs/, safety/).
- On desktop builds whose Host does not inherit
DSH_HOME, they fall back to a data/ directory next to this package.
- The journal is append-only and rotates at 64 MB (
journal.1.jsonl). Delete the directory to drop all checkpoint history; safety/ backups are plain files you can copy out first.
Security
- The three HTTP routes (
/preview, /rewind, /client.js) are same-origin only: each one runs connection.requestRejection and fails closed with 403 when the request is not the profile's own authenticated page.
- The plugin makes no network calls. It stores bytes locally and forks sessions through the Host's
sessions service.
- Restores happen inside the Host process on your explicit click and only touch absolute paths recorded in the journal for the selected turn.
Compatibility and limits
- DSH Web client and the DSH Desktop shell (any deployment that serves the Web GUI).
- Workspaces do not need Git; Git's index, HEAD, refs and commits are never changed. If the turn committed, the commit stays and the preview warns you.
- Only files changed by DSH file tools are restored; changes made by shell/terminal/code-runner tools are reported and left alone.
- The rewind boundary is an existing session event (
turn/start.seq - 1), so the first turn cannot be rewound.
Development
node --test test/ # unit tests: plan building, restore execution, TOCTOU, safety backup, manifest
npm run check # syntax check for every runtime file
Layout:
| File | Role |
|---|
index.js | Host half: capture, plan routes, restore |
client.js | Browser half: turn-tail action, preview panel, fork + switch |
lib/store.js | Content-addressed blobs + append-only journal |
lib/plan.js | Pure plan computation + plan execution (unit tested) |
test/ | Unit tests and manifest checks |
No build step: the runtime files are plain ESM plus one browser script.
License
MIT. See LICENSE.
