@xrn1997/dsh-session-delete 0.3.1 → 0.5.0

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

@@ -16,7 +16,7 @@ export interface JournalUndo {
 export interface JournalStep {
     /** 稳定的领域键，给 `restored(key)` 用。 */
     readonly key: JournalStepKey;
-    /** 这一步在做什么。失败原文按「`<label>：<原错误>`」拼——与迁移前那 22 处 `rollbackReason` 的措辞同形。 */
+    /** 这一步在做什么。失败原文按「`<label>：<原错误>`」拼。 */
     readonly label: string;
     /** 做这一步。抛什么都由 journal 折成 `sessiondelete/io`（除非它自己已经是一个动词码）。 */
     run(): Promise<void>;
@@ -39,8 +39,7 @@ export declare function attempt(label: string, run: () => Promise<unknown>): Pro
 export declare function stepUndo(label: string, run: () => Promise<unknown>): Promise<StepUndo>;
 /**
  * **组级回滚**：把已经做成的成员按相反顺序退回；某一步退不干净时把失败并进原错误的
- * `details.rollbackFailures`，绝不让原错误独走（2026-10-19 `f2a7757`；那些失败句子的合并与措辞住
- * `src/verbs/errors.ts`，这里只是唯一的调用方）。删除与恢复两个按组走的动词共用这一处，
- * "相反顺序 + 失败合并"不再各写一遍。
+ * `details.rollbackFailures`，绝不让原错误独走。那些失败句子的合并与措辞住 `src/verbs/errors.ts`；
+ * 删除与恢复两个按组走的动词共用这一处。
  */
 export declare function rollbackJournals(journals: readonly Journal[], error: unknown): Promise<never>;

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

@@ -1,42 +1,25 @@
 /**
  * 成员离场 / 归位的通告协议：摘活体、三态判断、成对事件只在这里做。
  *
- * 为什么要有它：delete（成功与回滚）/ restore 回滚 / purge（两个分支）/ orphan-clean
- * 六处调用曾经各写一遍
- * `evictLive → !== 'unknown' → announceRemoved`；删除回滚还要自己拼目录与账本两个布尔
- * 才发 `announceRestored`。
- * 这条协议说错一次就是客户端留着假行、或删掉真行，所以只留一个家。
+ * 调用方包括 delete、restore 回滚、purge、orphan-clean；协议说错一次就是客户端留假行或删真行。
  *
  * 边界：
- * - 批量恢复自己发起的那次通告（`announceRestored(ids)`）归 `verbs/batch.ts`（ADR-0002）：同一个方法、
- *   同一份预取，只是调用方是那一批的主人。这里只判单成员事实。
- * - 本模块不决定哪个键算归位：动词在 `tail.onUndone` 里把 `restored(key)` 读成事实再交进来，真值表住这里；
- *   `run` / `undo` 之后补一条通告的**形状**由 {@link withPresenceTail} 拥有。
- * - 本模块用到的三条（`evictLive` / `announceRemoved` / `announceRestored`）按契约不抛（evictLive 三态、
- *   announce* 内部吞异常），这里不再叠 catch。
+ * - 批量恢复的编排归 `verbs/batch.ts`（ADR-0002）；本模块只实现 `announceRestored(ids)`（ADR-0019）。
+ * - 哪个键算归位由动词在 `tail.onUndone` 里读成事实再交进来，真值表住这里；
+ *   `run`/`undo` 之后补通告的形状由 {@link withPresenceTail} 拥有。
+ * - `evictLive`/`announce*` 按契约不抛，这里不再叠 catch。
  */
 import type { HostPresencePort } from '../ports/host-port.js';
+import type { PresenceCapability } from '../ports/presence-port.js';
 import type { Journal, JournalUndo } from './member-journal.js';
 /** 本模块实际用到的三条宿主能力。`Pick` 此刻覆盖 `HostPresencePort` 的三条方法，仍留着它当闸：
- *  将来端口多出第四条时，这里不会被动跟着变宽——这里是单成员协议，批量恢复由 `verbs/batch.ts`
- *  自己发起，不该因为共用同一颗 adapter 就在类型上声明依赖。 */
+ *  将来端口多出第四条时，这里不会被动跟着变宽——能力面只暴露这三条，批量通告的编排归 `verbs/batch.ts`。 */
 export type MemberPresenceHost = Pick<HostPresencePort, 'evictLive' | 'announceRemoved' | 'announceRestored'>;
-export interface MemberBackFacts {
-    /** 目录搬回原处了吗。 */
-    readonly diskBack: boolean;
-    /** 账本挂回去了吗（本来没有账目时算 true）。 */
-    readonly workspaceBack: boolean;
-}
-export interface MemberPresence {
-    /** 成员已经不在宿主可见列表：摘活体；三态不是 unknown 时发 removed。
-     *  `backInTrash: false` 表示目录没退回回收站（恢复回滚失败），此时什么都不做。 */
-    memberGone(sessionId: string, facts?: {
-        readonly backInTrash?: boolean;
-    }): Promise<void>;
-    /** 成员已经回到原来的可见状态：目录与账本两件写都回去才发 added。 */
-    memberBack(sessionId: string, facts: MemberBackFacts): Promise<void>;
-}
-export declare function createMemberPresence(host: MemberPresenceHost): MemberPresence;
+/** 本仓的在场能力实现，也是**全仓唯一的盖章处**：端口形状住 `src/ports/presence-port.ts`，这里只做
+ *  三态与真值表。品牌字段是类型层的（unique symbol 不导出、没有运行时值），所以只有这一处显式断言
+ *  能把三件方法盖成 `PresenceCapability`——手拼同样的三件满足不了那个面（`tests/deps.test.ts` 钉住）。
+ *  `announceRestored` 直接交宿主那一手：能力面与宿主面同名同签名，再包一层只会多一个转调。 */
+export declare function createMemberPresence(host: MemberPresenceHost): PresenceCapability;
 /** 一次 undo 之后要发哪一条通告：`leave` = 成员已不在可见面，`return` = 已回到原可见状态。 */
 export type PresenceAnnounce = {
     readonly kind: 'leave';
@@ -55,13 +38,9 @@ export interface PresenceTail {
     onUndone(undo: JournalUndo): PresenceAnnounce;
 }
 /**
- * 给一次成员移动的 journal 补上「在场那条尾巴」：run 完全成功之后离场、undo 之后按事实归位或离场。
- *
- * 为什么是个工厂：删除与恢复此前各手拼一个匿名 journal，形状逐字相同（`journal.run` 加上
- * `presence.memberGone`／`journal.undo` 加上 `presence.memberBack`），只差键 → 事实的映射。
- * 两处各写一遍，就是「补在哪一拍」这条顺序又有第二个家。
+ * 给一次成员移动的 journal 补上「在场那条尾巴」：run 完全成功之后离场，undo 之后按事实归位或离场。
  *
- * 边界：`memberGone` 的 `backInTrash:false` 早退与 `memberBack` 的两件齐备真值表仍归 `createMemberPresence`；
- * 这里只把事实原样递过去，不替它判断。
+ * 边界：`memberGone` 的 `backInTrash:false` 早退与 `memberBack` 的两件齐备真值表归 `createMemberPresence`；
+ * 这里只把事实原样递过去。
  */
-export declare function withPresenceTail(presence: MemberPresence, journal: Journal, tail: PresenceTail): Journal;
+export declare function withPresenceTail(presence: PresenceCapability, journal: Journal, tail: PresenceTail): Journal;

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

@@ -12,7 +12,8 @@ export interface GroupMove<M, R> {
     readonly root: M;
     /** 跟随者：按序跑，每个都拿到根结果（彼此看不到对方的结果）。 */
     readonly followers: readonly M[];
-    move(member: M, rootResult: R | undefined): Promise<{
+    /** 属性声明：`move` 会被解构出来按序调用（实现不读 `this`），方法简写会带隐式 `this: GroupMove`。 */
+    move: (member: M, rootResult: R | undefined) => Promise<{
         journal: Journal;
         result: R;
     }>;

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

@@ -1,7 +1,7 @@
-import { type SessionIdentity } from '../ports/host-port.js';
+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';
+import type { CoreDeps, RemovalDeps } from '../deps.js';
 /** 组里一个人的盘上身份（字节是**扫描那一刻**量的，清理时按目录重量一次，不拿这份快照冒充准数）。 */
 export interface OrphanMember {
     readonly sessionId: string;
@@ -27,22 +27,28 @@ interface RawGroup {
  * 彻底删除（组语义见 `src/trash/groups.ts`），把它的根当孤儿删掉就是**替用户做了一个没人点过的决定**。孤儿只
  * 有一种来路：父被彻底删掉了（或被手工从盘上清掉了），清册里再也没有这一行。
  *
- * 根按**传递闭包**收全部后代（与 `HostCorpusPort.subagentMembersOf` 同一口径：孩子与孙代都算，深度不设上限），
- * 同一条记录只归一组（`claimed`）——数据里真出现环时结果是"少数一条"，不是把一个会话删两遍。
+ * 根按**传递闭包**收全部后代（与 `HostCorpusPort.subagentMembersOf` 同一实现：闭包核心住
+ * `src/domain/closure.ts` 的 `orphanRootsOf`，孩子与孙代都算，深度不设上限），同一条记录只归一组
+ * （`claimed`）——数据里真出现环时结果是"少数一条"，不是把一个会话删两遍。
  * 归堆与去重**两边都去 `session-` 前缀**：同一个父在两代宿主里写法不同（见 `bareSessionId` 的来历）。
  */
 export declare function orphanGroupsOf(corpus: readonly SessionIdentity[], trashSessionIds: readonly string[]): RawGroup[];
-/** **本函数是纯扫描，不对账、不写清册行**（`/orphans` 声明为 pure，一次扫描不能顺手写行）。清册默认读
- *   `ledger.raw()`；写路径（`orphan-clean`）可以在调它之前先 `ledger.list()` 对账，并把交回的行递进来，
- *  免得同一份索引再读一遍——否则刚被人手工搬进 `session-trash/` 的父目录还没有行，会被当成"父没了"
- *  直接删盘。
+/** **本函数是纯扫描，不对账、不写清册行**（`/orphans` 声明为 pure，一次扫描不能顺手写行）。
+ *  清册行由调用方选好再交进来：`/orphans` 交 `read.rows()`（raw 索引），`orphan-clean` 交
+ *  `ledger.list()`（对账后的行）——否则刚被人手工搬进 `session-trash/` 的父目录还没有行，会被当成
+ *  "父没了"直接删盘。扫描不再自己回落到 `ledger.raw()`：读面归属住路由记录（ADR-0004 / ADR-0012）。
  *
  *  `listSessions()` 回 `{ available: false }` 时**必须抛**：那是宿主的会话语料服务没挂，不是"这个家没有孤儿"。
  *  拿缺席当空语料 ⇒ 报告说"零条孤儿"、界面上一句"没有要清理的"，而盘上真有几百 MB——那是假话，
- *  所以这里按 `io` 响亮失败（AGENTS.md：`available: false` 意味着服务缺席，扫描方不许冒充读数）。 */
+ *  所以这里按 `io` 响亮失败（AGENTS.md：`available: false` 意味着服务缺席，扫描方不许冒充读数）。
+ *
+ *  `roots` 只收请求点名的那几组、**在量字节之前过滤**：`/orphans` 不传（报告全部），
+ *  `orphan-clean` 传这次的根——否则点一组会把整个家所有孤儿的树都递归量一遍。 */
 export declare function loadOrphanGroups(deps: CoreDeps, 
-/** 调用方已对账过的清册行（`ledger.list()`）；缺席则读 `ledger.raw()`。 */
-trash?: readonly TrashEntry[]): Promise<readonly OrphanGroup[]>;
+/** 调用方选好并交来的清册行：`/orphans` 交 `read.rows()`，`orphan-clean` 交 `ledger.list()`。 */
+trash: readonly TrashEntry[], 
+/** 只要这些根（两边都去 `session-` 前缀再比）；缺席 = 全量扫描。 */
+roots?: readonly string[]): Promise<readonly OrphanGroup[]>;
 /** 把一组组收成那份报告：根清单 + 闭包总数/总字节 + 失踪父的**去重计数** + 按项目目录的分摊。
  *  `groups` 按字节从多到少排（界面上"哪家还剩得最多"要看第一行）。 */
 export declare function reportOrphans(groups: readonly OrphanGroup[]): OrphanReportWire;
@@ -58,6 +64,7 @@ export declare function reportOrphans(groups: readonly OrphanGroup[]): OrphanRep
  * - `unarchive` 对未归档的会话是官方幂等 no-op（`registry.unarchiveSession`），所以这里不需要那次
  *   `wasArchived` 读——这里没有"还原到删除前"的义务。
  * - 摘账本只在账本真记着它时做（`workspaceOf` 未命中 = 本来就是「未分组」，不是故障）。
+ * - 独占图片的剩余引用源由附件域自己扫：活动会话 + 全部 session-trash + storages/cache。
  */
-export declare function cleanOrphanGroup(deps: CoreDeps, group: OrphanGroup): Promise<OrphanCleanStatsWire>;
+export declare function cleanOrphanGroup(deps: RemovalDeps, group: OrphanGroup): Promise<OrphanCleanStatsWire>;
 export {};

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

@@ -1,17 +1,22 @@
 /**
- * 永久删除的**测量、计划与执行**：一次永久删除（`/list` 的只读读数或 purge / orphan-clean 的删除计划）
- * 之前要记下的事实（目录、字节、账本归属），以及拿到计划之后按它动盘的那一步。计划函数**只读**——
- * 写不写由执行器决定，但活体准入在这里就做掉，调用方拿到计划才允许动盘。
+ * 永久删除的测量、计划与执行：先记录目录/字节/账本归属，再按计划动盘。
+ * 计划函数只读；活体准入在计划阶段、任何写之前完成，执行器动第一笔写前再查一次。
+ *
+ * 测量与补账本归属**分家**：`/list` 的只读计划只吃 {@link measureMembers}（零账本读，不再为每个
+ * 盘上后代问一次 `workspaceOf`，`/list` 的失败面不再含账本归属读）；`workspaceOf` 只有
+ * purge / orphan-clean 的删除计划（{@link planMemberRemovals}）才付——executor 摘账本要用它。
  */
 import { type TrashEntry } from '../trash/entry.js';
 import type { TrashGroupView } from '../trash/groups.js';
-import type { CoreDeps } from '../deps.js';
+import { type ImageRemovalPlan } from '../trash/attachments.js';
+import type { CoreDeps, RemovalDeps } from '../deps.js';
+import { type AttachmentCleanupWire } from '../shared/wire.js';
 export interface MeasuredMemberDir {
     readonly dir: string;
     readonly bytes: number;
 }
-/** 一条成员被删之前要记下的三件：目录、字节、账本归属（缺席 = 未分组）。`/list` 的只读计划与
- *  purge / orphan-clean 的删除计划共用这一份形状。 */
+/** 一条成员被删之前要记下的三件：目录、字节、账本归属（缺席 = 未分组）。purge / orphan-clean 的
+ *  删除计划共用这一份形状；`/list` 的只读计划不吃它——那一面零账本读，见 {@link measureMembers}。 */
 export interface PlannedMemberRemoval {
     readonly sessionId: string;
     readonly dir: string;
@@ -24,13 +29,21 @@ export declare function measureMemberDir(deps: CoreDeps, member: {
     readonly sessionId: string;
     readonly projectDir: string;
 }): Promise<MeasuredMemberDir | undefined>;
-/** 把一组成员折成"删之前要记下的计划"；目录不在的成员跳过（记录与盘不一致是那条成员自己的事）。
- *  `purge` 的盘上后代、`orphan-clean` 的整组与 `/list` 的盘上残留都走这一处，别再各写一遍
- *  measure + workspaceOf。 */
-export declare function planMemberRemovals(deps: CoreDeps, members: readonly {
+/** 一条成员的**测量**读数：身份两格 + 目录 + 实测字节。没有账本归属那一格——归属是删除动词才要
+ *  读的账本事实（见 {@link measureMembers} 与 {@link PlannedMemberRemoval} 的分工）。 */
+export interface MeasuredMember {
+    readonly sessionId: string;
+    readonly projectDir: string;
+    readonly dir: string;
+    readonly bytes: number;
+}
+/** 只测量（目录 + 实测字节）：`/list` 的只读计划只吃这一支，零账本读。目录不在的成员跳过
+ *  （记录与盘不一致是那条成员自己的事）。为什么不顺手把归属也问了：`/list` 投影只用字节与条数，
+ *  那一格立刻被丢弃——每开一次回收站为它付 N 次宿主调用，还把账本归属读拉进 `/list` 的失败面。 */
+export declare function measureMembers(deps: CoreDeps, members: readonly {
     readonly sessionId: string;
     readonly projectDir: string;
-}[]): Promise<PlannedMemberRemoval[]>;
+}[]): Promise<MeasuredMember[]>;
 /** 回收站里的一条要删的行：目录、在不在、实测字节（缺席 = 0）。purge 与 `/list` 都由它量。 */
 export interface PlannedTrashRow {
     readonly entry: TrashEntry;
@@ -38,10 +51,11 @@ export interface PlannedTrashRow {
     readonly present: boolean;
     readonly bytes: number;
 }
-/** `/list` 的一行（一组）所需的只读数：`releaseBytes` 是这一组**实测**会释放的字节。 */
+/** `/list` 的一行（一组）所需的只读数：`releaseBytes` 是这一组**实测**会释放的字节。
+ *  `members` 是 {@link MeasuredMember}（测量读数，无账本归属格）：清单只用它的字节与条数。 */
 export interface VisibleTrashGroup extends TrashGroupView {
     readonly trash: readonly PlannedTrashRow[];
-    readonly members: readonly PlannedMemberRemoval[];
+    readonly members: readonly MeasuredMember[];
     readonly releaseBytes: number;
     readonly subagentBytes: number;
     readonly strandedBytes: number;
@@ -52,7 +66,8 @@ export interface VisibleTrashGroup extends TrashGroupView {
  * 不用清册里记的 `sizeBytes`（那是删除那一刻的事实，盘上早就变了）。
  *
  * 盘上后代经 `selectStrandedMembers` 选出（排除全部清册 id、bare id 全局只算一次）；目录不在的成员
- * 不进 `members`（与 `planMemberRemovals` 同口径）。
+ * 不进 `members`（与 purge 计划同口径）。成员只吃 {@link measureMembers}：**零账本读**——不再为每个
+ * 盘上后代问一次 `workspaceOf`，`/list` 的失败面不再含账本归属读（归属只有 purge 摘账本才付）。
  */
 export declare function planVisibleTrash(deps: CoreDeps, rows: readonly TrashEntry[], groups: readonly TrashGroupView[]): Promise<VisibleTrashGroup[]>;
 /** 一次永久删除的只读计划：哪些目录要删、各自实测多少字节、哪些会话要先摘归档集。
@@ -66,17 +81,24 @@ export interface RemovalPlan {
     readonly unarchive: readonly string[];
     /** 计划量到的合计；成功回执的 freedBytes 只念它。 */
     readonly bytes: number;
+    /** 这一次要连带清掉的独占图片对象（`trash/attachments.ts` 的域判定；空计划 = 没有可删的、或
+     *  剩余引用源读不出而整体跳过——原因在 `skipped` 里）。附件字节**不进** `bytes`：那是会话目录的
+     *  释放量，附件读数单独走回执的 `attachments`。 */
+    readonly attachments: ImageRemovalPlan;
 }
 /**
  * purge 的删除计划：`targets` 由调用方按组语义（`trash/groups.ts`）选好，这里只量、只筛、只查活体。
- * **计划函数就是执行前的闸**——调用方拿到计划才允许写，所以准入必须发生在任何写之前。
+ * **计划函数是执行前的第一道闸**——调用方拿到计划才允许写；计划与第一笔写之间的窗口由
+ * `executeRemoval` 在首笔写前复查（见该函数头注）。
  *
  * - `trash` 按 targets 原序逐个实测（目录缺席的行 `present:false` / 0 字节，但清册行仍要摘）。
  * - 盘上后代经 `selectStrandedMembers` 选出（一次问全部 targets、排除全部清册 id、bare id 全局只计划一次）。
  * - `members` 只收盘上还有目录的成员（目录缺席没有可删的字节）；`unarchive` = targets + 这些成员：
  *   只摘这一次真要碰的 id。
+ * - `attachments` 由被删目录（targets + 这些成员）里的图片引用与全部剩余引用源算独占；共享的保留、
+ *   剩余引用源读不出就整体跳过（判据住 `trash/attachments.ts`，这里只接线）。
  * - 活体准入在量目录与任何写之前逐个查 targets 与**全部枚举到的**盘上后代；任一在跑就整条拒绝、
- *   零副作用。没有跳过它的开关——计划就是执行前的闸（ADR-0006）。
+ *   零副作用。没有跳过它的开关；执行器首笔写前还会用计划里的 `unarchive` 名单复查（ADR-0027）。
  * - `sessionQuery` 缺席时端口回 `{ available: false }` ⇒ members 为空、不抛（盘上残留留给 `GET /orphans` 兜底）。
  */
 export declare function planTrashRemoval(deps: CoreDeps, rows: readonly TrashEntry[], targets: readonly TrashEntry[]): Promise<RemovalPlan>;
@@ -87,6 +109,8 @@ export declare function planTrashRemoval(deps: CoreDeps, rows: readonly TrashEnt
  * - `unarchive` 覆盖**全部传入成员**（含目录缺席）：orphan-clean 在删目录之前整批摘归档集，
  *   目录缺席的 id 也可能还挂在归档集里；重试时不会再长出一条幽灵 id。
  * - live 准入覆盖**全部传入成员**（含目录缺席）：它们都在这一组的可见面里，任一在跑就整组拒绝。
+ * - `attachments` 的剩余引用源由附件域自己扫（活动会话 + 全部 session-trash + storages/cache），
+ *   共享图片因此保留（判据住 `trash/attachments.ts`）。
  * - 回执由 `kind:'orphan'` 派生：删目录阶段失败时执行器要交回 `{removed, freedBytes, failedSessionId}`。
  */
 export declare function planOrphanRemoval(deps: CoreDeps, members: readonly {
@@ -94,21 +118,32 @@ export declare function planOrphanRemoval(deps: CoreDeps, members: readonly {
     readonly projectDir: string;
 }[]): Promise<RemovalPlan>;
 /**
- * 按计划执行一次永久删除：只写、不再量、不再判活体（计划就是执行前的闸）。回执的字节念计划
- * （`plan.bytes`），执行期不再累加一遍。
+ * 按计划执行一次永久删除：不再量。回执的字节念计划（`plan.bytes`），执行期不再累加一遍。
+ *
+ * **计划 + 执行器、准入查两遍**（ADR-0027）：计划期准入证明计划成立时没有会话在跑；执行器首笔写前
+ * 再用同一份名单复查，补上附件扫描撑开的窗口。
+ *
+ * 计划期准入与第一笔写之间还隔着附件引用的全 home 扫描（`planImageAttachmentRemoval`），大 home
+ * 上那是秒级窗口——期间用户 resume 一个会话，它的目录随后仍会被删。所以动任何写之前用计划里同一份
+ * 会话名单**再查一次活体**（只读、廉价）；这一查失败仍然零写入。名单取 `plan.unarchive`：
+ * 它覆盖所有会被删目录的会话（回收站行与盘上成员），目录已不在的成员没有可删的东西。
+ *
+ * 顺序：整批摘归档集 → 摘有账本的成员的账本 → 逐条回收站行
+ * （在才删目录 → 摘清册行 → 通告成员离场）→ 逐条盘上成员（删目录 → 通告成员离场）→ 逐条附件对象。
+ * 目录删掉就没有"退回去"这回事，中途失败**不回滚**；已经删掉的由下面的计数器如实交回。
  *
- * 顺序（与迁移前的 purge / orphan-clean 一致）：整批摘归档集 → 摘有账本的成员的账本 → 逐条回收站行
- * （在才删目录 → 摘清册行 → 通告成员离场）→ 逐条盘上成员（删目录 → 通告成员离场）。目录删掉就没有
- * "退回去"这回事，中途失败**不回滚**；已经删掉的由下面的计数器如实交回。
+ * 附件清理排在**所有会话目录删完之后**：对象只在会话真的没了之后才动；单文件失败只进
+ * `attachments.failed`，不影响（也不回滚）会话删除的回执。
  *
- * 失败形状沿用调用方原来的措辞与结构：
+ * 失败形状：
  * - `kind:'orphan'`（orphan-clean）⇒ `io` + `{removed, freedBytes, failedSessionId}`，不伪装成整组没动；
- * - `kind:'trash'`（purge）⇒ 同一个标签、不带 details。
- * - orphan-clean 的 unarchive / detach 在旧实现里不包装，这里原样抛出（不改变现有错误形状）。
+ * - `kind:'trash'`（purge）⇒ 同一个标签、不带 details；
+ * - orphan-clean 的 unarchive / detach 原样抛出。
  *
  * 通告只经 `member-presence`（摘活体三态 + `api-session/removed`），不在这里另写一份。
  */
-export declare function executeRemoval(deps: CoreDeps, plan: RemovalPlan): Promise<{
+export declare function executeRemoval(deps: RemovalDeps, plan: RemovalPlan): Promise<{
     removed: number;
     freedBytes: number;
+    attachments: AttachmentCleanupWire;
 }>;

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

@@ -2,21 +2,15 @@ import { type TrashEntry } from '../trash/entry.js';
 import { type HostIdentityPort } from '../ports/host-port.js';
 import type { CoreDeps } from '../deps.js';
 /**
- * 恢复 = 把删除那次**按原路退回**，而且按组走：当年是按组一起搬进来的（父 + 它在盘上的孩子），
- * 只回父就会在回收站里留下一堆点不到的孩子行——清单只列父行，那些行既看不见也清不掉。
+ * 恢复：把删除那次按原路退回，并按组走。
  *
- * 三段与删除对称（成员循环与整组回滚的实现住 `verbs/move-group.ts`）：
- * ① **预检整组**（一个字节都不写）：每个成员的回收站目录与项目目录都得在。缺席的判据与原来一致
- *    （回收站目录不在 = `trash-empty`；原项目目录不在 = `project-missing`，且绝不静默建目录）。
- *    预检在写之前，是为了不让"父已经回到 `sessions/`、孩子因为项目目录没了而回不去"这种半组留在外面。
- *    **工作区账本不在这条硬前提里**：宿主的「删除工作区」只删注册、保留日志，记下的工作区没了就按
- *    「未分组」收（判据在 {@link attachableWorkspaceId}），照旧回盘——恢复是加法，不该因为一个可选的账目而失败。
- * ② **逐个恢复**，顺序与删除相反：文件先回来 → 挂账本 →（旧清单迁移）取消归档 → 摘清册行。
- * ③ 中途失败时 journal 把这个成员自己退回回收站；**已经恢复完的**兄弟由整组 catch 按相反顺序一起退回。
+ * 三段：
+ * 1. 预检整组（不写盘）：每个成员的回收站目录与原项目目录都必须在；工作区账本缺席不算硬失败，
+ *    恢复后归入「未分组」。预检在任何写之前，避免留下半组。
+ * 2. 逐个恢复：文件先回来 → 挂账本 →（旧条目）取消归档 → 摘清册行。
+ * 3. 中途失败由 journal 回滚当前成员；已恢复的兄弟由整组按相反顺序退回。
  *
- * **通告不在这里**：一次批量只该拉一遍宿主会话表、只发一次 `api-session/added`（2026-10-17 那次
- * "恢复很慢"就是逐条发）。通告归 `verbs/batch.ts`（ADR-0002），所以这个动词的 interface 是
- * "一个条目 id + 这一组进、回收站那一行出"，没有批量专用的开关。
+ * 通告不在本文件：批量层在批尾一次 `announceRestored(ids)`（ADR-0002）。
  */
 export declare function restoreSession(deps: CoreDeps): (entryId: string, 
 /** 这一组（只读）：批量层由 `batch-carried.ts` 的 `claimOf` 给出，直调者按 `trash/groups.ts`

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

@@ -0,0 +1,36 @@
+import type { TrashEntry } from '../trash/entry.js';
+import type { RemovalDeps } from '../deps.js';
+import type { PurgeStatsWire } from '../shared/wire.js';
+import { type OrphanGroup } from './orphan-subagents.js';
+/**
+ * **清册作用域（trash scope）**：purge 这条写路径的「拿目标」owner。调用方把一份选好读面的清册
+ * 快照交进来（写入口 = 真相读；报告入口不经作用域——`/orphans` 直接把 raw 快照交 `loadOrphanGroups`。
+ * 选哪一格是路由行 / 批量层的事，ADR-0012 的边界不在这里翻），快照与**收缩视图**从此归本模块、
+ * **不外露**：三态判据与按组收缩都仍读 `trash/groups.ts` 的 `claimOf` / `withoutGroup`，这里只**持有**
+ * 那份视图，不抄第二遍判据。三个成员的输入输出以 `CONTEXT.md` 的「清册作用域」与下面各成员的
+ * 注释为准，头注不重写一遍表面契约。
+ *
+ * 彻底删除：从回收站里**真的**抹掉一组（或整站），并连带那些"还留在盘上、没被带走"的后代。
+ * **这里只做两件事：拿目标、把计划交给执行器**。量目录、筛盘上后代、活体准入与"先退归档集、
+ * 再摘账本、最后删目录"的顺序都住 `verbs/permanent-removal.ts`——计划只读，执行器不再量、只在第一笔
+ * 写前补一次只读的活体复查，计划是执行前的第一道闸（别在这里再长出一段手写步骤）。
+ *
+ * **不做回滚**：目录删掉就没有"退回去"这回事（删到一半失败时已删目录不回滚；带部分计数的
+ * `details` 回执只属于 `orphan-clean`，purge 的 `removed` / `freedBytes` 仍只在成功回执里给）。
+ * 对应地，`kind:'trash'` 的计划失败时执行器只抛那一步的 `io` 与原文、不带 details。
+ *
+ * 回执里的 `attachments` 原样来自执行器：独占图片在会话目录删完之后才清，附件失败只计数、不改
+ * `removed` / `freedBytes`（`skipped` = 有候选或剩余引用源读不出、这一轮部分或整体没清，原因上屏）。
+ * 「已被同批前一条带走」的幂等回执**不带** `attachments`——那一趟没有附件读数，缺席与 0 是两件事，
+ * 不拿零冒充"清过"（与旧批量回执同形）。
+ */
+export interface TrashScope {
+    /** purge 这一组；已被同批带走 ⇒ `{removed:0,freedBytes:0}`；absent（原始快照里就认不出）⇒
+     *  `trash-empty`，原文点名 id。 */
+    purge(id: string): Promise<PurgeStatsWire>;
+    /** 清空：全部行一组。 */
+    purgeAll(): Promise<PurgeStatsWire>;
+    /** 点名根的无主组（根两边去 `session-` 前缀再比）；roots 缺席 = 全量。 */
+    orphanGroups(roots?: readonly string[]): Promise<readonly OrphanGroup[]>;
+}
+export declare function createTrashScope(deps: RemovalDeps, rows: readonly TrashEntry[]): TrashScope;

package/package.json

@@ -1,106 +1,117 @@
-{
-  "name": "@xrn1997/dsh-session-delete",
-  "version": "0.3.1",
-  "description": "在 DeepSeek Harness 里删除会话：删除=移入回收站（可恢复），另设显式彻底删除",
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/types/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lib/types/index.d.ts",
-      "default": "./lib/index.js"
-    },
-    "./client": {
-      "types": "./lib/types/client/index.d.ts",
-      "default": "./lib/client.js"
-    },
-    "./locale/*.json": "./locale/*.json",
-    "./package.json": "./package.json"
-  },
-  "icon": "./icon.svg",
-  "files": [
-    "lib/index.js",
-    "lib/client.js",
-    "lib/types/**/*.d.ts",
-    "locale",
-    "icon.svg",
-    "cordis.patch.yml",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=24",
-    "dsh": ">=0.1.7-rc.2 <0.3.0-0"
-  },
-  "scripts": {
-    "build": "tsdown && tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "prepack": "npm run build"
-  },
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.4",
-    "react": "^18.3.1"
-  },
-  "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.4",
-    "@testing-library/dom": "^10.4.2",
-    "@testing-library/jest-dom": "^6.10.0",
-    "@testing-library/react": "^16.3.3",
-    "@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"
-  },
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    },
-    "client": {
-      "inject": [
-        "@deepseek-ai/dsh-client-locale"
-      ],
-      "platform": "web"
-    },
-    "compatibility": {
-      "dshReleases": {
-        "0.2.0-rc.2": "compatible",
-        "0.2.1-rc.1": "compatible",
-        "0.2.1-rc.2": "compatible",
-        "0.2.1-rc.3": "compatible"
-      }
-    }
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/xrn1997/dsh-session-delete.git"
-  },
-  "homepage": "https://github.com/xrn1997/dsh-session-delete#readme",
-  "bugs": {
-    "url": "https://github.com/xrn1997/dsh-session-delete/issues"
-  },
-  "keywords": [
-    "dsh",
-    "deepseek-harness",
-    "plugin",
-    "session",
-    "trash",
-    "delete"
-  ],
-  "author": "xrn1997",
-  "license": "Apache-2.0",
-  "dependencies": {
-    "react-markdown": "^10.1.0",
-    "remark-gfm": "^4.0.1"
-  }
-}
+{
+  "name": "@xrn1997/dsh-session-delete",
+  "version": "0.5.0",
+  "description": "在 DeepSeek Harness 里删除会话：删除=移入回收站（可恢复），另设显式彻底删除",
+  "type": "module",
+  "packageManager": "pnpm@11.25.0",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./locale/*.json": "./locale/*.json",
+    "./package.json": "./package.json"
+  },
+  "icon": "./icon.svg",
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "locale",
+    "icon.svg",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=24",
+    "dsh": ">=0.1.7-rc.2 <0.3.0-0"
+  },
+  "scripts": {
+    "build": "tsdown && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "pack:dry": "npm pack --dry-run --ignore-scripts",
+    "prepack": "npm run build",
+    "gates": "pnpm typecheck && pnpm lint && pnpm test && pnpm build && pnpm run pack:dry"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.4",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@eslint/js": "^10.0.1",
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/jest-dom": "^6.10.0",
+    "@testing-library/react": "^16.3.3",
+    "@types/node": "24.19.0",
+    "@types/react": "18.3.31",
+    "@types/react-dom": "18.3.5",
+    "@types/semver": "^7.8.0",
+    "eslint": "^10.14.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^17.13.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",
+    "typescript-eslint": "^8.72.1",
+    "vitest": "3.2.7"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-locale"
+      ],
+      "platform": "web"
+    },
+    "compatibility": {
+      "dshReleases": {
+        "0.2.0-rc.2": "compatible",
+        "0.2.1-rc.1": "compatible",
+        "0.2.1-rc.2": "compatible",
+        "0.2.1-rc.3": "compatible",
+        "0.2.1-rc.5": "compatible"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xrn1997/dsh-session-delete.git"
+  },
+  "homepage": "https://github.com/xrn1997/dsh-session-delete#readme",
+  "bugs": {
+    "url": "https://github.com/xrn1997/dsh-session-delete/issues"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "session",
+    "trash",
+    "delete"
+  ],
+  "author": "xrn1997",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1"
+  }
+}