dsh-rewind-plugin 0.3.2 → 0.4.0

package/README.md

@@ -66,6 +66,7 @@ The plugin appends an **empty-content marker** `assistant/message` into the sess
 - The marker carries `sourceEventSeqs` covering every shadowed node, and `Session.append`'s surface rules validate the cut (a contiguous range on the current surface).
 - Because the marker is **empty**, the harness derives it to `null` — it never enters the model context and never renders as conversation content. Agent and user both see the conversation exactly as it was at the target.
 - The marker's **turn number reuses the last started turn** (`markerTurnOf`), never `lastTurn + 1`: the harness numbers its next real turn exactly `last turn/start + 1`, so a `maxTurn + 1` marker would sit *before* that `turn/start` — the client conversation builder rejects the ordering (`…turn-tail… received an update before its start Match`) and history load fails. Reusing an already-consumed turn makes the marker a harmless trailing update on the previous completed turn's tail — it can never collide with a future turn.
+- The marker rides a **ghost step frame** — its own `step/start` … `step/end` with a fresh step number (`markerStepOf`) — because the harness token-meter requires every `assistant/message` to sit inside an open step of the same turn/step; a bare idle-time marker would fail its replay and break `/compact` for the session.
 - The append-only log is **untouched** — every withdrawn event stays in the audit trail; only the model-visible surface is cut, so the next request derives its context from the target onward.
 
 A running turn (LLM thinking / streaming) is force-stopped first (`cancel({ kind: 'user' })`) and the rewind waits for quiescence; if it can't stop, the rewind is aborted with an error.
@@ -109,11 +110,19 @@ The essential difference: dsh-turn-rewind keeps the log immutable and therefore
 > This project and DeepSeek Harness are both in developer preview. Pin exact
 > versions in reproducible environments and review the behavior notes above.
 
+## Client contract
+
+Third-party DOM plugins that need to know which transcript rows a rewind
+withdrew should consume the stable, locale-independent helpers exported from
+`dsh-rewind-plugin/client` (`hiddenSeqsOf`, `targetSeqOfArgs`) — never parse
+`outcome.text`. The `data-dsh-rewind-hidden` attribute marks withdrawn rows
+(observational only). Details: [docs/client-contract.md](docs/client-contract.md).
+
 ## Known issues
 
-Rewinds created with versions `≤ v0.2.4` could corrupt client replay when followed by more conversation (a marker turn collides with the next `turn/start`). The offline repair tool ships **inside the npm package** (`dsh-rewind-repair`). This only affects sessions you already had before upgrading — a fresh install never hits it.
+Rewinds created with versions `≤ v0.2.4` could corrupt client replay when followed by more conversation (a marker turn collides with the next `turn/start`). Only pre-upgrade sessions are affected. The offline repair tool (`dsh-rewind-repair`) was shipped before v0.4.0 and is no longer provided from v0.4.0 on — install a pre-v0.4.0 release if you need it ([docs/troubleshooting.md](docs/troubleshooting.md)).
 
-Full instructions: [docs/troubleshooting.md](docs/troubleshooting.md)
+Rewinds from `≤ v0.3.3` appended a bare marker (no step frame); the harness token-meter rejects such a log on replay, so `/compact` fails for that session. Newer versions are compatible; affected old sessions have no online repair yet — start a new session.
 
 ## Security
 
@@ -125,7 +134,7 @@ This plugin only appends rewind-marker events to the session log; it never delet
 
 ```sh
 npm install            # devDeps from the npm registry
-npm run typecheck      # tsc on both compilation surfaces (host + client)
+npm run typecheck      # tsc on all three surfaces (host + client + client-test)
 npm test               # vitest: rewind / snapshot / hidden / session-cwd / integration
 npm run build          # esbuild: lib/index.js (host ESM) + lib/client.js (loader closure) + .d.ts
 node scripts/verify-host.mjs   # boot the BUILT host artifact end-to-end

package/README.zh.md

@@ -66,6 +66,7 @@ dsh plugin --profile web add dsh-rewind-plugin
 - 标记携带 `sourceEventSeqs` 覆盖所有被遮蔽节点，`Session.append` 的 surface 规则校验切割合法性（仅限当前 surface 上的连续区间）。
 - 因为标记**内容为空**，harness 会将其派生为 `null`——永不进入模型上下文、也永不渲染成对话内容。agent 与用户看到的对话都回到目标消息当时的样子。
 - 标记的 **turn 号复用最后一个已开始的回合**（`markerTurnOf`），而不是「最后回合 + 1」：harness 恰好用 `最后 turn/start + 1` 编号下一条真实回合。若标记也取这个数，日志里就会出现同一 turn 的 `assistant/message` 先于 `turn/start` 的乱序，客户端 conversation 构建器会以 `conversation Context …:turn-tail… received an update before its start Match` 拒绝重放——历史加载失败、整个对话从界面消失。复用已消费的 turn 号则标记只是上一个已完成回合尾部的一次无害追加，永不与新回合冲突。
+- 标记自带**幽灵步骤框架**——自己的 `step/start` … `step/end`，step 号取该回合未用过的新号（`markerStepOf`）：harness 的 token-meter 重放要求每条 `assistant/message` 位于打开的 step 内，裸标记则会让该会话的 `/compact` 失效。
 - append-only 日志**不被改写**——审计轨迹完整保留每条被撤回的事件，只有模型可见的 surface 被剪掉，下一条请求从目标消息起派生上下文。
 
 若 agent 正在运行（LLM 思考/流式输出），会先强制停止（`cancel({ kind: 'user' })`）并等待 quiescence 再回退；停不下来则中止并报错。
@@ -98,7 +99,7 @@ dsh plugin --profile web add dsh-rewind-plugin
 | 跟踪范围 | 仅写类工具编辑（同 Claude Code） | 任意 Git 管理文件（要求 Git worktree） |
 | 公共服务 API | 无——聚焦单用途插件 | 有——`ctx.changeLedger` 服务 + `/turn-rewind` HTTP 端点 |
 
-本质区别：dsh-turn-rewind 因保持日志不可变而必须派生新会话；本插件用空标记**就地剪掉**模型可见 surface，于是原对话在同一个窗口继续——这段并不平凡的实现（见[已知问题](#已知问题)）正是 dsh-turn-rewind 绕开的部分。
+本质区别：dsh-turn-rewind 因保持日志不可变而必须派生新会话；本插件用空标记**就地剪掉**模型可见 surface，于是原对话在同一个窗口继续——这段并不平凡的实现正是 dsh-turn-rewind 绕开的部分。
 
 ## 兼容性
 
@@ -109,11 +110,19 @@ dsh plugin --profile web add dsh-rewind-plugin
 > 本项目与 DeepSeek Harness 均处于开发者预览阶段。可复现环境请 pin 精确版本，
 > 并阅读上述行为说明。
 
+## 客户端契约
+
+需要获知哪些转录行被回退撤回的第三方 DOM 插件，应使用
+`dsh-rewind-plugin/client` 导出的稳定、与本地化无关的纯函数
+（`hiddenSeqsOf`、`targetSeqOfArgs`），切勿解析 `outcome.text`。
+`data-dsh-rewind-hidden` 属性标记被撤回的行（仅观测性）。
+详见：[docs/client-contract.zh.md](docs/client-contract.zh.md)。
+
 ## 已知问题
 
-`v0.2.4` 及之前版本创建的回退在随后继续对话时可能损坏客户端重放（标记 turn 与下一个 `turn/start` 撞号）。离线修复工具**已随 npm 包内置**（`dsh-rewind-repair`）。只影响升级前就已存在的旧会话——全新安装永不触发。
+`v0.2.4` 及之前版本创建的回退在随后继续对话时可能损坏客户端重放（标记 turn 与下一个 `turn/start` 撞号）。只影响升级前就已存在的旧会话。离线修复工具（`dsh-rewind-repair`）在 v0.4.0 之前随包提供，此后不再提供——需要修复的用户可安装 v0.4.0 之前的版本（[完整步骤](docs/troubleshooting.zh.md)）。
 
-完整步骤见：[docs/troubleshooting.zh.md](docs/troubleshooting.zh.md)
+`v0.3.3` 及之前版本的回退以裸标记追加（无步骤框架），token-meter 重放会拒绝该日志，`/compact` 对该会话失效。新版本均已兼容；已受影响的旧会话暂不提供在线修复——请新建会话。
 
 ## 安全
 
@@ -125,7 +134,7 @@ dsh plugin --profile web add dsh-rewind-plugin
 
 ```sh
 npm install            # devDeps 来自 npm registry
-npm run typecheck      # tsc 双面编译（host + client）
+npm run typecheck      # tsc 三面编译（host + client + client-test）
 npm test               # vitest：rewind / snapshot / hidden / session-cwd / 集成
 npm run build          # esbuild：lib/index.js（host ESM）+ lib/client.js（loader 闭包）+ .d.ts
 node scripts/verify-host.mjs   # 端到端验证构建产物

package/docs/client-contract.md

@@ -0,0 +1,56 @@
+# Client contract — rewind visibility
+
+How third-party DOM plugins learn **which transcript rows a rewind withdrew**.
+This is the only sanctioned answer to that question; anything not listed here
+is internal and may change without notice.
+
+## Stability tiers
+
+| Channel | Stability | Consumers |
+| --- | --- | --- |
+| `/rewind` command `args` `@<seq>` | ✅ stable, semver-protected | machine |
+| `outcome.sourceEventSeq` (marker log seq) | ✅ stable, semver-protected | machine |
+| `data-dsh-rewind-hidden` attribute | ✅ stable name; observational only | DOM plugins |
+| `outcome.text` | ❌ **not** stable — human copy, never parse | — |
+
+## The sanctioned machine channel
+
+`dsh-rewind-plugin/client` exports the pure, locale-independent computation
+the plugin itself uses (it never reads the DOM or host copy):
+
+```ts
+import { hiddenSeqsOf, type HiddenChat } from 'dsh-rewind-plugin/client'
+
+const chat = session.getSnapshot().chat
+const hidden = hiddenSeqsOf(chat as HiddenChat) // Set<number> of anchor seqs
+```
+
+`hiddenSeqsOf` hides every internal probe row (`preview` / `__candidates`),
+every successful executed `/rewind` row, and every message inside its
+`[target, marker]` span (each rewind cuts one span; spans stay separate).
+`targetSeqOfArgs` is exported for consumers that only need the target from a
+command's `args`. Reuse these instead of re-deriving the logic (cf.
+dsh-chat-timeline#6).
+
+## DOM attribute
+
+Each withdrawn row carries `data-dsh-rewind-hidden="true"` while hidden,
+removed on un-hide. Contract:
+
+- The **attribute name** is stable; treat the value as opaque.
+- It is **observational only** — rewind hides via `style.display`; the
+  attribute records the cause, not the mechanism. Do not write it, and do
+  not expect it on rows outside rewind's control (third-party own elements).
+
+## Explicit non-contract
+
+`outcome.text` is human-facing copy. Its wording changes freely with
+localization; parsing it is a bug. The `impact=<n>` trailer on preview text
+is machine-readable and stable but outside this contract's scope.
+
+## Maintenance rules
+
+- Any change to the meaning of `@<seq>` / `sourceEventSeq` /
+  `data-dsh-rewind-hidden` updates this document in the same PR.
+- Breaking a listed stability tier is a minor/major version bump.
+- `scripts/build.mjs` asserts the export surface on every build.

package/docs/client-contract.zh.md

@@ -0,0 +1,54 @@
+# 客户端契约 — 回退可见性
+
+第三方 DOM 插件如何获知**哪些转录行被回退撤回**。这是该问题的唯一权威
+答案；未在此列出的内容均属内部实现，可随时变更，恕不另行通知。
+
+## 稳定性分级
+
+| 通道 | 稳定性 | 适用方 |
+| --- | --- | --- |
+| `/rewind` 命令 `args` 中的 `@<seq>` | ✅ 稳定，受 semver 保护 | 机器 |
+| `outcome.sourceEventSeq`（marker 日志 seq） | ✅ 稳定，受 semver 保护 | 机器 |
+| `data-dsh-rewind-hidden` 属性 | ✅ 属性名稳定；仅观测性 | DOM 插件 |
+| `outcome.text` | ❌ **不**稳定 — 人类可读文案，禁止解析 | — |
+
+## 唯一机器通道
+
+`dsh-rewind-plugin/client` 导出插件自身所用的纯函数计算，与本地化无关
+（不读取 DOM，也不解析 host 文案）：
+
+```ts
+import { hiddenSeqsOf, type HiddenChat } from 'dsh-rewind-plugin/client'
+
+const chat = session.getSnapshot().chat
+const hidden = hiddenSeqsOf(chat as HiddenChat) // 被隐藏的 anchor seq 集合
+```
+
+`hiddenSeqsOf` 隐藏所有内部探针行（`preview` / `__candidates`）、所有成功
+执行的 `/rewind` 行，以及每条回退 `[target, marker]` 区间内的消息（每次
+回退切一条区间，区间互不合并）。只需从命令 `args` 取 target 时，可用同样
+导出的 `targetSeqOfArgs`。请复用这些实现，勿自行重写（参见
+dsh-chat-timeline#6）。
+
+## DOM 属性
+
+每条被撤回的行在隐藏期间带有 `data-dsh-rewind-hidden="true"`，取消隐藏时
+移除。契约如下：
+
+- **属性名**稳定；值视为不透明。
+- 仅**观测性**标记 — rewind 通过 `style.display` 隐藏，该属性记录的是
+  原因而非机制。不要写它；也不要在 rewind 控制范围之外（第三方自建元素）
+  期望它存在。
+
+## 明确非契约
+
+`outcome.text` 是面向人类用户的文案，措辞随本地化自由变更，解析它即视为
+bug。preview 文案中的 `impact=<n>` 尾注是机器可读且稳定的，但不属于本
+契约范围。
+
+## 维护规则
+
+- 任何改变 `@<seq>` / `sourceEventSeq` / `data-dsh-rewind-hidden` 语义的
+  改动，必须在同一 PR 中更新本文档。
+- 破坏已承诺的稳定性分级属于 minor/major 版本变更。
+- `scripts/build.mjs` 在每次构建时断言导出面。

package/docs/harness-reference.md

@@ -47,7 +47,6 @@ src/client/locales.ts   zh / en copy (LocaleNamespaceMap)
 src/client/styles.ts    injected styles (dsh design tokens)
 scripts/build.mjs       esbuild: lib/index.js (host ESM) + lib/client.js (loader closure) + .d.ts
 scripts/verify-host.mjs end-to-end host verification (18 checks)
-scripts/repair-markers.mjs  offline marker-turn repair tool (ships as `dsh-rewind-repair`)
 tests/                  vitest suites (rewind / snapshot / hidden / session-cwd / integration)
 docs/                   maintainer docs: harness reference, troubleshooting, release steps
 assets/screenshots/     UI screenshots

package/docs/troubleshooting.md

@@ -4,36 +4,17 @@
 
 ## History load failure: `…turn-tail… received an update before its start Match`
 
-Versions `≤ 0.2.4` corrupted client replay when a rewind was **followed by further
-conversation**: the marker's turn number collided with the next real turn's
-`turn/start`, so reopening the session showed
+Rewinds from `≤ 0.2.4` collided with the next real turn's `turn/start`, so reopening the session showed
 
 ```
 Failed to load history: conversation Context …:turn-tail… received an update before its start Match (internal)
 ```
 
-and the history vanished. Rewinds created from `0.2.5` on no longer produce the
-collision, but **already-corrupted sessions need an offline repair** (the log is
-append-only — it cannot be rewritten in memory).
-
-The repair tool ships **inside the npm package** (`dsh-rewind-repair`) — no
-source checkout needed:
+and the history vanished. Rewinds from `0.2.5` on no longer collide; already-corrupted sessions need an offline repair (the log is append-only). The repair tool (`dsh-rewind-repair`) is no longer shipped from v0.4.0 — install a pre-v0.4.0 release to get it (fully quit dsh web / host first, then):
 
 ```sh
-# 1. Fully quit dsh web / host first (while a session is resident in memory,
-#    a disk repair is overwritten by the next checkpoint)
-# 2. Run the offline repair (scans every session under ~/.dsh/sessions,
-#    rewriting each marker's turn back to the last started turn)
-npm exec --yes --package=dsh-rewind-plugin -- dsh-rewind-repair
-npm exec --yes --package=dsh-rewind-plugin -- dsh-rewind-repair -- --dry-run  # preview only
-# 3. Restart dsh web — the repaired sessions load their history again
+npm exec --yes --package=dsh-rewind-plugin@0.3.3 -- dsh-rewind-repair
+npm exec --yes --package=dsh-rewind-plugin@0.3.3 -- dsh-rewind-repair -- --dry-run  # preview only
 ```
 
-Or install it globally once (`npm i -g dsh-rewind-plugin`) and run
-`dsh-rewind-repair` directly; from a source checkout the same tool is
-`node scripts/repair-markers.mjs` (identical flags).
-
-The tool only rewrites the `data.turn` of `dsh-rewind` empty-marker events
-(keeping seqs, order, and the zstd frame structure intact), backs up the original
-file to `session.jsonl.zstd.bak-<timestamp>` before writing, and never touches
-any other event — safe to run repeatedly.
+It only rewrites the marker events' `data.turn` (seqs, order, and zstd frame structure intact) and backs up the original file before writing — safe to run repeatedly. From a source checkout of a pre-v0.4.0 tag: `node scripts/repair-markers.mjs` (identical flags).

package/docs/troubleshooting.zh.md

@@ -4,28 +4,11 @@
 
 ## 历史加载失败：`…turn-tail… received an update before its start Match`
 
-0.2.4 及之前版本在回退**之后继续对话**的场景下会损坏会话的客户端重放：标记的 turn 号
-与下一条真实回合的 `turn/start` 编号冲突，重新打开会话时界面报
-
-```
-历史加载失败：conversation Context …:turn-tail… received an update before its start Match（internal）
-```
-
-历史整段消失。0.2.5 起新的回退不再产生该冲突；但**已损坏的会话需要离线修复**（日志是
-append-only 的，不能在内存中改写）。
-
-修复工具**已随 npm 包发布**（`dsh-rewind-repair`）——无需下载源码：
+0.2.4 及之前版本的回退与下一条真实回合的 `turn/start` 撞号，重开会话时历史整段消失。0.2.5 起的新回退不再产生该冲突；**已损坏的旧会话需离线修复**（日志是 append-only 的）。修复工具（`dsh-rewind-repair`）v0.4.0 起不再随包提供——安装 v0.4.0 之前的版本即可获取（先完全退出 dsh web / host，然后）：
 
 ```sh
-# 1. 先完全退出 dsh web / host（会话处于驻留内存时，磁盘修复会被下次 checkpoint 覆盖）
-# 2. 运行离线修复（扫描 ~/.dsh/sessions 下所有会话，把标记 turn 改回最后一个已开始的回合）
-npm exec --yes --package=dsh-rewind-plugin -- dsh-rewind-repair
-npm exec --yes --package=dsh-rewind-plugin -- dsh-rewind-repair -- --dry-run  # 只预览不写盘
-# 3. 重启 dsh web，损坏的会话即可正常加载历史
+npm exec --yes --package=dsh-rewind-plugin@0.3.3 -- dsh-rewind-repair
+npm exec --yes --package=dsh-rewind-plugin@0.3.3 -- dsh-rewind-repair -- --dry-run  # 只预览不写盘
 ```
 
-也可以全局安装一次（`npm i -g dsh-rewind-plugin`）后直接运行 `dsh-rewind-repair`；
-源码方式为 `node scripts/repair-markers.mjs`（参数相同）。
-
-工具只改写 `dsh-rewind` 空标记事件的 `data.turn` 字段（保持 seq / 顺序 / zstd 帧结构不变），
-改前自动备份原文件为 `session.jsonl.zstd.bak-<时间戳>`；不改动任何其它事件，可安全重复运行。
+工具只改写标记事件的 `data.turn`（保持 seq / 顺序 / zstd 帧结构不变），改前自动备份原文件——可安全重复运行。源码方式：v0.4.0 之前的 tag 下 `node scripts/repair-markers.mjs`（参数相同）。

package/lib/client.js

@@ -27,8 +27,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   apply: () => apply,
+  hiddenSeqsOf: () => hiddenSeqsOf,
   inject: () => inject,
-  name: () => name
+  name: () => name,
+  targetSeqOfArgs: () => targetSeqOfArgs
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -467,9 +469,96 @@ function renderImpactStep(root, opts, back, cached) {
     impact.textContent = t("popover.impact.failed", { message: "unexpected error" });
   });
 }
+function mountShell(root, anchor, onKeyDown) {
+  const position = () => {
+    const rect = anchor.getBoundingClientRect();
+    const gap = 4;
+    const height = root.offsetHeight;
+    const top = rect.bottom + gap + height <= window.innerHeight - 8 ? rect.bottom + gap : Math.max(8, rect.top - gap - height);
+    root.style.top = `${Math.round(top)}px`;
+    root.style.left = `${Math.round(Math.min(rect.right, window.innerWidth - 8 - root.offsetWidth))}px`;
+  };
+  const onPointerDown = (event) => {
+    const target = event.target;
+    if (root.contains(target) || anchor.contains(target)) return;
+    closePopover();
+  };
+  const deferred = setTimeout(() => {
+    document.addEventListener("pointerdown", onPointerDown);
+    document.addEventListener("keydown", onKeyDown, true);
+  }, 0);
+  const dispose = () => {
+    clearTimeout(deferred);
+    document.removeEventListener("pointerdown", onPointerDown);
+    document.removeEventListener("keydown", onKeyDown, true);
+  };
+  document.body.append(root);
+  position();
+  return { position, dispose };
+}
+function openRetractPopover(opts) {
+  closePopover();
+  const { preview, anchor, t, retract, onRetract } = opts;
+  if (retract === void 0 || onRetract === void 0) return;
+  const root = el("div", CLASS.popover);
+  root.setAttribute("role", "dialog");
+  root.setAttribute("aria-label", t("popover.retract.title"));
+  const onKeyDown = (event) => {
+    if (event.key === "ArrowDown") {
+      event.preventDefault();
+      event.stopPropagation();
+      moveFocus(root, 1);
+      return;
+    }
+    if (event.key === "ArrowUp") {
+      event.preventDefault();
+      event.stopPropagation();
+      moveFocus(root, -1);
+      return;
+    }
+    if (event.key === "Escape") {
+      event.preventDefault();
+      event.stopPropagation();
+      closePopover();
+    }
+  };
+  const previewText = preview.length > 0 ? preview : t("popover.noText");
+  const actions = el("div", CLASS.popoverActions);
+  const confirm = document.createElement("button");
+  confirm.type = "button";
+  confirm.className = CLASS.popoverPrimary;
+  confirm.textContent = t("popover.retract.confirm");
+  confirm.addEventListener("click", () => {
+    closePopover();
+    onRetract();
+  });
+  const cancel = document.createElement("button");
+  cancel.type = "button";
+  cancel.className = CLASS.popoverGhost;
+  cancel.textContent = t("popover.cancel");
+  cancel.addEventListener("click", closePopover);
+  actions.append(confirm, cancel);
+  root.replaceChildren(
+    el("div", CLASS.popoverTitle, t("popover.retract.title")),
+    el("div", CLASS.popoverTarget, t("popover.retract.target", { preview: previewText })),
+    el("div", CLASS.popoverImpact, t("popover.retract.hint")),
+    actions
+  );
+  const shell = mountShell(root, anchor, onKeyDown);
+  popoverEl = root;
+  disposeOutside = shell.dispose;
+  focusFirst(root);
+}
 function openPopover(opts) {
   closePopover();
+  if (opts.retract !== void 0) {
+    openRetractPopover(opts);
+    return;
+  }
   const { session, seq, time, preview, anchor, t } = opts;
+  const onRewind = opts.onRewind;
+  if (seq === void 0 || time === void 0 || onRewind === void 0) return;
+  const durableOpts = { session, seq, time, preview, anchor, t, onRewind };
   const root = el("div", CLASS.popover);
   root.setAttribute("role", "dialog");
   root.setAttribute("aria-label", t("popover.title"));
@@ -483,11 +572,13 @@ function openPopover(opts) {
       el("div", CLASS.popoverTarget, formatTarget(t, seq, time, preview)),
       modeOption(t("popover.chat"), t("popover.chat.hint"), () => {
         closePopover();
-        opts.onRewind("chat");
+        durableOpts.onRewind("chat");
       })
     ];
     if (bothState.state === "noChanges") {
       children.push(el("div", CLASS.popoverImpact, t("popover.noChanges")));
+    } else if (bothState.state === "error") {
+      children.push(el("div", CLASS.popoverImpact, t("popover.impact.failed", { message: bothState.message })));
     } else {
       const option = modeOption(
         t("popover.both"),
@@ -510,38 +601,7 @@ function openPopover(opts) {
   };
   const renderImpact = () => {
     step = "impact";
-    renderImpactStep(root, opts, renderModes, impactOutcome);
-  };
-  const position = () => {
-    const rect = anchor.getBoundingClientRect();
-    const gap = 4;
-    const height = root.offsetHeight;
-    const top = rect.bottom + gap + height <= window.innerHeight - 8 ? rect.bottom + gap : Math.max(8, rect.top - gap - height);
-    root.style.top = `${Math.round(top)}px`;
-    root.style.left = `${Math.round(Math.min(rect.right, window.innerWidth - 8 - root.offsetWidth))}px`;
-  };
-  renderModes();
-  document.body.append(root);
-  position();
-  focusFirst(root);
-  void (async () => {
-    const outcome = await previewImpact(session, seq);
-    impactOutcome = outcome;
-    if (outcome !== null && outcome.kind === "success") {
-      bothState = { state: hasFileImpact(outcome.text) ? "hasChanges" : "noChanges" };
-    }
-    renderModes();
-    position();
-  })().catch(() => {
-    bothState = { state: "hasChanges" };
-    renderModes();
-    position();
-  });
-  popoverEl = root;
-  const onPointerDown = (event) => {
-    const target = event.target;
-    if (root.contains(target) || anchor.contains(target)) return;
-    closePopover();
+    renderImpactStep(root, durableOpts, renderModes, impactOutcome);
   };
   const onKeyDown = (event) => {
     if (event.key === "ArrowDown") {
@@ -563,20 +623,52 @@ function openPopover(opts) {
       else closePopover();
     }
   };
-  const deferred = setTimeout(() => {
-    document.addEventListener("pointerdown", onPointerDown);
-    document.addEventListener("keydown", onKeyDown, true);
-  }, 0);
-  disposeOutside = () => {
-    clearTimeout(deferred);
-    document.removeEventListener("pointerdown", onPointerDown);
-    document.removeEventListener("keydown", onKeyDown, true);
-  };
+  renderModes();
+  const shell = mountShell(root, anchor, onKeyDown);
+  popoverEl = root;
+  disposeOutside = shell.dispose;
+  void (async () => {
+    const outcome = await previewImpact(session, seq);
+    impactOutcome = outcome;
+    if (outcome !== null && outcome.kind === "success") {
+      bothState = { state: hasFileImpact(outcome.text) ? "hasChanges" : "noChanges" };
+    } else if (outcome !== null && outcome.kind === "error") {
+      bothState = { state: "error", message: outcome.text ?? "unknown error" };
+    }
+    renderModes();
+    shell.position();
+  })().catch(() => {
+    bothState = { state: "hasChanges" };
+    renderModes();
+    shell.position();
+  });
 }
 
 // src/client/portals.tsx
 var import_react = require("react");
 var import_react_dom = require("react-dom");
+
+// src/client/pending.ts
+function matchPendingRows(rows, steering) {
+  const matched = [];
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i];
+    const item = steering[i];
+    if (item !== void 0 && row.text === (item.text ?? "")) {
+      matched.push(item.id);
+    } else {
+      matched.push(null);
+    }
+  }
+  return matched;
+}
+function retractSpan(steering, targetId) {
+  const index = steering.findIndex((item) => item.id === targetId);
+  if (index === -1) return [];
+  return steering.slice(index).map((item) => item.id);
+}
+
+// src/client/portals.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 function userTextAt(session, seq) {
   const snap = session.getSnapshot();
@@ -609,16 +701,36 @@ async function runRewindAndFill(session, seq, mode, currentSessionId) {
   const result = await session.command(`/rewind @${seq} ${mode}`);
   if (!result.ok || result.value?.matched !== true) return;
   const outcome = await waitForCommand(session, (node) => isExecutedRewindCommand(node, seq) && !known.has(node.seq), 2e4);
-  if (outcome === null || outcome.kind !== "success") return;
+  if (outcome === null) return;
+  if (outcome.kind !== "success") {
+    showHint(outcome.text ?? "rewind failed");
+    return;
+  }
   if (currentSessionId() !== session.sessionId) return;
   const text = userTextAt(session, seq);
   if (text === void 0 || text === "") return;
   fillComposer(text);
 }
+function showHint(text) {
+  const textarea = document.querySelector(COMPOSER_SELECTOR);
+  const hint = document.createElement("div");
+  hint.className = CLASS.guardHint;
+  hint.setAttribute("role", "status");
+  hint.textContent = text;
+  document.body.appendChild(hint);
+  if (textarea !== null) {
+    const card = textarea.closest("[data-composer-card]");
+    const rect = card instanceof HTMLElement ? card.getBoundingClientRect() : textarea.getBoundingClientRect();
+    hint.style.left = `${Math.round(rect.left)}px`;
+    hint.style.bottom = `${Math.round(window.innerHeight - rect.top + 8)}px`;
+  }
+  window.setTimeout(() => hint.remove(), 3200);
+}
 var COMPOSER_SELECTOR = "[data-input-scroll] textarea, textarea[data-phase]";
 var USER_SEAT_SELECTOR = '[data-chat-flow-kind="user"][data-chat-anchor-key], [data-chat-flow-kind="steering"][data-chat-anchor-key]';
 var CHAT_SEAT_SELECTOR = "[data-chat-anchor-key]";
 var ACTIONS_ROOT_SELECTOR = "[data-time-hover-root]";
+var PENDING_SEAT_SELECTOR = "[data-pending-steering][data-time-hover-root]";
 function collectTargets(chat, hiddenSeqs) {
   const rows = /* @__PURE__ */ new Map();
   for (const element of document.querySelectorAll(USER_SEAT_SELECTOR)) {
@@ -635,14 +747,51 @@ function collectTargets(chat, hiddenSeqs) {
     const messageRoot = row?.querySelector(ACTIONS_ROOT_SELECTOR);
     const actions = messageRoot?.lastElementChild;
     if (!(actions instanceof HTMLElement) || actions.querySelector("button") === null) continue;
-    targets.push({ key, container: actions, seq: user.seq, time: user.time, preview: messagePreviewOf(user) });
+    targets.push({ kind: "durable", key, container: actions, seq: user.seq, time: user.time, preview: messagePreviewOf(user) });
+  }
+  return targets;
+}
+function bubbleTextOf(row) {
+  const clone = row.cloneNode(true);
+  clone.lastElementChild?.remove();
+  return clone.textContent ?? "";
+}
+function collectPendingTargets(snapshot) {
+  if (snapshot.subagent !== null) return [];
+  const steering = snapshot.queue.filter((item) => item.placement === "steering");
+  if (steering.length === 0) return [];
+  const rows = Array.from(document.querySelectorAll(PENDING_SEAT_SELECTOR));
+  const matched = matchPendingRows(
+    rows.map((row) => ({ text: bubbleTextOf(row) })),
+    steering.map((item) => ({ id: item.id, text: item.text }))
+  );
+  const targets = [];
+  for (let i = 0; i < matched.length; i++) {
+    const itemId = matched[i];
+    if (itemId === null) continue;
+    const row = rows[i];
+    if (row === void 0) continue;
+    const messageRoot = row.matches(ACTIONS_ROOT_SELECTOR) ? row : row.querySelector(ACTIONS_ROOT_SELECTOR);
+    const actions = messageRoot?.lastElementChild;
+    if (!(actions instanceof HTMLElement) || actions.querySelector("button") === null) continue;
+    const item = steering[i];
+    targets.push({
+      kind: "pending",
+      key: `pending:${itemId}`,
+      container: actions,
+      itemId,
+      text: item.text,
+      preview: item.preview
+    });
   }
   return targets;
 }
 function sameTargets(left, right) {
   return left.length === right.length && left.every((target, index) => {
     const other = right[index];
-    return other !== void 0 && target.key === other.key && target.container === other.container && target.seq === other.seq;
+    if (other === void 0 || target.key !== other.key || target.container !== other.container) return false;
+    if (target.kind === "durable") return other.kind === "durable" && target.seq === other.seq;
+    return other.kind === "pending" && target.itemId === other.itemId;
   });
 }
 function RewindPortals({ sessionId, sessionOf, currentSessionId, t, subscribeLocale }) {
@@ -662,7 +811,8 @@ function RewindPortals({ sessionId, sessionOf, currentSessionId, t, subscribeLoc
         setTargets([]);
         return;
       }
-      const chat = session.getSnapshot().chat;
+      const snapshot = session.getSnapshot();
+      const chat = snapshot.chat;
       const hiddenSeqs = hiddenSeqsOf(chat);
       let hiddenCount = 0;
       for (const seat of document.querySelectorAll(CHAT_SEAT_SELECTOR)) {
@@ -684,7 +834,7 @@ function RewindPortals({ sessionId, sessionOf, currentSessionId, t, subscribeLoc
           `[dsh-rewind] hiding: ${hiddenCount} rows, seqs [${[...hiddenSeqs].slice(0, 20).join(", ")}${hiddenSeqs.size > 20 ? "\u2026" : ""}]`
         );
       }
-      const next = collectTargets(chat, hiddenSeqs);
+      const next = [...collectTargets(chat, hiddenSeqs), ...collectPendingTargets(snapshot)];
       setTargets((current) => sameTargets(current, next) ? current : next);
     };
     const queueRefresh = () => {
@@ -704,7 +854,16 @@ function RewindPortals({ sessionId, sessionOf, currentSessionId, t, subscribeLoc
     };
   }, [sessionId, sessionOf]);
   return targets.map((target) => (0, import_react_dom.createPortal)(
-    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    target.kind === "pending" ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      RetractButton,
+      {
+        target,
+        sessionId,
+        sessionOf,
+        t
+      },
+      target.key
+    ) : /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
       RewindButton,
       {
         target,
@@ -753,6 +912,49 @@ function RewindButton({ target, sessionId, sessionOf, currentSessionId, t }) {
     }
   );
 }
+function composerText() {
+  const textarea = document.querySelector(COMPOSER_SELECTOR);
+  return textarea === null ? "" : textarea.value;
+}
+async function retractPending(session, itemId, text) {
+  await session.cancel();
+  const queue = session.getSnapshot().queue;
+  const steering = queue.filter((item) => item.placement === "steering");
+  for (const id of retractSpan(steering, itemId)) {
+    await session.updateQueue(id, { kind: "remove" });
+  }
+  if (text !== null && text !== "" && composerText().trim() === "") {
+    fillComposer(text);
+  }
+}
+function RetractButton({ target, sessionId, sessionOf, t }) {
+  const onClick = (event) => {
+    event.stopPropagation();
+    const session = sessionOf(sessionId);
+    if (session === void 0) return;
+    openPopover({
+      session,
+      preview: target.preview,
+      anchor: event.currentTarget,
+      t,
+      retract: { itemId: target.itemId, text: target.text },
+      onRetract: () => {
+        void retractPending(session, target.itemId, target.text);
+      }
+    });
+  };
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    "button",
+    {
+      type: "button",
+      className: CLASS.button,
+      "aria-label": t("button.retract.aria"),
+      title: t("button.retract.title"),
+      onClick,
+      dangerouslySetInnerHTML: { __html: REWIND_ICON_SVG }
+    }
+  );
+}
 function createRewindBridge(deps) {
   return function RewindBridge({ sessionId }) {
     return (0, import_react.createElement)(RewindPortals, { sessionId, ...deps });
@@ -763,8 +965,14 @@ function createRewindBridge(deps) {
 var zh = {
   "button.aria": "\u56DE\u9000\u5230\u6B64\u6D88\u606F",
   "button.title": "\u56DE\u9000",
+  "button.retract.aria": "\u56DE\u9000\u5230\u6B64\u63D2\u8BDD\u6D88\u606F",
+  "button.retract.title": "\u56DE\u9000",
   "popover.title": "\u56DE\u9000\u5230\u8FD9\u6761\u6D88\u606F",
   "popover.noText": "\uFF08\u65E0\u6587\u672C\uFF09",
+  "popover.retract.title": "\u56DE\u9000\u5230\u8FD9\u6761\u63D2\u8BDD\u6D88\u606F",
+  "popover.retract.target": "\u63D2\u8BDD\u4E2D \xB7 {preview}",
+  "popover.retract.hint": "\u5C06\u505C\u6B62\u5F53\u524D\u751F\u6210\uFF0C\u5E76\u56DE\u9000\u5230\u8BE5\u6D88\u606F\u4E4B\u524D",
+  "popover.retract.confirm": "\u786E\u8BA4\u56DE\u9000",
   "popover.chat": "\u4EC5\u56DE\u9000\u5BF9\u8BDD",
   "popover.chat.hint": "\u53EA\u56DE\u9000\u6A21\u578B\u4E0A\u4E0B\u6587\uFF0C\u4E0D\u52A8\u5DE5\u4F5C\u533A\u6587\u4EF6",
   "popover.both": "\u56DE\u9000\u5BF9\u8BDD\u548C\u4EE3\u7801",
@@ -784,8 +992,14 @@ var zh = {
 var en = {
   "button.aria": "Rewind to this message",
   "button.title": "Rewind",
+  "button.retract.aria": "Rewind to this pending message",
+  "button.retract.title": "Rewind",
   "popover.title": "Rewind to this message",
   "popover.noText": "(no text)",
+  "popover.retract.title": "Rewind to this pending message",
+  "popover.retract.target": "Pending \xB7 {preview}",
+  "popover.retract.hint": "Stops the current run and rewinds to before this message",
+  "popover.retract.confirm": "Confirm rewind",
   "popover.chat": "Rewind conversation only",
   "popover.chat.hint": "Cut the model context only; workspace files stay untouched",
   "popover.both": "Rewind conversation and code",

package/lib/index.js

@@ -90,6 +90,15 @@ function markerTurnOf(events) {
   }
   return lastStarted;
 }
+function markerStepOf(events, turn) {
+  let lastStarted = 0;
+  for (const event of events) {
+    if (event.type === "step/start" && event.data.turn === turn && event.data.step > lastStarted) {
+      lastStarted = event.data.step;
+    }
+  }
+  return lastStarted + 1;
+}
 function isUserMessageEvent(event) {
   return event.type === "user/message";
 }
@@ -653,6 +662,11 @@ async function waitForAgentIdle(agent, signal, timeoutMs = 15e3) {
     if (onAbort !== void 0) signal.removeEventListener("abort", onAbort);
   }
 }
+function dropPendingSteering(agent) {
+  for (const message of [...agent.inbox.nextStep]) {
+    agent.inbox.remove(message.id);
+  }
+}
 async function executeRewind(ctx, store, fs, invocation, rawTarget, mode, inflight) {
   const { agent } = invocation;
   const sessionId = agent.session.id;
@@ -662,12 +676,13 @@ async function executeRewind(ctx, store, fs, invocation, rawTarget, mode, inflig
   inflight.add(sessionId);
   try {
     if (agent.status !== "idle") {
-      agent.cancel({ kind: "user" });
+      agent.cancel({ kind: "user" }, { keepInbox: true });
       const stopped = await waitForAgentIdle(agent, invocation.signal);
       if (!stopped) {
         return { kind: "error", text: t("stopFailed") };
       }
     }
+    dropPendingSteering(agent);
     if (invocation.signal.aborted) {
       return { kind: "error", text: t("cancelled") };
     }
@@ -680,10 +695,19 @@ async function executeRewind(ctx, store, fs, invocation, rawTarget, mode, inflig
     const marker = buildMarker();
     let event;
     try {
-      event = agent.session.append("assistant/message", { turn: markerTurnOf(agent.session.events), step: 0, message: marker }, {
-        surfaceOp: { op: "replace", start: plan.surfaceStart, end: plan.surfaceEnd },
-        sourceEventSeqs: [...plan.shadowedSeqs]
-      });
+      const turn = markerTurnOf(agent.session.events);
+      const step = markerStepOf(agent.session.events, turn);
+      agent.session.append("step/start", { turn, step });
+      try {
+        event = agent.session.append("assistant/message", { turn, step, message: marker }, {
+          surfaceOp: { op: "replace", start: plan.surfaceStart, end: plan.surfaceEnd },
+          sourceEventSeqs: [...plan.shadowedSeqs]
+        });
+      } catch (error) {
+        agent.session.append("step/end", { turn, step });
+        throw error;
+      }
+      agent.session.append("step/end", { turn, step });
     } catch (error) {
       return {
         kind: "error",

package/lib/types/client/index.d.ts

@@ -35,3 +35,8 @@ export declare const inject: string[];
  * @param ctx - client root context carrying `slots`, `sessions`, `locale` and `commandUi`.
  */
 export declare function apply(ctx: ClientContext): void;
+/**
+ * Public contract — rewind visibility. Stable, semver-protected; the rest of
+ * this module is internal. See `docs/client-contract.md`.
+ */
+export { hiddenSeqsOf, targetSeqOfArgs, type HiddenChat } from './hidden.ts';

package/lib/types/client/locales.d.ts

@@ -3,8 +3,14 @@
 export declare const zh: {
     'button.aria': string;
     'button.title': string;
+    'button.retract.aria': string;
+    'button.retract.title': string;
     'popover.title': string;
     'popover.noText': string;
+    'popover.retract.title': string;
+    'popover.retract.target': string;
+    'popover.retract.hint': string;
+    'popover.retract.confirm': string;
     'popover.chat': string;
     'popover.chat.hint': string;
     'popover.both': string;
@@ -33,8 +39,14 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 export declare const en: {
     'button.aria': string;
     'button.title': string;
+    'button.retract.aria': string;
+    'button.retract.title': string;
     'popover.title': string;
     'popover.noText': string;
+    'popover.retract.title': string;
+    'popover.retract.target': string;
+    'popover.retract.hint': string;
+    'popover.retract.confirm': string;
     'popover.chat': string;
     'popover.chat.hint': string;
     'popover.both': string;

package/lib/types/client/pending.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Pure pending-message matching: pairs the rendered pending-steering bubble
+ * rows with the session's transient queue mirror rows (`placement === 'steering'`).
+ *
+ * Both sides derive from the host's next-step inbox order — the ChatView
+ * renders `pendingSteering` in array order and the queue mirror keeps the same
+ * host order — so index-primary matching is reliable. Text equality is still
+ * verified as a per-row cross-check, and a row that fails (or a row with no
+ * mirror item, or a mirror item with no row) is skipped INDIVIDUALLY: one bad
+ * row never takes down the other rows' buttons. The matching text is the
+ * bubble's message text WITHOUT its actions container — the harness copy
+ * button's Tooltip mounts a label bubble inside that container on hover, so
+ * the full row textContent would flip between "message" and "message+Copy"
+ * with the mouse, flickering the button (see `bubbleTextOf` in portals.tsx).
+ *
+ * The browser half lives in `portals.tsx`; this module stays DOM-free so the
+ * matching contract is unit-testable in a plain node environment.
+ *
+ * @module dsh-rewind/client/pending
+ */
+/** One rendered pending-steering bubble row (only the fields matching reads). */
+export interface PendingRow {
+    /** The bubble's message text, excluding the actions container (see module doc). */
+    readonly text: string;
+}
+/** One steering occurrence from the session queue mirror. */
+export interface PendingSteeringItem {
+    readonly id: string;
+    /** Complete editable text; null when the message contains non-text blocks. */
+    readonly text: string | null;
+}
+/**
+ * Pair rows to steering items by index, verifying text equality per row.
+ * @param rows - pending bubble rows in DOM order (== render order).
+ * @param steering - steering queue items in host order (== render order).
+ * @returns the item id for each row, or null for rows that cannot be matched
+ *   safely (missing counterpart, text mismatch). A bad row never affects the
+ *   other rows.
+ */
+export declare function matchPendingRows(rows: readonly PendingRow[], steering: readonly PendingSteeringItem[]): readonly (string | null)[];
+/**
+ * The pending-steering ids a "rewind to this pre-sent message" retracts: the
+ * target occurrence and every steering message after it, in inbox (FIFO)
+ * order. Queued (next-turn) messages are deliberately NOT included — the
+ * harness QueueDock already offers the user per-item edit/remove, so a rewind
+ * must not silently drop messages the user may still want to send.
+ * @param steering - steering queue items in host order (== render order).
+ * @param targetId - the rewind target's inbox occurrence id.
+ * @returns the ids to remove, oldest-first; empty when the target is no
+ *   longer pending (already claimed/consumed).
+ */
+export declare function retractSpan(steering: readonly {
+    readonly id: string;
+}[], targetId: string): readonly string[];

package/lib/types/client/popover.d.ts

@@ -19,8 +19,17 @@ import type { RewindKey } from './locales.ts';
 type Translate = (key: RewindKey, params?: Record<string, unknown>) => string;
 export interface PopoverOptions {
     readonly session: SessionFace;
-    readonly seq: number;
-    readonly time: number;
+    /** Durable variant: the target message seq (mode-selection flow). */
+    readonly seq?: number;
+    /** Durable variant: the target message time. */
+    readonly time?: number;
+    /** Pending variant: retract a pre-sent steering message (single-confirm flow). */
+    readonly retract?: {
+        readonly itemId: string;
+        readonly text: string | null;
+    };
+    /** Pending variant: executed after the retract confirm closes the popover. */
+    readonly onRetract?: () => void;
     readonly preview: string;
     /** The button that opened the popover (outside-click ignore target). */
     readonly anchor: HTMLElement;
@@ -30,7 +39,7 @@ export interface PopoverOptions {
      * the callback owns the command + composer-refill lifecycle (see
      * runRewindAndFill in index.ts).
      */
-    readonly onRewind: (mode: 'chat' | 'both') => void;
+    readonly onRewind?: (mode: 'chat' | 'both') => void;
 }
 /** Close the current popover, if any. */
 export declare function closePopover(): void;

package/lib/types/client/portals.d.ts

@@ -26,6 +26,28 @@ import { type ReactNode } from 'react';
 import type { SessionFace } from '@deepseek-ai/dsh-client-runtime/client';
 import type { RewindKey } from './locales.ts';
 type Translate = (key: RewindKey, params?: Record<string, unknown>) => string;
+/** One portal target: the actions row of a user/steering seat + its durable node. */
+export type PortalTarget = {
+    readonly kind: 'durable';
+    /** The seat's chat node key (React reconciliation + diff identity). */
+    readonly key: string;
+    /** The row's actions container (React portal target). */
+    readonly container: HTMLElement;
+    readonly seq: number;
+    readonly time: number;
+    readonly preview: string;
+} | {
+    readonly kind: 'pending';
+    /** `pending:${itemId}` — stable per inbox occurrence. */
+    readonly key: string;
+    /** The row's actions container (React portal target). */
+    readonly container: HTMLElement;
+    /** The host inbox occurrence the retract button addresses. */
+    readonly itemId: string;
+    /** Complete editable text; null when the message contains non-text blocks. */
+    readonly text: string | null;
+    readonly preview: string;
+};
 /** Capabilities the session-scoped bridge receives from the plugin apply(). */
 export interface RewindBridgeDeps {
     readonly sessionOf: (sessionId: string) => SessionFace | undefined;

package/lib/types/rewind.d.ts

@@ -9,6 +9,24 @@
  * transcript) is untouched; only the model-visible surface is cut, so the
  * next request derives its context from the target message onward.
  *
+ * Marker shape (v0.3.4+): the marker is an EMPTY `assistant/message` with a
+ * replace `surfaceOp`, wrapped in its own step frame —
+ *
+ *   step/start (turn, step) → assistant/message (marker) → step/end (turn, step)
+ *
+ * The step frame exists because the harness token-meter replays the log and
+ * requires every `assistant/message` to sit inside an OPEN step whose
+ * `(turn, step)` matches exactly (`token meter: assistant/message at seq N
+ * has no matching step/start event` otherwise) — a bare marker appended while
+ * idle (every step already closed) makes every later measure() call throw,
+ * which disables /compact and automatic compaction. The frame's `turn` is the
+ * LAST STARTED turn (`markerTurnOf`) and `step` is that turn's next unused
+ * step number (`markerStepOf`): never a reused one, or the client
+ * conversation assembler sees a duplicate `step/start` and rejects the log
+ * with "received more than one start Match". The agent loop numbers its own
+ * steps from memory (each new turn restarts at 1), so the ghost step can
+ * never collide with a future real step.
+ *
  * @module dsh-rewind/rewind
  */
 import type { SessionEvent, UserMessage } from '@deepseek-ai/dsh-session';
@@ -89,6 +107,25 @@ export declare const DEFAULT_CANDIDATE_LIMIT = 50;
  * @returns a turn number the harness can never reuse for a future `turn/start`.
  */
 export declare function markerTurnOf(events: readonly SessionEvent[]): number;
+/**
+ * Step number for the rewind marker's ghost step frame.
+ *
+ * The marker's `assistant/message` must be wrapped in `step/start` …
+ * `step/end` of the SAME `(turn, step)` so the harness token-meter replay
+ * accepts it (see the module doc). The step number MUST be a step this turn
+ * has never started: the client conversation assembler treats `step/start`
+ * as the start of an `assistant-step` context keyed `turn:step`, so reusing
+ * an already-started step number makes the log replay throw "received more
+ * than one start Match" and the history disappears from the UI. Reusing
+ * `lastStep + 1` is always safe: the harness numbers a turn's steps from
+ * memory (each new turn restarts at 1), so the ghost step can never collide
+ * with a future real step of this turn.
+ *
+ * @param events - the full session event log.
+ * @param turn - the marker's turn (normally `markerTurnOf(events)`).
+ * @returns the smallest step number this turn has never started (≥ 1).
+ */
+export declare function markerStepOf(events: readonly SessionEvent[], turn: number): number;
 /** Narrow an event to a user message. */
 export declare function isUserMessageEvent(event: SessionEvent): event is SessionEvent<'user/message'>;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-rewind-plugin",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "DeepSeek Harness plugin: in-place conversation rewind in the same session window (Claude Code /rewind semantics) with optional workspace file restore",
   "keywords": [
     "deepseek-harness",
@@ -23,9 +23,6 @@
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
-  "bin": {
-    "dsh-rewind-repair": "scripts/repair-markers.mjs"
-  },
   "exports": {
     ".": {
       "types": "./lib/types/index.d.ts",
@@ -44,8 +41,7 @@
     "README.zh.md",
     "docs",
     "assets",
-    "LICENSE",
-    "scripts/repair-markers.mjs"
+    "LICENSE"
   ],
   "dsh": {
     "bundle": {
@@ -63,7 +59,7 @@
   },
   "scripts": {
     "build": "node scripts/build.mjs",
-    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.client.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.client.json && tsc --noEmit -p tsconfig.client-test.json",
     "test": "vitest run",
     "verify:host": "node scripts/verify-host.mjs",
     "prepare": "npm run build"
@@ -132,6 +128,8 @@
     "@deepseek-ai/dsh-client-ui-input-trigger": "^0.1.0-rc.7",
     "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.7",
     "@deepseek-ai/dsh-commands": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-compaction": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-token-meter": "^0.1.0-rc.7",
     "@deepseek-ai/dsh-fs": "^0.1.0-rc.7",
     "@deepseek-ai/dsh-llm": "^0.1.0-rc.7",
     "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.7",

package/scripts/repair-markers.mjs

@@ -1,176 +0,0 @@
-#!/usr/bin/env node
-/**
- * Offline repair for sessions corrupted by the ≤ 0.2.4 marker turn-number bug.
- *
- * Symptom: reopening a session shows
- *   Failed to load history: conversation Context …:turn-tail… received an
- *   update before its start Match (internal)
- * and the history disappears. Root cause: the rewind marker was numbered
- * `lastTurn + 1`, which is exactly how the harness numbers its NEXT real turn —
- * so the log holds an `assistant/message` (the marker) BEFORE the `turn/start`
- * of the same turn, and the client conversation-context builder rejects that
- * ordering.
- *
- * This script rewrites ONLY the `data.turn` of `dsh-rewind` empty-marker events
- * to the last turn/start that precedes them (a turn the harness has already
- * consumed and can never reuse). It preserves:
- *   - every other event byte-for-byte (seqs, times, surface metadata, …),
- *   - the JSONL record order and line structure,
- *   - the zstd multi-frame structure the persistence backend expects
- *     (each frame is decoded, fixed, and re-compressed independently, with the
- *     "last started turn" state threaded across frames).
- *
- * The original file is backed up to `session.jsonl.zstd.bak-<timestamp>` before
- * the first write. Run with the host fully stopped (a resident session would
- * overwrite the repaired file at its next checkpoint), then restart dsh web.
- *
- * Usage:
- *   node scripts/repair-markers.mjs            # scan ~/.dsh/sessions
- *   node scripts/repair-markers.mjs --dry-run  # report only, no writes
- *   node scripts/repair-markers.mjs --dir <sessions root>
- */
-
-import { readdirSync, readFileSync, writeFileSync, copyFileSync, statSync, existsSync } from 'node:fs'
-import { join } from 'node:path'
-import { homedir } from 'node:os'
-import { zstdCompressSync, zstdDecompressSync } from 'node:zlib'
-
-const ZSTD_MAGIC = 0xfd2fb528
-const MARKER_SOURCE = { provider: 'dsh-rewind', model: 'rewind-marker' }
-const DEFAULT_ROOT = join(homedir(), '.dsh', 'sessions')
-
-/** @param {Buffer} buffer @returns {{start:number,end:number}[]} */
-function scanFrames(buffer) {
-  const frames = []
-  let offset = 0
-  while (offset < buffer.length) {
-    const start = offset
-    if (buffer.length - offset < 4 || buffer.readUInt32LE(offset) !== ZSTD_MAGIC) break
-    offset += 4
-    const next = buffer.indexOf(Buffer.from([0x28, 0xb5, 0x2f, 0xfd]), offset)
-    frames.push(next === -1 ? { start, end: buffer.length } : { start, end: next })
-    offset = next === -1 ? buffer.length : next
-  }
-  return frames
-}
-
-/**
- * Rewrite marker turn numbers in ONE frame's JSONL text. Line-preserving: the
- * fix never adds or removes lines, only rewrites a marker line's turn. State
- * (`lastStarted`) is threaded across frames, because a marker in a later frame
- * must know the turn/start events of earlier frames.
- * @param {string} text - this frame's JSONL text.
- * @param {{lastStarted:number}} state - running "last started turn" state.
- * @returns {{text:string, changed:number}} the fixed text (identical when
- *   nothing changed) and the number of rewritten markers in this frame.
- */
-function fixMarkerTurns(text, state) {
-  const lines = text.split('\n')
-  let changed = 0
-  const out = []
-  for (const line of lines) {
-    if (line.trim() === '') {
-      out.push(line)
-      continue
-    }
-    let record
-    try {
-      record = JSON.parse(line)
-    } catch {
-      out.push(line) // keep unknown/torn lines verbatim
-      continue
-    }
-    if (record && record.type === 'turn/start' && Number.isSafeInteger(record.data?.turn)) {
-      if (record.data.turn > state.lastStarted) state.lastStarted = record.data.turn
-      out.push(line)
-      continue
-    }
-    const isMarker =
-      record?.type === 'assistant/message' &&
-      record.data?.message?.source?.provider === MARKER_SOURCE.provider &&
-      record.data?.message?.source?.model === MARKER_SOURCE.model
-    if (!isMarker) {
-      out.push(line)
-      continue
-    }
-    const badTurn = record.data.turn
-    if (badTurn === state.lastStarted) {
-      out.push(line) // already safe (post-0.2.5 marker) — idempotent
-      continue
-    }
-    changed += 1
-    out.push(JSON.stringify({ ...record, data: { ...record.data, turn: state.lastStarted } }))
-  }
-  return { text: out.join('\n'), changed }
-}
-
-/** Repair one session artifact file. @returns {string} a human summary line. */
-function repairFile(file, dryRun) {
-  const original = readFileSync(file)
-  const frames = scanFrames(original)
-  const state = { lastStarted: 0 }
-  const fixedTexts = []
-  let changed = 0
-  for (const frame of frames) {
-    const frameText = zstdDecompressSync(original.subarray(frame.start, frame.end)).toString('utf8')
-    const result = fixMarkerTurns(frameText, state)
-    changed += result.changed
-    fixedTexts.push(result.text)
-  }
-  if (changed === 0) return `  ok (no marker fix needed): ${file}`
-  if (dryRun) return `  would fix ${changed} marker(s): ${file}`
-  const stamp = new Date().toISOString().replace(/[:.]/g, '-')
-  copyFileSync(file, `${file}.bak-${stamp}`)
-  // Preserve the zstd frame structure: one re-compressed frame per original
-  // frame, in order.
-  writeFileSync(file, Buffer.concat(fixedTexts.map(text => zstdCompressSync(Buffer.from(text)))))
-  return `  fixed ${changed} marker(s): ${file} (backup: ${file}.bak-${stamp})`
-}
-
-function collectSessions(root) {
-  const files = []
-  for (const project of readdirSync(root)) {
-    const projectDir = join(root, project)
-    let stat
-    try {
-      stat = statSync(projectDir)
-    } catch {
-      continue
-    }
-    if (!stat.isDirectory()) continue
-    for (const entry of readdirSync(projectDir)) {
-      const file = join(projectDir, entry, 'session.jsonl.zstd')
-      if (existsSync(file)) files.push(file)
-    }
-  }
-  return files
-}
-
-const args = process.argv.slice(2)
-const dryRun = args.includes('--dry-run')
-const dirIndex = args.indexOf('--dir')
-const root = dirIndex !== -1 && args[dirIndex + 1] !== undefined ? args[dirIndex + 1] : DEFAULT_ROOT
-
-if (!existsSync(root)) {
-  console.error(`sessions root not found: ${root}`)
-  process.exit(1)
-}
-
-console.log(`${dryRun ? '[dry-run] ' : ''}scanning ${root}`)
-const files = collectSessions(root)
-console.log(`${files.length} session artifact(s) found`)
-let fixedCount = 0
-for (const file of files) {
-  try {
-    const line = repairFile(file, dryRun)
-    if (!line.includes('no marker fix needed')) {
-      console.log(line)
-      fixedCount += 1
-    }
-  } catch (error) {
-    console.error(`  ERROR ${file}: ${error instanceof Error ? error.message : String(error)}`)
-  }
-}
-console.log(fixedCount === 0
-  ? 'no corrupted sessions found — nothing to do'
-  : `${dryRun ? 'would repair' : 'repaired'} ${fixedCount} session(s). ${dryRun ? '' : 'Restart dsh web to reload the repaired histories.'}`)