@xrn1997/dsh-session-delete 0.3.0 → 0.3.1

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

@@ -0,0 +1,51 @@
+/**
+ * 一次逐条 `/apply` 写入的**唯一生命周期**：apply → 解信封 → `readReceipt` → settlement → refresh。
+ *
+ * 收尾顺序与 `anySuccess` 门住 `src/client/write-settlement.ts`（为什么按 action 收见 ADR-0013）；
+ * 这里只管时机、信封判读、整趟的闸与 `refresh` 的交法。清空回收站是聚合回执（`/empty`），收尾仍住
+ * `use-trash-query.ts` 的 `emptyTrash`。
+ *
+ * 五条判据：
+ * - `ok` 只说**信封**成不成；逐条成败在 `failures` 里，调用方自己决定怎么上屏。
+ * - 顶层失败把同一句原文铺到每个 id，不结算；`refresh` 照样交（成败都在 outcome 里）。
+ * - **信封成功就结算**（逐条全失败也跑：批量写入的失效通告不能漏）；`anySuccess` 由这里算好，
+ *   按 action 的呈现材质由 settlement 按它上闸。调用方只交呈现材质，再按 `outcome` 决定是否真的重读。
+ *   结算在 `refresh` 之前：列表重读看得到收尾后的现场。
+ * - `single: true` 时把 N=1 模式交给 `receipt.ts` 的读法；单条 null 在那一处折成 failed，
+ *   这里不再重复守卫。
+ * - **闸包住整趟**：给了 `gate` 就把 apply → settle → refresh 一起包进去——refresh 落在闸外时，
+ *   旧清单还在屏上，同一个动作能被再点一次；调用方不再自己 `around`。
+ */
+import type { BusyGate } from './busy-gate.js';
+import { type OneShotDeps } from './remote.js';
+import { type SettledFacts, type WritePresentation } from './write-settlement.js';
+import type { ApplyAction, RemoteFailure } from '../shared/wire.js';
+export type WriteSuccess<A extends ApplyAction> = SettledFacts<A> & {
+    readonly ok: true;
+    /** 逐条失败原文（failed / neutral / missing），按 id。 */
+    readonly failures: ReadonlyMap<string, string>;
+};
+export interface WriteFailure<A extends ApplyAction> {
+    readonly ok: false;
+    readonly action: A;
+    readonly ids: readonly string[];
+    readonly failure: RemoteFailure;
+    /** 顶层失败时同一句原文铺到每个请求 id。 */
+    readonly failures: ReadonlyMap<string, string>;
+}
+export type WriteOutcome<A extends ApplyAction> = WriteSuccess<A> | WriteFailure<A>;
+export interface WriteInput<A extends ApplyAction> {
+    readonly deps: OneShotDeps;
+    readonly action: A;
+    readonly ids: readonly string[];
+    /** 单条写入面：把 N=1 模式交给 receipt 读法（null 折成协议错）。 */
+    readonly single?: boolean;
+    /** 信封成功时交给 settlement 的呈现材质（`successIds` 可能为空）；按 action 的收尾顺序住 `write-settlement.ts`。 */
+    readonly presentation?: WritePresentation<A>;
+    /** 这一趟的闸：给了就把 apply → settle → refresh 整趟包进 busy。refresh 不许落在闸外。 */
+    readonly gate?: BusyGate;
+    /** 写完（顶层失败或信封成功，无论逐条成败）后的重读策略；成败与 `anySuccess` 都在 outcome 里，
+     *  是否真的重读由调用方决定。 */
+    readonly refresh?: (outcome: WriteOutcome<A>) => void | Promise<void>;
+}
+export declare function runWrite<A extends ApplyAction>(input: WriteInput<A>): Promise<WriteOutcome<A>>;

package/lib/types/deps.d.ts

@@ -1,11 +1,11 @@
 import type { FsPort } from './ports/fs-port.js';
 import type { HostPort } from './ports/host-port.js';
-import type { ManifestPort } from './trash/manifest.js';
+import type { TrashLedger } from './trash/ledger.js';
 /** Node 半的基础依赖面：组合根只装配这一颗；动词之间不互相 import 依赖面 interface。 */
 export interface CoreDeps {
     fs: FsPort;
     host: HostPort;
-    manifest: ManifestPort;
+    ledger: TrashLedger;
     home: string;
 }
 /** 只有删除读时钟；其余读 / 计划 / 恢复 / 永久删除只用 CoreDeps。 */

package/lib/types/index.d.ts

@@ -19,7 +19,8 @@ export declare const name = "@xrn1997/dsh-session-delete";
  * `super(ctx, "webServer")`），服务名与 `register({kind:'prefix', path, handler})` 的形状按
  * `dsh-host-webserver/lib/index.js` 与 `README.md` 原文读实，不是猜的。
  *
- * 清单（storage domain 绑定）与数据根各有一个家：`src/trash/storage-manifest.ts`、`src/ports/home.ts`。
+ * 清册的三层各有各的家：raw 绑定 `src/trash/storage-manifest.ts`、读面（对账 + 读）`src/trash/ledger.ts`、
+ * 数据根 `src/ports/home.ts`。这里只把它们接起来，任何一层都不在组合根里长判据。
  */
 export declare const inject: string[];
 /**

package/lib/types/ports/host-port.d.ts

@@ -49,23 +49,9 @@ export interface HostPresencePort {
     /** **如实通告**客户端"这个会话没了"：发宿主自己声明并转发的 `api-session/removed`，客户端当场删行。
      *  冷会话没有活体可摘，但同样需要这一条——否则那一行要等到重连（`handleConnected` → 重列）才消失。 */
     announceRemoved(sessionId: string): Promise<void>;
-    /** **如实通告**客户端"这个会话回来了"：摘要取自宿主自己的会话列表，发 `api-session/added`。
-     *  正常恢复走 {@link HostPresencePort.announceRestoredBatch}（整批一次预取）；这一条单条路是**删除组回滚**
-     *  用的（成员已经收过"已移除"、退回原处后补发）。取不到摘要就不发。 */
-    announceRestored(sessionId: string): Promise<void>;
-    /** 宿主会话表的一次预取：`[{ sessionId, summary }]`，`summary` 是宿主**原样**那一条。
-     *  给 {@link announceRestoredBatch} 当 `known` 用——整批只拉一次表。服务没挂回空表，不抛。 */
-    restoredSummariesOf(): Promise<readonly {
-        readonly sessionId: string;
-        readonly summary: unknown;
-    }[]>;
-    /** 一组会话的通告（2026-10-17 批量重构）：`known` 是调用方**整批预取**的摘要表——给了就一次都不
-     *  再拉表（每条一次 `controller.list()` 在 100 条的批量里就是 100 遍全表扫，那是那次"恢复很慢"的
-     *  头号来源）；没给则自己拉一次。缺席 id 不发，不影响已完成的恢复。 */
-    announceRestoredBatch(ids: readonly string[], known?: readonly {
-        readonly sessionId: string;
-        readonly summary: unknown;
-    }[]): Promise<void>;
+    /** 一组会话的「回来了」通告：implementation 拉一次宿主会话表，按 id 逐条发 added。
+     *  单条就是长度为 1 的批；批量只调一次。缺席 id 不发，不影响已完成的恢复。 */
+    announceRestored(sessionIds: readonly string[]): Promise<void>;
 }
 /**
  * 一次语料读的结果：**缺席显式化**——`available: false` 说的是"这一趟看不见语料"（`sessionQuery` 没挂，
@@ -96,7 +82,7 @@ export interface HostCorpusPort {
      *  键按调用方传进来的写法回（同一个父的 `session-x` / `x` 两种写法是同一个根，见 `membersFor`）。 */
     subagentMembersOf(parentIds: readonly string[]): Promise<CorpusRead<Record<string, readonly SubagentMember[]>>>;
 }
-/** 复合别名：adapter（`createHostPort`）与调用方把这 17 个方法当一个端口用；三个角色是它的切面。 */
+/** 复合别名：adapter（`createHostPort`）与调用方把这 15 个方法当一个端口用；三个角色是它的切面。 */
 export type HostPort = HostIdentityPort & HostPresencePort & HostCorpusPort;
 export interface SessionIdentity {
     readonly sessionId: string;

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

@@ -212,6 +212,13 @@ export type RouteCode = (typeof ROUTE_CODES)[number];
  */
 export type AllCodeSuffix = VerbCode | RouteCode;
 export declare const SESSION_DELETE_CODES: Record<AllCodeSuffix, `sessiondelete/${AllCodeSuffix}`>;
+/** `error.code` 是不是本仓的失败形状（`sessiondelete/<后缀>`）。**只认前缀**：后缀在不在册是
+ *  {@link verbCodeOf} 的问题。任何要「已经是本仓的码就原样对待」的调用点都问这一句，不在调用点
+ *  再写一份前缀字面量。 */
+export declare function isSessionDeleteCodeError(error: unknown): boolean;
+/** `error.code` 折回那个动词词：前缀与后缀两件都成立才交回（后缀要在 {@link VERB_CODES} 册上）。
+ *  路由自检码、别域的码、非字符串 code 一律 `undefined`。 */
+export declare function verbCodeOf(error: unknown): VerbCode | undefined;
 /** 回收站目录名（相对宿主数据根）。Node 半拼路径，浏览器半在页脚念它——同一个字面量。 */
 export declare const TRASH_DIR_NAME = "session-trash";
 /** 页脚/文案里带尾斜杠的那一版（`splitOn` 按它切一刀再把目录名包成 code）。 */

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

@@ -1,4 +1,4 @@
-import type { ManifestPort } from './manifest.js';
+import type { TrashLedger } from './ledger.js';
 import type { FsPort } from '../ports/fs-port.js';
 import type { TrashDetailMessageWire, TrashDetailWire } from '../shared/wire.js';
 /** 每条文字的上限（字符）。超出即截断并置 `truncated`。 */
@@ -10,8 +10,11 @@ export declare const TOTAL_CHAR_CAP = 500000;
 export type TrashDetailMessage = TrashDetailMessageWire;
 export type TrashDetail = TrashDetailWire;
 export type DetailDeps = {
+    /** 详情自己直接要的三件（判目录在不在、挑日志、读日志）。对账不在这条路上，所以不需要 `listDirs`。 */
     fs: Pick<FsPort, 'exists' | 'listFiles' | 'readFile'>;
-    manifest: ManifestPort;
+    /** 详情只读清册的 **raw 面**：`/detail` 声明为 pure，读一次不能顺手对账——对账会写清册行，那是写动作，
+     *  必须排在到达序链上。代价是有意的：只有目录、清册还没这一行的手工搬入条目读不到（`/list` 对账后可见）。 */
+    ledger: Pick<TrashLedger, 'raw'>;
     home: string;
 };
 /** 两个载荷闸（可调是为把策略单独验穿；生产走的就是这两个默认值，用例里钉着）。 */

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

@@ -9,8 +9,9 @@
  * **接得住孩子的只有组根**——自己不记 `parentEntryId` 的那一行。父行不在、或父行自己也是孩子时，
  * 孩子必须自己占一行，否则它的字节会被头部合计数两遍（而它自己既看不见也清不掉）。
  *
- * 三个函数都是**纯函数**、都吃一份快照：`/apply` 那条路会在同一批里多次重问、而快照会被就地收缩，
- * 收缩的时机归调用方——groups module 不持有可变状态，也就没有"这份快照谁负责更新"的第二套契约。
+ * 三个函数都是**纯函数**、都吃一份快照：`/apply` 那条路会在同一批里多次重问；批量层持有一份
+ * 会收缩的当前视图（`verbs/batch-carried.ts`），收缩时机归调用方——groups module 不持有可变状态，
+ * 也就没有"这份快照谁负责更新"的第二套契约。
  */
 import type { TrashEntry } from './entry.js';
 /** 一条露面的组根，连同它接住的孩子（顺序与清册一致）。 */
@@ -35,11 +36,21 @@ export declare function visibleGroups(rows: readonly TrashEntry[]): TrashGroupVi
  *   调用方据此报 `trash-empty` / 判"已被同批前一条带走"。
  */
 export declare function groupOf(rows: readonly TrashEntry[], id: string): TrashEntry[];
+/** 一条 id 在「原始快照 vs 当前视图」里的三态。判别联合：**只有 `fresh` 带当前这一组**——
+ *  组语义只对"还在"的 id 有意义，carried / absent 没有可交的组，调用方也就无从误用。 */
+export type GroupClaim = {
+    readonly verdict: 'fresh';
+    readonly group: readonly TrashEntry[];
+} | {
+    readonly verdict: 'carried';
+} | {
+    readonly verdict: 'absent';
+};
 /**
- * 「这条是被**同批前一条**带走的，还是整批开始前就没有？」
+ * 「这条是被**同批前一条**带走的，还是整批开始前就没有，还是仍在？」
  *
- * 幂等语义只属于前者：后来者本来就不在清册里（用户点了条幽灵 id、或对账刚摘掉它）必须照样响亮报
+ * 幂等语义只属于 `carried`：后来者本来就不在清册里（用户点了条幽灵 id、或对账刚摘掉它）必须照样响亮报
  * `trash-empty`，不能被"已被带走"这句话掩盖成成功。**所以判据是快照的原始形状，不是当前形状**：
- * 原始快照里认得出（它自己、它的父、或它的孩子任一在），而当前快照里已经空了 ⇒ 同批带走的。
+ * 原始快照里认得出（它自己、或指向它的孩子任一在），而当前快照里已经空了 ⇒ 同批带走的。
  */
-export declare function takenByEarlierInBatch(original: readonly TrashEntry[], current: readonly TrashEntry[], id: string): boolean;
+export declare function claimOf(original: readonly TrashEntry[], current: readonly TrashEntry[], id: string): GroupClaim;

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

@@ -0,0 +1,20 @@
+/**
+ * 清册的两个读面：**真相读走 `list()`（先对账，再交行）；pure 读面走 `raw()`（只回索引，不写行）**。
+ *
+ * 外部事实源是 `session-trash/` 里的目录；`manifest.list()` 只是 raw 索引。
+ * 消费方只认这个 seam：写动作与真相读用 `list()`，不再各自记得"读前先 reconcile"；`/orphans` 与 `/detail`
+ * 声明为 pure，只许 `raw()`——一次 pure 读若顺手对账，就等于把一个写动作带到了到达序链之外。
+ * **它不是 `ManifestPort`**：同名 `list()` 的语义已经换成真相读，拿它当 raw 端口用会漏对账或递归对账。
+ * 两条写口从 raw 端口取；raw 端口本身只留给本 module 与 `src/trash/reconcile.ts` 的 implementation。
+ */
+import type { FsPort } from '../ports/fs-port.js';
+import type { TrashEntry } from './entry.js';
+import type { ManifestPort } from './manifest.js';
+export interface TrashLedger extends Pick<ManifestPort, 'add' | 'remove'> {
+    /** 真相读：先对账、再交行。`/list`、`/empty` 与写动词都认这一条。 */
+    list(): Promise<TrashEntry[]>;
+    /** raw 索引快照：**不对账、不写行**。只给声明为 pure 的读面（`/orphans` 扫描、`/detail` 详情）；
+     *  要知道"此刻真有的一切"用 `list()`。 */
+    raw(): Promise<TrashEntry[]>;
+}
+export declare function createTrashLedger(raw: ManifestPort, fs: FsPort, home: string): TrashLedger;

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

@@ -1,5 +1,6 @@
 import type { TrashEntry } from './entry.js';
-/** 回收站清单的**唯一**读法（动词只依赖这个端口，不认 storage domain 的形状）。 */
+/** 回收站清单的 **raw 索引端口**：只给 `src/trash/ledger.ts` 与对账实现；动词与路由只认 ledger，
+ *  不认 storage domain 的形状。`list()` 不保证与 `session-trash/` 目录一致（对账在 ledger 的 `list()`）。 */
 export interface ManifestPort {
     list(): Promise<TrashEntry[]>;
     add(e: TrashEntry): Promise<void>;

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

@@ -5,9 +5,10 @@
  * `~/.dsh/storages/` 那份清单从此是**内部索引**，不用手碰。
  *
  * 五条口径（都不是口味）：
- * ① **每次读清单都对账**（`GET /list` 的正文就是"对账 + 读"）：挂载、刷新、别处动过后的自动重读、
- *    客户端启动探测全走这条 ⇒ "改完目录不用再做任何事，下一次读就对了"。代价 = 每次读多一次目录枚举
- *    （本机 124 条，毫秒级）；**零漂移零写入**（快路直接返回原清单）。
+ * ① **每次真相读都对账**（`src/trash/ledger.ts` 的 `list()`；`GET /list` 的正文就是"对账 + 读"）：挂载、
+ *    刷新、别处动过后的自动重读、客户端挂载后的首次列表读全走这条 ⇒ "改完目录不用再做任何事，下一次读就对了"。
+ *    pure 读面（`/orphans`、`/detail`）走 `raw()`，不对账——对账会写行，必须排在到达序链上。
+ *    代价 = 每次真相读多一次目录枚举（本机 124 条，毫秒级）；**零漂移零写入**（快路直接返回原清单）。
  * ② **回收站根不在 ⇒ 整套跳过、一个字节都不动**：那不是"回收站空了"，是"这块地不在原处"
  *    （人为搬走、盘没挂上）——照常对账会把全部行的元数据一次判没。
  * ③ **重建行只写"文件里真有的事实"**：`id` = 目录名、`sessionId`/`cwd` 读日志 header、

package/lib/types/verbs/batch-carried.d.ts

@@ -0,0 +1,20 @@
+import type { TrashEntry } from '../trash/entry.js';
+import { type GroupClaim } from '../trash/groups.js';
+export interface EntryBatchCarried {
+    claim(id: string): GroupClaim;
+    take(id: string): void;
+    /** 收缩中的当前视图（`take` 过的那一组已经不在里面）。 */
+    rows(): readonly TrashEntry[];
+}
+/** session 域没有组可交：claim 只回答 fresh / carried。 */
+export type SessionClaim = {
+    readonly verdict: 'fresh' | 'carried';
+};
+export interface SessionBatchCarried {
+    claim(id: string): SessionClaim;
+    take(id: string): void;
+}
+/** 恢复 / 彻底删除：原始快照认得、当前视图已经空了 ⇒ 同批前一条带走的。 */
+export declare function createEntryCarried(original: readonly TrashEntry[]): EntryBatchCarried;
+/** 删除：会话 id 域；`take` 只收这次真的搬走的成员（父 + 盘上的孩子）。 */
+export declare function createSessionCarried(): SessionBatchCarried;

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

@@ -2,7 +2,7 @@ import { type TrashEntry } from '../trash/entry.js';
 import type { DeleteDeps } from '../deps.js';
 export interface DeleteResult {
     readonly entry: TrashEntry;
-    /** 这一次真的搬进回收站的成员（父 + 盘上存在的孩子）；批量层用它建幂等账本。 */
+    /** 这一次真的搬进回收站的成员（父 + 盘上存在的孩子）；批量层用它建同批已带走集。 */
     readonly movedSessionIds: readonly string[];
 }
 /**
@@ -10,7 +10,7 @@ export interface DeleteResult {
  * 整排藏了 ⇒ 那些目录既看不见也继续占着字节（本机实测 41 条父留了 320 个目录 / 74.6 MB）。
  * 所以这里把父在盘上的孩子一起搬进来，各自成目录、各自一行，清册用 `parentEntryId` 记它是谁的孩子。
  *
- * 三段，顺序承重：
+ * 三段，顺序承重（成员循环与整组回滚的实现住 `verbs/move-group.ts`）：
  * ① **先点组、先验活体**（一个字节都不写）。任一成员在跑就整组拒绝——不替用户终止正在跑的活，
  *    也绝不允许"父已经搬进回收站、孩子因为在跑而搬不动"这种半套。
  * ② **逐个搬**：每个成员是一份 `journal`（`verbs/member-journal.ts`），搬不动时 journal 自己把
@@ -18,7 +18,8 @@ export interface DeleteResult {
  * ③ **组级回滚**：某一个成员搬不动时，把**已经搬进去的**那些按相反顺序退回原处（清册行跟着摘、
  *    账本跟着挂），失败照抛——不留"半组在回收站、半组在原地"的世界。
  *
- * interface 只有**一个 id**：批量的性质不在这里（同批"已被前一条带走"的判据归 `verbs/batch.ts`）。
+ * interface 只有**一个 id**：批量的性质不在这里（同批已带走集归 `verbs/batch-carried.ts`，
+ * 组语义归 `trash/groups.ts`）。
  * 结果带回这次真的搬走的整组（`movedSessionIds`）——它是动词交回的内部数据，不再靠回调借用动词的手。
  */
 export declare function deleteSession(deps: DeleteDeps): (sessionId: string) => Promise<DeleteResult>;

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

@@ -1,14 +1,6 @@
-/** 五个码 / 三个路由自检码的**家都在 `shared/wire.ts`**（ADR-0003）：浏览器半也要认它们（比如
- *  `not-found` 在界面上是中性提示而不是失败），所以它们属于两半共同的契约，不属于 Node 半。
- *  这里只转出旧名，免得调用点全改一遍。 */
+/** 失败的**结构与措辞**。码本身、码的前缀读法与动词词表都住在 `shared/wire.ts`（ADR-0003）：
+ *  浏览器半也要认它们，它们属于两半共同的契约，不属于 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 declare const ROUTE_CODES: readonly ["bad-method", "not-found-route", "bad-request"];
-export type { RouteCode, VerbCode };
-/** `error.code` 是不是本仓的动词码（`sessiondelete/<码>`）。**唯一判据**：`journalFailure` 与永久删除
- *  执行器要"已经是动词码就原样抛"时都问这一句。同文件的 `withRollbackFailures` 还要码的后缀，所以它
- *  就地 `slice` 一次——前缀仍只住 `VERB_CODE_PREFIX` 这一处，别在调用点另写一份字面量。 */
-export declare function isVerbCodeError(error: unknown): boolean;
 /** 一次失败的**结构**：码、上屏原文、可选 cause（`map-error` 沿 cause 链认宿主类型化错误）、
  *  可选的结构化附带物（对齐官方 `rpcErrorSchema` 的第三件 `details`）。 */
 export interface VerbError extends Error {

package/lib/types/verbs/live-admission.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 活体准入：一次删除 / 永久删除 / 孤儿清理之前，逐个问「这个会话在宿主内存里 attach 着吗」——
+ * 任一个在跑就整组拒绝、零副作用（词表见 CONTEXT.md 的「活体」条；裁决见 ADR-0008）。
+ *
+ * 为什么单独一个 module：删除的逐个成员与永久删除计划的 targets + 盘上后代，此前各手写一遍同一条
+ * 循环、同一句原文。两处只要有一处改了措辞或漏查一个 id，客户端拿到的就是两种「还在跑」。
+ *
+ * 边界：**什么时候查归调用方**。永久删除的准入仍住在计划里、在任何写之前（ADR-0006：计划就是执行前的闸）；
+ * 这个 module 只拥有「查什么、怎么判、怎么说」。
+ */
+import type { HostIdentityPort } from '../ports/host-port.js';
+/** 逐个问，任一在跑就抛 `live`。名单的挑选（哪些成员算这一组）归调用方，这里只按传入顺序问完。 */
+export declare function assertNoLive(host: Pick<HostIdentityPort, 'isLive'>, sessionIds: readonly string[]): Promise<void>;

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

@@ -1,10 +1,27 @@
+/** 一步反向动作的结果：这一 step 的领域键（`key`）是否回到原样 + 没能退干净的原因。
+ *  `restored` 只回答键所指的那件写；同一步里的附属写失败仍进 `failures`
+ *  （例如删除的目录回来了、清册行没摘掉：客户端仍要收到 added，失败只算回滚不完整）。 */
+export interface StepUndo {
+    readonly restored: boolean;
+    readonly failures: readonly string[];
+}
+/** 一步的领域键（`read` / `workspace` / `dir` / `archive` / `manifest`）。`restored(key)` 用它点名
+ *  要核的那件写；收成联合，动词手滑写错键在编译期就报。 */
+export type JournalStepKey = 'read' | 'workspace' | 'dir' | 'archive' | 'manifest';
+/** 一次 undo 的汇总：失败串仍按原样合并；`restored(key)` 给动词判「成员归位 / 已移除」用。 */
+export interface JournalUndo {
+    readonly failures: readonly string[];
+    restored(key: JournalStepKey): boolean;
+}
 export interface JournalStep {
+    /** 稳定的领域键，给 `restored(key)` 用。 */
+    readonly key: JournalStepKey;
     /** 这一步在做什么。失败原文按「`<label>：<原错误>`」拼——与迁移前那 22 处 `rollbackReason` 的措辞同形。 */
     readonly label: string;
     /** 做这一步。抛什么都由 journal 折成 `sessiondelete/io`（除非它自己已经是一个动词码）。 */
     run(): Promise<void>;
-    /** 反向动作。**`run` 成功之后**才会被登记；返回**这一步自己**没能退干净的原因列表（空 = 完全退回）。 */
-    undo?(): Promise<readonly string[]>;
+    /** 反向动作。**`run` 成功之后**才会被登记；返回这一步退没退成与原因。 */
+    undo?(): Promise<StepUndo>;
     /** 这一步**自己**失败时也跑 `undo`：给"可能已经半做完"的非原子步骤用（取消归档是唯一的例子）。 */
     readonly undoOnFailure?: boolean;
 }
@@ -12,12 +29,14 @@ export interface Journal {
     /** 按顺序跑完。中途失败 ⇒ 已做成的按相反顺序退回，然后把原错误（带 `rollbackFailures`）抛出去。 */
     run(): Promise<void>;
     /** 把**已经做成**的步骤按相反顺序退回去（整组回滚用：组里后面那个成员搬不动时叫这一句）。 */
-    undo(): Promise<readonly string[]>;
+    undo(): Promise<JournalUndo>;
 }
 /** 已经把某个前缀做成了的 journal——`undo()` 就退那一个前缀。 */
 export declare function createJournal(steps: readonly JournalStep[]): Journal;
 /** 跑一步反向动作并把它自己的失败收成一条原因（不抛：这些失败由调用方汇总成 `rollbackFailures`）。 */
 export declare function attempt(label: string, run: () => Promise<unknown>): Promise<readonly string[]>;
+/** 一步反向动作的完整结果：主写是否回到原样 + 失败串。附属写失败只进 `failures`，不推翻 `restored`。 */
+export declare function stepUndo(label: string, run: () => Promise<unknown>): Promise<StepUndo>;
 /**
  * **组级回滚**：把已经做成的成员按相反顺序退回；某一步退不干净时把失败并进原错误的
  * `details.rollbackFailures`，绝不让原错误独走（2026-10-19 `f2a7757`；那些失败句子的合并与措辞住

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

@@ -3,19 +3,23 @@
  *
  * 为什么要有它：delete（成功与回滚）/ restore 回滚 / purge（两个分支）/ orphan-clean
  * 六处调用曾经各写一遍
- * `evictLive → !== 'unknown' → announceRemoved`；删除回滚还要自己拼
- * `movedBack && workspaceBack` 才发 `announceRestored`。
+ * `evictLive → !== 'unknown' → announceRemoved`；删除回滚还要自己拼目录与账本两个布尔
+ * 才发 `announceRestored`。
  * 这条协议说错一次就是客户端留着假行、或删掉真行，所以只留一个家。
  *
  * 边界：
- * - 批量恢复的 `announceRestoredBatch` 不进来：一次预取、一批一次通告归 `verbs/batch.ts`（ADR-0002）。
- * - 不读 journal 的失败串：调用方交事实（目录 / 账本是否回去），真值表住这里。
+ * - 批量恢复自己发起的那次通告（`announceRestored(ids)`）归 `verbs/batch.ts`（ADR-0002）：同一个方法、
+ *   同一份预取，只是调用方是那一批的主人。这里只判单成员事实。
+ * - 本模块不决定哪个键算归位：动词在 `tail.onUndone` 里把 `restored(key)` 读成事实再交进来，真值表住这里；
+ *   `run` / `undo` 之后补一条通告的**形状**由 {@link withPresenceTail} 拥有。
  * - 本模块用到的三条（`evictLive` / `announceRemoved` / `announceRestored`）按契约不抛（evictLive 三态、
  *   announce* 内部吞异常），这里不再叠 catch。
  */
 import type { HostPresencePort } from '../ports/host-port.js';
-/** 本模块实际用到的三条宿主能力。取窄面而不是整个 `HostPresencePort`：那条协议里还有批量通告与
- *  摘要预取，它们各有自己的家（`verbs/batch.ts`），这里不该因为共用同一颗 adapter 就声明依赖。 */
+import type { Journal, JournalUndo } from './member-journal.js';
+/** 本模块实际用到的三条宿主能力。`Pick` 此刻覆盖 `HostPresencePort` 的三条方法，仍留着它当闸：
+ *  将来端口多出第四条时，这里不会被动跟着变宽——这里是单成员协议，批量恢复由 `verbs/batch.ts`
+ *  自己发起，不该因为共用同一颗 adapter 就在类型上声明依赖。 */
 export type MemberPresenceHost = Pick<HostPresencePort, 'evictLive' | 'announceRemoved' | 'announceRestored'>;
 export interface MemberBackFacts {
     /** 目录搬回原处了吗。 */
@@ -33,3 +37,31 @@ export interface MemberPresence {
     memberBack(sessionId: string, facts: MemberBackFacts): Promise<void>;
 }
 export declare function createMemberPresence(host: MemberPresenceHost): MemberPresence;
+/** 一次 undo 之后要发哪一条通告：`leave` = 成员已不在可见面，`return` = 已回到原可见状态。 */
+export type PresenceAnnounce = {
+    readonly kind: 'leave';
+    readonly backInTrash: boolean;
+} | {
+    readonly kind: 'return';
+    readonly diskBack: boolean;
+    readonly workspaceBack: boolean;
+};
+/** 动词给工厂的那一格：哪个成员、run 成不成功要不要补离场、undo 之后按逐步结果发哪一条。 */
+export interface PresenceTail {
+    readonly sessionId: string;
+    /** `run()` 成功后补离场通告（删除用）。省略 = run 不动在场（恢复的 run 本来就不该发东西）。 */
+    readonly onDone?: 'leave';
+    /** `undo()` 完成后按逐步结果发通告。 */
+    onUndone(undo: JournalUndo): PresenceAnnounce;
+}
+/**
+ * 给一次成员移动的 journal 补上「在场那条尾巴」：run 完全成功之后离场、undo 之后按事实归位或离场。
+ *
+ * 为什么是个工厂：删除与恢复此前各手拼一个匿名 journal，形状逐字相同（`journal.run` 加上
+ * `presence.memberGone`／`journal.undo` 加上 `presence.memberBack`），只差键 → 事实的映射。
+ * 两处各写一遍，就是「补在哪一拍」这条顺序又有第二个家。
+ *
+ * 边界：`memberGone` 的 `backInTrash:false` 早退与 `memberBack` 的两件齐备真值表仍归 `createMemberPresence`；
+ * 这里只把事实原样递过去，不替它判断。
+ */
+export declare function withPresenceTail(presence: MemberPresence, journal: Journal, tail: PresenceTail): Journal;

package/lib/types/verbs/move-group.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 组级成员移动：组根先跑（拿到 `undefined`），跟随者按序跑并拿到根结果；任一失败就把**已经做成**的
+ * 按相反顺序退回。
+ *
+ * 这里拥有顺序、整组回滚与**组根结果的交回**：根先跑，跟随者按序拿到根结果；调用方直接拿
+ * 返回的根结果，不按位置索引结果数组。跟随者自己的结果不向上交回——当前调用方不需要。
+ * 单成员的步骤与反向动作仍归 `member-journal.ts`；这条归属的裁决见 ADR-0002。
+ */
+import { type Journal } from './member-journal.js';
+export interface GroupMove<M, R> {
+    /** 组根：先跑，`move` 收到的 `rootResult` 是 `undefined`。 */
+    readonly root: M;
+    /** 跟随者：按序跑，每个都拿到根结果（彼此看不到对方的结果）。 */
+    readonly followers: readonly M[];
+    move(member: M, rootResult: R | undefined): Promise<{
+        journal: Journal;
+        result: R;
+    }>;
+}
+export declare function moveGroup<M, R>({ root, followers, move, }: GroupMove<M, R>): Promise<R>;

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

@@ -1,4 +1,5 @@
 import { type SessionIdentity } from '../ports/host-port.js';
+import type { TrashEntry } from '../trash/entry.js';
 import type { OrphanCleanStatsWire, OrphanReportWire } from '../shared/wire.js';
 import type { CoreDeps } from '../deps.js';
 /** 组里一个人的盘上身份（字节是**扫描那一刻**量的，清理时按目录重量一次，不拿这份快照冒充准数）。 */
@@ -31,13 +32,17 @@ interface RawGroup {
  * 归堆与去重**两边都去 `session-` 前缀**：同一个父在两代宿主里写法不同（见 `bareSessionId` 的来历）。
  */
 export declare function orphanGroupsOf(corpus: readonly SessionIdentity[], trashSessionIds: readonly string[]): RawGroup[];
-/** 纯读：调用方应先走一次 `/list` 对账（面板的 refresh 就是这样）；本函数不写清单。
- *  写动作 `orphan-clean` 会自己先 reconcile，避免拿一份过期清册判"父没了"。
+/** **本函数是纯扫描，不对账、不写清册行**（`/orphans` 声明为 pure，一次扫描不能顺手写行）。清册默认读
+ *   `ledger.raw()`；写路径（`orphan-clean`）可以在调它之前先 `ledger.list()` 对账，并把交回的行递进来，
+ *  免得同一份索引再读一遍——否则刚被人手工搬进 `session-trash/` 的父目录还没有行，会被当成"父没了"
+ *  直接删盘。
  *
  *  `listSessions()` 回 `{ available: false }` 时**必须抛**：那是宿主的会话语料服务没挂，不是"这个家没有孤儿"。
  *  拿缺席当空语料 ⇒ 报告说"零条孤儿"、界面上一句"没有要清理的"，而盘上真有几百 MB——那是假话，
  *  所以这里按 `io` 响亮失败（AGENTS.md：`available: false` 意味着服务缺席，扫描方不许冒充读数）。 */
-export declare function loadOrphanGroups(deps: CoreDeps): Promise<readonly OrphanGroup[]>;
+export declare function loadOrphanGroups(deps: CoreDeps, 
+/** 调用方已对账过的清册行（`ledger.list()`）；缺席则读 `ledger.raw()`。 */
+trash?: readonly TrashEntry[]): Promise<readonly OrphanGroup[]>;
 /** 把一组组收成那份报告：根清单 + 闭包总数/总字节 + 失踪父的**去重计数** + 按项目目录的分摊。
  *  `groups` 按字节从多到少排（界面上"哪家还剩得最多"要看第一行）。 */
 export declare function reportOrphans(groups: readonly OrphanGroup[]): OrphanReportWire;

package/lib/types/verbs/permanent-removal.d.ts

@@ -64,22 +64,22 @@ export interface RemovalPlan {
     readonly trash: readonly PlannedTrashRow[];
     readonly members: readonly PlannedMemberRemoval[];
     readonly unarchive: readonly string[];
+    /** 计划量到的合计；成功回执的 freedBytes 只念它。 */
     readonly bytes: number;
 }
 /**
  * purge 的删除计划：`targets` 由调用方按组语义（`trash/groups.ts`）选好，这里只量、只筛、只查活体。
+ * **计划函数就是执行前的闸**——调用方拿到计划才允许写，所以准入必须发生在任何写之前。
  *
  * - `trash` 按 targets 原序逐个实测（目录缺席的行 `present:false` / 0 字节，但清册行仍要摘）。
  * - 盘上后代经 `selectStrandedMembers` 选出（一次问全部 targets、排除全部清册 id、bare id 全局只计划一次）。
  * - `members` 只收盘上还有目录的成员（目录缺席没有可删的字节）；`unarchive` = targets + 这些成员：
  *   只摘这一次真要碰的 id。
- * - `admission:'live'` 在量目录与任何写之前逐个查 targets 与**全部枚举到的**盘上后代；
- *   任一在跑就整条拒绝，零副作用。
+ * - 活体准入在量目录与任何写之前逐个查 targets 与**全部枚举到的**盘上后代；任一在跑就整条拒绝、
+ *   零副作用。没有跳过它的开关——计划就是执行前的闸（ADR-0006）。
  * - `sessionQuery` 缺席时端口回 `{ available: false }` ⇒ members 为空、不抛（盘上残留留给 `GET /orphans` 兜底）。
  */
-export declare function planTrashRemoval(deps: CoreDeps, rows: readonly TrashEntry[], targets: readonly TrashEntry[], options: {
-    readonly admission: 'none' | 'live';
-}): Promise<RemovalPlan>;
+export declare function planTrashRemoval(deps: CoreDeps, rows: readonly TrashEntry[], targets: readonly TrashEntry[]): Promise<RemovalPlan>;
 /**
  * orphan-clean 的删除计划：成员是调用方扫出来的传递闭包（`orphanGroupsOf`）。
  *
@@ -94,7 +94,8 @@ export declare function planOrphanRemoval(deps: CoreDeps, members: readonly {
     readonly projectDir: string;
 }[]): Promise<RemovalPlan>;
 /**
- * 按计划执行一次永久删除：只写、不再量、不再判活体（计划就是执行前的闸）。
+ * 按计划执行一次永久删除：只写、不再量、不再判活体（计划就是执行前的闸）。回执的字节念计划
+ * （`plan.bytes`），执行期不再累加一遍。
  *
  * 顺序（与迁移前的 purge / orphan-clean 一致）：整批摘归档集 → 摘有账本的成员的账本 → 逐条回收站行
  * （在才删目录 → 摘清册行 → 通告成员离场）→ 逐条盘上成员（删目录 → 通告成员离场）。目录删掉就没有

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

@@ -3,10 +3,12 @@ import type { CoreDeps } from '../deps.js';
 /**
  * 彻底删除：从回收站里**真的**抹掉一条（或整组、或整站），并连带那些"还留在盘上、没被带走"的后代。
  *
- * 与另外两个动词的关系（ADR-0002）：它的 interface 只有"一个条目 id（或缺席 = 清空）"，
- * 批量的快照与"已被同批前一条带走"的判据不在这里（归 `verbs/batch.ts`）。
+ * 与另外两个动词的关系（ADR-0002）：它的 interface 是"这一组目标 + 一份只读清册快照
+ *（targets 缺席 = 清空）"；目标由 `verbs/batch-carried.ts` 按组语义算好，批量的"已被同批前一条
+ * 带走"判据不在这里。`requestedId` 是唯一的例外参数，但它**不参与任何判据**：只是让
+ * `trash-empty` 的原文点得出用户点的是哪一条（原文要上屏，点名承重），批量语义仍在批量层。
  *
- * **这条动词只做两件事：选目标、拿计划交给执行器**。量目录、筛盘上后代、活体准入与"先退归档集、
+ * **这条动词只做两件事：拿目标、把计划交给执行器**。量目录、筛盘上后代、活体准入与"先退归档集、
  * 再摘账本、最后删目录"的顺序都住 `verbs/permanent-removal.ts`——计划只读，执行器只写，计划就是
  * 执行前的闸（别在这里再长出一段手写步骤）。
  *
@@ -14,9 +16,15 @@ import type { CoreDeps } from '../deps.js';
  * 带部分计数的 `details` 回执只属于 `orphan-clean`，purge 的 `removed` / `freedBytes` 仍只在成功回执里给）。
  * 对应地，`kind:'trash'` 的计划失败时执行器只抛那一步的 `io` 与原文、不带 details。
  */
-export declare function purgeTrash(deps: CoreDeps): (entryId?: string, 
-/** **只读**清册快照：批量层已经读过一次就递下来（ADR-0002）；收缩归批量层，动词不碰它。 */
-snapshot?: readonly TrashEntry[]) => Promise<{
+export declare function purgeTrash(deps: CoreDeps): (
+/** 这一组（只读）；`undefined` = 清空。批量层由 `batch-carried.ts` 的 `claimOf` 给出，直调者
+ *  按 `trash/groups.ts` 的 `groupOf` 自己算；ghost 父的组只有孩子（不含 `requestedId`），照样清
+ *  这一组。 */
+targets: readonly TrashEntry[] | undefined, 
+/** **只读**清册快照：批量层已经读过一次就递下来；收缩归 `batch-carried.ts`，动词不碰它。 */
+rows: readonly TrashEntry[], 
+/** 只用于 `trash-empty` 的原文要点名用户点的那一条；不参与任何判据（批量语义归 `batch-carried.ts`）。 */
+requestedId?: string) => Promise<{
     removed: number;
     freedBytes: number;
 }>;

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

@@ -5,7 +5,7 @@ import type { CoreDeps } from '../deps.js';
  * 恢复 = 把删除那次**按原路退回**，而且按组走：当年是按组一起搬进来的（父 + 它在盘上的孩子），
  * 只回父就会在回收站里留下一堆点不到的孩子行——清单只列父行，那些行既看不见也清不掉。
  *
- * 三段与删除对称：
+ * 三段与删除对称（成员循环与整组回滚的实现住 `verbs/move-group.ts`）：
  * ① **预检整组**（一个字节都不写）：每个成员的回收站目录与项目目录都得在。缺席的判据与原来一致
  *    （回收站目录不在 = `trash-empty`；原项目目录不在 = `project-missing`，且绝不静默建目录）。
  *    预检在写之前，是为了不让"父已经回到 `sessions/`、孩子因为项目目录没了而回不去"这种半组留在外面。
@@ -15,13 +15,15 @@ import type { CoreDeps } from '../deps.js';
  * ③ 中途失败时 journal 把这个成员自己退回回收站；**已经恢复完的**兄弟由整组 catch 按相反顺序一起退回。
  *
  * **通告不在这里**：一次批量只该拉一遍宿主会话表、只发一次 `api-session/added`（2026-10-17 那次
- * "恢复很慢"就是逐条发）。通告归 `verbs/batch.ts`（ADR-0002），所以这个动词的 interface 只有
- * "一个条目 id 进、回收站那一行出"，没有批量专用的开关。
+ * "恢复很慢"就是逐条发）。通告归 `verbs/batch.ts`（ADR-0002），所以这个动词的 interface 是
+ * "一个条目 id + 这一组进、回收站那一行出"，没有批量专用的开关。
  */
 export declare function restoreSession(deps: CoreDeps): (entryId: string, 
-/** **只读**清册快照：批量层已经读过一次就递下来，整批因此只读一次（ADR-0002）。
- *  动词**不收缩**它——收缩与"已被同批前一条带走"的判据都归 `verbs/batch.ts`。 */
-snapshot?: readonly TrashEntry[]) => Promise<TrashEntry>;
+/** 这一组（只读）：批量层由 `batch-carried.ts` 的 `claimOf` 给出，直调者按 `trash/groups.ts`
+ *  的 `groupOf` 自己算。ghost 父（父行已摘、只剩孩子）的组只有孩子、不含 `entryId`，这里照旧
+ *  报 `trash-empty`；其余调用按这一组整体恢复。动词**不收缩**它——收缩与同批已带走集都归
+ *  `verbs/batch-carried.ts`，组语义归 `trash/groups.ts`。 */
+group: readonly TrashEntry[]) => Promise<TrashEntry>;
 /**
  * 这一次恢复**到底挂不挂账本**：交出能挂的那个 `workspaceId`，挂不了就 `undefined`。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xrn1997/dsh-session-delete",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "在 DeepSeek Harness 里删除会话：删除=移入回收站（可恢复），另设显式彻底删除",
   "type": "module",
   "main": "lib/index.js",
@@ -73,7 +73,8 @@
       "dshReleases": {
         "0.2.0-rc.2": "compatible",
         "0.2.1-rc.1": "compatible",
-        "0.2.1-rc.2": "compatible"
+        "0.2.1-rc.2": "compatible",
+        "0.2.1-rc.3": "compatible"
       }
     }
   },

package/lib/types/client/write-commit.d.ts

@@ -1,10 +0,0 @@
-/**
- * 回收站面板之外发生的写入（菜单删除、批量删除、撤销恢复）的**跨槽位收尾顺序**：
- * 主视图收尾 → 失效回收站 → 撤销通告。面板自己的写入，本地 refresh / 缓存的
- * 生命周期仍住在 controller 与 query 里。
- */
-export declare function commitExternalDelete(input: {
-    sessionIds: readonly string[];
-    publishUndo(): void;
-}): void;
-export declare function commitExternalRestore(sessionIds: readonly string[]): void;