# dsh-rollback-visual

[简体中文](README.md) | English

> ## ⚠️ This repository is deprecated — do not use
>
> What was built here is **conversation rollback** (forking child sessions) plus frontend visualization. Both directions have been overturned:
> - **Conversation rollback**: official DSH ships fork/branch functionality natively — this was reinventing the wheel;
> - **Frontend visualization**: the DOM-injection approach had fundamental problems and has been abandoned.
>
> **Replacement project**: [`QinLuza/dsh-file-undo`](https://github.com/QinLuza/dsh-file-undo) — the real, finished product: **operation-level rollback** (undo agent file write/edit operations, restore pre-operation state via `/undo`). Field-tested and open source.
>
> This repository is kept only as a **pitfall archive** (`docs/踩过的雷.md` documents 10 pitfalls, useful for avoiding them in future plugin development) and is no longer maintained.

---

DeepSeek Harness session rollback (`/rollback`) repository: the **backend trio** (fork-child-session rollback, working). Frontend visualization abandoned (fundamental DOM-injection problems); pitfall log at [docs/踩过的雷.md](docs/踩过的雷.md).

## Features

Rollback = pick a boundary seq in the session event log and fork a child session — **the source session's history is untouched**, and the child starts a new timeline from the boundary.

- **Checkpoint anchors**: every turn end automatically appends a `rollback/checkpoint` event (turn number + boundary seq; disable with `checkpoints: false`), so humans can roll back "to turn N" without memorizing seq numbers.
- **Fork rollback**: derives a child session at the boundary; the source session records paired `rollback/start` → `rollback/end` transaction markers (closed on both success and failure, no dangling brackets), fully persisted and replayable.
- **Boundary validation**: illegal boundaries are always rejected — out of range, inside an open turn, inside a compaction interval, agent busy, cancelled by signal.

## Usage (CLI)

Enter in the GUI input box (or run in a CLI environment):

| Command | Description |
|---|---|
| `/rollback` | Show usage + the list of all checkpoint anchors in the current session |
| `/rollback checkpoint` | Roll back to the **most recent** anchor |
| `/rollback checkpoint:<turn>` | Roll back to the anchor of a specific turn |
| `/rollback <seq>` | Roll back precisely to a specific event seq (advanced, error-prone) |

Example:

```
/rollback
→ turn 3 -> seq 47
→ turn 7 -> seq 120

/rollback checkpoint:3
→ Rolled back to seq 47 — new child session rollback-xxxx.
```

On success: the new child session has been created — switch to it in the session list to continue. The source session stays intact and can be switched back to anytime.

**Notes**:
- Rollback forks session history only; **workspace / sandbox files are NOT reverted**;
- Rollback must happen between turns (agent idle, boundary at a turn end);
- Failures return human-readable reasons: `busy`, `boundary` (illegal), `cancelled`, `persistence`.

## Frontend Visualization (Abandoned)

The DOM-injection rendering approach is abandoned and will not be rebuilt. The data layer (the conversationEvents/conversationViews definitions in `src/client/anchors.ts`) was written correctly and is reusable; the rendering layer (MutationObserver-pinned DOM) is condemned. Full pitfall log and root causes: [docs/踩过的雷.md](docs/踩过的雷.md).

## Roadmap for Redoing the Frontend (For Reference)

- [ ] **Pie 1: native node refactor**. Move the rendering layer from DOM injection to trajectory-native nodes: patch the trajectory source, add `rollback-anchor` / `rollback-bracket` branches to the renderer's kind dispatch chain, making anchors first-class trajectory citizens (layout, collapsing, tooltips all follow); copy the data layer from this repo's `anchors.ts`.
- [ ] **Pie 2: derived badge**. Anchors that have been forked display a "derived" badge (the `boundarySeq` of `rollback/start` is ready-made evidence).
- [ ] **Pie 3: lineage breadcrumb**. Child sessions show "← forked from source session turn N" at the top (`sessionQuery.traceSession` already exists; `parentSession` is recorded at fork time).
- [ ] **Pie 4: lineage tree + side-by-side view**. Visualize multi-generation derivation; view source and child sessions side by side.
- [ ] **Pie 5: workspace snapshot notice**. Waiting for the official `WorkspaceSnapshotter` seam — until then, a dialog with large print saying "files are not reverted".
- [ ] **Pie 6: agent tool channel**. Wrap `ctx.rollback` as a model tool, so users can say "go back to before X" and get a rollback — no clicking, no commands.

## Installation

**Backend trio** (`timeline-rollback` / `rollback-basic` / `command-rollback`): sources and build configuration live on the [feat/timeline-rollback](https://github.com/QinLuza/deepseek-harness-research/tree/feat/timeline-rollback) branch; loading means inserting `rollback-basic` and `command-rollback` entries in the profile's `cordis.patch.yml` (`timeline-rollback` is a Service Definition pulled in automatically as a dependency — do **not** load it separately).

**Frontend plugin** (this repository):

```sh
pnpm build
dsh plugin --profile web add .
```

## Structure

```
src/index.ts          host stub (browser plugin; the host does nothing)
src/client/anchors.ts data layer: conversationEvents/conversationViews definitions (✅ reusable)
src/client/overlay.ts rendering layer: MutationObserver DOM injection (transitional; awaiting native-node rewrite)
src/client/styles.ts  badge/dialog styles (design-token driven)
cordis.patch.yml      loader patch (inserted into the plugin tree)
```

## References

- Backend sources & fixes: [feat/timeline-rollback](https://github.com/QinLuza/deepseek-harness-research/tree/feat/timeline-rollback)
- Full test conclusions & visualization design doc: [docs/测试与参考.md](docs/测试与参考.md)
- **Pitfalls learned (experience summary)**: [docs/踩过的雷.md](docs/踩过的雷.md)