dsh-retrace 0.4.32 → 0.4.131

package/README.md

@@ -2,21 +2,20 @@
 
 # 🧭 dsh-retrace
 
-**Recall · Edit-and-resend · Regenerate**, plus **write-safe** in-conversation
+**Recall · Resend (restart from here) · Regenerate**, plus **write-safe** in-conversation
 versioning — the **Agent business layer (production-grade guarantees)** for
 DeepSeek Harness.
 
 [![npm version](https://img.shields.io/npm/v/dsh-retrace)](https://www.npmjs.com/package/dsh-retrace)
 [![npm downloads](https://img.shields.io/npm/dm/dsh-retrace)](https://www.npmjs.com/package/dsh-retrace)
-[![License: MIT](https://img.shields.io/npm/l/dsh-retrace)](https://github.com/yamingmou/dsh-retrace/blob/main/LICENSE)
+[![License: MIT](https://img.shields.io/npm/l/dsh-retrace)](https://www.npmjs.com/package/dsh-retrace)
 [![DSH plugin](https://img.shields.io/badge/DSH-plugin-4A90D9)](https://github.com/topics/dsh-plugin)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](https://github.com/yamingmou/dsh-retrace/pulls)
 
 **English** · [简体中文](./README.zh.md)
 
 </div>
 
-**Recall / edit-and-resend / regenerate** — the three moves every conversation
+**Recall / resend / regenerate** — the three moves every conversation
 deserves. But rewinding is not just "delete a message": DeepSeek Harness stores
 conversations in an append-only event log, so a recall only rewinds the context
 while changed **artifact files stay changed**. dsh-retrace versions the
@@ -27,8 +26,8 @@ it cannot dirty the log, and new markers create **no token-meter pairing debt**
 > ⚠️ **Honest scope (matches the companion contract's own note)**: sessions that
 > already contain **legacy single-segment markers** — written by older versions —
 > are **known design debt**. Before `/compact`, run the companion `check` and
-> clean them up (`fix --remove-markers`); otherwise the host's own T1 self-check
-> blocks compaction. New rewinds do not add to that debt.
+> clean them up (`fix --remove-markers`); otherwise the host's own pre-compaction
+> self-check blocks compaction. New rewinds do not add to that debt.
 
 > 🛡️ **Write safety** · 🔍 **Deep offline checks** · 🔄 **Detect → repair → guard** — see below.
 
@@ -41,8 +40,8 @@ it cannot dirty the log, and new markers create **no token-meter pairing debt**
 ```sh
 dsh plugin --profile desktop add dsh-retrace    # DSH Desktop
 # or Web: dsh plugin --profile web add dsh-retrace
-# or GitHub: dsh plugin --profile desktop add github:yamingmou/dsh-retrace
-# or ZIP: dsh plugin --profile desktop add ~/plugins/dsh-retrace
+# or from an unpacked checkout / ZIP:
+#   dsh plugin --profile desktop add ~/plugins/dsh-retrace
 ```
 
 **No command line?** Install the community plugin market once, then find
@@ -61,7 +60,7 @@ Full steps in [📦 Installation](#-installation).
 
 | | Capability | What it means |
 |---|---|---|
-| 🛡️ | **Write safety** | Every rewind passes a three-layer pre-write contract guard; running agents are auto-stopped (official `cancel`/`whenIdle`); turn-interval markers are wrapped in a temporary step — **new rewinds cannot dirty the log and add no token-meter pairing debt**; **legacy single-segment markers are known debt** (run the companion `check` + `fix --remove-markers` before `/compact`) |
+| 🛡️ | **Write safety** | Every rewind passes a three-layer pre-write contract guard; a running agent is stopped automatically (official `cancel`/`whenIdle`, with a bounded wait); turn-interval markers are wrapped in a temporary step — **new rewinds cannot dirty the log and add no token-meter pairing debt**; **legacy single-segment markers are known debt** (run the companion `check` + `fix --remove-markers` before `/compact`) |
 | 🔍 | **Deep offline checks** | Companion `dsh-log-contract` ships 30+ contract rules (token-meter pairing / cross-step references / physical order / inbox replay), validated against real corrupted-session fixtures — it finds the class of problem that makes /compact permanently fail |
 | 🔄 | **Detect → repair → guard** | A watchdog snapshots the log at the first sign of concurrent writes; offline `fix` neutralizes problem markers and clips cross-step references in place; pre-write validation stops bad events before they land |
 
@@ -71,18 +70,33 @@ Full steps in [📦 Installation](#-installation).
 
 | Action | Where | What happens |
 | --- | --- | --- |
-| **↩ Recall** | hover any assistant reply, or the row under any user message | Removes the **whole exchange round** (the input **and** the agent's output, tool rows included) from both the model context and the conversation view; the input text is echoed into the composer so you can re-ask or re-edit immediately. A small transient notice marks the rewind and disappears once you keep typing. |
-| **✎ Edit & re-send** | row under any user message | The edited round is rewound and the new text is re-sent. By default **only the edited round** is replaced — earlier history stays visible; the optional "fresh conversation" setting rewinds the whole surface (earlier messages then leave the model context, and stay visible in the view as a marker notice by default). A collapsed **"original input"** reference sits right under the new message — click to expand, configurable off. |
+| **↩ Recall** | hover any assistant reply, or the row under any user message | Opens a **confirmation first** (destructive: this message and everything after it leaves the conversation). On confirm, if a turn is still running the plugin **pauses it first** through the official stop entry and waits (bounded); if the pause fails or times out the recall still continues, with a visible notice. The whole exchange round (the input **and** the agent's output, tool rows included) is then removed from both the model context and the conversation view; the input text is echoed into the composer so you can re-ask or re-edit immediately. A transient notice marks the rewind and disappears once you keep typing. |
+| **✎ Resend (restart from here)** | row under any user message | The primary meaning is **restart from this message**: this round and everything after it is rewound and the new text is re-sent, so the conversation continues on a new timeline branch. If that range is refused by the guard (too large to rewrite in place), the error offers a fallback action — **Change this text only (keep what follows)**. A collapsed **"original input"** reference sits right under the new message — click to expand, configurable off. |
 | **↻ Regenerate** | hover any assistant reply | The reply (and everything after it) is rewound and hidden, then the original prompt is re-sent so the agent answers again. |
 
-**Versioning & rollback (live in 0.4.x)** — every rewind is also recorded as a **version**:
+### Undoing a recall
+
+| Action | Scope | What happens |
+| --- | --- | --- |
+| ↺ **Restore display** | view only | Puts the rows hidden by that marker back into the conversation view. The log only grows, the model context is unchanged, and the recall trace stays. Available on the marker row. |
+| ⏪ **True restore** | log level | Neutralizes the two marker segments **in place** (sequence numbers are not renumbered), so the recalled range returns to the **model surface** and its edit / resend / recall actions work again. Requires an idle session that is not the one you are currently viewing; once it succeeds, switch away and reopen that session (or refresh the page) to see the restored content. Refusals are explained with a next step (session running / held by another process / already re-shadowed by a later marker / host does not provide the capability). |
+
+**Checkpoints & rollback (live in 0.4.x)** — every rewind is also recorded as a **checkpoint**:
 
 | | What | |
 |---|---|---|
-| 🕘 | **Timeline** | a **Versions** tab in the conversation view: every version (type, time, message count, file-change badges), pushed live via `session/projection` (no polling), windowed for long histories |
-| ↩️ | **Artifact rollback** | **context-only / artifacts-only / both** with dry-run preview; git-first + content-addressed snapshot fallback; the rollback is itself a new version (`restore`) |
-| 🧭 | **Jump-to-conversation** | one click from a version to that point in the conversation (auto-loads history, anchor highlight) |
-| 🧹 | **Bounded storage** | snapshots keep the most recent N versions (default 50); throttled background sweep prunes truncated ones |
+| 🕘 | **Checkpoints** | a **Checkpoints** tab in the conversation view: every change (type, time, message count, file-change badges), pushed live via `session/projection` (no polling), windowed for long histories; nested history is browsable outline-style |
+| ↩️ | **Artifact rollback** | **context-only / artifacts-only / both** with dry-run preview; git-first + content-addressed snapshot fallback; a rollback is itself a new checkpoint (`restore`). Preview refuses while the agent is running (so "preview says yes, confirm says no" cannot happen), and preview/rollback failures are shown in the UI instead of failing silently |
+| 🧭 | **Jump-to-conversation** | one click from a checkpoint to that point in the conversation (auto-loads history, anchor highlight); when the point is out of the auto-load budget the reason is reported instead of nothing happening |
+| 🧹 | **Bounded storage** | snapshots keep the most recent N checkpoints (default 50); throttled background sweep prunes truncated ones |
+
+> **Rollback on a damaged log** is not silent: the host's strict replay is the
+> authority, but a single malformed event (for example a `sourceEventSeqs` row
+> written by a third party with range encoding) can poison the whole replay. In
+> that case the rollback degrades to a mirror replay, logs both the degradation
+> and the original error, and flags the result as `degraded` on the wire; if even
+> the mirror cannot run you get a structured `replay-failed` error, not a generic
+> `internal`.
 
 **Why it's different** (the interaction layer — the guarantees above are the storage layer):
 
@@ -124,14 +138,15 @@ The same result with plain file edits and `pnpm` — exactly the steps
 1. Open the profile manifest (defaults: `<plugin data home>/profiles/desktop`
    on DSH Desktop, `<plugin data home>/profiles/web` for standalone Web — where
    `<plugin data home>` is `$DSH_HOME` when set, otherwise the **active session
-   base**, e.g. a newer `DSH_HOME` directory; `~/.dsh/profiles` is only the
-   pre-migration fallback) and add **both** the
+   base** (`$DSH_HOME` and any base configured through `$DSH_SESSION_BASES`,
+   falling back to `~/.dsh`); `~/.dsh/profiles` is only the pre-migration fallback)
+   and add **both** the
    dependency and the bundle-layer entry:
 
    ```json
    {
      "dependencies": {
-       "dsh-retrace": "^0.4.0"
+       "dsh-retrace": "^0.4.131"
      },
      "dsh": {
        "profile": {
@@ -159,9 +174,10 @@ The same result with plain file edits and `pnpm` — exactly the steps
 For local development, point the dependency at a checkout instead of the
 registry: `"dsh-retrace": "file:/path/to/dsh-retrace"` — or let
 `dsh` do it: `dsh plugin --profile <name> add /path/to/dsh-retrace`.
-For the latest GitHub commit without a release: use
-`"dsh-retrace": "github:yamingmou/dsh-retrace"` (standard pnpm git
-dependency syntax) in the same `dependencies` block, then `pnpm install`.
+For the latest commit without a release, add a git dependency using the repository
+URL from this package's `repository` field (pnpm syntax
+`"dsh-retrace": "github:<owner>/dsh-retrace"`) in the same `dependencies` block,
+then `pnpm install`.
 
 ### 3. npm package + composition (classic)
 
@@ -194,6 +210,66 @@ The dynamic host registers the same operations behind the package-private
 `harness.handle` RPC (`retrace.recall` / `retrace.editAndResend` /
 `retrace.regenerate`).
 
+### 5. Requirements
+
+- DeepSeek Harness providing the peer packages listed in `package.json`
+  (`@deepseek-ai/dsh-session`, `@deepseek-ai/dsh-client-*`, `cordis`, `react` — the
+  current build targets the `0.1.7-rc.2` generation).
+- `dsh-log-contract >= 0.3.12` (installed automatically as a dependency).
+- The plugin declares the host capabilities it needs via `inject`
+  (`sessions`, `agents`, `webServer`, `fs`, `subprocess`, `sandboxPolicy`, `jobs`).
+  A missing capability degrades the corresponding feature (for example, no
+  `subprocess` ⇒ rollback uses the built-in snapshots only); it does not block boot.
+
+---
+
+## 🔒 Close guard (don't lose work by accident)
+
+Before you exit or reload, know what is still running:
+
+| | What | |
+|---|---|---|
+| 🛡️ | **Running-work detection** | every session is scanned for live work: agent running, queued inbox items, background jobs, unclosed turns |
+| 📋 | **Running banner** | sessions with live work show a persistent in-page banner (short session code + reasons), so you can see it before quitting |
+| ⚠️ | **Exit prompt** | on plugin dispose (app exit / reload) a Chinese notice lists each running session and why it is considered busy — it only warns, it never cancels your running agent |
+| 🔒 | **Page-close interception** | The desktop never arms the host's native confirm dialog; it uses a **page-drawn confirm gate** instead: it draws the box and **verifies visibility synchronously** before blocking (`preventDefault`); if it cannot draw, is not visible, or the page is hidden ⇒ **lets the close through immediately**; the dialog waits for your choice (**Esc = cancel**); a **Web-Worker watchdog** (immune to background throttling) is only the *last* resort. Turning off "Exit confirmation (close guard)" recovers immediately (**no restart**) |
+| 🔎 | **Query surface** | `retrace.runningState` (host RPC) + `GET\|POST /api/plugins/retrace/runningState` (HTTP) — same shape on both transports; the all-sessions shape also carries the host-reported page surface (`surface` / `quitVeto`) |
+
+> **How the close confirm behaves (user-visible)**: whether the host pops its own
+> **native** quit confirmation is decided **jointly by the host and the page**. On a
+> desktop shell the plugin does **not** use the host's native dialog — it draws its
+> **own in-page confirmation** (Esc cancels). If the page cannot draw that box, the
+> box is not visible, or the page itself is hidden, the close is let through
+> immediately. Turning off "Exit confirmation (close guard)" reverts to the host's
+> default behaviour (no restart needed).
+>
+> **Known limitation (stated plainly)**: some desktop shells route quit **around
+> the page entirely** (e.g. the tray item destroys the window directly, or the X
+> button merely hides the window) ⇒ on those shells a plugin **cannot** show a
+> confirm dialog at quit time; it **needs a shell seam** (a `will-prevent-unload`
+> handler, or a pre-quit prompt hook). If the app cannot quit, turning off "Exit
+> confirmation (close guard)" recovers immediately (no restart).
+
+### Session badge & display name (**planned / off by default**)
+
+Badges are for human collaboration; **identity is still decided by the session id**.
+The transports (`sessionBadge` / `setBadgeTitle` / `initBadgeTitles` / `badgeMap`,
+on both HTTP and harness), the resolver and the write guards are **in place**, but
+the **automatic startup path that writes titles is off by default** (the client
+gate is `globalThis.__DSH_RETRACE_BADGE_BOOTSTRAP = true`):
+
+- A session title renders as `[badge] original title` — the **stable identifier is
+  derived deterministically from the session id**, so a title change never changes it.
+- Sessions with **no `session/title` event are left blank on purpose** (the title shows just
+  `[badge]`) — **no project-name fallback, no fabricated name**.
+- If the resolver is unavailable it falls back to the **raw session id as a placeholder**.
+- The sidebar row, the running banner and the checkpoint view share **one source**: the same badge
+  map the host hands down (host op `badgeMap`).
+
+> **Planned (not shipped)**: the agent business-layer plan (runtime guard,
+> interruption governance, ecosystem-facing interfaces) is a **plan**, not a
+> shipped capability.
+
 ---
 
 ## ⚙️ Settings → General
@@ -201,11 +277,18 @@ The dynamic host registers the same operations behind the package-private
 | Setting | Default | Description |
 | --- | --- | --- |
 | **Show the original input after editing** | on | A collapsed "original input" reference under the re-sent message showing the **most recent** replaced text (reference only — never sent to the model). |
-| **Start a fresh conversation after editing** | off | Hide earlier messages too, so the conversation looks like a fresh start (the whole surface is rewound before re-sending). Default off: only the edited round's context is replaced. |
-| **Hide shadowed messages per marker** | on | On (default): recall/edit/regenerate hide the replaced round per their markers. Off: every message stays visible; markers only show the notice and reference (review the full history). A single marker that would hide more than 40% of the conversation degrades to notice-only (history never silently vanishes). |
-| **Version & artifact snapshots** | on | On: every recall/edit records a version (messages and touched files) powering the timeline and artifact rollback. Off: only rewinds context — no version records, no artifact tracking (lightest). |
-| **Git integration** | on | On: use git to record and roll back when the workspace is a repository (never auto-commits, never touches your branches); non-repo workspaces can enable git from the timeline. Off: built-in snapshots under the plugin data home only — the plugin never touches the workspace git state; features are equivalent. |
-| **Version retention limit** | 50 | File snapshots are kept for the most recent N versions; older ones are pruned automatically (timeline records and the audit trail are always kept). |
+| **Checkpoints & artifact snapshots** | on | On: every recall/edit records a checkpoint (messages and touched files) powering the checkpoint list and artifact rollback. Off: only rewinds context — no checkpoint records, no artifact tracking (lightest). |
+| **Summarize old content with AI** | off | On: each recall/edit makes one small model call to summarize the discarded old content. Requires the host `llm` service (the official `@deepseek-ai/dsh-llm`); absent ⇒ it degrades to **verbatim excerpts only**. Off: **zero LLM calls**; the verbatim excerpt (zero token cost) is **always recorded**. At most one small call per operation (input text capped at 500 characters, ≤200 output tokens, 5 s timeout); model and credentials follow the session's own default selection, and the plugin adds **no configuration surface of its own**. |
+| **Git integration** | on | On: use git to record and roll back when the workspace is a repository (never auto-commits, never touches your branches); non-repo workspaces can enable git from the checkpoint view. Off: built-in snapshots under the plugin data home only — the plugin never touches the workspace git state; features are equivalent. |
+| **Checkpoint retention limit** | 50 | File snapshots are kept for the most recent N checkpoints; older ones are pruned automatically (checkpoint records and the audit trail are always kept). |
+| **Exit confirmation (close guard)** | off | On: confirm before the page closes when sessions have running or unfinished work (the plugin draws its own dialog; Esc cancels). Off by default because the gate can also intercept an in-app reload — see [🔒 Close guard](#-close-guard-dont-lose-work-by-accident) for the desktop details and the self-recovery note. |
+
+The two toggles "hide shadowed messages per marker" and "start a fresh
+conversation after editing" no longer exist: recall/resend/regenerate always hide
+what they replaced (a single marker that would hide more than 40% of the
+conversation degrades to notice-only, so history never silently vanishes), and
+resend always uses the "restart from here" semantics with the fallback action
+described above.
 
 ---
 
@@ -228,19 +311,20 @@ The dynamic host registers the same operations behind the package-private
    `[message … last surface node]`, and appends one replacement
    `assistant/message` with an **empty** body — a valid surface node that
    derives to *no* model message, so the LLM context simply rewinds.
-2. **Edit / regenerate** additionally call `agent.followup(...)` with the
+2. **Resend / regenerate** additionally call `agent.followup(...)` with the
    (new) prompt text; the agent's next turn builds its request from the
    rewound `session.deriveMessages()`.
 3. **Client** (`lib/client.js`) registers:
    - a `user-actions` conversation node under every user message
-     (an edit/recall row with an inline editor); recall echoes the text into the
+     (a resend/recall row with an inline editor); recall echoes the text into the
      composer,
    - the `recall-marker` node renderer: a notice row that injects CSS hiding
      every shadowed message row from the flow (view and model context stay in
-     sync), plus the optional original-input comparison block,
+     sync), plus the optional original-input comparison block, the
+     **Restore display** button and the **True restore** action,
    - the `retrace` entry in the `conversation.chat.assistant-actions`
      strip (recall / regenerate),
-   - preference toggles and the retention limit under Settings → General.
+   - the **Checkpoints** view and the preference toggles under Settings → General.
 
 > Two different layers are at play: the **durable transcript** (append-only; old
 > events are never rewritten or deleted) and the **model-visible surface** (rewound
@@ -248,7 +332,8 @@ The dynamic host registers the same operations behind the package-private
 > trail — but they are **synchronized out of both the model context and the visible
 > conversation**, and the view always reflects what the agent actually sees.
 > Persistence, projections and the transcript remain consistent because the plugin
-> only appends valid, typed session events.
+> only appends valid, typed session events. (**True restore** is the one operation
+> that does edit the log, and it does so in place, without renumbering sequences.)
 
 ---
 
@@ -262,114 +347,93 @@ the symptom is usually a failed boot, not a wrong-looking feature.
 This section exists so you can tell **host-side breakage** from **plugin-side bugs**.
 Read it before filing an issue.
 
-### Host-side breaking changes that `0.4.26` adapts to — *not caused by this plugin*
+### Host-side breaking changes this plugin adapts to — *not caused by this plugin*
 
-1. **`@deepseek-ai/dsh-session` dropped `decodeStorageRecord` from its public export surface (in `0.1.5-rc.1`; the function still exists internally but is no longer exported from the package root and is unreachable via the exports map).**
+1. **`@deepseek-ai/dsh-session` removed the `Session.events` member** (in `0.1.5-rc.1`).
+   The supported readers are `snapshotEvents(fromSeq, toSeqExclusive)` (frozen,
+   sequence-indexed), `eventAt(seq)`, `ownEvents()` and `isOwnSeq(seq)`. Before the
+   fix, recall and edit did nothing and surfaced
+   `TypeError: Cannot read properties of undefined (reading 'length')`. The plugin
+   now reaches the log through a compatibility accessor that prefers the new API and
+   falls back to the old array, so both host generations work.
+2. **`@deepseek-ai/dsh-session` dropped `decodeStorageRecord` from its public export
+   surface** (in `0.1.5-rc.1`; the function still exists internally but is no longer
+   exported from the package root and is unreachable via the exports map).
    `dsh-retrace` itself never imported it, but its dependency `dsh-log-contract` did.
    With no such export the loader aborts with
    `plugin tree failed to load … does not provide an export named 'decodeStorageRecord'`
    and **the whole plugin tree fails to load — not just this plugin**, so the app does
-   not start. `0.4.26` requires a `dsh-log-contract` build that decodes through its own
-   local compatibility layer instead of the removed host export.
+   not start.
    → **Dependency note:** needs `dsh-log-contract >= 0.3.12`.
-2. **A client **service** disappeared: `conversationEvents`** — it used to be provided by
-   the legacy client runtime `@deepseek-ai/dsh-client-runtime`, which has been removed
-   (the string `conversationEvents` no longer occurs anywhere in the host). A plugin whose
-   client half still declares that service in `export const inject` never becomes ready:
-   its fiber stays **pending**, which the host reports as
+3. **A client **service** disappeared: `conversationEvents`** — it used to be provided by
+   the legacy client runtime `@deepseek-ai/dsh-client-runtime`, which has been removed.
+   A plugin whose client half still declares that service in `export const inject` never
+   becomes ready: its fiber stays **pending**, which the host reports as
    `renderer boot failed (plugins: …): The client Loader did not provide an error message.`
    — no error text at all, the window does not finish starting, and the only way in is to
-   disable the plugin.
-   `0.4.26` drops the service from `inject` and resolves it **defensively** in `apply`
-   (`uiConversation`, falling back to the legacy name), so it runs on hosts that provide
-   the new service *and* on older hosts that still provide the old one.
+   disable the plugin. The plugin drops the service from `inject` and resolves it
+   **defensively** in `apply` (`uiConversation`, falling back to the legacy name).
    > Note: declaring a **package** that no longer exists in `dsh.client.inject` is *not*
    > what breaks the boot — the client loader skips unknown entries silently. The
    > breakage comes from the **service name** the plugin waits for.
+4. **The client-side session store has no `keys()`** (`ctx.sessions`). A plugin that
+   enumerates sessions with `keys()` silently sees **zero** of them: no crash, no error,
+   just safety warnings that never fire. The plugin prefers the official `list()` and
+   falls back to `keys()`; it deliberately does **not** fall back to enumerating service
+   fields, because guessing produces a silent empty result as well.
 
-> Both items above are **host-side removals**, documented here on purpose: if you hit
-> either symptom right after a host upgrade, the first question is "does this plugin
-> build predate the removal?", not "what did the plugin break?".
+> All four items are **host-side removals**, documented here on purpose: if you hit
+> one of these symptoms right after a host upgrade, the first question is "does this
+> plugin build predate the removal?", not "what did the plugin break?".
 
-### Plugin-side fixes in `0.4.26` (these are ours)
+### Plugin-side fixes (0.4.26 – 0.4.28)
 
 - **Data home and session base are now one source.** The plugin previously resolved its
   own data directory through the host's home resolver (`$DSH_HOME` → `~/.dsh`), which
-  does not know about a migrated base (for example a newer `DSH_HOME` directory). With
-  `$DSH_HOME` unset,
-  sessions were read from one base while snapshots and the artifact store were written
-  to another. Snapshots, version stores and `verify-install` now follow the **active
-  session base**. When `$DSH_HOME` is set, behaviour is unchanged.
+  does not know about extra bases configured through `$DSH_SESSION_BASES`. With
+  `$DSH_HOME` unset, sessions were read from one base while snapshots and the artifact
+  store were written to another. Snapshots,
+  version stores and `verify-install` now follow the **active session base**. When
+  `$DSH_HOME` is set, behaviour is unchanged.
 - **No user-visible string hard-codes `~/.dsh` any more** (the settings hint used to say
   snapshots live under `~/.dsh`).
-- Stale peer declarations with no remaining import site removed
-  (`@deepseek-ai/dsh-home-paths`, `@deepseek-ai/dsh-client-runtime`).
-
-### Host-side breaking changes that `0.4.28` adapts to — *not caused by this plugin*
-
-1. **`@deepseek-ai/dsh-session` removed the `Session.events` member** (in `0.1.5-rc.1`).
-   The class has no `events` field and no `events` getter at all any more; the supported
-   readers are `snapshotEvents(fromSeq, toSeqExclusive)` (frozen, sequence-indexed),
-   `eventAt(seq)`, `ownEvents()` and `isOwnSeq(seq)`. `0.4.28` reaches the log through a
-   compatibility accessor that prefers the new API and falls back to the old array, so it
-   runs on both host generations.
-   **Symptom before the fix:** recall and edit did nothing and surfaced the raw error
-   `TypeError: Cannot read properties of undefined (reading 'length')` — both operations
-   start by locating the target message id, and that lookup read the removed member.
-2. **The client-side session store has no `keys()`** (`ctx.sessions`). A plugin that
-   enumerates sessions with `keys()` silently sees **zero** of them: no crash, no error,
-   just safety warnings that never fire. `0.4.28` prefers the official `list()` and falls
-   back to `keys()`; it deliberately does **not** fall back to enumerating service fields,
-   because guessing produces a silent empty result as well.
-3. **The client session controller has no title accessor** — `getTitle` does not exist
-   anywhere in `@deepseek-ai/dsh-api-session-controller`, and its `getSnapshot()` carries
-   no `title`. See the plugin-side item below: this one used to *overwrite your titles*.
-
-### Plugin-side fixes in `0.4.28` (these are ours)
-
 - **The edit / recall affordances never appeared at all.** The client half read chat
   nodes from `snapshot.chat.nodes`, a path this host build does not have — nodes live in
   the `useChat` store (`snapshot.nodes`). Every message-level component threw while
   rendering and was swallowed by the error boundary, so the buttons were missing, while
-  the settings entry (which reads no nodes) rendered fine. Fixed: the client half now
-  takes `useChat` from the slot contract.
-- **"Jump to message" in the version and fork views did nothing.** It resolved the target
+  the settings entry (which reads no nodes) rendered fine.
+- **"Jump to message" in the checkpoint view did nothing.** It resolved the target
   anchor through `store.getSnapshot()?.chat?.nodes`, which is permanently `undefined`
   here. It now resolves through the `useChat` snapshot injected by the view and pages
   with the official `store.loadThrough(seq)`; when the jump cannot complete it reports a
   **diagnosable reason** (renderer warning + host-log line) instead of failing silently.
-- **Assigning a short code could overwrite your session title.** The client composed
-  `[CODE] <current title>` locally but had no way to read the current title, so the base
-  degraded to the session-id prefix (`[XXXXXX] <session-id-prefix>`). Title tagging now goes
+- **Assigning a lineage ID could overwrite your session title.** Title tagging now goes
   through the host route only (`setBadgeTitle`), which reads the current title from the
   session log. Manual renames are unaffected.
-- **Host-side operation failures are logged again** (code + message + stack). They used to
-  return the message to the UI without a log line, which is why this whole class of bug
-  was hard to diagnose from outside.
-
-- **The version and fork views now explain themselves.** They used to show a title plus a row of
-  actions with **no sentence anywhere saying what a "version" or a "fork" is** (the only near-miss
-  was an empty-state line that disappears as soon as data arrives), and fork rows printed raw node
-  types. They now carry an always-visible concept sentence, a type legend, and a plain-language
-  "why" line on every row; impact text reads `旧路径的 N 条消息被替换`, not `被遮蔽 N 个节点`.
-- **Client hide-lookup no longer rescans per row.** `useSeqHidden` re-scanned the node map for every
-  row (measured **346 ms** at 2000 rows / 20 markers, **1568 ms** at 3000/30 — and that path was
-  *dead* on this host until this release made the rows render at all, so it is this fix own cost).
-  It now reuses one per-snapshot hide plan: **8.3 ms** and **18.3 ms** respectively, with the
-  predicate verified equivalent against the old one.
+- **Host-side operation failures are logged again** (code + message + stack). They used
+  to return the message to the UI without a log line, which made this class of bug hard
+  to diagnose from outside.
+- **The checkpoint view now explains itself.** It used to show a title plus a row of
+  actions with **no sentence anywhere saying what a "checkpoint" is**, and rows printed
+  raw node types. It now carries an always-visible concept sentence, a type legend, and
+  a plain-language "why" line on every row.
+- **Client hide-lookup no longer rescans per row.** `useSeqHidden` re-scanned the node map
+  for every row (measured **346 ms** at 2000 rows / 20 markers, **1568 ms** at 3000/30).
+  It now reuses one per-snapshot hide plan: **8.3 ms** and **18.3 ms** respectively, with
+  the predicate verified equivalent against the old one.
+
 ### Upgrading
 
 ```bash
-dsh plugin --profile desktop add dsh-retrace@0.4.32
+dsh plugin --profile desktop add dsh-retrace@0.4.131
 # then restart DSH — plugins are not hot-reloaded
 ```
 
-**`0.4.27` was withdrawn.** It was briefly published and then recalled — `latest` points at `0.4.26`
-again and `0.4.27` is marked deprecated. **`0.4.28` is its replacement**: it carries every fix
-`0.4.27` had, plus the two items below.
+**`0.4.27` and `0.4.31` were withdrawn** (briefly published, then recalled and marked
+deprecated on npm). Their replacements carry every fix they had.
 
-**`0.4.28` needs no data migration.** The session format is unchanged (v3), no session is
-re-written, and nothing has to be re-indexed: upgrade, restart, and the two symptoms above
+**No data migration is required.** The session format is unchanged (v3), no session is
+re-written, and nothing has to be re-indexed: upgrade, restart, and the symptoms above
 are gone. If you are on a host that still provides the old members, the compatibility
 accessors keep those paths working — this build does not drop older hosts.
 
@@ -385,7 +449,7 @@ whole tree down, so recover first and diagnose second:
 
 ### Pinning
 
-Pin an exact plugin version (`dsh-retrace@0.4.32`) and let `dsh-log-contract` resolve to
+Pin an exact plugin version (`dsh-retrace@0.4.131`) and let `dsh-log-contract` resolve to
 `>=0.3.12`. Do not rely on `^0.4` across a host upgrade: compatibility here is decided by
 the **host surface**, not by semver alone.
 
@@ -393,28 +457,23 @@ the **host surface**, not by semver alone.
 
 ## ⚠️ Requirements & limitations
 
-- **Optional dependency (deliberately NOT in `package.json`)**: AI summaries need
-  an `llm` service from the host (the official `@deepseek-ai/dsh-llm`, bundled
-  with DSH Desktop). The plugin takes it **dynamically** via `ctx.get('llm')`:
-  present ⇒ summaries available, absent ⇒ it degrades to **verbatim excerpts
-  only**. Install and startup are unaffected either way. Model and credentials
-  follow the session's own default selection
-  (`agentDefaultModel.currentSelection()`); the plugin adds **no configuration
-  surface of its own**. Summaries sit behind a **default-off** switch (at most one
-  small call per operation: ≤6×400 chars in, ≤200 tokens out, 5 s timeout); when
-  it is off there are **zero LLM calls**, while the verbatim excerpt (zero token
-  cost) is **always recorded**.
-- Only **user messages** can be edited; recall works on user and assistant
+- Only **user messages** can be re-sent from; recall works on user and assistant
   messages. Tool results are shadowed along with the recalled range but are not
   themselves recall targets.
-- The agent must be **idle**: while a reply is streaming you must stop it
-  (⏹) before recalling or editing. The Host rejects with `agent-busy`
+- A recall that targets a running turn **pauses it first** (official stop entry, bounded
+  wait). If the pause fails or times out, the recall continues and a notice tells you so.
+  True restore and rollback preview require an **idle** session; they are rejected
   otherwise.
-- Recall/edit operate on the **active model surface**: a message that was
+- Recall/resend operate on the **active model surface**: a message that was
   already compacted away or previously recalled is rejected
-  (`target-shadowed`).
+  (`target-shadowed`), and a message whose write has not flushed yet is reported as
+  `message-pending` ("still being generated") rather than being misreported as gone.
 - Regenerate re-sends only the **text** of the original prompt; prompts that
   carried images fall back to the text-only content.
+- True restore edits the session log **in place** (it neutralizes the two marker
+  segments; sequence numbers stay as they are). It refuses to run while the session is
+  the one you are viewing, while it is running, or while another process holds the file,
+  and you must reopen the session (or refresh) to see the result.
 
 ---
 
@@ -422,82 +481,22 @@ the **host surface**, not by semver alone.
 
 **What's in today (0.4.x):**
 
-- Recall / edit-and-resend / regenerate, each written through a three-layer
+- Recall / resend / regenerate, each written through a three-layer
   **pre-write contract guard** and a safe-edit path (auto-stop the agent, temp-step
   markers) — new rewinds do not corrupt the log and add no `/compact` debt;
   **legacy single-segment markers** remain known debt (see the honest note above).
-- In-session **version timeline** + **artifact rollback** (git-first, snapshot
+- **Undo**: Restore display (view) and True restore (log level, in place).
+- In-session **checkpoint timeline** + **artifact rollback** (git-first, snapshot
   fallback, dry-run preview, jump-to-conversation).
-- **Fork map + session lineage** in the conversation view.
+- **Close guard** (running-work banner, exit notice, page-drawn confirm gate).
 - **Real-time watchdog** — snapshots the log at the first sign of concurrent writes.
 - Companion **`dsh-log-contract`**: 30+ offline contract rules + in-place repair
   (`fix --neutralize` / `--clip-crossstep`) for sessions that would fail `/compact`.
-**Close guard (don't lose work by accident)** — before you exit or reload, know what is still running:
-
-| | What | |
-|---|---|---|
-| 🛡️ | **Running-work detection** | every session is scanned for live work: agent running, queued inbox items, background jobs, unclosed turns |
-| 📋 | **Running banner** | sessions with live work show a persistent in-page banner (short session code + reasons), so you can see it before quitting |
-| ⚠️ | **Exit prompt** | on plugin dispose (app exit / reload) a Chinese notice lists each running session and why it is considered busy — it only warns, it never cancels your running agent |
-| 🔒 | **Page-close interception** | **Does not arm the host's native confirm dialog**; uses a **page-drawn confirm gate** instead: it draws the box and **verifies visibility synchronously** before blocking (`preventDefault`); if it cannot draw, is not visible, or the page is hidden ⇒ **lets the close through immediately**; the dialog waits for your choice (**Esc = cancel**); a **Web-Worker watchdog** (immune to background throttling) is only the *last* resort; turning the setting off returns to the official behaviour (**no restart**) |
-| 🔎 | **Query surface** | `retrace.runningState` (host RPC) + `GET|POST /api/plugins/retrace/runningState` (HTTP) — same shape on both transports; the all-sessions shape also carries the host-reported page surface (`surface` / `quitVeto`) |
-
-> Desktop wording (corrected 2026-09-20): **desktop never arms the host's native confirm dialog** —
-> quit entry points differ **by version/platform**, and the native dialog either does not exist on a
-> desktop shell or is swallowed: the 2.0.9 shell we inspected has no `will-prevent-unload` handler
-> (0 hits across the packaged `app.asar`) and routes the tray item through
-> `requestQuit(0) → window.destroy() → app.exit(0)`; on the external report's DSH Desktop 0.9.0 /
-> Windows the entry **does reach** the page `beforeunload` (0.9.0), but the veto is **swallowed
-> silently** (no dialog, no feedback — the exit just looks stuck).
->
-> What actually protects on desktop is the **page-drawn confirm gate** (finalised 2026-09-19):
-> it **does call `preventDefault`** — but only after it has **drawn the box and verified it is
-> visible, synchronously**; a `visibilityState` pre-check lets the close through immediately when the
-> box cannot be drawn / is not visible / the page is hidden; the dialog waits for your choice
-> (**Esc = cancel**); a **Web-Worker watchdog** (immune to background throttling) is only the
-> **last** resort.
->
-> **Both criteria must hold** (2026-09-18, second round): the host side is only a *non-objection*
-> (`quitVeto: true`), and the client keeps a **veto** — if this page's `navigator.userAgent`
-> contains `Electron`, or the page URL contains `dsh-desktop-` (the external report's shell puts its
-> desktop marker in the query string), the native gate is **never** armed. The host-side criteria
-> were widened to four request-level facts: the `x-dsh-desktop-renderer` capability header, a
-> request `User-Agent` containing `Electron`, or a request URL **or `Referer`** containing
-> `dsh-desktop-` — **any one** of them classifies the page as a desktop page. (Our own polling URL
-> carries no query string, so the page marker is in practice read from `Referer`, which a
-> same-origin `fetch` sends by default.) That covers the hosts that expose no desktop evidence at
-> all (the reporter's: a pure-Node harness plus an Electron renderer, where all three older criteria
-> were false, and the old code filed "no evidence at all" as a browser page ⇒ the gate was still
-> armed ⇒ the exit still hung).
->
-> **Known limitation (stated plainly)**: some desktop shells route quit **around the page entirely**
-> (e.g. `requestQuit → destroy → app.exit`, or the X button merely hides the window) ⇒ on those
-> shells a plugin **cannot** show a confirm dialog at quit time; it **needs a shell seam**
-> (a `will-prevent-unload` handler, or a pre-quit prompt hook). If Desktop cannot quit, turning off
-> "Exit confirmation (close guard)" in settings recovers immediately (no restart).
-
-**Session badge & display name** (**planned / off by default**) — badges are for human
-collaboration; **identity is still decided by the session id**. The transports
-(`sessionBadge` / `setBadgeTitle` / `initBadgeTitles` / `badgeMap`, on both HTTP and harness),
-the resolver and the write guards are **in place**, but the **automatic startup path that writes
-titles is off by default** (after three distinct on-device failures it moves to the **scripting
-layer T3**, which is not implemented yet) — set `__DSH_RETRACE_BADGE_BOOTSTRAP = true` to enable it:
-
-- A session title renders as `[badge] original title` (shape placeholder: `[opxxxopxxx] original title`); the badge
-  shape is **`opxxxopxxx`** and comes from the **real table** `codes.json` (workspace + sequence +
-  parent-chain semantics — **not a hash**).
-- Sessions with **no `session/title` event are left blank on purpose** (the title shows just
-  `[badge]`) — **no project-name fallback, no fabricated name**.
-- If the table / resolver is unavailable it falls back to the **raw session id as a placeholder**,
-  and **never** to FNV.
-- The sidebar row, the running banner and the checkpoint view share **one source**: the same badge
-  map the host hands down (host op `badgeMap`).
-
-> **Planned (not shipped)**: the scripting-layer T3 is not implemented yet (the badge/name
-> **automatic title-writing startup path** is blocked on it); the agent business-layer plan (runtime guard,
-> interruption governance, ecosystem-facing interfaces) is a **plan**, not a shipped capability.
-
-> Command surface: `retrace.runningState` (host RPC) + `GET|POST /api/plugins/retrace/runningState` (HTTP).
+- Read-only host surfaces for integration: `retrace/versions` and `retrace/forkmap`
+  projections, `GET /api/plugins/retrace/{versions,forkmap,lineage,event,surface,doctor,snapshot}`,
+  `POST /api/plugins/retrace/{rollback/preview,rollback,git/init}`, plus the badge
+  ops (`sessionBadge` / `setBadgeTitle` / `initBadgeTitles` / `badgeMap`) and the
+  `retrace` CLI (see below).
 
 **What's next** — the agent business-layer plan (runtime guard, interruption
 governance, ecosystem-facing interfaces) is **not published yet**: it is a plan,
@@ -526,10 +525,10 @@ cordis.patch.yml      # dsh.bundle profile patch layer
 ```
 
 ```sh
-pnpm install          # install dev dependencies (vitest, esbuild)
+pnpm install          # install dev dependencies (vitest, esbuild); Node >= 22.13
 pnpm check            # syntax-check sources AND the generated dynamic entries
 pnpm build            # regenerate lib/dynamic-*.js + lib/client.bundle.js
-pnpm test             # run the host-core unit tests
+pnpm test             # run the unit tests
 npm pack --dry-run    # verify the published file list
 ```
 
@@ -541,8 +540,8 @@ npm pack --dry-run    # verify the published file list
 > one and only swaps the transport (`host.call` vs the HTTP route) via
 > `__setMessageEditorWire`.
 
-PRs and issues are welcome — a `CONTRIBUTING.md` is coming soon
-and the [issue tracker](https://github.com/yamingmou/dsh-retrace/issues).
+PRs and issues are welcome — a `CONTRIBUTING.md` is coming soon; use the issue
+tracker linked from this package's `repository`/`bugs` metadata.
 
 ---
 
@@ -554,22 +553,22 @@ Part of the **Agent business layer (production-grade guarantees)** — the
 framework-agnostic layer that dsh-retrace implements on DeepSeek Harness.
 Companion components:
 
-- [**dsh-log-contract**](https://github.com/yamingmou/dsh-log-contract) — the
+- [**dsh-log-contract**](https://www.npmjs.com/package/dsh-log-contract) — the
   business layer's "doctor": 30+ offline contract rules + in-place repair
   (`fix --neutralize` / `--clip-crossstep`). Installed automatically as a
   dependency; also published standalone for direct use.
 
-> **Install straight from GitHub** (no npm registry needed — handy when you
+> **Install straight from git** (no npm registry needed — handy when you
 > hand this repo's link to an AI or want the latest commit):
 >
 > ```sh
-> dsh plugin --profile desktop add github:yamingmou/dsh-retrace
+> dsh plugin --profile desktop add github:<owner>/dsh-retrace
 > # or with pnpm directly into a profile:
-> cd "$DSH_HOME/profiles/desktop" && pnpm add github:yamingmou/dsh-retrace
+> cd "$DSH_HOME/profiles/desktop" && pnpm add github:<owner>/dsh-retrace
 > ```
 >
-> Then restart DSH Desktop as usual. The `dsh-log-contract` dependency is
-> pulled in automatically.
+> Substitute the owner from this package's `repository` field. Then restart DSH
+> Desktop as usual — the `dsh-log-contract` dependency is pulled in automatically.
 
 A curated overview of the DeepSeek Harness plugin ecosystem lives at
 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
@@ -581,13 +580,13 @@ A curated overview of the DeepSeek Harness plugin ecosystem lives at
 
 Built by the [OfferKuai](https://www.offerkuai.com) team — an AI job application
 assistant on a mission that "users need results, not repeated conversations".
-Founder: Zhaofeng (Yaming). This plugin is released as open source for the
-DeepSeek Harness community.
+This plugin is released as open source for the DeepSeek Harness community.
 
 ## 📄 License
 
 MIT
 
+---
 
 ## 🧭 Session archaeology (`retrace` CLI)
 
@@ -596,20 +595,21 @@ audit asset. The `retrace` CLI provides read-only archaeology (reusing
 dsh-log-contract's contracts and extraction):
 
 ```sh
-retrace index <session>                        # tool-call index (A1)
-retrace query <session> --cmd "seed-scale"     # search outputs by command regex (A1)
-retrace extract <session> --pattern "seed-scale" --out ./found   # export outputs (A2)
-retrace file-history <session> <path>          # write/edit history of a file (A3)
-retrace file-diff <session> <path> 0 5         # line diff between two versions (A3)
-retrace lineage <session>                      # parent-chain lineage (A4)
+retrace index <session>                        # tool-call index
+retrace query <session> --cmd "seed-scale"     # search outputs by command regex
+retrace extract <session> --pattern "seed-scale" --out ./found   # export outputs
+retrace file-history <session> <path>          # write/edit history of a file
+retrace file-diff <session> <path> 0 5         # line diff between two versions
+retrace lineage <session>                      # parent-chain lineage
 ```
 
-`<session>` is a full log path or a sessionId (auto-looked-up under
-the active session base — `$DSH_HOME/sessions`, else a newer base, else `~/.dsh/sessions`). All read-only.
+`<session>` is a full log path or a sessionId (auto-looked-up under the active
+session base — `$DSH_HOME/sessions`, else each `$DSH_SESSION_BASES` base, else
+`~/.dsh/sessions`).
+All read-only.
 
-**Session lineage in the fork map (A4, UI)**: the Fork map view header shows the
-current session's `parentSession` chain (session → parent → root, `←` direction).
-Data comes from `GET /api/plugins/retrace/lineage?sessionId=` (read-only header
-walk with cycle protection), the same semantics as the CLI `retrace lineage` —
-so "which session did this one continue/fork from" is visible at a glance, and
-serves as the fork-topology metadata source.
+**Session lineage**: `GET /api/plugins/retrace/lineage?sessionId=` walks the
+current session's `parentSession` chain (read-only, with cycle protection) — the
+same semantics as the CLI `retrace lineage` — so "which session did this one
+continue/fork from" is available to any client, and serves as the fork-topology
+metadata source.