dsh-config-manager 0.1.71 → 0.1.73

package/src/client/recovery/RollbackDiffPane.tsx

@@ -0,0 +1,69 @@
+/**
+ * 单文件前后对照面板 —— DSH 右侧栏标签页与预览弹窗的降级内嵌**共用同一个**渲染。
+ *
+ * 数据面只有一种形状（`RollbackFileDiffResult`）：界面按「能不能逐行对照」分派四态
+ * （结构原因 / 一致 / 有差异 / 读失败），**不猜、不撒谎**：
+ *  · `reason` 有值 ⇒ 说「看不了」并给原因（绝不显示成「没有差异」）；
+ *  · `identical` ⇒ 才说「一致」。
+ * 安全：单元格正文是磁盘原文 ⇒ 展示前必过 redact()（由 DiffTable 的 sanitize 承接）。
+ */
+import type { TranslateNS } from '../client-types.ts'
+import type { RollbackFileDiffResult } from '../../ui/rollback-view.ts'
+import { rollbackFileDiffComparable, rollbackFileDiffReasonKey } from '../../ui/rollback-view.ts'
+import { redact } from '../../security/redaction.ts'
+import { Banner, Spinner } from '../common/ui.tsx'
+import { DiffTable } from '../common/DiffTable.tsx'
+import css from '../config-manager.module.css'
+
+type RKey = Parameters<TranslateNS<'config-manager-recovery'>>[0]
+const rk = (key: string): RKey => key as RKey
+
+/** 面板状态（加载 / 就绪 / 读失败）。 */
+export type RollbackDiffState =
+  | { status: 'loading' }
+  | { status: 'ready'; diff: RollbackFileDiffResult }
+  | { status: 'error'; message: string | null }
+
+export interface RollbackDiffPaneProps {
+  state: RollbackDiffState
+  rt: TranslateNS<'config-manager-recovery'>
+  /**
+   * 文件头（可选）= 该文件路径：给了就在差异上方画一行「路径 + +A/−R」（编辑器式）。
+   * 调用方**已在别处写过这份路径**（聊天预览/设置页的就地展示原本各画一行）时**不要传** —— 同一路径不画两遍。
+   */
+  title?: string
+  /**
+   * 撑满宿主给的高度（**只有侧栏标签页该给**）：正文是那一屏的唯一内容时，
+   * 表格自己吃掉剩余高度、滚动只发生在表格里；弹窗 / 计划列表里的就地差异不给（那些容器有别的约束）。
+   */
+  fill?: boolean
+}
+
+export function RollbackDiffPane({ state, rt, title, fill }: RollbackDiffPaneProps) {
+  if (state.status === 'loading') return <Spinner label={rt('rollback.diff.loading')} />
+  if (state.status === 'error') return <Banner kind="error">{state.message === null ? rt('rollback.diff.failed') : redact(state.message)}</Banner>
+  const diff = state.diff
+  if (diff.ok !== true) {
+    // 宿主结构化拒绝（未命中记录 / 存储栈不可用 …）：给可读文案 + 真实 code（不裸渲染机器码，但也不藏）
+    const code = diff.code === undefined || diff.code === '' ? '' : ' — ' + diff.code
+    return <Banner kind="error">{rt('rollback.diff.failed') + code}</Banner>
+  }
+  if (!rollbackFileDiffComparable(diff)) {
+    const key = rollbackFileDiffReasonKey(diff.reason)
+    return <div className={css.hint}>{key === null ? rt('rollback.diff.reason.unknown') : rt(rk(key))}</div>
+  }
+  if (diff.identical) return <div className={css.hint}>{rt('rollback.diff.identical')}</div>
+  return (
+    <div className={fill === true ? css.diffPane + ' ' + css.diffPaneFill : css.diffPane}>
+      {diff.degraded && <div className={css.hint}>{rt('rollback.diff.degraded')}</div>}
+      <DiffTable
+        hunks={diff.hunks}
+        title={title}
+        beforeLabel={rt('rollback.diff.before')}
+        afterLabel={rt('rollback.diff.after')}
+        truncatedNotice={(shown, total) => rt('rollback.diff.truncated', { shown: String(shown), total: String(total) })}
+        sanitize={redact}
+      />
+    </div>
+  )
+}

package/src/client/recovery/RollbackFileChanges.tsx

@@ -0,0 +1,163 @@
+/**
+ * 回退预览的文件清单 —— **一份实现，两处调用**：
+ *  · 聊天里用户消息旁的回退预览（`src/client/chat/RollbackReviewDialog.tsx`）；
+ *  · 设置页「环境 → 工作区 + 会话回滚」回滚卡的预览弹窗（`src/client/recovery/RollbackCard.tsx`）。
+ *
+ * 为什么抽成一个文件（2026-10-12 用户要求「设置页的回退预览也要一眼看清被改动的文件」）：
+ * 两处必须**逐字同版式** —— 图标 | 目录（弱化）+ 基名（主色）| 右对齐统计；删除行写「删除」；
+ * 行数不可信写「行数未统计」。版式散在两处就会漂移，所以渲染只有这一份。
+ * 数据面与判定面照旧各自只有一份：行数据来自 `readRollbackPreviewFiles` /
+ * `readRollbackPreviewRemovals`（引擎 `preview.workspace` 的同一份数据），统计口径来自
+ * `rollbackPreviewScope`（只累加两侧都可信的行数）。
+ *
+ * 诚实边界（不假装）：
+ *  · **删除行不是按钮**：这类路径不在该回滚点的记录里，引擎的 file-diff 也读不出它 ⇒ 点了也没有
+ *    差异可看。「点文件名看差异」只对**能看**的行成立（调用方给了 `view` 才把路径画成按钮）。
+ *  · 行数可能是 `null`（超限 / 非文本 / 内容副本读不出）⇒ 那一格写「行数未统计」，**绝不写 0**：
+ *    「0 行」是一个会被证伪的具体断言，而「不知道」不是。
+ *  · 形状读不出（`status` 不在取值域）⇒ 不画语义色条（宁可不画，也不按猜测上色）。
+ */
+import type { TranslateNS } from '../client-types.ts'
+import { rollbackPreviewFileLabel, splitRollbackPath } from '../../ui/rollback-view.ts'
+import { RollbackFileIcon, type RollbackFileIconRenderer } from '../chat/RollbackFileIcon.tsx'
+import {
+  previewFileStatusKnown,
+  rollbackPreviewFileKey,
+  type ChatPreviewFileRow,
+} from '../chat/rollback-entry-view.ts'
+import css from '../config-manager.module.css'
+
+type RKey = Parameters<TranslateNS<'config-manager-recovery'>>[0]
+const rk = (key: string): RKey => key as RKey
+
+/** 一个文件的「查看差异」入口（调用方给的已插值文案 + 点击回调）。 */
+export interface RollbackFileViewEntry {
+  /** 该行的无障碍名 / 悬停提示（把 {path} 插好的完整句）。 */
+  hint: (path: string) => string
+  /** 忙态或还没有可写目标时禁用 —— 入口仍占位（不消失）。 */
+  disabled: boolean
+  onView: (path: string) => void
+}
+
+export interface RollbackFileChangesProps {
+  /** 会被**改动**的文件（`readRollbackPreviewFiles(preview.workspace)` 的产物）。 */
+  files: readonly ChatPreviewFileRow[]
+  /** 会被整文件**删除**的路径（`readRollbackPreviewRemovals(preview.workspace)` 的产物）。 */
+  removals: readonly string[]
+  /** recovery 字典翻译器（±行数 / 「删除」/「行数未统计」的词汇单一所有）。 */
+  rt: TranslateNS<'config-manager-recovery'>
+  /** 逐行「查看差异」；不给 = 该表面没有差异通道（那时路径只是文字，不给假入口）。 */
+  view?: RollbackFileViewEntry
+  /** 文件类型图标的外部来源（装了 dsh-better-sidebar 时由装配点注入）。 */
+  renderFileIcon?: RollbackFileIconRenderer
+}
+
+/**
+ * 一行文件统计：`+N` / `−M`；任一侧是 null ⇒ 「行数未统计」整句替换（绝不打 0）。
+ * 两侧都可信时**两个数字都给**（新增与删除是两件事，用户两个都要看）。
+ *
+ * 例外：**整文件删除写「删除」**，不写 `+0 −N`。判据只看引擎给的 `status === 'delete'`
+ * （取值域在 src/ui/rollback-view.ts，契约里已有），**绝不**从 `added === 0` 反推删除 ——
+ * 一个文件被清空成 0 行同样是 `+0 −N`，那是另一件事。
+ */
+function FileStat({ status, added, removed, unknown, deleted, rt }: {
+  status: string
+  added: number | null
+  removed: number | null
+  unknown: string
+  /** 「删除」这一句（调用点传已翻译文本，本组件不碰字典键）。 */
+  deleted: string
+  rt: TranslateNS<'config-manager-recovery'>
+}) {
+  if (status === 'delete') return <span className={css.rollbackDeleted}>{deleted}</span>
+  if (added === null || removed === null) return <span className={css.hint}>{unknown}</span>
+  return (
+    <>
+      <span className={css.rollbackAdded}>{rt(rk('rollback.preview.file.added'), { n: String(added) })}</span>
+      <span className={css.rollbackRemoved}>{rt(rk('rollback.preview.file.removed'), { n: String(removed) })}</span>
+    </>
+  )
+}
+
+/** 文件清单（改动行 + 删除行）。两处调用共用这一份渲染。 */
+export function RollbackFileChanges({ files, removals, rt, view, renderFileIcon }: RollbackFileChangesProps) {
+  return (
+    <div className={css.rollbackFileList} role="list">
+      {files.map((file, index) => {
+        // 目录弱化 + 基名主色：只画基名时 `.git/index` 读不出「在哪」。
+        const { dir, base } = splitRollbackPath(file.path)
+        const label = (
+          <>
+            {dir !== '' && <span className={css.rollbackFileDir}>{dir}</span>}
+            {base}
+          </>
+        )
+        return (
+          <div
+            key={rollbackPreviewFileKey(file.path, file.added, file.removed, index)}
+            className={css.rollbackFileRow}
+            role="listitem"
+            data-kind={previewFileStatusKnown(file.status) ? file.status : undefined}
+          >
+            {/* 文件类型图标（DSH 文件树同一颗）。装饰性：行内文件名就是它的可访问名。 */}
+            <span className={css.rollbackFileIcon} aria-hidden="true">
+              <RollbackFileIcon path={file.path} size={14} render={renderFileIcon} />
+            </span>
+            {/* 主标签 = 目录（弱化）+ 文件名（主色）。给了 `view` 时**它本身就是那颗按钮**
+                （2026-10-12 用户要求：不要尾部的独立「查看」按钮，点文件名直接跳）。
+                为什么按钮不是整行：整行做热区会把右侧 `+N −M` 也变成可点区域，鼠标停在统计上
+                像是要点它；这里只有名字/目录可点，统计永远点不到。完整路径仍在 title 里。 */}
+            {view === undefined ? (
+              <span className={`${css.rollbackFilePath} ${css.mono}`} title={file.path}>{label}</span>
+            ) : (
+              <button
+                type="button"
+                className={`${css.rollbackFilePath} ${css.mono}`}
+                title={file.path}
+                aria-label={view.hint(file.path)}
+                disabled={view.disabled}
+                onClick={() => { view.onView(file.path) }}
+              >
+                {label}
+              </button>
+            )}
+            {/* ±行数紧跟文件名（统计列右对齐、列宽固定）：三种取值的右缘对齐成一条竖线。 */}
+            <span className={css.rollbackFileStat}>
+              <FileStat
+                status={file.status}
+                added={file.added}
+                removed={file.removed}
+                unknown={rt('rollback.preview.file.unknown')}
+                deleted={rt(rk('rollback.preview.file.deleted'))}
+                rt={rt}
+              />
+            </span>
+          </div>
+        )
+      })}
+      {removals.map((path, index) => {
+        const { dir, base } = splitRollbackPath(path)
+        return (
+          <div
+            key={'remove:' + rollbackPreviewFileKey(path, null, null, index)}
+            className={css.rollbackFileRow}
+            role="listitem"
+            data-kind="delete"
+          >
+            <span className={css.rollbackFileIcon} aria-hidden="true">
+              <RollbackFileIcon path={path} size={14} render={renderFileIcon} />
+            </span>
+            {/* 删除行**不是按钮**（纯文本）：见文件头「诚实边界」第 1 条。 */}
+            <span className={`${css.rollbackFilePath} ${css.mono}`} title={path}>
+              {dir !== '' && <span className={css.rollbackFileDir}>{dir}</span>}
+              {base || rollbackPreviewFileLabel(path)}
+            </span>
+            <span className={css.rollbackFileStat}>
+              <span className={css.rollbackDeleted}>{rt(rk('rollback.preview.file.deleted'))}</span>
+            </span>
+          </div>
+        )
+      })}
+    </div>
+  )
+}

package/src/client/recovery/incident-api.ts

@@ -13,7 +13,7 @@
  * 安全约束：错误文本由 Host 侧脱敏；进入救援模式是高风险写盘动作，confirm 必须由调用方在
  * 显式确认弹窗后传入 —— 本层绝不代填。本文件不 import 任何 node 模块（纯浏览器 bundle）。
  */
-import { zhUiT, type UiT } from '../../ui/i18n.ts'
+import type { UiT } from '../../ui/i18n.ts'
 import { getJson, LONG_REQUEST_TIMEOUT_MS, postJson, type RequestOptions } from '../common/http.ts'
 import { INCIDENT_API } from '../common/routes.ts'
 
@@ -62,7 +62,7 @@ export interface RescueActionResult {
 /** 事故恢复（崩溃归因 + 救援模式）浏览器半数据入口。 */
 export class IncidentApi {
   readonly t: UiT
-  constructor(t: UiT = zhUiT) {
+  constructor(t: UiT) {
     this.t = t
   }
 

package/src/client/recovery/recovery-api.ts

@@ -16,6 +16,12 @@
  * POST /api/dsh-config-manager/recovery/lock/recover            → RecoveryLockRecoverResult
  * POST /api/dsh-config-manager/recovery/safe-mode/clear         → RecoverySafeModeClearResult
  * POST /api/dsh-config-manager/recovery/sessions/layout         → SessionLayoutPlanView | SessionLayoutApplyView
+ * GET  /api/dsh-config-manager/recovery/rollback-points              → RollbackListResult
+ * GET  /api/dsh-config-manager/recovery/rollback-points/storage      → RollbackStorageStatus
+ * GET  /api/dsh-config-manager/recovery/rollback-points/<id>         → RollbackDetailResult
+ * GET  /api/dsh-config-manager/recovery/rollback-points/<id>/preview → RollbackPreviewResult
+ * POST /api/dsh-config-manager/recovery/rollback-points/<id>/rewind  → RollbackRewindResult
+ * POST /api/dsh-config-manager/recovery/rollback-points/<id>/delete  → RollbackRemoveResult
  * ```
  *
  * 安全约束（§9.4 / §11）：
@@ -35,9 +41,22 @@ import type {
   SessionRepairResult,
   SessionRepairRollbackResult,
 } from '../../ui/session-inventory-view.ts';
-import type { SessionLayoutResponse } from '../../ui/session-layout-view.ts';
+import type { SessionLayoutResponse } from '../../ui/session-layout-view.ts'
+import type {
+  RollbackDetailResult,
+  RollbackFileDiffResult,
+  RollbackListResult,
+  RollbackPointPort,
+  RollbackPreviewResult,
+  RollbackRemoveResult,
+  RollbackRewindOptions,
+  RollbackRewindResult,
+  RollbackPrefsResult,
+  RollbackPurgeResult,
+  RollbackStorageStatus,
+} from '../../ui/rollback-view.ts';
 import { ConfigManagerApiError, getJson, LONG_REQUEST_TIMEOUT_MS, postJson, type RequestOptions } from '../common/http.ts';
-import { zhUiT, type UiT } from '../../ui/i18n.ts';
+import type { UiT } from '../../ui/i18n.ts';
 import { RECOVERY_API } from '../common/routes.ts';
 
 /** recovery 端点常量：**唯一来源** = `common/routes.ts`（W4 单点化），此处重导出保持导入面。 */
@@ -49,7 +68,25 @@ const RECOVERY_OPTS: RequestOptions = { timeoutMs: LONG_REQUEST_TIMEOUT_MS, time
 /* 请求封装（readJson / getJson / postJson：统一超时 + 取消 + 错误映射）见 common/http.ts。 */
 
 /** operationId 严格 UUID 校验（与 Host 侧 isValidOperationId 一致；防路径穿越）。 */
-const OPERATION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const OPERATION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/**
+ * rollback-point 台账 id → 子路径。
+ *
+ * 只接受 `[A-Za-z0-9._-]{1,128}`：id 是宿主生成的，这里**只做形态收窄**（与 operationId 的
+ * UUID 校验同一条理由 —— 防路径穿越）；不合形态的 id 直接抛，**绝不回显原始 id**、绝不拼进 URL
+ * 让宿主去兜。路径由 `RECOVERY_API.rollbackPoints` **派生**（路由常量是唯一来源；源码级守卫
+ * `http-usage-guard` 也只允许 `common/routes.ts` 出现 `/api/dsh-config-manager…` 字面量）。
+ */
+const ROLLBACK_POINT_ID_RE = /^[A-Za-z0-9._-]{1,128}$/
+function rollbackPointUrl(id: string): string {
+  if (!ROLLBACK_POINT_ID_RE.test(id)) throw new Error('rollback point id invalid')
+  return RECOVERY_API.rollbackPoints + '/' + id
+}
+
+function rollbackPointPath(id: string, sub: string): string {
+  return rollbackPointUrl(id) + '/' + sub
+}
 
 /**
  * E2：`POST /recovery/sessions/layout`（布局归位 / 重复 id 隔离）。
@@ -67,10 +104,10 @@ function operationPath(operationId: string, action: string): string {
   return `${RECOVERY_API.base}/${operationId}/${action}`;
 }
 
-/** Recovery 浏览器半数据入口（实现 RecoveryPort 契约）。 */
-export class RecoveryApi implements RecoveryPort {
+/** Recovery 浏览器半数据入口（实现 RecoveryPort 契约 + rollback-points 族）。 */
+export class RecoveryApi implements RecoveryPort, RollbackPointPort {
   readonly t: UiT
-  constructor(t: UiT = zhUiT) {
+  constructor(t: UiT) {
     this.t = t
   }
 
@@ -106,6 +143,107 @@ export class RecoveryApi implements RecoveryPort {
     return postJson<SessionRepairResult>(RECOVERY_API.sessionsRepair, body, this.t, RECOVERY_OPTS)
   }
 
+  /* ------------------------------------------------- S7 rollback-points（工作区 + 会话回滚，两态） */
+
+  /**
+   * GET /recovery/rollback-points：台账列表（按时间倒序）+ 存储栈状态 + 留存上限。
+   *
+   * 列表本身**只读**：SAFE MODE 下也能看（宿主侧只有 rewind / delete 被 423 拦下），
+   * 因此界面必须能「看得见、但按钮说明为什么点不了」。
+   * 存储栈不可用时宿主回 **503 + 同体**（`storage.available=false` + guidance）；`getJson` 对非 2xx
+   * 抛 `ConfigManagerApiError`（`status`=503，`code` 取响应体 code），调用方按 status 区分「读不出来」
+   * 与「本来就没有」。
+   */
+  async rollbackPoints(): Promise<RollbackListResult> {
+    return getJson<RollbackListResult>(RECOVERY_API.rollbackPoints, this.t, RECOVERY_OPTS)
+  }
+
+  /** GET /recovery/rollback-points/storage：存储栈探针（不可用 → 503 + guidance，同上）。 */
+  async rollbackPointStorage(): Promise<RollbackStorageStatus> {
+    return getJson<RollbackStorageStatus>(RECOVERY_API.rollbackPointsStorage, this.t, RECOVERY_OPTS)
+  }
+
+  /** GET /recovery/rollback-points/<id>：单条详情（不存在 → 404 `record-not-found`）。 */
+  async rollbackPoint(id: string): Promise<RollbackDetailResult> {
+    return getJson<RollbackDetailResult>(rollbackPointUrl(id), this.t, RECOVERY_OPTS)
+  }
+
+  /**
+   * GET /recovery/rollback-points/<id>/preview：**只读预览（零写入）**。
+   *
+   * 回传两态将覆盖多少项、其中多少项内容不同、多少项当前已不存在、多少项是该点**未记录**的
+   * （`removals` = 会被删除的、`createdSkipped` = 按安全判据拒删的；两者都只是**读回来的清单**，
+ * 本方法零写入），以及会话边界（from → to）与回合号；`canRestore` / `canRemove`
+   * 是宿主给出的权威判定，界面据此决定按钮可用性（展示判定见 `src/ui/rollback-view.ts`）。
+   */
+  async rollbackPointPreview(id: string): Promise<RollbackPreviewResult> {
+    return getJson<RollbackPreviewResult>(rollbackPointPath(id, 'preview'), this.t, RECOVERY_OPTS)
+  }
+
+  /**
+   * GET /recovery/rollback-points/<id>/file-diff?path=...：**单个记录在案文件**的前后逐行对照。
+   *
+   * 只读、零写入；路径以 query 传递（宿主内再收窄一次：未命中该点记录一律 `file-not-recorded`，
+   * 一个字节都不读）。非 2xx（存储栈 503 / 参数 400）由 getJson 抛 ConfigManagerApiError，
+   * 由调用方按 status + code 出文案。
+   */
+  async rollbackPointFileDiff(id: string, path: string): Promise<RollbackFileDiffResult> {
+    const query = '?path=' + encodeURIComponent(path)
+    return getJson<RollbackFileDiffResult>(rollbackPointPath(id, 'file-diff') + query, this.t, RECOVERY_OPTS)
+  }
+
+  /**
+   * POST /recovery/rollback-points/<id>/rewind：回退（工作区文件覆盖 + 会话 fork 子会话）。
+   *
+   * **确认门是 fail-closed**：`userConfirmed` 必须**恰好** true（宿主缺省 / 假值一律
+   * 409 `confirmation-required` + 零写入）。本方法绝不自动置 true —— 由确认弹窗的 onClick 传进来。
+   * 409（confirmation-required / protected-point / record-incomplete）与 423（mutation-locked）
+   * 都以 `ConfigManagerApiError` 抛出，`status` / `code` 保留，界面按 code 出文案（不靠状态码猜原因）。
+   * 会话回退 **不改写原会话日志**：结果里回传 `childSessionId`（新子会话），原会话只读。
+   */
+  async restoreRollbackPoint(id: string, opts: RollbackRewindOptions): Promise<RollbackRewindResult> {
+    const body: Record<string, unknown> = { userConfirmed: opts.userConfirmed === true }
+    if (opts.mode !== undefined) body['mode'] = opts.mode
+    if (opts.segments !== undefined && opts.segments.length > 0) body['segments'] = [...opts.segments]
+    if (opts.allowPartial === true) body['allowPartial'] = true
+    if (opts.preRewindGuard !== undefined) body['preRewindGuard'] = opts.preRewindGuard
+    return postJson<RollbackRewindResult>(rollbackPointPath(id, 'rewind'), body, this.t, RECOVERY_OPTS)
+  }
+
+  /**
+   * POST /recovery/rollback-points/<id>/delete：删除一个回滚点（保护点由宿主拒绝）。
+   * body 必须 `userConfirmed: true`（未确认 → 409 `confirmation-required`）；本方法不自动置 true。
+   */
+  async removeRollbackPoint(id: string, userConfirmed: boolean): Promise<RollbackRemoveResult> {
+    return postJson<RollbackRemoveResult>(rollbackPointPath(id, 'delete'), { userConfirmed: userConfirmed === true }, this.t, RECOVERY_OPTS)
+  }
+
+  /**
+   * GET /recovery/rollback-points/prefs（issue #88）：读开关。
+   * `rollbackEnabled` = 磁盘偏好（用户意图，随 self 分区进备份）；
+   * `rollbackActive` = 本进程此刻是否真的在留点（关闭后订阅已解绑）。两者正常一致。
+   */
+  async rollbackPrefs(): Promise<RollbackPrefsResult> {
+    return getJson<RollbackPrefsResult>(RECOVERY_API.rollbackPointsPrefs, this.t, RECOVERY_OPTS)
+  }
+
+  /**
+   * POST /recovery/rollback-points/prefs（issue #88）：写开关。
+   * 宿主写盘成功后才切进程 gate —— 写失败却把功能打开，等于「界面说开着、实际不留点」。
+   */
+  async setRollbackEnabled(enabled: boolean): Promise<RollbackPrefsResult> {
+    return postJson<RollbackPrefsResult>(RECOVERY_API.rollbackPointsPrefs, { rollbackEnabled: enabled === true }, this.t, RECOVERY_OPTS)
+  }
+
+  /**
+   * POST /recovery/rollback-points/cleanup（issue #89）：清理台账占用。
+   * **只删自动点**；`includeGuards` 为 true 时连救援点也删（protected 永不删）。
+   * 返回逐类删除计数与释放字节，界面照实说「删了多少 / 还剩多少」。
+   */
+  async purgeRollbackPoints(opts: { includeGuards: boolean }): Promise<RollbackPurgeResult> {
+    return postJson<RollbackPurgeResult>(RECOVERY_API.rollbackPointsCleanup, { userConfirmed: true, includeGuards: opts.includeGuards === true }, this.t, RECOVERY_OPTS)
+  }
+
   /** POST /recovery/sessions/rollback（T8）：按台账 repairId 回滚（客户端不传路径）。 */
   async rollbackSessionRepair(repairId: string): Promise<SessionRepairRollbackResult> {
     return postJson<SessionRepairRollbackResult>(RECOVERY_API.sessionsRollback, { repairId }, this.t, RECOVERY_OPTS)