@xrn1997/dsh-session-delete 0.3.0 → 0.4.0

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/trash/storage-manifest.d.ts

@@ -4,7 +4,7 @@ import { type ManifestPort } from './manifest.js';
  * 清单的真实绑定：官方 storage domain → `ManifestPort`（`StorageDomainLike` 在动词层保持一种读法）。
  * 域**懒开**且成功句柄只开一次（`apply` 是同步的，而 `open()` 是异步的），并挂一条 `ctx.effect` 清理：
  * 插件卸载时关掉句柄并把 `close()` 的落地交回框架（句柄归调用方所有，这是 `open()` 的 JSDoc 明写的契约；
- * 2026-10-17 起不再 `void` 走掉——没关严的句柄会让下一份同名域撞 `already-open`）。
+ * 不能 `void` 走掉——没关严的句柄会让下一份同名域撞 `already-open`）。
  *
  * **失败不缓存**：`open()` 被拒是瞬态（域被别的持有者占着、装载竞态），把第一次的 rejected promise
  * 缓存起来等于"这个会话永远删不掉"——下一次读会重新走 `open()`，成功才落下活句柄。

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

@@ -1,8 +1,8 @@
 import { type TrashEntry } from '../trash/entry.js';
-import type { DeleteDeps } from '../deps.js';
+import type { DeleteSessionDeps } 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>;
+export declare function deleteSession(deps: DeleteSessionDeps): (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 {
@@ -17,6 +9,8 @@ export interface VerbError extends Error {
     cause?: unknown;
 }
 export declare function verbError(code: VerbCode, message: string, cause?: unknown, details?: Record<string, unknown>): VerbError;
+/** `trash-empty` 的原文：有具体条目就点名那个 id，拿不到时只报通用那句。 */
+export declare function trashEmpty(entryId?: string): VerbError;
 /** 路由自检用的失败：带 HTTP 状态语义，**不**冒充五个动词码。 */
 export declare function routeError(code: RouteCode, httpStatus: number, message: string): VerbError & {
     httpStatus: number;

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

@@ -0,0 +1,10 @@
+/**
+ * 活体准入：删除 / 永久删除 / 孤儿清理之前，逐个问会话是否在宿主内存里 attach 着；
+ * 任一在跑就整组拒绝、零副作用（ADR-0008）。
+ *
+ * 边界：什么时候查归调用方——永久删除的准入在计划里、任何写之前（ADR-0006）；
+ * 本模块只拥有「查什么、怎么判、怎么说」。
+ */
+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 {
-    /** 这一步在做什么。失败原文按「`<label>：<原错误>`」拼——与迁移前那 22 处 `rollbackReason` 的措辞同形。 */
+    /** 稳定的领域键，给 `restored(key)` 用。 */
+    readonly key: JournalStepKey;
+    /** 这一步在做什么。失败原文按「`<label>：<原错误>`」拼。 */
     readonly label: string;
     /** 做这一步。抛什么都由 journal 折成 `sessiondelete/io`（除非它自己已经是一个动词码）。 */
     run(): Promise<void>;
-    /** 反向动作。**`run` 成功之后**才会被登记；返回**这一步自己**没能退干净的原因列表（空 = 完全退回）。 */
-    undo?(): Promise<readonly string[]>;
+    /** 反向动作。**`run` 成功之后**才会被登记；返回这一步退没退成与原因。 */
+    undo?(): Promise<StepUndo>;
     /** 这一步**自己**失败时也跑 `undo`：给"可能已经半做完"的非原子步骤用（取消归档是唯一的例子）。 */
     readonly undoOnFailure?: boolean;
 }
@@ -12,16 +29,17 @@ 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`；那些失败句子的合并与措辞住
- * `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,35 +1,44 @@
 /**
  * 成员离场 / 归位的通告协议：摘活体、三态判断、成对事件只在这里做。
  *
- * 为什么要有它：delete（成功与回滚）/ restore 回滚 / purge（两个分支）/ orphan-clean
- * 六处调用曾经各写一遍
- * `evictLive → !== 'unknown' → announceRemoved`；删除回滚还要自己拼
- * `movedBack && workspaceBack` 才发 `announceRestored`。
- * 这条协议说错一次就是客户端留着假行、或删掉真行，所以只留一个家。
+ * 调用方包括 delete、restore 回滚、purge、orphan-clean；协议说错一次就是客户端留假行或删真行。
  *
  * 边界：
- * - 批量恢复的 `announceRestoredBatch` 不进来：一次预取、一批一次通告归 `verbs/batch.ts`（ADR-0002）。
- * - 不读 journal 的失败串：调用方交事实（目录 / 账本是否回去），真值表住这里。
- * - 本模块用到的三条（`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';
-/** 本模块实际用到的三条宿主能力。取窄面而不是整个 `HostPresencePort`：那条协议里还有批量通告与
- *  摘要预取，它们各有自己的家（`verbs/batch.ts`），这里不该因为共用同一颗 adapter 就声明依赖。 */
+import type { PresenceCapability } from '../ports/presence-port.js';
+import type { Journal, JournalUndo } from './member-journal.js';
+/** 本模块实际用到的三条宿主能力。`Pick` 此刻覆盖 `HostPresencePort` 的三条方法，仍留着它当闸：
+ *  将来端口多出第四条时，这里不会被动跟着变宽——能力面只暴露这三条，批量通告的编排归 `verbs/batch.ts`。 */
 export type MemberPresenceHost = Pick<HostPresencePort, 'evictLive' | 'announceRemoved' | 'announceRestored'>;
-export interface MemberBackFacts {
-    /** 目录搬回原处了吗。 */
+/** 本仓的在场能力实现：端口形状住 `src/ports/presence-port.ts`，这里只做三态与真值表。
+ *  `announceRestored` 直接交宿主那一手：能力面与宿主面同名同签名，再包一层只会多一个转调。 */
+export declare function createMemberPresence(host: MemberPresenceHost): PresenceCapability;
+/** 一次 undo 之后要发哪一条通告：`leave` = 成员已不在可见面，`return` = 已回到原可见状态。 */
+export type PresenceAnnounce = {
+    readonly kind: 'leave';
+    readonly backInTrash: boolean;
+} | {
+    readonly kind: 'return';
     readonly diskBack: boolean;
-    /** 账本挂回去了吗（本来没有账目时算 true）。 */
     readonly workspaceBack: boolean;
+};
+/** 动词给工厂的那一格：哪个成员、run 成不成功要不要补离场、undo 之后按逐步结果发哪一条。 */
+export interface PresenceTail {
+    readonly sessionId: string;
+    /** `run()` 成功后补离场通告（删除用）。省略 = run 不动在场（恢复的 run 本来就不该发东西）。 */
+    readonly onDone?: 'leave';
+    /** `undo()` 完成后按逐步结果发通告。 */
+    onUndone(undo: JournalUndo): PresenceAnnounce;
 }
-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;
+/**
+ * 给一次成员移动的 journal 补上「在场那条尾巴」：run 完全成功之后离场，undo 之后按事实归位或离场。
+ *
+ * 边界：`memberGone` 的 `backInTrash:false` 早退与 `memberBack` 的两件齐备真值表归 `createMemberPresence`；
+ * 这里只把事实原样递过去。
+ */
+export declare function withPresenceTail(presence: PresenceCapability, 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,6 +1,7 @@
 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;
@@ -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，一次扫描不能顺手写行）。
+ *  清册行由调用方选好再交进来：`/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` 意味着服务缺席，扫描方不许冒充读数）。 */
-export declare function loadOrphanGroups(deps: CoreDeps): Promise<readonly OrphanGroup[]>;
+export declare function loadOrphanGroups(deps: CoreDeps, 
+/** 调用方选好并交来的清册行：`/orphans` 交 `read.rows()`，`orphan-clean` 交 `ledger.list()`。 */
+trash: readonly TrashEntry[]): Promise<readonly OrphanGroup[]>;
 /** 把一组组收成那份报告：根清单 + 闭包总数/总字节 + 失踪父的**去重计数** + 按项目目录的分摊。
  *  `groups` 按字节从多到少排（界面上"哪家还剩得最多"要看第一行）。 */
 export declare function reportOrphans(groups: readonly OrphanGroup[]): OrphanReportWire;
@@ -53,6 +58,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,11 +1,12 @@
 /**
- * 永久删除的**测量、计划与执行**：一次永久删除（`/list` 的只读读数或 purge / orphan-clean 的删除计划）
- * 之前要记下的事实（目录、字节、账本归属），以及拿到计划之后按它动盘的那一步。计划函数**只读**——
- * 写不写由执行器决定，但活体准入在这里就做掉，调用方拿到计划才允许动盘。
+ * 永久删除的测量、计划与执行：先记录目录/字节/账本归属，再按计划动盘。
+ * 计划函数只读；活体准入在计划阶段、任何写之前完成。
  */
 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;
@@ -24,13 +25,6 @@ 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 {
-    readonly sessionId: string;
-    readonly projectDir: string;
-}[]): Promise<PlannedMemberRemoval[]>;
 /** 回收站里的一条要删的行：目录、在不在、实测字节（缺席 = 0）。purge 与 `/list` 都由它量。 */
 export interface PlannedTrashRow {
     readonly entry: TrashEntry;
@@ -64,22 +58,28 @@ export interface RemovalPlan {
     readonly trash: readonly PlannedTrashRow[];
     readonly members: readonly PlannedMemberRemoval[];
     readonly unarchive: readonly string[];
+    /** 计划量到的合计；成功回执的 freedBytes 只念它。 */
     readonly bytes: number;
+    /** 这一次要连带清掉的独占图片对象（`trash/attachments.ts` 的域判定；空计划 = 没有可删的、或
+     *  剩余引用源读不出而整体跳过——原因在 `skipped` 里）。附件字节**不进** `bytes`：那是会话目录的
+     *  释放量，附件读数单独走回执的 `attachments`。 */
+    readonly attachments: ImageRemovalPlan;
 }
 /**
  * purge 的删除计划：`targets` 由调用方按组语义（`trash/groups.ts`）选好，这里只量、只筛、只查活体。
+ * **计划函数就是执行前的闸**——调用方拿到计划才允许写，所以准入必须发生在任何写之前。
  *
  * - `trash` 按 targets 原序逐个实测（目录缺席的行 `present:false` / 0 字节，但清册行仍要摘）。
  * - 盘上后代经 `selectStrandedMembers` 选出（一次问全部 targets、排除全部清册 id、bare id 全局只计划一次）。
  * - `members` 只收盘上还有目录的成员（目录缺席没有可删的字节）；`unarchive` = targets + 这些成员：
  *   只摘这一次真要碰的 id。
- * - `admission:'live'` 在量目录与任何写之前逐个查 targets 与**全部枚举到的**盘上后代；
- *   任一在跑就整条拒绝，零副作用。
+ * - `attachments` 由被删目录（targets + 这些成员）里的图片引用与全部剩余引用源算独占；共享的保留、
+ *   剩余引用源读不出就整体跳过（判据住 `trash/attachments.ts`，这里只接线）。
+ * - 活体准入在量目录与任何写之前逐个查 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`）。
  *
@@ -87,6 +87,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,20 +96,25 @@ export declare function planOrphanRemoval(deps: CoreDeps, members: readonly {
     readonly projectDir: string;
 }[]): Promise<RemovalPlan>;
 /**
- * 按计划执行一次永久删除：只写、不再量、不再判活体（计划就是执行前的闸）。
+ * 按计划执行一次永久删除：只写、不再量、不再判活体（计划就是执行前的闸）。回执的字节念计划
+ * （`plan.bytes`），执行期不再累加一遍。
+ *
+ * 顺序：整批摘归档集 → 摘有账本的成员的账本 → 逐条回收站行
+ * （在才删目录 → 摘清册行 → 通告成员离场）→ 逐条盘上成员（删目录 → 通告成员离场）→ 逐条附件对象。
+ * 目录删掉就没有"退回去"这回事，中途失败**不回滚**；已经删掉的由下面的计数器如实交回。
  *
- * 顺序（与迁移前的 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/purge-trash.d.ts

@@ -1,22 +1,35 @@
 import type { TrashEntry } from '../trash/entry.js';
-import type { CoreDeps } from '../deps.js';
+import type { RemovalDeps } from '../deps.js';
+import type { AttachmentCleanupWire } from '../shared/wire.js';
 /**
  * 彻底删除：从回收站里**真的**抹掉一条（或整组、或整站），并连带那些"还留在盘上、没被带走"的后代。
  *
- * 与另外两个动词的关系（ADR-0002）：它的 interface 只有"一个条目 id（或缺席 = 清空）"，
- * 批量的快照与"已被同批前一条带走"的判据不在这里（归 `verbs/batch.ts`）。
+ * 与另外两个动词的关系（ADR-0002）：它的 interface 是"这一组目标 + 一份只读清册快照
+ *（targets 缺席 = 清空）"；目标由 `verbs/batch-carried.ts` 按组语义算好，批量的"已被同批前一条
+ * 带走"判据不在这里。`requestedId` 是唯一的例外参数，但它**不参与任何判据**：只是让
+ * `trash-empty` 的原文点得出用户点的是哪一条（原文要上屏，点名承重），批量语义仍在批量层。
  *
- * **这条动词只做两件事：选目标、拿计划交给执行器**。量目录、筛盘上后代、活体准入与"先退归档集、
+ * **这条动词只做两件事：拿目标、把计划交给执行器**。量目录、筛盘上后代、活体准入与"先退归档集、
  * 再摘账本、最后删目录"的顺序都住 `verbs/permanent-removal.ts`——计划只读，执行器只写，计划就是
  * 执行前的闸（别在这里再长出一段手写步骤）。
  *
- * **这条动词不做回滚**：目录删掉就没有"退回去"这回事（2026-10-19 `f2a7757`：删到一半失败时已删目录不回滚；
+ * **这条动词不做回滚**：目录删掉就没有"退回去"这回事（删到一半失败时已删目录不回滚；
  * 带部分计数的 `details` 回执只属于 `orphan-clean`，purge 的 `removed` / `freedBytes` 仍只在成功回执里给）。
  * 对应地，`kind:'trash'` 的计划失败时执行器只抛那一步的 `io` 与原文、不带 details。
+ *
+ * 回执里的 `attachments` 原样来自执行器：独占图片在会话目录删完之后才清，附件失败只计数、不改
+ * `removed` / `freedBytes`（`skipped` = 有候选或剩余引用源读不出、这一轮部分或整体没清，原因上屏）。
  */
-export declare function purgeTrash(deps: CoreDeps): (entryId?: string, 
-/** **只读**清册快照：批量层已经读过一次就递下来（ADR-0002）；收缩归批量层，动词不碰它。 */
-snapshot?: readonly TrashEntry[]) => Promise<{
+export declare function purgeTrash(deps: RemovalDeps): (
+/** 这一组（只读）；`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;
+    attachments: AttachmentCleanupWire;
 }>;

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

@@ -2,26 +2,22 @@ import { type TrashEntry } from '../trash/entry.js';
 import { type HostIdentityPort } from '../ports/host-port.js';
 import type { CoreDeps } from '../deps.js';
 /**
- * 恢复 = 把删除那次**按原路退回**，而且按组走：当年是按组一起搬进来的（父 + 它在盘上的孩子），
- * 只回父就会在回收站里留下一堆点不到的孩子行——清单只列父行，那些行既看不见也清不掉。
+ * 恢复：把删除那次按原路退回，并按组走。
  *
- * 三段与删除对称：
- * ① **预检整组**（一个字节都不写）：每个成员的回收站目录与项目目录都得在。缺席的判据与原来一致
- *    （回收站目录不在 = `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, 
-/** **只读**清册快照：批量层已经读过一次就递下来，整批因此只读一次（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,8 +1,9 @@
 {
   "name": "@xrn1997/dsh-session-delete",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "在 DeepSeek Harness 里删除会话：删除=移入回收站（可恢复），另设显式彻底删除",
   "type": "module",
+  "packageManager": "pnpm@11.25.0",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
   "exports": {
@@ -73,7 +74,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;