@kangyishuai/dsh-session-rewind 0.1.0 → 0.1.1

package/README.md

@@ -8,7 +8,7 @@
 
 Unofficial plugin for [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness). Not affiliated with DeepSeek.
 
-> **Status: early.** Verified end to end on DSH 0.2.2-rc.1: 31 GUI assertions in a throwaway DSH home, 155 unit tests, and a CDP-driven desktop pass (conflict refusal, conversation + file rewind, created-file trash, modified-file restore, rescue restore, panel/audit/diagnostics). Young software — keep backups of anything you cannot lose.
+> **Status: early.** Verified end to end on DSH 0.2.2-rc.1: 31 GUI assertions in a throwaway DSH home, 158 unit tests, and a CDP-driven desktop pass (conflict refusal, conversation + file rewind, created-file trash, modified-file restore, rescue restore, panel/audit/diagnostics). Young software — keep backups of anything you cannot lose.
 
 ## What it does
 
@@ -79,7 +79,7 @@ All plugin data lives under `<DSH_HOME>/session-rewind/` (`DSH_HOME` defaults to
 | `rescues/<session>/<rescueId>/` | rescue points (current files before a restore)       |
 | `audit.jsonl`                   | one line per rewind (append-only)                    |
 
-Retention: the 20 latest message anchors per session, the 5 latest rescue points, the 20 latest trash operations (30 days), and a 1 GiB soft cap across blobs/trash/rescues. When the cap is exceeded, old trash → old rescues → unreferenced blobs → oldest anchors are cleaned in that order; if still over the cap, new captures stop and diagnostics report it (no referenced data is deleted). Uninstalling keeps the data. The data root can be overridden with the plugin's `dataRoot` config.
+On startup the plugin also removes data for sessions that no longer exist (they were deleted); the audit log is kept. Retention: the 20 latest message anchors per session, the 5 latest rescue points, the 20 latest trash operations (30 days), and a 1 GiB soft cap across blobs/trash/rescues. When the cap is exceeded, old trash → old rescues → unreferenced blobs → oldest anchors are cleaned in that order; if still over the cap, new captures stop and diagnostics report it (no referenced data is deleted). Uninstalling keeps the data. The data root can be overridden with the plugin's `dataRoot` config.
 
 ## Side effects & risks
 
@@ -94,7 +94,7 @@ Retention: the 20 latest message anchors per session, the 5 latest rescue points
 
 | DSH version | Status                                                                                                                      |
 | ----------- | --------------------------------------------------------------------------------------------------------------------------- |
-| 0.2.2-rc.1  | Verified: `pnpm smoke:session-rewind` (31/31) + 155 unit tests + CDP-driven desktop pass (conversation-only and file modes) |
+| 0.2.2-rc.1  | Verified: `pnpm smoke:session-rewind` (31/31) + 158 unit tests + CDP-driven desktop pass (conversation-only and file modes) |
 
 The plugin declares no `engines.dsh` and no `@deepseek-ai/*` peer range: DSH is pre-release and semver ranges over prereleases are unreliable (see [ADR 0005](../../docs/adr/0005-dsh-version-compatibility.md)). Treat the table as the compatibility statement. After a DSH upgrade run `pnpm probe:runtime`, `pnpm smoke:session-rewind`, and check the plugin's diagnostics tab; if a private seam changed, the plugin degrades instead of breaking the session.
 
@@ -103,7 +103,8 @@ The plugin declares no `engines.dsh` and no `@deepseek-ai/*` peer range: DSH is
 ```bash
 pnpm test                     # unit tests (host engine, host RPC, client helpers)
 pnpm verify                   # repo-wide gates
-pnpm smoke:session-rewind     # temp DSH home + real GUI end-to-end (needs dsh & ego-browser)
+pnpm smoke:session-rewind           # temp DSH home + real GUI end-to-end (needs dsh & ego-browser)
+pnpm smoke:session-rewind-desktop   # read-only desktop check (needs --remote-debugging-port=9222)
 ```
 
 Design notes: [ADR 0006](../../docs/adr/0006-session-rewind-architecture.md) and [ADR 0007](../../docs/adr/0007-session-rewind-file-restore.md) (Chinese; the repository docs are written in Chinese).

package/README.zh-CN.md

@@ -8,7 +8,7 @@
 
 非官方插件，与 DeepSeek 无关。面向 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness)。
 
-> **状态：早期。** 已在 DSH 0.2.2-rc.1 上端到端验证：一次性 DSH 目录里 31 项 GUI 断言 + 155 个单测 + CDP 驱动的桌面版实测（冲突拒绝、对话+文件回退、新建文件进回收站、修改文件还原、救援点恢复、面板/审计/诊断）。插件还年轻，重要数据请自行备份。
+> **状态：早期。** 已在 DSH 0.2.2-rc.1 上端到端验证：一次性 DSH 目录里 31 项 GUI 断言 + 158 个单测 + CDP 驱动的桌面版实测（冲突拒绝、对话+文件回退、新建文件进回收站、修改文件还原、救援点恢复、面板/审计/诊断）。插件还年轻，重要数据请自行备份。
 
 ## 它做什么
 
@@ -79,7 +79,7 @@ dsh plugin --profile desktop add /tmp/kangyishuai-dsh-session-rewind-*.tgz
 | `rescues/<session>/<rescueId>/` | 还原前的救援点                |
 | `audit.jsonl`                   | 每次回溯一行（只追加）        |
 
-保留策略：每会话最近 20 个消息锚点、最近 5 份救援点、最近 20 次回收站操作（30 天）、blobs/trash/rescues 合计 1 GiB 软上限。超限时按「旧回收站 → 旧救援点 → 无引用 blob → 最旧锚点」清理；仍超限则停止新捕获并在诊断里告警（不删有引用的数据）。卸载保留数据。数据根可用插件配置 `dataRoot` 覆盖。
+启动时会自动清理已删除会话的残留数据（entries/trash/救援点）；审计日志保留。保留策略：每会话最近 20 个消息锚点、最近 5 份救援点、最近 20 次回收站操作（30 天）、blobs/trash/rescues 合计 1 GiB 软上限。超限时按「旧回收站 → 旧救援点 → 无引用 blob → 最旧锚点」清理；仍超限则停止新捕获并在诊断里告警（不删有引用的数据）。卸载保留数据。数据根可用插件配置 `dataRoot` 覆盖。
 
 ## 副作用与风险
 
@@ -94,7 +94,7 @@ dsh plugin --profile desktop add /tmp/kangyishuai-dsh-session-rewind-*.tgz
 
 | DSH 版本   | 状态                                                                                              |
 | ---------- | ------------------------------------------------------------------------------------------------- |
-| 0.2.2-rc.1 | 已验证：`pnpm smoke:session-rewind` 31/31 + 155 个单测 + CDP 驱动的桌面版实测（仅对话与文件模式） |
+| 0.2.2-rc.1 | 已验证：`pnpm smoke:session-rewind` 31/31 + 158 个单测 + CDP 驱动的桌面版实测（仅对话与文件模式） |
 
 插件不声明 `engines.dsh`，也不声明 `@deepseek-ai/*` 的 peer 范围：DSH 还在预发布阶段，预发布版本的 semver 范围不可靠（见 [ADR 0005](../../docs/adr/0005-dsh-version-compatibility.md)）。以这张表为准。DSH 升级后跑 `pnpm probe:runtime`、`pnpm smoke:session-rewind`，并看插件诊断页签；私有 seam 变了会降级而不是让会话出错。
 
@@ -103,7 +103,8 @@ dsh plugin --profile desktop add /tmp/kangyishuai-dsh-session-rewind-*.tgz
 ```bash
 pnpm test                     # 单测（宿主文件引擎、宿主 RPC、客户端 helper）
 pnpm verify                   # 仓库统一门禁
-pnpm smoke:session-rewind     # 临时 DSH 目录 + 真实 GUI 端到端（需要 dsh 与 ego-browser）
+pnpm smoke:session-rewind           # 临时 DSH 目录 + 真实 GUI 端到端（需要 dsh 与 ego-browser）
+pnpm smoke:session-rewind-desktop   # 只读桌面回归（需要以 --remote-debugging-port=9222 重启）
 ```
 
 设计记录：[ADR 0006](../../docs/adr/0006-session-rewind-architecture.md)、[ADR 0007](../../docs/adr/0007-session-rewind-file-restore.md)。

package/lib/orphans.js

@@ -0,0 +1,141 @@
+// @ts-check
+// 孤儿数据清理：会话被删除后，`<DSH_HOME>/session-rewind/` 里可能还留着它的
+// entries / trash / rescues。本模块只做“找出并删除这些残留”，不碰仍然存在的会话，
+// 也不碰 audit.jsonl（审计是 append-only 的历史记录）。
+//
+// 安全性：
+//   - 只扫描 `pluginHome` 下的 sessions/ trash/ rescues/ 三个目录；
+//   - 会话 id 必须匹配安全字符集，避免路径穿越；
+//   - 只有「在 <dataRoot>/sessions/<workspace>/<sessionId> 里找不到」的 id 才算孤儿；
+//   - 删除前可以 dryRun 只统计；删除失败逐条记录，不中断其余清理。
+import { readdir, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+/** 目录名安全字符集。 */
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+
+/**
+ * @typedef {object} OrphanReport
+ * @property {string[]} sessionIds 插件 data 里存在、但会话已不存在的 id
+ * @property {string[]} trashIds 孤儿 trash 目录对应的 id
+ * @property {string[]} rescueIds 孤儿 rescue 目录对应的 id
+ * @property {number} bytes 估算占用字节数
+ */
+
+/**
+ * 读取目录下的子目录名；不存在时返回空数组。
+ * @param {string} dir
+ * @param {any} [fs]
+ * @returns {Promise<string[]>}
+ */
+async function listDirs(dir, fs = { readdir }) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch (_error) {
+    return [];
+  }
+  return entries
+    .filter((/** @type {any} */ entry) => entry.isDirectory() && SAFE_ID.test(entry.name))
+    .map((/** @type {any} */ entry) => entry.name)
+    .sort();
+}
+
+/**
+ * 递归计算目录字节数（估算）。
+ * @param {string} target
+ * @param {any} [fs]
+ * @returns {Promise<number>}
+ */
+async function dirBytes(target, fs = { readdir, stat }) {
+  let info;
+  try {
+    info = await fs.stat(target);
+  } catch (_error) {
+    return 0;
+  }
+  if (!info.isDirectory()) return info.size;
+  let total = 0;
+  let entries;
+  try {
+    entries = await fs.readdir(target);
+  } catch (_error) {
+    return 0;
+  }
+  for (const entry of entries)
+    total += await dirBytes(join(target, /** @type {string} */ (entry)), fs);
+  return total;
+}
+
+/**
+ * 找出插件数据里已经没有对应会话的 id。
+ * @param {{dataRoot: string, pluginHome?: string, fs?: any}} input
+ * @returns {Promise<OrphanReport>}
+ */
+export async function findOrphans(input) {
+  /** @type {any} */
+  const fs = input.fs ?? { readdir, rm, stat };
+  const pluginHome = input.pluginHome ?? join(input.dataRoot, "session-rewind");
+  const existing = new Set();
+  const workspaceRoot = join(input.dataRoot, "sessions");
+  for (const workspace of await listDirs(workspaceRoot, fs)) {
+    for (const sessionId of await listDirs(join(workspaceRoot, workspace), fs)) {
+      existing.add(sessionId);
+    }
+  }
+  const sessionIds = [];
+  const trashIds = [];
+  const rescueIds = [];
+  let bytes = 0;
+  for (const id of await listDirs(join(pluginHome, "sessions"), fs)) {
+    if (existing.has(id)) continue;
+    sessionIds.push(id);
+    bytes += await dirBytes(join(pluginHome, "sessions", id), fs);
+  }
+  for (const id of await listDirs(join(pluginHome, "trash"), fs)) {
+    if (existing.has(id)) continue;
+    trashIds.push(id);
+    bytes += await dirBytes(join(pluginHome, "trash", id), fs);
+  }
+  for (const id of await listDirs(join(pluginHome, "rescues"), fs)) {
+    if (existing.has(id)) continue;
+    rescueIds.push(id);
+    bytes += await dirBytes(join(pluginHome, "rescues", id), fs);
+  }
+  return { sessionIds, trashIds, rescueIds, bytes };
+}
+
+/**
+ * 删除孤儿数据。`dryRun` 只返回报告、不做任何删除。
+ * @param {{dataRoot: string, pluginHome?: string, dryRun?: boolean, fs?: any}} input
+ * @returns {Promise<{report: OrphanReport, removed: {sessions: string[], trash: string[], rescues: string[]}, failed: Array<{target: string, error: string}>}>}
+ */
+export async function pruneOrphans(input) {
+  /** @type {any} */
+  const fs = input.fs ?? { readdir, rm, stat };
+  const pluginHome = input.pluginHome ?? join(input.dataRoot, "session-rewind");
+  const report = await findOrphans({ ...input, pluginHome });
+  /** @type {{sessions: string[], trash: string[], rescues: string[]}} */
+  const removed = { sessions: [], trash: [], rescues: [] };
+  /** @type {Array<{target: string, error: string}>} */
+  const failed = [];
+  if (input.dryRun === true) return { report, removed, failed };
+  /** @type {Array<[string, string[], string[]]>} */
+  const plan = [
+    [join(pluginHome, "sessions"), report.sessionIds, removed.sessions],
+    [join(pluginHome, "trash"), report.trashIds, removed.trash],
+    [join(pluginHome, "rescues"), report.rescueIds, removed.rescues],
+  ];
+  for (const [root, ids, sink] of plan) {
+    for (const id of ids) {
+      const target = join(root, id);
+      try {
+        await fs.rm(target, { recursive: true, force: true });
+        sink.push(id);
+      } catch (error) {
+        failed.push({ target, error: error instanceof Error ? error.message : String(error) });
+      }
+    }
+  }
+  return { report, removed, failed };
+}

package/lib/service.js

@@ -25,6 +25,7 @@ import {
   resolveRewindTarget,
   sessionEvents,
 } from "./operations.js";
+import { findOrphans, pruneOrphans } from "./orphans.js";
 import { cutsOf, hasOpenToolCalls, listCandidatesPage, targetContent } from "./plan.js";
 
 /**
@@ -159,6 +160,8 @@ export class SessionRewindService extends TypertRemoteService {
     this._store = null;
     this.installFileTracking();
     this.installCommand();
+    // 启动时清一次已删除会话的残留数据（失败只告警，不阻塞插件）。
+    if (this.config.cleanupOrphans !== false) void this.cleanupOrphans();
   }
 
   /** 惰性创建文件引擎：数据根/配置在服务挂载后解析。 @returns {any} */
@@ -186,6 +189,44 @@ export class SessionRewindService extends TypertRemoteService {
     return this._store;
   }
 
+  /**
+   * 删除已不存在会话的插件数据（entries/trash/rescues）。audit.jsonl 保留。
+   * @returns {Promise<void>}
+   */
+  async cleanupOrphans() {
+    try {
+      const result = await pruneOrphans({ dataRoot: this.dataRoot, dryRun: false });
+      const removed =
+        result.removed.sessions.length +
+        result.removed.trash.length +
+        result.removed.rescues.length;
+      if (removed > 0) {
+        this.ctx?.logger?.info?.(
+          `session-rewind: cleaned ${removed} orphan data dir(s) (${result.report.bytes} bytes)`,
+        );
+        try {
+          await this.store.appendAudit({
+            id: `cleanup-${Date.now()}`,
+            action: "cleanup-orphans",
+            time: Date.now(),
+            sessionId: null,
+            sessions: result.removed.sessions,
+            trash: result.removed.trash,
+            rescues: result.removed.rescues,
+            bytes: result.report.bytes,
+            failed: result.failed,
+          });
+        } catch (_error) {
+          /* 审计失败不影响清理 */
+        }
+      }
+    } catch (error) {
+      this.ctx?.logger?.warn?.(
+        `session-rewind: orphan cleanup failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
   /** 文件追踪是否开启。 @returns {boolean} */
   trackingEnabled() {
     return this.config.fileTracking !== false;
@@ -766,6 +807,17 @@ export class SessionRewindService extends TypertRemoteService {
     } catch (error) {
       push("审计日志", false, error instanceof Error ? error.message : String(error));
     }
+    try {
+      const orphans = await findOrphans({ dataRoot: this.dataRoot });
+      const count = orphans.sessionIds.length + orphans.trashIds.length + orphans.rescueIds.length;
+      push(
+        "孤儿数据",
+        count === 0,
+        count === 0 ? "none" : `${count} dir(s), ${orphans.bytes} bytes`,
+      );
+    } catch (error) {
+      push("孤儿数据", false, error instanceof Error ? error.message : String(error));
+    }
     if (typeof request?.sessionId === "string" && request.sessionId !== "") {
       try {
         const { events, session } = sessionEvents(this.deps(), request.sessionId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kangyishuai/dsh-session-rewind",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "In-place conversation rewind for DSH: withdraw a user message and everything after it, then refill the composer",
   "keywords": [
     "dsh",