@xrn1997/dsh-session-delete 0.2.0 → 0.2.2

package/lib/types/shared/wire.d.ts

@@ -1,5 +1,5 @@
 /**
- * 跨半 wire 契约：`/dsh-session-delete-api` 的**前缀、五个端点段、请求字段名**——
+ * 跨半 wire 契约：`/dsh-session-delete-api` 的**前缀、六个端点段、请求字段名**——
  * Node 半（`src/api/dispatch.ts` 注册并分发）与浏览器半（`src/client/remote.ts` 同源 fetch）
  * 之间唯一的那份真相。两侧都 import 它，不各写一份字面量。
  *
@@ -22,13 +22,15 @@
  * 撞了就是整棵插件树 boot 失败——所以这条路径是与生态的硬边界，不是显示好不好看的问题。
  */
 export declare const SESSION_DELETE_API_PREFIX = "/dsh-session-delete-api";
-/** 五个段名（相对前缀）。2026-10-17 批量重构：写动词从「一条一段」收成**一段 `/apply`**——
+/** 六个段名（相对前缀）。2026-10-17 批量重构：写动词从「一条一段」收成**一段 `/apply`**——
  *  一次 HTTP 带一组 id、逐条回结果；单条就是长度为 1 的批量，仓里不再留第二条执行路径。
  *  - `GET /list`：**对账并读**清单（`session-trash/` 里的目录是准）。
  *  - `GET /ping`：最便宜的在/不在（不碰清册、不碰盘、不进链）——客户端探测用它，不用一次全表读。
  *  - `POST /detail`：单条详情（用 POST 表达一个读：见设计稿 2026-10-15 §3）。
- *  - `POST /apply`：批量执行一个动作（`delete` / `restore` / `purge` / `count`），逐条回 `ApplyOutcome`。
- *  - `POST /empty`：清空回收站（聚合回执，**不**按条回）。 */
+ *  - `POST /apply`：批量执行一个动作（`delete` / `restore` / `purge` / `count` / `orphan-clean`），逐条回 `ApplyOutcome`。
+ *  - `POST /empty`：清空回收站（聚合回执，**不**按条回）。
+ *  - `GET /orphans`：无主子会话的扫描报告（纯读，2026-10-19）。**清理不在这里**——它是 `/apply` 的
+ *    第五个动作，这一段只负责"有多少、在哪、多大"。 */
 export declare const ROUTES: {
     readonly list: "/list";
     /** 通道的"在不在"专用：没有入参、没有副作用、没有磁盘读。 */
@@ -39,18 +41,23 @@ export declare const ROUTES: {
     readonly apply: "/apply";
     /** 清空回收站。 */
     readonly empty: "/empty";
+    /** 纯读：扫描回收站之外的无主子会话（父已不在语料/清册）。 */
+    readonly orphans: "/orphans";
 };
-/** `/apply` 的四个动作。id 的含义随动作走：`delete`/`count` 是**宿主会话 id**（还没进回收站），
- *  `restore`/`purge` 是**回收站条目 id**。 */
-export type ApplyAction = 'delete' | 'restore' | 'purge' | 'count';
+/** `/apply` 的五个动作。id 的含义随动作走：`delete`/`count`/`orphan-clean` 是**宿主会话 id**
+ *  （前两个还没进回收站，第三个压根没有回收站行），`restore`/`purge` 是**回收站条目 id**。 */
+export type ApplyAction = 'delete' | 'restore' | 'purge' | 'count' | 'orphan-clean';
 /** 每个动作的成功值：`count` 是一个数（拿不到就是 0，界面上那半句整句不出现）；
  *  `delete`/`restore` 是回收站那一行（`null` = 这一条已被**同批前一条**带走，幂等 no-op）；
- *  `purge` 是这一组的聚合回执（同批已带走 ⇒ `{removed:0,freedBytes:0}`）。 */
+ *  `purge` 是这一组的聚合回执（同批已带走 ⇒ `{removed:0,freedBytes:0}`）；
+ *  `orphan-clean` 删的是**盘上目录**（不进回收站），所以清册那一行给不出 `null` 这种幂等 no-op——
+ *  组已经不在了就是 `not-found`，见 `verbs/batch.ts`。 */
 export type ApplyValueByAction = {
     delete: TrashEntryWire | null;
     restore: TrashEntryWire | null;
     purge: PurgeStatsWire;
     count: number;
+    'orphan-clean': OrphanCleanStatsWire;
 };
 /** 一条动作的落地：原始输入 id 一律回带，成败各按信封（成功 `value` / 失败 `error`）。
  *  按 `action` + `ok` 双重可判别——浏览器半的便捷包装靠它把 `value` 收成各自动作的类型。 */
@@ -67,7 +74,8 @@ export type ApplyOutcome = {
         error: RemoteFailure;
     };
 }[ApplyAction];
-/** `TrashEntry` 的线上形状（浏览器半自己有一份窄镜像 `TrashEntryLike`）。 */
+/** 清册那一行（`trash/entry.ts` 的 `TrashEntry`）的**线上形状**。
+ *  它与落地形状不是同一个东西：线上**只发**这里列的东西，落地形状另有运行期必填清单（见 `entry.ts`）。 */
 export interface TrashEntryWire {
     id: string;
     sessionId: string;
@@ -79,11 +87,79 @@ export interface TrashEntryWire {
     sizeBytes: number;
     parentEntryId?: string;
 }
+/**
+ * `GET /list` 真正发出去的那一行：清册那一行 + 六个**现算现给**的只读数（ADR-0003）。
+ *
+ * 六个只读数都**不落清册**：它们随盘上状态随时变，清册只记文件里真有的事实。所以除了必填的
+ * `releaseBytes` 之外全是可选字段，而且「缺席」与「是 0」是两件事——界面上不许拿 0 冒充「没有」，
+ * 也不许拿缺席冒充否。
+ */
+export interface TrashRowWire extends TrashEntryWire {
+    /** **这一行「彻底删除」会释放多少**：本行 + 跟着进来的孩子 + 盘上还留着的后代。
+     *  它是**存储侧的事实**（彻底删除删的正是这三样），所以由 Node 半算一次过线；界面上头部合计与
+     *  单条确认框共用这一个数——不许各算一遍（各算一遍就是两套口径，且客户端那套会重复计数）。 */
+    releaseBytes: number;
+    /** 跟着这条父会话**一起进了回收站**的孩子数（清册里 `parentEntryId` 指向它的行）。 */
+    subagentCount?: number;
+    /** 那些孩子的字节合计（头部合计要算上它们，不能只加父自己那一格）。 */
+    subagentBytes?: number;
+    /** **还留在盘上、没被带走**的孩子数（宿主 `sessionQuery`）。与 `subagentCount` 各说各的。 */
+    strandedSubagents?: number;
+    /** 那些盘上后代的实际字节合计；彻底删除/清空会一起释放。 */
+    strandedBytes?: number;
+    /** 删除时记下的工作区**已经不在账本里**（宿主的「删除工作区」只删注册、保留日志）。 */
+    workspaceMissing?: boolean;
+}
+/** 单条详情里的一条消息（`trash/detail.ts` 读出来的那一份）。 */
+export interface TrashDetailMessageWire {
+    role: 'user' | 'assistant';
+    time: number;
+    text: string;
+    truncated: boolean;
+}
+/** 回收站单条详情的线上形状（`POST /detail`）。 */
+export interface TrashDetailWire {
+    entryId: string;
+    /** 日志 header 里的原串（**无损**，比从 `projectKey` 反推那一路强，设计稿 §7 组头那条是另一回事）。 */
+    cwd: string;
+    createdAt: number;
+    lastActivity: number;
+    /** 日志内 `session/title` 那条记录；清册标题为空串时客户端拿它兜底。 */
+    logTitle: string;
+    models: string[];
+    turnCount: number;
+    userMessageCount: number;
+    assistantMessageCount: number;
+    toolCallCount: number;
+    injectedCount: number;
+    messages: TrashDetailMessageWire[];
+    omittedByPayloadCap: number;
+}
 /** 清空回收站的回执（与旧 `purge` 同形）。 */
 export interface PurgeStatsWire {
     removed: number;
     freedBytes: number;
 }
+/** 无主子会话扫描里**一个项目目录**的汇总（界面上那条"哪一家还剩多少"的读数）。 */
+export interface OrphanProjectGroupWire {
+    projectDir: string;
+    sessions: number;
+    bytes: number;
+}
+/** 一次孤儿扫描的报告（纯读的产物）。`roots` 是每组那个"父没了"的 subagent 自己写的原形状；
+ *  `missingParents` 按**去前缀后的形状**去重——同一个失踪父在两种写法下只算一个。 */
+export interface OrphanReportWire {
+    roots: readonly string[];
+    totalSessions: number;
+    totalBytes: number;
+    missingParents: number;
+    groups: readonly OrphanProjectGroupWire[];
+}
+/** 清理一组无主子会话的回执（与 {@link PurgeStatsWire} 同形，但计的是"删掉的会话目录"）。 */
+export interface OrphanCleanStatsWire {
+    removed: number;
+    freedBytes: number;
+}
 /** 请求体字段名：浏览器半发、Node 半读，同名同义（`empty` 没有入参）。 */
 export declare const PARAMS: {
     readonly entryId: "entryId";
@@ -120,6 +196,24 @@ export type RemoteResult<T> = {
  * 浏览器半是 `src/client/remote.ts` 的 `throwRemoteFailure`。
  */
 export declare function isDSHRemoteError(value: unknown): value is RemoteFailure;
+/** 失败码的域。与宿主官方域（`workspace/*`、`session/*`…）不重名，见设计稿 §6。 */
+export declare const SESSION_DELETE_ERROR_DOMAIN = "sessiondelete";
+/** 五个**动词码**（设计稿 §6 那张表）。`io` 是唯一兜底。 */
+export declare const VERB_CODES: readonly ["live", "not-found", "trash-empty", "project-missing", "io"];
+export type VerbCode = (typeof VERB_CODES)[number];
+/** 三个**路由自检码**：请求本身不对，不是一次操作的结果（它们带 HTTP 状态，见 `api/dispatch.ts`）。 */
+export declare const ROUTE_CODES: readonly ["bad-method", "not-found-route", "bad-request"];
+export type RouteCode = (typeof ROUTE_CODES)[number];
+/**
+ * 完整码（`sessiondelete/<后缀>`）。**`Record<…, …>` 是闸**：加一个后缀而忘了这里，
+ * 编译不过；写错一个字面量，也编译不过。
+ */
+export type AllCodeSuffix = VerbCode | RouteCode;
+export declare const SESSION_DELETE_CODES: Record<AllCodeSuffix, `sessiondelete/${AllCodeSuffix}`>;
+/** 回收站目录名（相对宿主数据根）。Node 半拼路径，浏览器半在页脚念它——同一个字面量。 */
+export declare const TRASH_DIR_NAME = "session-trash";
+/** 页脚/文案里带尾斜杠的那一版（`splitOn` 按它切一刀再把目录名包成 code）。 */
+export declare const TRASH_DIR_LABEL = "session-trash/";
 /**
  * 宿主 `projectKey` 的 **`~XXXX` 转义还原**。
  *

package/lib/types/trash/detail.d.ts

@@ -1,32 +1,14 @@
 import type { ManifestPort } from './manifest.js';
 import type { FsPort } from '../ports/fs-port.js';
+import type { TrashDetailMessageWire, TrashDetailWire } from '../shared/wire.js';
 /** 每条文字的上限（字符）。超出即截断并置 `truncated`。 */
 export declare const PER_MESSAGE_CHAR_CAP = 3000;
 /** 一次回信的正文总量上限（字符）。 */
 export declare const TOTAL_CHAR_CAP = 500000;
-export interface TrashDetailMessage {
-    role: 'user' | 'assistant';
-    time: number;
-    text: string;
-    truncated: boolean;
-}
-export interface TrashDetail {
-    entryId: string;
-    /** 日志 header 里的原串（**无损**，比从 `projectKey` 反推那一路强，设计稿 §7 组头那条是另一回事）。 */
-    cwd: string;
-    createdAt: number;
-    lastActivity: number;
-    /** 日志内 `session/title` 那条记录；清册标题为空串时客户端拿它兜底。 */
-    logTitle: string;
-    models: string[];
-    turnCount: number;
-    userMessageCount: number;
-    assistantMessageCount: number;
-    toolCallCount: number;
-    injectedCount: number;
-    messages: TrashDetailMessage[];
-    omittedByPayloadCap: number;
-}
+/** 详情正文里的一条消息 / 整份详情：**线上形状的家在 `shared/wire.ts`**（ADR-0003）——
+ *  Node 半产出它，浏览器半按同一份类型消费，这里只留旧名做别名。 */
+export type TrashDetailMessage = TrashDetailMessageWire;
+export type TrashDetail = TrashDetailWire;
 export type DetailDeps = {
     fs: FsPort;
     manifest: ManifestPort;

package/lib/types/trash/entry.d.ts

@@ -12,8 +12,8 @@ export interface TrashEntry {
      *  恢复时按这个字段还原可见性：true ⇒ 仍处归档态，false ⇒ 取消归档放回树里。 */
     wasArchived: boolean;
     deletedAt: number;
-    /** 删除时**尽力**取的会话标题（来源：`storages/session_projcache/sessions/<会话id>.json`
-     *  里的 `rows.title.val`）；取不到存空串，绝不因此让删除失败。 */
+    /** 删除时**尽力**取的会话标题（来源：宿主 projection cache 服务；底层是
+     *  `storages/session_projcache/sessions/<会话id>.json` 里的 `title` 投影）。取不到存空串，绝不因此让删除失败。 */
     title: string;
     /** 删除时用 `fs.sizeOfDir` 量到的会话目录字节数。 */
     sizeBytes: number;
@@ -24,6 +24,25 @@ export interface TrashEntry {
      *  的如实结果，不假装知道（设计稿 2026-10-15 §10）。 */
     parentEntryId?: string;
 }
+/**
+ * 清册里**每条记录都必须有**的那几格（`TrashEntry` 的非可选字段）——运行期校验器与「文件里真有的事实」
+ * 共用这一份清单。
+ *
+ * **可选字段不在这里**：`parentEntryId`（级联那批加的）缺席是合法的——老行没有它，缺了就是"没有父"；
+ * 校验器只管这几格的类型，其余键**原样带走**（`parse` 交回的就是 `raw` 本身）⇒ 新字段照旧存得住。
+ *
+ * 键集与接口由 `tests/wire-shape.test.ts` 双向钉住：接口加一个必填字段而这里没跟 ⇒ 测试红。
+ */
+export declare const REQUIRED_ENTRY_FIELDS: {
+    readonly id: "string";
+    readonly sessionId: "string";
+    readonly projectDir: "string";
+    readonly workspaceId: "string";
+    readonly wasArchived: "boolean";
+    readonly deletedAt: "number";
+    readonly title: "string";
+    readonly sizeBytes: "number";
+};
 export declare function makeEntryId(deletedAt: number, sessionDirName: string): string;
 /** `makeEntryId` 的逆。时间戳按 UTC 拆字段再 `Date.UTC` 合回——不交给 `Date.parse`
  *  去猜（`20260930T130500Z` 不是任何被承认的日期格式，猜出来的是 NaN）。 */
@@ -31,5 +50,9 @@ export declare function parseEntryId(id: string): {
     deletedAt: number;
     sessionDirName: string;
 };
+/** 路径里的每一段都必须是**单段**：这一层不信宿主的 `header.id` 与清册，破坏性动词直接删目录。
+ *  `/`、`\`、`.`、`..` 与 NUL 都能把递归删除带出 `sessions/` / `session-trash/`。 */
+export declare function isSinglePathSegment(value: string): boolean;
+/** `sessionDirName` 允许空串：恢复的预检用它取**项目根**（`sessions/<projectDir>`），不是会话目录。 */
 export declare function sessionDirOf(projectDir: string, sessionDirName: string, home: string): string;
 export declare function trashDirOf(entryId: string, home: string): string;

package/lib/types/trash/groups.d.ts

@@ -0,0 +1,45 @@
+/**
+ * **组语义的唯一家**（ADR-0001）：回收站里「这一组有谁」以及「哪些行在清单里露面」。
+ *
+ * 此前这条关系在四个地方各算一遍，而且已经算出两种答案：
+ * `assembleTrashRows` 与 `restoreSession` 都认为「父自己也是孩子时，它接不住孩子」，
+ * 而 `purgeTrash` 的 `id === x || parentEntryId === x` 不认这条 ⇒ 嵌套组上它会连带删掉不属于这一组的孙代
+ * （不可恢复）。判据原文只在这里写一次：
+ *
+ * **接得住孩子的只有组根**——自己不记 `parentEntryId` 的那一行。父行不在、或父行自己也是孩子时，
+ * 孩子必须自己占一行，否则它的字节会被头部合计数两遍（而它自己既看不见也清不掉）。
+ *
+ * 三个函数都是**纯函数**、都吃一份快照：`/apply` 那条路会在同一批里多次重问、而快照会被就地收缩，
+ * 收缩的时机归调用方——groups module 不持有可变状态，也就没有"这份快照谁负责更新"的第二套契约。
+ */
+import type { TrashEntry } from './entry.js';
+/** 一条露面的组根，连同它接住的孩子（顺序与清册一致）。 */
+export interface TrashGroupView {
+    readonly root: TrashEntry;
+    /** 跟着这条根进来的孩子（`parentEntryId` 指向根的 id）。根自己不在里面。 */
+    readonly kids: readonly TrashEntry[];
+}
+/**
+ * 清单露面的一行 = 组根，按清册原序。孩子折进根那一行（宿主的客户端本来就把 `origin:"subagent"`
+ * 的行整排藏了 ⇒ 我们若单列就会冒出一堆点不到的行）。
+ *
+ * 折不进去的那两种孩子（父行不在 / 父行自己也是孩子）**自己站出来占一行**——那正是
+ * `visibleGroups` 与 `groupOf` 共用同一条判据的地方。
+ */
+export declare function visibleGroups(rows: readonly TrashEntry[]): TrashGroupView[];
+/**
+ * 一条 id 所属的整组。三种形状，三个答案：
+ * - **组根** ⇒ 它自己 + 它接住的孩子（UI 点的是父那一行，删除/恢复/彻底删除都按整组走）；
+ * - **孩子**（自己记着 `parentEntryId`）⇒ **只回它自己**。清单不单独列它，只有手工/降级路径会点到这里；
+ * - **清册里没有这一条 id，但还有孩子指向它**（父行已被别的路径摘掉）⇒ 那一批孩子；仍然没有 ⇒ 空数组，
+ *   调用方据此报 `trash-empty` / 判"已被同批前一条带走"。
+ */
+export declare function groupOf(rows: readonly TrashEntry[], id: string): TrashEntry[];
+/**
+ * 「这条是被**同批前一条**带走的，还是整批开始前就没有？」
+ *
+ * 幂等语义只属于前者：后来者本来就不在清册里（用户点了条幽灵 id、或对账刚摘掉它）必须照样响亮报
+ * `trash-empty`，不能被"已被带走"这句话掩盖成成功。**所以判据是快照的原始形状，不是当前形状**：
+ * 原始快照里认得出（它自己、它的父、或它的孩子任一在），而当前快照里已经空了 ⇒ 同批带走的。
+ */
+export declare function takenByEarlierInBatch(original: readonly TrashEntry[], current: readonly TrashEntry[], id: string): boolean;

package/lib/types/verbs/delete-session.d.ts

@@ -17,14 +17,11 @@ export interface DeleteDeps {
  * 三段，顺序承重：
  * ① **先点组、先验活体**（一个字节都不写）。任一成员在跑就整组拒绝——不替用户终止正在跑的活，
  *    也绝不允许"父已经搬进回收站、孩子因为在跑而搬不动"这种半套。
- * ② **逐个搬**：每个成员内部沿用原来那套顺序与就地回滚（归档 → 摘账本 → 搬目录 → 写清册），
- *    任何一步失败就把这个成员自己退回原地。
+ * ② **逐个搬**：每个成员是一份 `journal`（`verbs/member-journal.ts`），搬不动时 journal 自己把
+ *    这个成员已经做成的步骤退回去。
  * ③ **组级回滚**：某一个成员搬不动时，把**已经搬进去的**那些按相反顺序退回原处（清册行跟着摘、
  *    账本跟着挂、可见性跟着还原），失败照抛——不留"半组在回收站、半组在原地"的世界。
+ *
+ * interface 只有**一个 id**：批量的性质不在这里（同批"已被前一条带走"的判据归 `verbs/batch.ts`）。
  */
-export declare function deleteSession(deps: DeleteDeps): (sessionId: string, 
-/** 批量层（`verbs/apply.ts`）在写之前收一份"这次真正要搬的成员"（父 + 盘上存在的孩子），
- *  成功后用它记下"已被同批前一条带走"的 id。单条调用不传。 */
-options?: {
-    readonly onMembers?: (sessionIds: readonly string[]) => void;
-}) => Promise<TrashEntry>;
+export declare function deleteSession(deps: DeleteDeps): (sessionId: string) => Promise<TrashEntry>;

package/lib/types/verbs/errors.d.ts

@@ -1,11 +1,10 @@
-/** 五个码（设计稿 §6 的表）。**唯一定义处**：`remote/map-error.ts` 从这份数组反推它的 `Code`，
- *  免得"加了一个码只在一边加"让两张表各自漂移（漂移的后果是那个码静默降级成 `io`）。 */
+/** 五个码 / 三个路由自检码的**家都在 `shared/wire.ts`**（ADR-0003）：浏览器半也要认它们（比如
+ *  `not-found` 在界面上是中性提示而不是失败），所以它们属于两半共同的契约，不属于 Node 半。
+ *  这里只转出旧名，免得调用点全改一遍。 */
+import { type RouteCode, type VerbCode } from '../shared/wire.js';
 export declare const VERB_CODES: readonly ["live", "not-found", "trash-empty", "project-missing", "io"];
-export type VerbCode = (typeof VERB_CODES)[number];
-/** 路由层的自检（不是五个动词码之一）：**请求本身不对**——方法、路径、body 形状。
- *  它上的是 HTTP 状态那条口（404/405），信封里也带着它，好让只看信封的调用方拿到同一句原文。 */
 export declare const ROUTE_CODES: readonly ["bad-method", "not-found-route", "bad-request"];
-export type RouteCode = (typeof ROUTE_CODES)[number];
+export type { RouteCode, VerbCode };
 /** 一次失败的**结构**：码、上屏原文、可选 cause（`map-error` 沿 cause 链认宿主类型化错误）、
  *  可选的结构化附带物（对齐官方 `rpcErrorSchema` 的第三件 `details`）。 */
 export interface VerbError extends Error {
@@ -18,3 +17,11 @@ export declare function verbError(code: VerbCode, message: string, cause?: unkno
 export declare function routeError(code: RouteCode, httpStatus: number, message: string): VerbError & {
     httpStatus: number;
 };
+/** 一条回滚步骤失败的**标签句**：label 说的是"这一步在退什么"，原文带出**那一步抛的东西**
+ *  （`Error` 取 message，其余一律 `String()`；对象带 `message` 的差异归 `map-error.messageOf` 管）。
+ *  调用方不许另抄这份格式——那样 details 里的句子会随各处 catch 变形，界面上就变成"同一个失败三个说法"。 */
+export declare function rollbackReason(label: string, error: unknown): string;
+/** 原错误保留，回滚失败作为 `details.rollbackFailures` 上线；码仍按原错误的动词码，
+ *  没有可继承的就落 io。**内层的回滚失败要并进来**：一个成员自己退失败、兄弟也退失败时，
+ *  两份失败都得在 details 里，消息也不能出现第二个「回滚未完成」。 */
+export declare function withRollbackFailures(error: unknown, failures: readonly string[]): VerbError;

package/lib/types/verbs/member-journal.d.ts

@@ -0,0 +1,26 @@
+export interface JournalStep {
+    /** 这一步在做什么。失败原文按「`<label>：<原错误>`」拼——与既有那 22 处 `rollbackReason` 的措辞同形。 */
+    readonly label: string;
+    /** 做这一步。抛什么都由 journal 折成 `sessiondelete/io`（除非它自己已经是一个动词码）。 */
+    run(): Promise<void>;
+    /** 反向动作。**`run` 成功之后**才会被登记；返回**这一步自己**没能退干净的原因列表（空 = 完全退回）。 */
+    undo?(): Promise<readonly string[]>;
+    /** 这一步**自己**失败时也跑 `undo`：给"可能已经半做完"的非原子步骤用（取消归档是唯一的例子）。 */
+    readonly undoOnFailure?: boolean;
+}
+export interface Journal {
+    /** 按顺序跑完。中途失败 ⇒ 已做成的按相反顺序退回，然后把原错误（带 `rollbackFailures`）抛出去。 */
+    run(): Promise<void>;
+    /** 把**已经做成**的步骤按相反顺序退回去（整组回滚用：组里后面那个成员搬不动时叫这一句）。 */
+    undo(): Promise<readonly string[]>;
+}
+/** 已经把某个前缀做成了的 journal——`undo()` 就退那一个前缀。 */
+export declare function createJournal(steps: readonly JournalStep[]): Journal;
+/** 跑一步反向动作并把它自己的失败收成一条原因（不抛：这些失败由调用方汇总成 `rollbackFailures`）。 */
+export declare function attempt(label: string, run: () => Promise<unknown>): Promise<readonly string[]>;
+/**
+ * **组级回滚**：把已经做成的成员按相反顺序退回；某一步退不干净时把失败并进原错误的
+ * `details.rollbackFailures`，绝不让原错误独走（设计稿第十七批）。删除与恢复两个按组走的动词
+ * 共用这一处——"相反顺序 + 失败合并"不再各写一遍。
+ */
+export declare function rollbackJournals(journals: readonly Journal[], error: unknown): Promise<never>;

package/lib/types/verbs/orphan-subagents.d.ts

@@ -0,0 +1,82 @@
+import { type SessionIdentity } from '../ports/host-port.js';
+import type { OrphanCleanStatsWire, OrphanReportWire } from '../shared/wire.js';
+import type { DeleteDeps } from './delete-session.js';
+/** 组里一个人的盘上身份（字节是**扫描那一刻**量的，清理时按目录重量一次，不拿这份快照冒充准数）。 */
+export interface OrphanMember {
+    readonly sessionId: string;
+    readonly projectDir: string;
+    readonly bytes: number;
+}
+/** 一组无主子会话：根是那"父没了"的 subagent，`members` 是它的**传递闭包**（含根自己）。 */
+export interface OrphanGroup {
+    readonly root: OrphanMember;
+    readonly parentSessionId: string;
+    readonly members: readonly OrphanMember[];
+}
+export interface MeasuredMemberDir {
+    readonly dir: string;
+    readonly bytes: number;
+}
+/** 一个成员被删之前要记下的三件：目录、字节、账本归属（缺席 = 未分组）。purge 与 orphan-clean 共用。 */
+export interface MemberRemovalPlan extends MeasuredMemberDir {
+    readonly sessionId: string;
+    readonly workspaceId?: string;
+}
+/** 成员的盘上目录与字节（扫描、清单装配与 purge 共用这一条路径/存在性/度量口径；
+ *  目录缺席回 `undefined`，不拿一份"记录还在、盘上已经没了"的旧读数冒充盘上残留）。 */
+export declare function measureMemberDir(deps: DeleteDeps, member: {
+    readonly sessionId: string;
+    readonly projectDir: string;
+}): Promise<MeasuredMemberDir | undefined>;
+/** 把一组成员折成"删之前要记下的计划"；目录不在的成员跳过（记录与盘不一致是那条成员自己的事）。
+ *  `purge` 的盘上后代与 `orphan-clean` 的整组都走这一处，别再各写一遍 measure + workspaceOf。 */
+export declare function planMemberRemovals(deps: DeleteDeps, members: readonly {
+    readonly sessionId: string;
+    readonly projectDir: string;
+}[]): Promise<MemberRemovalPlan[]>;
+/** {@link orphanGroupsOf} 的中间形状：还没量字节的那一组（纯函数不碰盘）。 */
+interface RawGroup {
+    readonly root: SessionIdentity;
+    readonly parentSessionId: string;
+    readonly members: readonly SessionIdentity[];
+}
+/**
+ * 无主子会话 = `origin:"subagent"`、父**既不在当前语料（live ∪ persisted）也不在回收站清册里**的会话。
+ *
+ * 为什么清册里的父不算孤儿：那种是 **stranded**——父还在回收站里等着，孩子本该跟着父一起恢复或一起
+ * 彻底删除（10-15 稿 §11 的组语义），把它的根当孤儿删掉就是**替用户做了一个没人点过的决定**。孤儿只
+ * 有一种来路：父被彻底删掉了（或被手工从盘上清掉了），清册里再也没有这一行。
+ *
+ * 根按**传递闭包**收全部后代（与 `HostPort.subagentCounts` 同一口径：孩子与孙代都算，深度不设上限），
+ * 同一条记录只归一组（`claimed`）——数据里真出现环时结果是"少数一条"，不是把一个会话删两遍。
+ * 归堆与去重**两边都去 `session-` 前缀**：同一个父在两代宿主里写法不同（见 `bareSessionId` 的来历）。
+ */
+export declare function orphanGroupsOf(corpus: readonly SessionIdentity[], trashSessionIds: readonly string[]): RawGroup[];
+/** 纯读：调用方应先走一次 `/list` 对账（面板的 refresh 就是这样）；本函数不写清单。
+ *  写动作 `orphan-clean` 会自己先 reconcile，避免拿一份过期清册判"父没了"。
+ *
+ *  `listSessions()` 回 `undefined` 时**必须抛**：那是宿主的会话语料服务没挂，不是"这个家没有孤儿"。
+ *  拿 undefined 当空语料 ⇒ 报告说"零条孤儿"、界面上一句"没有要清理的"，而盘上真有几百 MB——那是假话，
+ *  所以这里按 `io` 响亮失败（AGENTS.md：`undefined` 意味着服务缺席，扫描方不许冒充读数）。 */
+export declare function loadOrphanGroups(deps: DeleteDeps): Promise<readonly OrphanGroup[]>;
+/** 把一组组收成那份报告：根清单 + 闭包总数/总字节 + 失踪父的**去重计数** + 按项目目录的分摊。
+ *  `groups` 按字节从多到少排（界面上"哪家还剩得最多"要看第一行）。 */
+export declare function reportOrphans(groups: readonly OrphanGroup[]): OrphanReportWire;
+/**
+ * 清一组：先**整组 live 准入（零写）**，再收集目录/字节/账本归属，再 unarchive → detach → 删目录。
+ * 任何 preflight 失败都在第一件写之前抛出；删目录到一半失败时**已删目录不回滚**，失败错误的
+ * `details` 带 `{ removed, freedBytes, failedSessionId }` 作为部分回执（不伪装成整组没动）。
+ * 删目录之后照 purge 的规矩摘活体并如实通告。不碰投影缓存与附件。
+ *
+ * 顺序与删除那一半是**对偶**的，但不是照抄：
+ * - 删除要先把会话藏起来（归档）再摘账本，免得中间那一拍它掉进「未分组」；这里目录是**删掉**不是搬走，
+ *   藏不藏都不影响可见性 ⇒ 归档集反而是**在写之前整批摘掉**的：失败时目录还在，下一次还能重试，
+ *   不会留下"会话没了但还在归档集里挂着"的幽灵 id。
+ * - `unarchive` 对未归档的会话是官方幂等 no-op（`registry.unarchiveSession`），所以不需要删除侧那次
+ *   `wasArchived` 读——这里没有"还原到删除前"的义务。
+ * - 摘账本只在账本真记着它时做（`workspaceOf` 未命中 = 本来就是「未分组」，不是故障）。
+ * - `evictLive` 的三态照 `HostPort.evictLive` 的契约：`unknown` 时**不通告**（发了就是假话），
+ *   `evicted` / `not-live` 才发 `api-session/removed`。冷会话没有活体可摘，通告照样必须发。
+ */
+export declare function cleanOrphanGroup(deps: DeleteDeps, group: OrphanGroup): Promise<OrphanCleanStatsWire>;
+export {};

package/lib/types/verbs/purge-trash.d.ts

@@ -1,6 +1,18 @@
 import { type TrashEntry } from '../trash/entry.js';
 import type { DeleteDeps } from './delete-session.js';
-export declare function purgeTrash(deps: DeleteDeps): (entryId?: string, snapshot?: TrashEntry[]) => Promise<{
+/**
+ * 彻底删除：从回收站里**真的**抹掉一条（或整组、或整站），并连带那些"还留在盘上、没被带走"的后代。
+ *
+ * 与另外两个动词的关系（ADR-0002）：它的 interface 只有"一个条目 id（或缺席 = 清空）"，
+ * 批量的快照与"已被同批前一条带走"的判据不在这里（归 `verbs/batch.ts`）。
+ *
+ * **这条动词不做回滚**：目录删掉就没有"退回去"这回事（设计稿第十七批：删到一半失败时已删目录不回滚；
+ * 带部分计数的 `details` 回执只属于 `orphan-clean`，purge 的 `removed` / `freedBytes` 仍只在成功回执里给）。
+ * 所以它的 journal 只有正向步骤、没有 `undo`——顺序仍由 journal 统一表达，不再是手写的四段 `try/catch`。
+ */
+export declare function purgeTrash(deps: DeleteDeps): (entryId?: string, 
+/** **只读**清册快照：批量层已经读过一次就递下来（ADR-0002）；收缩归批量层，动词不碰它。 */
+snapshot?: readonly TrashEntry[]) => Promise<{
     removed: number;
     freedBytes: number;
 }>;

package/lib/types/verbs/restore-session.d.ts

@@ -1,4 +1,5 @@
 import { type TrashEntry } from '../trash/entry.js';
+import { type HostPort } from '../ports/host-port.js';
 import type { DeleteDeps } from './delete-session.js';
 /**
  * 恢复 = 把删除那次**按原路退回**，而且按组走：当年是按组一起搬进来的（父 + 它在盘上的孩子），
@@ -8,12 +9,31 @@ import type { DeleteDeps } from './delete-session.js';
  * ① **预检整组**（一个字节都不写）：每个成员的回收站目录与项目目录都得在。缺席的判据与原来一致
  *    （回收站目录不在 = `trash-empty`；原项目目录不在 = `project-missing`，且绝不静默建目录）。
  *    预检在写之前，是为了不让"父已经回到 `sessions/`、孩子因为项目目录没了而回不去"这种半组留在外面。
- * ② **逐个恢复**，顺序与删除相反：文件先回来 → 挂账本 → 还原可见性 → 摘清册行 → 通告回来。
- * ③ 中途失败把这个成员自己退回回收站（就地回滚），并把**已经恢复完的**兄弟按相反顺序一起退回，失败照抛。
+ *    **工作区账本不在这条硬前提里**：宿主的「删除工作区」只删注册、保留日志，记下的工作区没了就按
+ *    「未分组」收（判据在 {@link attachableWorkspaceId}），照旧回盘——恢复是加法，不该因为一个可选的账目而失败。
+ * ② **逐个恢复**，顺序与删除相反：文件先回来 → 挂账本 → 还原可见性 → 摘清册行。
+ * ③ 中途失败时 journal 把这个成员自己退回回收站；**已经恢复完的**兄弟由整组 catch 按相反顺序一起退回。
+ *
+ * **通告不在这里**：一次批量只该拉一遍宿主会话表、只发一次 `api-session/added`（2026-10-17 那次
+ * "恢复很慢"就是逐条发）。通告归 `verbs/batch.ts`（ADR-0002），所以这个动词的 interface 只有
+ * "一个条目 id 进、回收站那一行出"，没有批量专用的开关。
+ */
+export declare function restoreSession(deps: DeleteDeps): (entryId: string, 
+/** **只读**清册快照：批量层已经读过一次就递下来，整批因此只读一次（ADR-0002）。
+ *  动词**不收缩**它——收缩与"已被同批前一条带走"的判据都归 `verbs/batch.ts`。 */
+snapshot?: readonly TrashEntry[]) => Promise<TrashEntry>;
+/**
+ * 这一次恢复**到底挂不挂账本**：交出能挂的那个 `workspaceId`，挂不了就 `undefined`。
+ *
+ * 两种缺席是同一件事：空串 = 删除时它就没有账目（「未分组」的会话）；非空但账本里已经没它 =
+ * 宿主的「删除工作区」只删注册、保留目录与每一份日志，那些会话之后本来就在「未分组」下。
+ * 恢复不该为了挂一个不存在的账本把整条退回回收站。
+ *
+ * 判据**只有这一处**：`memberRestore` 拿它决定挂不挂，`GET /list` 拿它决定行上那句「原工作区已不存在，
+ * 恢复后归入未分组」说不说。两边各问一遍就会有一天一个说、一个不挂。
  */
-export declare function restoreSession(deps: DeleteDeps): (entryId: string, options?: {
-    readonly snapshot?: TrashEntry[];
-    /** 批量（`verbs/apply.ts`）**自己收尾一次发**时传 `suppressAnnounce`：动词不再逐条通告——
-     *  单条一份摘要 = 一条一次宿主全表扫，那是 2026-10-17 "恢复很慢"的头号来源。 */
-    readonly suppressAnnounce?: boolean;
-}) => Promise<TrashEntry>;
+export declare function attachableWorkspaceId(host: Pick<HostPort, 'workspaceExists'>, entry: TrashEntry): Promise<string | undefined>;
+/** 这一条记着的工作区**是不是已经没了**（区别于"删除时它就没有账目"的空串）——清单行据此决定
+ *  要不要在点之前说那句「原工作区已不存在，恢复后归入未分组」。由 {@link attachableWorkspaceId}
+ *  派生，不另起一份判据：那样会有一天一个说、一个不挂。 */
+export declare function isWorkspaceMissing(host: Pick<HostPort, 'workspaceExists'>, entry: TrashEntry): Promise<boolean>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xrn1997/dsh-session-delete",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "在 DeepSeek Harness 里删除会话：删除=移入回收站（可恢复），另设显式彻底删除",
   "type": "module",
   "main": "lib/index.js",
@@ -29,7 +29,8 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=24"
+    "node": ">=24",
+    "dsh": ">=0.1.7-rc.2 <0.3.0-0"
   },
   "scripts": {
     "build": "tsdown && tsc -p tsconfig.build.json",
@@ -49,9 +50,11 @@
     "@types/node": "24.19.0",
     "@types/react": "18.3.31",
     "@types/react-dom": "18.3.5",
+    "@types/semver": "^7.8.0",
     "jsdom": "^26.1.0",
     "react": "^18.3.1",
     "react-dom": "18.3.1",
+    "semver": "^7.8.5",
     "tsdown": "0.23.0",
     "typescript": "5.9.3",
     "vitest": "3.2.7"
@@ -68,7 +71,9 @@
     },
     "compatibility": {
       "dshReleases": {
-        "0.2.0-rc.2": "compatible"
+        "0.2.0-rc.2": "compatible",
+        "0.2.1-rc.1": "compatible",
+        "0.2.1-rc.2": "compatible"
       }
     }
   },