dsh-turn-fork

Turn-atomic message editing, retry, reroll, and version-tree navigation for DeepSeek Harness conversations.

简体中文

• Edit any settled user message and re-run the conversation from that turn (truncate or preserve downstream turns).
• Retry any historical turn; regenerate the latest reply.
• Version tree Timeline with undo/redo navigation across branches.
• Branch logs survive a dsh process restart — the P0 durability guarantee the community plugin dsh-message-edit fails (see below).
• Official slots only: Timeline tab, session-header actions, and per-message assistant actions. No DOM injection, no text guessing.
• Bilingual UI (zh / en) through the dsh-client-locale service.

Install

dsh plugin add dsh-turn-fork

Then restart dsh. The plugin registers a Turn Fork tab (between Trajectory and Prompt Studio), compact undo/redo/regenerate buttons in the session header, and retry/regenerate buttons on each finalized assistant message.

Why this plugin exists

dsh-message-edit (v0.2.3) has a P0 defect: its durable provenance event message-edit/version is written without the ignorable marker. The live write path accepts it, but after a dsh restart the persistence layer's cold-read vocabulary guard (assertEventsSupported) rejects the whole log with SessionFormatUnsupportedError — every branch session becomes unreadable. See tests/p0-persistence.test.mjs for a reproduction (live write OK → restart → cold read REJECTED) and this plugin's regression test (ignorable marker → restart → cold read PASSES), run against the real dsh-session + dsh-session-persistence-jsonl packages in a fresh child process.

dsh-turn-fork also fixes the design gaps the review found in the community plugin:

Usage

• Edit a user message — open the Turn Fork tab, pick a message, correct the text, choose the downstream policy and save. A new branch session is created from the completed prefix and the corrected turn re-runs.
• Retry / regenerate — per-turn buttons in the tab, per-message buttons on assistant replies, or the header regenerate button for the latest reply.
• Version tree — the tab lists every branch with its operation summary (from "…" to "…"), marks the current version, and offers Undo/Redo navigation plus Open for any branch. Branches with a running agent show a warning and a Stop control.
• Cascade policy — truncate drops everything after the edited turn; preserve replays the edited turn and every later turn (each replayed input becomes its own turn, with inputs of the same original turn kept in order). The editor shows how many turns preserve will replay before you confirm.

Design notes

• Fork semantics. The official session.fork(atSeq) RPC cuts including the anchored turn, which cannot express "edit turn N and re-run it". This plugin therefore uses the same underlying transaction seam the official fork uses internally — ctx.agents.create — with the seed cut before the target turn, official lineage meta (parentSession, seedLength, cwd, agentPreset), the source's preset re-mounted, and durability flushed before the branch is announced.
• Workspace. The fork inherits the source's workspace attachment exactly like the official fork does (re-attach, no filesystem snapshot). Re-running a task that rewrites files can therefore leave the working tree at the new branch's state. Pair with a checkpointing plugin (e.g. dsh-checkpoint-rewind) when you need workspace state rewind.
• Branch deletion / GC. The platform currently exposes no session-delete API, so branches cannot be garbage-collected yet; the version tree is a plain disclosure of this lineage.
• Migration from dsh-message-edit. Logs written by the broken event format are refused by the persistence layer itself, so no reader — this plugin included — can repair them in place. The Timeline detects the refusal and reports it explicitly. To recover old transcripts, use the official export flow before upgrading, or wait for the upstream fix.

HTTP trust fence

The host route /turn-fork is served by the dsh web server, which performs no origin checks of its own. Every request must pass the plugin's fence: a browser Origin must be http(s)://localhost|127.0.0.1|[::1] with the server's exact port (relaxed only when the server listens on 0.0.0.0, the operator's explicit remote-exposure opt-in); requests without an Origin must carry a loopback Host. POST bodies must be application/json and at most 64 KiB.

Development

npm install
npm run build      # tsc typecheck + tsdown host/client bundles
npm test           # build + node:test (core, lineage, P0 persistence regression)

Tests

• tests/p0-persistence.test.mjs — the P0 regression: the plugin's real fork seed is written through a real dsh-session store and dsh-session-persistence-jsonl backend, flushed to disk, then cold-read in a fresh child process ("restart"). A negative control proves the guard rejects the same log with the marker stripped.
• tests/core.test.mjs — steering fidelity, plan boundaries, seed construction, model-config derivation, trust-fence matrix, body cap, operation decoding.
• tests/lineage.test.mjs — version projection, undo/redo stacks, running flags.
• dsh-testkit.yaml — real-host lifecycle gate (install → boot → register → uninstall → reboot → residue) via the community dsh-testkit, plus the generated .github/workflows/dsh-lifecycle.yml CI workflow.

Testkit notes

dsh-test --suite full reports flaky under --runner local: every attempt passes every stage with identical assertions, but the repeatability digest includes attempt-scoped absolute paths and timestamps, which necessarily differ between attempts (the Docker default runner keeps the run-root path stable). The quick suite is the authoritative lifecycle gate here; the CI workflow runs it under Docker.

License

MIT. The client bundle preset under scripts/dsh-client-preset.ts is vendored from the DeepSeek Harness repository (MIT, © DeepSeek).