dsh-zcode-rewind
English | 简体中文
Per-tool-call workspace checkpoints for DeepSeek Harness — every file mutation, shell side effects included.
Why
Every checkpoint system we could find only tracks changes made through file-editing tools.
The Claude Code documentation says it outright: "Checkpointing does not track files modified by
Bash commands" — rm file.txt, mv old.txt new.txt, cp source.txt dest.txt cannot be undone
through rewind. Cline does catch command side effects, but by committing the whole repository to a
shadow git repository after every tool call, and its own documentation warns that large repositories
suffer significant storage use and slowdown.
DSH's own market is no different: all four rollback plugins we read (dsh-rewind-plugin,
@anionex/dsh-turn-rewind, dsh-undo-savepoint, dsh-recall-plugin) either parse only the
file_path argument of write/edit, or snapshot at turn boundaries — so a sed -i mid-turn is
invisible to all of them.
What it captures
- Every mutating tool call:
bash, pwsh, write, edit, MCP tools, subagent tools.
- Deletions, creations and modifications — with a revertible previous-content hash for each path.
- Content-addressed file contents, deduplicated across sessions and workspaces.
- A durable ledger of who changed what, in entry order, that survives restarts.
How it works
tools/execute (before) ──> mark pending; first capture writes a full baseline
│ (the tool runs: bash rm/mv/sed, write, edit, MCP …)
tools/post-execute ─────> fingerprint diff → read changed files →
content-addressed blobs (sha-256, deduped) →
append-only ledger record
The fingerprint is path → size + mtime for the whole workspace. Capture costs one O(files) stat
walk plus content reads only for files that actually changed — measured at 88 ms for 3000 files,
against 2936 ms for the initial full-content baseline, i.e. 86 ms for a no-change capture.
Install
dsh plugin --profile web add dsh-zcode-rewind
Restart DSH — a bundle plugin binds during startup assembly. Verify the composed tree with
dsh --profile web --dump-config | grep workspace-rewind. The store lives outside your workspace,
at $DSH_HOME/workspace-rewind/, and never touches your git repository.
Tools
| Tool | What it does |
|---|
rewind_now | Create a manual checkpoint right now, e.g. before a risky operation |
rewind_list | Recent records, newest first: id, time, tool, +added ~modified -deleted, sample paths |
rewind_diff | Restore plan plus a line-level unified diff; changes nothing |
rewind_restore | mode=revert undoes one record; mode=asof returns to a point in time |
rewind_undo | Undo the last restore — repeating it toggles undo/redo |
rewind_status | Store statistics: records, blobs, bytes, quota, active configuration |
Configuration
- insert:
- id: workspace-rewind
name: 'dsh-zcode-rewind'
config:
capture: all # all | fileTools | off
maxFileBytes: 8388608 # larger files are recorded as events only
maxFiles: 20000 # per-walk file cap
maxTotalBytes: 536870912 # store quota; oldest unreferenced blobs are evicted
keepRecords: 500 # ledger trim threshold
excludes: ['.git', 'node_modules', 'dist']
secretNames: ['.env', '*.pem', '*.key']
Restore semantics
| Mode | Meaning |
|---|
revert | Undo exactly the delta of one record — the "undo what just broke" case |
asof | Return the workspace to the state recorded at a checkpoint, folding the ledger and resolving files created after the target |
Safety
- Restores are dry-run by default;
apply=true is required to touch the filesystem.
- Every restore first writes a rescue record, so
rewind_undo can reverse it — repeatedly.
- Restore and rescue records are exempt from quota eviction: the undo trail is never evicted.
- Secret-named and oversized files are recorded as events only, and a restore plan keeps them
untouched rather than guessing their history.
Compatibility
Developed and verified on DSH 0.1.5-rc.2 (desktop harness) and 0.1.6-alpha.2 (WSL). The declared
range is:
>=0.1.5-alpha.1 || >=0.1.6-alpha.1
Host APIs used: ctx.tools.register with defineTool, ctx.inject(['fs'], …) and the
tools/execute / tools/post-execute / tools/result events, ctx.systemPrompt.section,
ctx.logger, plus resolveDshHome() from @deepseek-ai/dsh-home-paths. Peers are resolved through a
multi-anchor createRequire, so a link:-installed copy works without a local node_modules.
Tests and guards
node test/run.mjs # 2 suites, 73 checks — no DSH required
node tools/verify-translation-pairing.mjs --write # bilingual pair hashes
node tools/verify-doc-numbers.mjs # documented numbers vs the real run
node tools/verify-version-consistency.mjs --dsh 0.1.6-alpha.2
Known limitations
- External edits made between tool calls are attributed to the next captured call, the same class of
limitation as a whole-tree shadow commit.
- Files whose content was never captured — secret-named, oversized, or deleted before first capture —
cannot be content-restored; plans keep them as they are and say so.
- Massive monorepos need a larger
excludes list or capture: fileTools.
License
MIT
