dsh-manage-session 0.1.0-alpha.0 → 0.2.3

package/lib/index.d.ts

@@ -1,9 +1,9 @@
-//#region node_modules/.pnpm/cosmokit@1.8.1/node_modules/cosmokit/lib/index.d.ts
+//#region node_modules/cosmokit/lib/index.d.ts
 type Dict<T = any, K extends string | symbol = string> = { [key in K]: T; };
 type Promisify<T> = Promise<T extends Promise<infer S> ? S : T>;
 type Awaitable<T> = [T] extends [Promise<unknown>] ? T : T | Promise<T>;
 //#endregion
-//#region node_modules/.pnpm/@standard-schema+spec@1.1.0/node_modules/@standard-schema/spec/dist/index.d.ts
+//#region node_modules/@standard-schema/spec/dist/index.d.ts
 /** The Standard Typed interface. This is a base type extended by other specs. */
 interface StandardTypedV1<Input = unknown, Output = Input> {
   /** The Standard properties. */
@@ -80,7 +80,7 @@ declare namespace StandardSchemaV1 {
   type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
 }
 //#endregion
-//#region node_modules/.pnpm/cordis@4.0.0-rc.10/node_modules/cordis/lib/utils.d.ts
+//#region node_modules/cordis/lib/utils.d.ts
 declare class DisposableList<T extends WeakKey> {
   private sn;
   private map;
@@ -112,7 +112,7 @@ declare const symbols: {
   resolveConfig: typeof Service.resolveConfig;
 };
 //#endregion
-//#region node_modules/.pnpm/cordis@4.0.0-rc.10/node_modules/cordis/lib/registry.d.ts
+//#region node_modules/cordis/lib/registry.d.ts
 type Inject<M = Dict> = (keyof M)[] | { [K in keyof M]?: M[K]; };
 type InjectKey = keyof { [K in keyof Context & string as Context[K] extends {
   [symbols.config]: any;
@@ -182,7 +182,7 @@ declare class RegistryService {
   plugin(plugin: Plugin, config?: any, getOuterStack?: () => string[]): Fiber & PromiseLike<Fiber>;
 }
 //#endregion
-//#region node_modules/.pnpm/cordis@4.0.0-rc.10/node_modules/cordis/lib/reflect.d.ts
+//#region node_modules/cordis/lib/reflect.d.ts
 declare module './context' {
   interface Context {
     get<K extends string & keyof this>(name: K, strict?: boolean): undefined | this[K];
@@ -230,7 +230,7 @@ declare class ReflectService {
   bind<T extends Function>(callback: T): T;
 }
 //#endregion
-//#region node_modules/.pnpm/cordis@4.0.0-rc.10/node_modules/cordis/lib/fiber.d.ts
+//#region node_modules/cordis/lib/fiber.d.ts
 declare module './context' {
   interface Context extends Pick<Fiber, 'effect'> {
     fiber: Fiber;
@@ -291,7 +291,7 @@ declare class Fiber {
   update(config: any, noSave?: boolean): Awaitable<void>;
 }
 //#endregion
-//#region node_modules/.pnpm/cordis@4.0.0-rc.10/node_modules/cordis/lib/events.d.ts
+//#region node_modules/cordis/lib/events.d.ts
 type Parameters<F> = F extends ((...args: infer P) => any) ? P : never;
 type ReturnType<F> = F extends ((...args: any) => infer R) ? R : never;
 type ThisType<F> = F extends ((this: infer T, ...args: any) => any) ? T : never;
@@ -349,7 +349,7 @@ interface Events {
   'internal/dispatch'(mode: DispatchMode, name: string | symbol, args: any[], thisArg: any): void;
 }
 //#endregion
-//#region node_modules/.pnpm/cordis@4.0.0-rc.10/node_modules/cordis/lib/logger.d.ts
+//#region node_modules/cordis/lib/logger.d.ts
 declare module './context' {
   interface Intercept {
     logger: LoggerService.Intercept;
@@ -411,7 +411,7 @@ declare class LoggerService {
   [symbols.invoke](name?: string): Logger;
 }
 //#endregion
-//#region node_modules/.pnpm/cordis@4.0.0-rc.10/node_modules/cordis/lib/context.d.ts
+//#region node_modules/cordis/lib/context.d.ts
 interface Context {
   [symbols.isolate]: Dict<symbol>;
   [symbols.intercept]: Dict;
@@ -438,7 +438,7 @@ declare class Context {
   intercept(name: string, config: any): this;
 }
 //#endregion
-//#region node_modules/.pnpm/cordis@4.0.0-rc.10/node_modules/cordis/lib/service.d.ts
+//#region node_modules/cordis/lib/service.d.ts
 declare abstract class Service<out T = never> {
   protected ctx: Context;
   static readonly init: unique symbol;
@@ -469,7 +469,7 @@ declare abstract class Service<out T = never> {
 interface StewardConfig {
   /** 插件总开关。 */
   enabled: boolean;
-  /** 会话历史文件（归档浏览与清理）。关闭后不注册 history 路由、不渲染「病案室」页签。 */
+  /** 会话历史文件（归档浏览与清理）。关闭后不注册 history 路由、不渲染「养老院」页签。 */
   historyFiles?: boolean;
   /** 会话健康检查（体检 → 处方 → 出院）。关闭后不注册 health 路由、不渲染「体检」页签。 */
   healthCheck?: boolean;
@@ -486,6 +486,13 @@ declare const STEWARD_API_PREFIX = "/session-steward/api";
 interface StewardArchiveRead {
   ids: readonly string[];
   source: 'registry' | 'storage-file' | 'none';
+  /**
+   * 宿主内存 registry 里的同一集合（尽力而为，读不到时缺省）。
+   *
+   * 与 `ids` 的差集 = 「已从存储文件移除、但本进程仍生效」的悬挂项：
+   * registry 是宿主启动时载入的快照，prune 写不到它，重启才会重载。
+   */
+  registryIds?: readonly string[];
 }
 /** workspaceRegistry 镜像面（只读 getter）。 */
 interface StewardRegistryFace {
@@ -493,17 +500,44 @@ interface StewardRegistryFace {
 }
 /**
  * 解析一次官方归档集合。
+ *
+ * **存储文件优先**：prune 唯一能改的就是这份文件，列表必须与「能被改的那份」
+ * 同源，否则清理成功后面板看起来毫无变化 —— 宿主 registry 是进程启动时的快照，
+ * 直接编辑文件不会回写它，于是「文件在瘦身、列表纹丝不动」。
+ * registry 退居为文件缺失时的兜底，同时作为诊断面（`registryIds`）返回。
  * @param registry - 惰性 workspaceRegistry 面（可能缺失或抛错）。
  * @param searchPaths - 可选候选路径覆盖（DSH_HOME 非默认值或测试注入时使用）。
- * @returns 归档 ids 以及服务它的来源。
+ * @returns 归档 ids、服务它的来源，以及宿主内存里的同一集合。
  */
 declare function readArchiveSet(registry?: StewardRegistryFace, searchPaths?: readonly string[]): StewardArchiveRead;
+/** 一次存储文件编辑的结果。 */
+type StewardEditOutcome = {
+  ok: true;
+  changed: boolean;
+  file: string;
+} | {
+  ok: false;
+  reason: string;
+};
 /**
- * 从存储中枢的 global.archivedSessionIds 中移除会话 id。
+ * **本插件写 workspace.json 的唯一入口。**
+ *
+ * 任何「改归档集合 / 改工作区成员表」都必须走这里 —— 出现第二个写文件的实现，
+ * 就会重现「读的人和写的人不是同一份数据」那类问题。
  *
- * 官方后端没有 unarchive 端点，因此直接编辑规范文件，遵循 storage-json 自身的协议：
- * 备份、同目录临时写入、改名。运行中的宿主把集合留在内存里、只在启动时重载 ——
- * 调用方必须提示需要重启 DSH。
+ * 协议与 storage-json 自身一致：读 → `edit(document)` 就地改 → 备份 → 同目录临时写入
+ * → 原子改名。`edit` 返回 `false` 表示无需写入（此时**不产生备份**）。
+ * @param path - 规范存储文件路径。
+ * @param edit - 就地修改文档；返回是否真的改了。
+ * @param log - 可选日志出口。
+ * @returns 编辑结果；失败时给出原因而非抛错。
+ */
+declare function editWorkspaceDocument(path: string, edit: (document: Record<string, unknown>) => boolean, log?: (msg: string) => void): StewardEditOutcome;
+/**
+ * 从存储中枢的 `global.archivedSessionIds` 中移除会话 id（= 取消归档状态）。
+ *
+ * 官方后端没有 unarchive 端点，因此直接编辑规范文件；运行中的宿主把集合留在内存里、
+ * 只在启动时重载 —— 调用方必须提示需要重启 DSH。
  * @param ids - 要从归档数组中移除的会话 id。
  * @param log - 可选日志出口。
  * @param searchPaths - 可选候选路径覆盖（测试注入用）。
@@ -515,61 +549,6 @@ declare function pruneArchiveFile(ids: readonly string[], log?: (msg: string) =>
   file?: string;
 };
 //#endregion
-//#region src/host/history/archive.d.ts
-/** 一行历史文件条目（尽力而为的元数据）。 */
-interface StewardHistoryRow {
-  sessionId: string;
-  title: string;
-  cwd: string;
-  updatedAt: number;
-}
-/** 列表结果。 */
-interface StewardHistoryListResult {
-  ok: boolean;
-  items?: StewardHistoryRow[];
-  /** 归档集合来源；`none` 表示两处都没读到。 */
-  source?: 'registry' | 'storage-file' | 'none';
-  /** 元数据降级原因（标题/cwd 缺失时给出）。 */
-  degraded?: string;
-  error?: string;
-}
-/** 标题快照读取面（结构化镜像，零 value import）。 */
-interface StewardTitleQueryFace {
-  readTitleSnapshots?(ids: readonly string[]): Promise<readonly {
-    status: 'fulfilled' | 'rejected';
-    value?: {
-      title?: {
-        title: string;
-      };
-    };
-  }[]>;
-}
-/**
- * `session-history-list`：列出官方归档集合（尽力附带标题等元数据）。
- * @param getRegistry - 惰性 workspaceRegistry 面。
- * @param query - 可选标题快照面。
- * @param searchPaths - 可选存储文件候选路径（DSH_HOME 非默认值/测试注入）。
- * @returns 归档行清单。
- */
-declare function listHistory(getRegistry: () => StewardRegistryFace | undefined, query?: StewardTitleQueryFace, searchPaths?: readonly string[]): Promise<StewardHistoryListResult>;
-/** 清理结果。 */
-interface StewardHistoryPruneResult {
-  ok: boolean;
-  removed?: number;
-  remaining?: number;
-  requiresRestart?: boolean;
-  error?: string;
-}
-/**
- * `session-history-prune`：从官方归档数组中批量移除会话 id。
- * 行为与迁移前等价：校验入参 → 备份并原子替换存储文件 → 返回 removed/remaining，
- * 并明确要求重启 DSH（宿主内存中的集合只在启动时重载）。
- * @param payload - `{ sessionIds: string[] }`。
- * @param log - 可选日志出口。
- * @param searchPaths - 可选候选路径覆盖（测试注入用）。
- */
-declare function pruneHistory(payload: unknown, log?: (msg: string) => void, searchPaths?: readonly string[]): StewardHistoryPruneResult;
-//#endregion
 //#region src/host/health/decode.d.ts
 /** 一次读取的统计与问题清单。 */
 interface SessionLogRead {
@@ -631,8 +610,21 @@ declare function decodeSessionLogBytes(file: string, bytes: Buffer, decoders?: O
 declare function decodeSessionLogFile(file: string, decoders?: OfficialDecoders): SessionLogRead;
 //#endregion
 //#region src/host/health/gates.d.ts
-/** gate 严重级。 */
-type GateLevel = 'ok' | 'warn' | 'fail';
+/**
+ * gate 严重级。
+ *
+ * 判定标准（新增 gate 必须遵守）：
+ * - `ok`：判定通过；
+ * - `warn`：**观测到了**异常现象，但尚不致命（必须有可复现的观测依据）；
+ * - `fail`：观测到硬损坏，判定不通过；
+ * - `skipped`：**无从观测/无从判定**（冷态会话没有热态投影、缓存记录尚未生成、
+ *   日志里没有 turn/end 可判）——中性档，不抬升会话总判。
+ *
+ * 关键区分：把「无法判定」记成 `warn` 是错的。那会让所有无从观测的会话恒为
+ * 「注意」，真信号被淹没（实测事故：30 条会话全标「注意」）。
+ * 无从观测 ⇒ `skipped`，有观测依据 ⇒ `warn`。
+ */
+type GateLevel = 'ok' | 'warn' | 'fail' | 'skipped';
 /** 归属信息：把失败字段指回具体插件包与字段路径。 */
 interface GateAttribution {
   /** 投影 key（例如 liveTokenStats）。 */
@@ -712,6 +704,198 @@ declare function gateColdRead(facts: TailFacts): GateResult;
 /** 聚合四门结果为一份报告。 */
 declare function buildSessionReport(context: GateContext): SessionHealthReport;
 //#endregion
+//#region src/host/health/cache.d.ts
+/** 一份已成型的缓存。 */
+interface HealthCacheEntry {
+  /** 非 ok 的会话报告（与 `onlyProblems: true` 的扫描结果同构）。 */
+  findings: SessionHealthReport[];
+  /** 生成这份缓存时的语料总数（用于「语料已变化」判断）。 */
+  total: number;
+  /** 生成时刻（epoch ms）。面板据此显示「N 分钟前」。 */
+  generatedAt: number;
+}
+/** 进程内体检缓存：分批扫描过程中累积，走完一遍语料才成型。 */
+declare class HealthCache {
+  private ready;
+  private pending;
+  /** 读当前成型的缓存（未成型则 undefined）。 */
+  read(): HealthCacheEntry | undefined;
+  /** 开始一轮分批扫描（客户端以 `offset: 0` 发起时调用）。 */
+  begin(total: number): void;
+  /**
+   * 追加一批扫描结果。
+   *
+   * 只有累积的已访问数走满语料总数才成型；语言中途断掉（关面板、报错）不会留下
+   * 半份缓存冒充完整结果。
+   * @param findings - 本批的非 ok 报告。
+   * @param scanned - 本批**已访问**的会话数（不是命中数）。
+   * @param now - 时间源（测试可控）。
+   * @returns 本批追加后缓存是否刚好成型。
+   */
+  append(findings: SessionHealthReport[], scanned: number, now?: () => number): boolean;
+  /**
+   * 单条就地回写（单会话体检 / 可逆处置后调用）。
+   *
+   * 这是缓存的**关键收益**：处置本就重算了 `after` 报告，把它写回即可，
+   * 不必为了刷新一行而重扫整个语料。
+   * @param report - 重算出的单会话报告。
+   * @returns 是否真的改动了缓存（无缓存时为 false）。
+   */
+  patch(report: SessionHealthReport): boolean;
+  /** 丢弃缓存与未完成的累积。 */
+  clear(): void;
+}
+//#endregion
+//#region src/host/history/archive.d.ts
+/** 一行历史文件条目（尽力而为的元数据 + 磁盘占用）。 */
+interface StewardHistoryRow {
+  sessionId: string;
+  title: string;
+  cwd: string;
+  updatedAt: number;
+  /** 转录目录占用字节数（未知/未解析时为 0）。 */
+  bytes: number;
+  /** 投影缓存占用字节数。 */
+  cacheBytes: number;
+}
+/** 列表结果。 */
+interface StewardHistoryListResult {
+  ok: boolean;
+  items?: StewardHistoryRow[];
+  /** 归档集合来源；`none` 表示两处都没读到。 */
+  source?: 'registry' | 'storage-file' | 'none';
+  /** 元数据降级原因（标题/cwd 缺失时给出）。 */
+  degraded?: string;
+  /**
+   * 已从存储文件移除、但宿主内存 registry 里仍生效的 id 数。
+   *
+   * 大于 0 时列表展示的是**存储文件真值**（已不含这些 id），但它们在本进程内
+   * 仍然隐藏着对应会话 —— 面板据此提示「需重启 DSH 才彻底消失」。
+   */
+  pendingRestart?: number;
+  error?: string;
+}
+/** 标题快照读取面（结构化镜像，零 value import）。 */
+interface StewardTitleQueryFace {
+  readTitleSnapshots?(ids: readonly string[]): Promise<readonly {
+    status: 'fulfilled' | 'rejected';
+    value?: {
+      title?: {
+        title: string;
+      };
+    };
+  }[]>;
+}
+/**
+ * `session-history-list`：列出官方归档集合（尽力附带标题等元数据）。
+ * @param getRegistry - 惰性 workspaceRegistry 面。
+ * @param query - 可选标题快照面。
+ * @param searchPaths - 可选存储文件候选路径（DSH_HOME 非默认值/测试注入）。
+ * @returns 归档行清单。
+ */
+declare function listHistory(getRegistry: () => StewardRegistryFace | undefined, query?: StewardTitleQueryFace, searchPaths?: readonly string[], dshHome?: string): Promise<StewardHistoryListResult>;
+/** 清理结果。 */
+interface StewardHistoryPruneResult {
+  ok: boolean;
+  removed?: number;
+  remaining?: number;
+  requiresRestart?: boolean;
+  error?: string;
+}
+/**
+ * `session-history-prune`：从官方归档数组中批量移除会话 id。
+ * 行为与迁移前等价：校验入参 → 备份并原子替换存储文件 → 返回 removed/remaining，
+ * 并明确要求重启 DSH（宿主内存中的集合只在启动时重载）。
+ * @param payload - `{ sessionIds: string[] }`。
+ * @param log - 可选日志出口。
+ * @param searchPaths - 可选候选路径覆盖（测试注入用）。
+ */
+declare function pruneHistory(payload: unknown, log?: (msg: string) => void, searchPaths?: readonly string[]): StewardHistoryPruneResult;
+//#endregion
+//#region src/host/history/purge.d.ts
+/** 一个归档会话在磁盘上的实体与占用。 */
+interface StewardSessionUsage {
+  sessionId: string;
+  /** 转录目录绝对路径（不存在时缺省）。 */
+  dir?: string;
+  /** 转录目录占用字节数。 */
+  bytes: number;
+  /** 投影缓存文件绝对路径（不存在时缺省）。 */
+  cacheFile?: string;
+  /** 投影缓存占用字节数。 */
+  cacheBytes: number;
+}
+/** 转录根目录（`<dshHome>/sessions`）。 */
+declare function sessionsRootFor(dshHome: string): string;
+/**
+ * 投影缓存（**逐条布局**）根目录。
+ *
+ * 注意另有一个 `<dshHome>/storages/session_projcache.json`（整份布局）——
+ * 那是布局迁移留下的**化石**，宿主早已不再写它，本插件也不碰它。
+ */
+declare function projCacheRootFor(dshHome: string): string;
+/**
+ * 扫一遍转录根，建立「会话 id → 目录」索引。
+ *
+ * 同一个 id 同时存在带前缀与不带前缀的目录时，**优先带 `session-` 前缀的那个**
+ * （归档集合里的 id 本身带前缀）。
+ * @param sessionsRoot - `<dshHome>/sessions`。
+ * @returns 归一化 id → 目录绝对路径。
+ */
+declare function indexSessionDirs(sessionsRoot: string): Map<string, string>;
+/** 递归求目录占用字节数（读不到的条目跳过，不抛错）。 */
+declare function dirSize(dir: string): number;
+/**
+ * 解析一批会话在磁盘上的实体与占用（**只读，不删任何东西**）。
+ *
+ * 列表按行显示体积就走这里 —— 体积差异极大（实测单条缓存可达 23 MB、单条转录可达
+ * 6 MB，也有 0 字节的），报一个总量对用户没有意义。
+ * @param ids - 会话 id（带不带 `session-` 前缀都接受）。
+ * @param dshHome - DSH 主目录。
+ * @returns 会话 id → 实体位置与占用。
+ */
+declare function locateSessionUsage(ids: readonly string[], dshHome: string): Map<string, StewardSessionUsage>;
+/**
+ * 断言目标是 `root` 的**直接子项**（层级也校验）。
+ *
+ * 破坏性操作不能只靠「路径拼对了」—— 拼错一层就是删掉整个 sessions 根。
+ * @param root - 允许的父目录。
+ * @param target - 待删目标。
+ * @param depth - 相对 root 的期望层数。
+ * @returns 是否安全。
+ */
+declare function isSafeChild(root: string, target: string, depth: number): boolean;
+/** 清理结果。 */
+interface StewardHistoryPurgeResult {
+  ok: boolean;
+  /** 成功清理的会话数。 */
+  purged?: number;
+  /** 释放的字节数（转录 + 投影缓存）。 */
+  freedBytes?: number;
+  /** 逐条失败原因；不阻断其余条目。 */
+  failures?: {
+    sessionId: string;
+    reason: string;
+  }[];
+  requiresRestart?: boolean;
+  error?: string;
+}
+/** 清理选项。 */
+interface StewardPurgeOptions {
+  /** DSH 主目录；**缺失时拒绝执行**（破坏性操作不接受猜测的路径）。 */
+  dshHome?: string;
+  /** workspace.json 候选路径覆盖（测试注入用）。 */
+  searchPaths?: readonly string[];
+}
+/**
+ * `session-history-purge`：**真删除**归档会话的磁盘实体，并连带取消其归档状态。
+ * @param payload - `{ sessionIds: string[] }`。
+ * @param log - 可选日志出口。
+ * @param options - `dshHome` 必填；`searchPaths` 可选覆盖。
+ * @returns 清理条数、释放字节数与逐条失败。
+ */
+declare function purgeHistory(payload: unknown, log?: (msg: string) => void, options?: StewardPurgeOptions): StewardHistoryPurgeResult;
+//#endregion
 //#region src/host/health/lossless.d.ts
 /**
  * 无损 JSON 判定 —— 本次事故的核心 gate 判据。
@@ -790,6 +974,44 @@ declare function quarantineProjectionCache(sessionId: string, dshHome?: string,
  * @returns 可复制执行的命令与人读说明。
  */
 declare function prescribe(report: SessionHealthReport, dshHome?: string): string[];
+/** 处置结果的定性分类。 */
+type RepairVerdict =
+/** 四门全绿，没有要做的事。 */
+'nothing-to-do' |
+/** 处置生效且异常已消除。 */
+'repaired' |
+/** 处置生效，但仍有与投影缓存无关的异常（如会话日志的 open step）。 */
+'repaired-with-residual' |
+/** 没有任何可逆处置项能命中当前异常。 */
+'not-applicable' |
+/** 处置本身执行失败。 */
+'failed';
+/** 处置结果的判定。 */
+interface RepairAssessment {
+  verdict: RepairVerdict;
+  /** 人读说明：直接展示给用户，解释「为什么处置后还是异常/已恢复」。 */
+  explanation: string;
+  /** 处置后仍未解决的门（可处置档位）。 */
+  residual: {
+    id: string;
+    level: GateLevel;
+  }[];
+}
+/**
+ * 判定一次处置的结果，并给出人读说明。
+ *
+ * 存在的理由：处置**只**隔离投影缓存记录，而会话的异常可能来自别处
+ * （最典型是 `cold-read` 的 open step——插件红线不改会话日志，这类异常
+ * 本就不该由处置修复）。旧版 UI 只显示 `处置前/处置后` 两个档位，
+ * 两者都是「异常」时用户无法判断是处置失败还是处置与病灶无关。
+ *
+ * @param input - 处置前后的报告与处置执行结果。
+ */
+declare function assessRepair(input: {
+  before: SessionHealthReport;
+  after: SessionHealthReport;
+  repair: RepairOutcome;
+}): RepairAssessment;
 //#endregion
 //#region src/host/health/scan.d.ts
 /** 一个已发现的会话日志。 */
@@ -801,24 +1023,45 @@ interface DiscoveredSession {
 }
 /** 枚举全部会话日志（按 mtime 倒序），带可选上限。 */
 declare function discoverSessions(dshHome?: string, limit?: number): DiscoveredSession[];
+/**
+ * 语料总数：只做目录枚举，**不跑体检**。
+ *
+ * 用于判断缓存是否已过期——枚举很便宜，而重扫要解 zstd、跑四门。
+ * 正因为两者代价差着量级，「对账」才不构成缓存失效策略本身。
+ * @param dshHome - DSH home（缺省 ~/.dsh）。
+ */
+declare function countCorpus(dshHome?: string): number;
 /** 定位一个会话的日志路径（跨工程目录查找）。 */
 declare function findSessionLog(sessionId: string, dshHome?: string): string | undefined;
 /** 扫描结果。 */
 interface HealthScanResult {
   ok: boolean;
+  /** 本批实际体检的会话数（已访问数，不受 onlyProblems 过滤影响）。 */
   scanned: number;
+  /**
+   * 语料总数（进度分母）。分批调用时每批都拿到同一个值，客户端据此算
+   * `已访问 = offset + scanned` / `total`，宿主无需持有跨请求状态。
+   */
+  total: number;
+  /** 本批在语料中的起点（原样回显，便于客户端对账）。 */
+  offset: number;
   findings: SessionHealthReport[];
   /** 仅保留非 ok 的报告时使用。 */
   filtered?: boolean;
   error?: string;
 }
 /**
- * 批量体检。
- * @param options - dshHome / 扫描上限 / 是否只返回非 ok / 归属查询 / 热态状态提供者。
+ * 批量体检（支持分批）。
+ *
+ * 语料先整体列出（按 mtime 倒序，≤ DISCOVERY_LIMIT），再按 `[offset, offset+limit)`
+ * 切片扫描。这样客户端可以用小批次连续调用、自己累计真实进度，而宿主保持无状态
+ * ——不必把同步循环改成异步，也不必新增进度轮询端点。
+ * @param options - dshHome / 批大小 / 批起点 / 是否只返回非 ok / 归属查询 / 热态状态提供者。
  */
 declare function scanSessions(options: {
   dshHome?: string;
   limit?: number;
+  offset?: number;
   onlyProblems?: boolean;
   attribute?: GateContext['attribute'];
   projectionStateFor?: (sessionId: string) => Record<string, unknown> | undefined;
@@ -840,9 +1083,21 @@ interface StewardRuntime {
     field?: string;
   } | undefined;
   log: (message: string) => void;
+  /**
+   * 体检结果缓存（进程内，随 fiber 存活）。
+   *
+   * 可选：缺省表示本次装配不启用缓存（只影响「关面板重开」是否零延迟，
+   * 不影响任何判定结果）。`apply()` 总是提供实例。
+   */
+  cache?: HealthCache;
 }
-/** 支持的路由方法（按子域分组；用于对外声明与测试断言）。 */
-declare const HISTORY_METHODS: readonly ["session-history-list", "session-history-prune"];
+/**
+ * 支持的路由方法（按子域分组；用于对外声明与测试断言）。
+ *
+ * `session-history-prune` 与 `session-history-purge` 是**两件事**，不可合并：
+ * prune = 取消归档状态（可逆，会话回到侧边栏）；purge = 清理归档文件（不可逆，真删实体）。
+ */
+declare const HISTORY_METHODS: readonly ["session-history-list", "session-history-prune", "session-history-purge"];
 declare const HEALTH_METHODS: readonly ["session-health-status", "session-health-scan", "session-health-session", "session-health-repair"];
 /** 依据开关判定某方法是否启用。 */
 declare function methodEnabled(method: string, config: Required<StewardConfig>): boolean;
@@ -859,4 +1114,4 @@ declare function handleMethod(method: string, payload: unknown, runtime: Steward
  */
 declare function apply(ctx: Context): void;
 //#endregion
-export { DEFAULT_CONFIG, HEALTH_METHODS, HISTORY_METHODS, STEWARD_API_PREFIX, STEWARD_SETTINGS_NAMESPACE, type StewardConfig, StewardRuntime, apply, buildProjectionOwnerIndex, buildSessionReport, createAttributor, decodeSessionLogBytes, decodeSessionLogFile, discoverSessions, findSessionLog, firstLosslessViolation, gateColdRead, gateLogIntegrity, gateLosslessJson, gateProjectionCache, handleMethod, inject, isLossless, listHistory, methodEnabled, prescribe, pruneArchiveFile, pruneHistory, quarantineProjectionCache, readArchiveSet, readProjectionCache, readTailFacts, scanSessions, scanZstdFrames };
+export { DEFAULT_CONFIG, HEALTH_METHODS, HISTORY_METHODS, HealthCache, type HealthCacheEntry, type RepairAssessment, type RepairVerdict, STEWARD_API_PREFIX, STEWARD_SETTINGS_NAMESPACE, type StewardConfig, StewardRuntime, apply, assessRepair, buildProjectionOwnerIndex, buildSessionReport, countCorpus, createAttributor, decodeSessionLogBytes, decodeSessionLogFile, dirSize, discoverSessions, editWorkspaceDocument, findSessionLog, firstLosslessViolation, gateColdRead, gateLogIntegrity, gateLosslessJson, gateProjectionCache, handleMethod, indexSessionDirs, inject, isLossless, isSafeChild, listHistory, locateSessionUsage, methodEnabled, prescribe, projCacheRootFor, pruneArchiveFile, pruneHistory, purgeHistory, quarantineProjectionCache, readArchiveSet, readProjectionCache, readTailFacts, scanSessions, scanZstdFrames, sessionsRootFor };