@xrn1997/dsh-session-delete 0.4.0 → 0.5.0

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

@@ -13,37 +13,71 @@
  * 撞了就是整棵插件树 boot 失败——所以这条路径是与生态的硬边界，不是显示好不好看的问题。
  */
 export declare const SESSION_DELETE_API_PREFIX = "/dsh-session-delete-api";
-/** 九个段名（相对前缀）。写动作统一走一段 `/apply`：一次 HTTP 带一组 id、逐条回结果；
+/** 九个段名（相对前缀）。**每项 `{ path, method }` 两键**：某段用什么方法也是线上形状的一部分
+ *  （ADR-0003），家就在这一张表——路由记录（`src/api/route-table.ts`）逐行投影（`ROUTES.x.method`），
+ *  浏览器半的 GET 段同样投影、写段把 `ROUTES.x.method` 交给 `src/client/remote.ts` 的 `post()`，
+ *  两半都不逐段手写一份。
+ *  写动作统一走一段 `/apply`：一次 HTTP 带一组 id、逐条回结果；
  *  单条就是长度为 1 的批量，仓里不留第二条执行路径。
- *  - `GET /list`：对账并读清单（`session-trash/` 里的目录是准）。
- *  - `GET /ping`：最便宜的在/不在（不碰清册、不碰盘、不进链），供客户端探测。
- *  - `POST /detail`：单条详情（用 POST 表达一个读，判据在 `src/api/route-table.ts`）。
- *  - `POST /apply`：批量执行一个动作（`delete` / `restore` / `purge` / `count` / `orphan-clean`），逐条回 `ApplyOutcome`。
- *  - `POST /empty`：清空回收站（聚合回执，不按条回）。
- *  - `GET /orphans`：无主子会话的扫描报告（纯读）。清理是 `/apply` 的第五个动作，
+ *  - `list`：对账并读清单（`session-trash/` 里的目录是准）。
+ *  - `ping`：最便宜的在/不在（不碰清册、不碰盘、不进链），供客户端探测。
+ *  - `detail`：单条详情（用 POST 表达一个读，判据在 `src/api/route-table.ts` 的 detail 行）。
+ *  - `apply`：批量执行一个动作（`delete` / `restore` / `purge` / `count` / `orphan-clean`），逐条回 `ApplyOutcome`。
+ *  - `empty`：清空回收站（聚合回执，不按条回）。
+ *  - `orphans`：无主子会话的扫描报告（纯读）。清理是 `/apply` 的第五个动作，
  *    这一段只负责"有多少、在哪、多大"。
- *  - `GET /attachment`：附件原始字节（全仓唯一的二进制响应段；失败仍回 JSON 信封）。
- *  - `GET /attachment-orphans`：无引用图片对象的扫描报告（纯读；数量/字节 + 供预览的对象清单）。
- *  - `POST /attachment-clean`：清掉报告那一刻无引用的图片对象（聚合回执 `AttachmentCleanupWire`）。 */
+ *  - `attachment`：附件原始字节（全仓唯一的二进制响应段；失败仍回 JSON 信封）。
+ *  - `attachmentOrphans`：无引用图片对象的扫描报告（纯读；数量/字节 + 供预览的对象清单）。
+ *  - `attachmentClean`：清掉报告那一刻无引用的图片对象（聚合回执 `AttachmentCleanupWire`）。 */
 export declare const ROUTES: {
-    readonly list: "/list";
+    readonly list: {
+        readonly path: "/list";
+        readonly method: "GET";
+    };
     /** 通道的"在不在"专用：没有入参、没有副作用、没有磁盘读。 */
-    readonly ping: "/ping";
+    readonly ping: {
+        readonly path: "/ping";
+        readonly method: "GET";
+    };
     /** 单条详情（读回收站目录里那条会话自己的日志）。 */
-    readonly detail: "/detail";
+    readonly detail: {
+        readonly path: "/detail";
+        readonly method: "POST";
+    };
     /** 一组 id 上的同一个动作；删除确认框那句「含 N 个子会话」也走这里（`action: 'count'`，纯读语义）。 */
-    readonly apply: "/apply";
+    readonly apply: {
+        readonly path: "/apply";
+        readonly method: "POST";
+    };
     /** 清空回收站。 */
-    readonly empty: "/empty";
+    readonly empty: {
+        readonly path: "/empty";
+        readonly method: "POST";
+    };
     /** 纯读：扫描回收站之外的无主子会话（父已不在语料/清册）。 */
-    readonly orphans: "/orphans";
+    readonly orphans: {
+        readonly path: "/orphans";
+        readonly method: "GET";
+    };
     /** 附件字节（图片/普通文件）：全仓唯一的二进制响应段，读的是宿主附件库。 */
-    readonly attachment: "/attachment";
+    readonly attachment: {
+        readonly path: "/attachment";
+        readonly method: "GET";
+    };
     /** 纯读：扫全部引用源与附件库 `objects`，报无引用图片的数量、字节与预览清单。 */
-    readonly attachmentOrphans: "/attachment-orphans";
+    readonly attachmentOrphans: {
+        readonly path: "/attachment-orphans";
+        readonly method: "GET";
+    };
     /** 聚合清理：只删 `objects` 下无引用的图片，回 `AttachmentCleanupWire`。 */
-    readonly attachmentClean: "/attachment-clean";
+    readonly attachmentClean: {
+        readonly path: "/attachment-clean";
+        readonly method: "POST";
+    };
 };
+/** 段名 → 那一段的路径。从结构化段名表派生：加一段只在上面加一项，`Record<RouteName, …>` 类型闸
+ *  （`src/api/route-table.ts`）与运行期键集比对（`tests/route-table.test.ts`）都跟着这一格走。 */
+export type RouteName = (typeof ROUTES)[keyof typeof ROUTES]['path'];
 /** `/apply` 的五个动作。id 的含义随动作走：`delete`/`count`/`orphan-clean` 是**宿主会话 id**
  *  （前两个还没进回收站，第三个压根没有回收站行），`restore`/`purge` 是**回收站条目 id**。
  *  两域都是 string（线上形状）；这里不引入品牌类型——错域不靠类型拦，交给各动词在运行期按自己的
@@ -125,16 +159,54 @@ export interface TrashDetailAttachmentWire {
     width?: number;
     height?: number;
 }
-/** 单条详情里的一条消息（`trash/detail.ts` 读出来的那一份）。
- *  `attachments` 必填：没有附件就是空数组（界面上"这一条带没带附件"不靠字段缺席判断）。 */
-export interface TrashDetailMessageWire {
-    role: 'user' | 'assistant';
+/** 单条详情里的一块正文（`trash/detail.ts` 读出来的那一份）。
+ *
+ *  **判别联合**：`kind` 决定这块怎么画、哪些字段有意义。`attachments` 在每种块上都必填
+ *  （没有附件就是空数组）——"这一条带没带附件"不靠字段缺席判断。
+ *  `truncated` / `argsTruncated` / `resultTruncated` 说的是**单块载荷闸**截过一刀；
+ *  分页游标（`olderCursor`）管的是"更早的块还没取"，两者不是同一件事。
+ *  出线的每块**都有内容**（非空正文或至少一个附件；工具块的名字与状态就是内容）：判据住
+ *  `src/trash/detail.ts`，空块不建也不出线，渲染侧不用兜。 */
+export interface TrashDetailTextBlockWire {
+    kind: 'user' | 'assistant' | 'reasoning' | 'system' | 'compaction';
+    /** 块在整条日志里的稳定序号（分页游标也用它）；跨页不重复。 */
+    id: string;
+    time: number;
+    text: string;
+    truncated: boolean;
+    attachments: TrashDetailAttachmentWire[];
+}
+/** 宿主注入的上下文（`user/message` 里 `source.kind !== 'user'` 的那些）。 */
+export interface TrashDetailInjectionBlockWire {
+    kind: 'injection';
+    id: string;
     time: number;
+    /** 日志里的 `source.kind` 原串（`runtime-context` / `agent-instructions` / …；日志里没写就是空串）；界面自己映射标签。 */
+    sourceKind: string;
     text: string;
     truncated: boolean;
     attachments: TrashDetailAttachmentWire[];
 }
-/** 回收站单条详情的线上形状（`POST /detail`）。 */
+/** 一次工具调用：`tool/call` 建块、`tool/result` 按 `callId` 回填。
+ *  `unfinished` = 日志走完也没等到结果（会话可能在工具执行中被杀），不是失败。 */
+export interface TrashDetailToolBlockWire {
+    kind: 'tool';
+    id: string;
+    time: number;
+    callId: string;
+    name: string;
+    status: 'ok' | 'error' | 'unfinished';
+    args: string;
+    argsTruncated: boolean;
+    result: string;
+    resultTruncated: boolean;
+    attachments: TrashDetailAttachmentWire[];
+}
+export type TrashDetailBlockWire = TrashDetailTextBlockWire | TrashDetailInjectionBlockWire | TrashDetailToolBlockWire;
+/** 回收站单条详情的线上形状（`POST /detail`）。
+ *
+ *  正文按块分页：`blocks` 是当前这一页（从新往旧取），`olderCursor` 指向更早一页的边界；
+ *  计数是**整条日志**的，不受分页影响。 */
 export interface TrashDetailWire {
     entryId: string;
     /** 日志 header 里的原串（**无损**，比从 `projectKey` 反推那一路强；组头怎么念项目名见 `src/client/trash-view.ts` 的 `projectLabel`，那是另一回事）。 */
@@ -146,11 +218,23 @@ export interface TrashDetailWire {
     models: string[];
     turnCount: number;
     userMessageCount: number;
+    /** 日志里**每一条** assistant/message 记录（含只带 reasoning / tool-call 的那些）。 */
     assistantMessageCount: number;
     toolCallCount: number;
+    /** 宿主注入的上下文块数（空文本且无附件的注入不建块，也不计）。 */
     injectedCount: number;
-    messages: TrashDetailMessageWire[];
-    omittedByPayloadCap: number;
+    blocks: TrashDetailBlockWire[];
+    /** 更早一页的块序号；`null` = 已经到顶。把它原样回传给 `POST /detail` 的 `before`。 */
+    olderCursor: number | null;
+    /** 跟着这条父条目一起进回收站、并**折进这一行**的孩子（清册里 `parentEntryId` 指向它，
+     *  且组语义接得住——折的判据复用 `src/trash/groups.ts` 的 `visibleGroups`），按清册原序。
+     *  确有孩子时出线；**缺席 = 没有孩子**，不是空数组。孩子的详情仍按 `entryId` 走同一个 `/detail`。
+     *  最多过线 `src/trash/detail.ts` 的 `SUBAGENT_SUMMARY_LIMIT` 条，超出时 `subagentsTotal` 给总数。
+     *  这是详情线上唯一带清册事实的一格：孩子不在客户端清单里，没有「按 entryId 与清单配对」
+     *  那条路可走（`src/client/remote.ts` 头注的例外说明）。 */
+    subagents?: TrashEntryWire[];
+    /** 子会话总数；**只在 `subagents` 被条数闸截断时出线**（缺席 = 上面就是全部）。 */
+    subagentsTotal?: number;
 }
 /** 一次永久删除顺带、或一次孤儿附件清理的附件读数。`skipped` 有值 = 这一轮**部分或整体没清**：
  *  有候选日志或剩余引用源读不出（原因上屏）。此时 `removed` 仍可能 > 0——损坏的只是某一组候选，
@@ -206,6 +290,8 @@ export interface OrphanCleanStatsWire {
  *  附件段是 **query 参数**（GET 二进制响应，没有请求体）。 */
 export declare const PARAMS: {
     readonly entryId: "entryId";
+    /** `/detail` 的分页游标：只取这个块序号之前的块。缺省 = 从尾部取。 */
+    readonly before: "before";
     readonly action: "action";
     readonly ids: "ids";
     readonly attachmentId: "id";
@@ -242,6 +328,13 @@ export type RemoteResult<T> = {
  * 浏览器半是 `src/client/remote.ts` 的 `throwRemoteFailure`。
  */
 export declare function isDSHRemoteError(value: unknown): value is RemoteFailure;
+/**
+ * 运行期判形「这段 JSON 是不是信封」。中间层（反代 / SPA 兜底）会回 `{}`、`{"error":"…"}` 这类
+ * 不是信封的 JSON；判形不过就该走「回的不是信封」诊断，而不是把垃圾喂给展开层炸出
+ * TypeError / "undefined" 上屏（issue #8 第 1 条）。判据就是两臂的形状：`ok` 必须是布尔，
+ * `ok:true` 须带 `value` 键（值可以是 null），`ok:false` 的 `error` 须是带 string `code`/`message` 的对象。
+ */
+export declare function isRemoteResult(value: unknown): value is RemoteResult<unknown>;
 /** 失败码的域。与宿主官方域（`workspace/*`、`session/*`…）不重名，见本文件。 */
 export declare const SESSION_DELETE_ERROR_DOMAIN = "sessiondelete";
 /** 五个**动词码**（本文件那张表）。`io` 是唯一兜底。 */

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

@@ -16,7 +16,11 @@ export interface FileRef {
     bytes: number;
 }
 export type AttachmentRef = ImageRef | FileRef;
-export declare function isAttachmentId(value: unknown): value is string;
+/** 合法附件 ID：形状是 `sha256:` + 64 位小写十六进制。
+ *  谓词必须收成**模板字面量形状**而不是 `string`：`attachmentPathOf` 里 `!isAttachmentId(id)` 的
+ *  假支若按「是 string」取反会被 TS 收成 `never`（参数本来就是 string），插值就成了 never 读数。
+ *  这里判的仍是同一条正则，谓词只是把「形状」写进类型面。 */
+export declare function isAttachmentId(value: unknown): value is `sha256:${string}`;
 /** `statFile` / `readFile` / `sizeOfDir` 里只有 ENOENT 能当"不在"；权限、盘挂、I/O 错误都必须露成读不出。 */
 export declare function isMissing(error: unknown): boolean;
 /** 合法附件 ID → 宿主附件库里的绝对路径。`name` 不参与拼接。 */
@@ -37,6 +41,9 @@ export interface AttachmentRemovalDeps extends AttachmentReadDeps {
  *  同样按不可读处理（宁可留下对象等维护卡兜底，不冒"没引用"）。
  *  **规范日志旁的文件也要过关**：老一代规范日志可以并存（新代包含旧代）；0 字节临时日志是
  *  写盘未完成的空产物，也没有引用。非空临时日志、明文日志或其他任何文件仍按不可读处理（fail closed）。
+ *  **宿主的内核写锁不是会话内容**：0 字节的锁在判目录形状之前先剥掉——不然每个已实体化的会话目录
+ *  （含搬进回收站的条目）都会被读成"读不懂"，整份引用扫描在真机上恒跳过；没有日志的锁目录因此与
+ *  空目录同判。非空的锁说明我们对这个文件的理解失效（宿主不会往里写字节），仍按不可读处理。
  */
 export declare function imageIdsOfDir(deps: AttachmentReadDeps, dir: string): Promise<{
     ids: Set<string>;

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

@@ -1,32 +1,38 @@
 /**
- * 回收站**单条详情**：从回收站目录里那条会话自己的日志读出元信息与正文（用例见 `tests/trash-detail.test.ts`）。
+ * 回收站**单条详情**：从回收站目录里那条会话自己的日志读出元信息与正文块（用例见 `tests/trash-detail.test.ts`）。
  *
  * 三层里的策略层——编解码在 `src/log/*`，这里只回答"给谁看、给多少、算不算失败"。
  *
- * 三条硬口径，都不是口味：
+ * 四条硬口径，都不是口味：
  * ① **寻址只认清册（raw 索引）**：`entryId` 先在对账之外的 raw 索引里查，目录一律由 `trashDirOf(record.id, home)` 推
  *    ⇒ 外部输入进不了文件系统寻址（不给"传个路径就读任意目录"留缝）。
- * ② **正文只认 `source.kind === "user"`**：`user/message` 里绝大多数是宿主注入的上下文
- *    （本机实测一条会话：真实提问 21 条、注入 241 条），不过滤就被淹掉；注入条数照样上线
- *    （`injectedCount`），让"为什么少了这么多条"能与页面上的数字对账。
- * ③ **两个闸是载荷闸，不是读盘闸**：每条 3 000 字符、累计 50 万字符（CJK 最坏 ≈ 1.5 MB UTF-8）。
- *    本机存量一条都触发不了（量级随盘上会话数摆动，不在这里钉数）⇒ 它们是防异常
- *    膨胀的；**不设"文件太大就拒绝"**，那种阈值只会把真读得出来的正文挡在外面。
+ * ② **正文是块，不是消息**：`user/message` 按 `source.kind` 拆成 user / injection；`assistant/message.content`
+ *    按 `text` / `reasoning` 拆块，附件并进相邻的文字块；`tool/call` 建工具块、`tool/result` 按 `callId` 回填；
+ *    `system/message` 与 `compaction/summary` 各成一块。turn/step/job/request 这类簿记事件不进正文——它们不是
+ *    "用户想看的对话"，铺进来只会把真正的提问和回复淹掉。
+ * ③ **分页是游标，不是总量闸**：一次只回尾部一页，`olderCursor` 指页首；客户端把游标原样回传取更早一页。
+ *    页有两道闸：块数 `pageBlocks` 与正文总量 `pageChars`（单块超字符闸仍保留一块，游标才能前进）；
+ *    每块另有 `perBlockChars` 的单块闸（正文与工具参数/结果各自算），超了标 `truncated`。
+ *    构建时用**有界缓冲只留当前页**，不把整条日志的正文堆在内存里；工具结果可能落在游标之后，
+ *    仍会回填到页内那个调用块（别把"已完成"误报成"未完成"）。
+ * ④ **计数与正文同源过滤、各过各的闸**：`userMessageCount` / `injectedCount` 只数建了块的；`assistantMessageCount`
+ *    数**每一条** assistant/message（含只带 reasoning / tool-call 的）；`toolCallCount` 数每一条 tool/call。
+ *    计数是整条日志的，不受分页与任何字符闸影响。
  *
- * 计数与正文**同源过滤、各过各的闸**：`user/message` 先要求 `source.kind === 'user'`，两类都过"空文本**且**
- * 无附件"过滤；`userMessageCount` / `assistantMessageCount` 数的是通过过滤的条数，**不受载荷闸影响**。正文再受
- * 单条/累计两个闸：单条超限截断并把那一条标成 `truncated`，累计到上限后剩下的整条不再收、只累进
- * `omittedByPayloadCap`——所以计数可以大于正文条数，详情里两件事分开说。
- * 附件随消息一起收（`attachmentsInContent`），也有两个闸：每条 20、总量 200；超出的**静默丢**，
- * 不累进 `omittedByPayloadCap`——那个计数说的是"整条正文没进来"，拿它兼报少了几张附件会让两个数都对不上。
+ * 附件随块一起收（`attachmentsInContent`）：每块最多 20、每页最多 200；超出的**静默丢**，不另立计数——
+ * "少了几张图"与"这块被截断"不是同一件事，拿一个数兼报会让两个数都对不上。
  */
 import { type TrashEntry } from './entry.js';
 import type { FsPort } from '../ports/fs-port.js';
 import type { TrashDetailWire } from '../shared/wire.js';
-/** 每条文字的上限（字符）。超出即截断并置 `truncated`。 */
-export declare const PER_MESSAGE_CHAR_CAP = 3000;
-/** 一次回信的正文总量上限（字符）。 */
-export declare const TOTAL_CHAR_CAP = 500000;
+/** 每块文字的上限（字符）。正文、工具参数、工具结果各自吃这一刀。 */
+export declare const PER_BLOCK_CHAR_CAP = 16000;
+/** 一页最多多少块。 */
+export declare const PAGE_BLOCK_LIMIT = 30;
+/** 一页正文的总字符上限（块按日志顺序累计；单块超闸时仍保留一块）。 */
+export declare const PAGE_CHAR_LIMIT = 500000;
+/** 子会话摘要最多列多少条；超出时只过线前 N 条，总数另走 `subagentsTotal`。 */
+export declare const SUBAGENT_SUMMARY_LIMIT = 200;
 export type TrashDetail = TrashDetailWire;
 export type DetailDeps = {
     /** 详情自己直接要的三件（判目录在不在、挑日志、读日志）。对账不在这条路上，所以不需要 `listDirs`。 */
@@ -37,9 +43,13 @@ export type DetailDeps = {
     rows: () => Promise<readonly TrashEntry[]>;
     home: string;
 };
-/** 两个载荷闸（可调是为把策略单独验穿；生产走的就是这两个默认值，用例里钉着）。 */
+/** 四个分页/截断参数（可调是为把策略单独验穿；生产走的就是这四个默认值，用例里钉着）。 */
 export interface DetailLimits {
-    perMessageChars: number;
-    totalChars: number;
+    perBlockChars: number;
+    pageBlocks: number;
+    /** 一页正文的总字符闸；缺省 `PAGE_CHAR_LIMIT`。 */
+    pageChars?: number;
+    /** 子会话摘要的条数闸；缺省 `SUBAGENT_SUMMARY_LIMIT`。 */
+    subagents?: number;
 }
-export declare function readTrashDetail(deps: DetailDeps, limits?: DetailLimits): (entryId: string) => Promise<TrashDetail>;
+export declare function readTrashDetail(deps: DetailDeps, limits?: DetailLimits): (entryId: string, before?: number) => Promise<TrashDetail>;

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

@@ -1,6 +1,8 @@
+import { type TrashEntryWire } from '../shared/wire.js';
 /** 回收站的一条记录。`id` 由 `makeEntryId` 生成（`<删除时刻>-<原目录名>`）——**它不是随手起的键**：
  *  回收站目录名就是它，恢复也按它反推出原目录名放回（CONTEXT.md 的「条目」条），所以 id 的形状有契约意义。
- *  其余字段在删除那一刻就地取。 */
+ *  目录名里的空白/引号照原样进 id（往返契约压倒 HTML 合法性——DOM id 的编码归浏览器半的
+ *  `trash-panel.tsx`）。其余字段在删除那一刻就地取。 */
 export interface TrashEntry {
     id: string;
     sessionId: string;
@@ -43,6 +45,10 @@ export declare const REQUIRED_ENTRY_FIELDS: {
     readonly title: "string";
     readonly sizeBytes: "number";
 };
+/** 清册行 → 线上清册行形状。**显式字面量、不用 `...row`**：线上多一格必填时这里编译不过。
+ *  只搬清册里真有的事实、不带任何只读数；`/list` 的 `toWire` 与详情的子会话摘要共用这一份
+ *  （否则同一条清册行会有两份会漂移的投影）。 */
+export declare function entryWire(row: TrashEntry): TrashEntryWire;
 export declare function makeEntryId(deletedAt: number, sessionDirName: string): string;
 /** `makeEntryId` 的逆。时间戳按 UTC 拆字段再 `Date.UTC` 合回——不交给 `Date.parse`
  *  去猜（`20260930T130500Z` 不是任何被承认的日期格式，猜出来的是 NaN）。 */

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

@@ -4,7 +4,7 @@
  * 接得住孩子的只有组根——自己不记 `parentEntryId` 的那一行。父行不在、或父行自己也是孩子时，
  * 孩子必须自己占一行，否则它的字节会被头部合计数两遍，而它自己既看不见也清不掉。
  *
- * 三个函数都是纯函数、都吃一份快照；收缩时机归调用方，本模块不持有可变状态。
+ * 这些函数都是纯函数、都吃一份快照；什么时候收缩、把收缩后的视图存在哪里归调用方，本模块不持有可变状态。
  */
 import type { TrashEntry } from './entry.js';
 /** 一条露面的组根，连同它接住的孩子（顺序与清册一致）。 */
@@ -29,6 +29,11 @@ export declare function visibleGroups(rows: readonly TrashEntry[]): TrashGroupVi
  *   调用方据此报 `trash-empty` / 判"已被同批前一条带走"。
  */
 export declare function groupOf(rows: readonly TrashEntry[], id: string): TrashEntry[];
+/**
+ * 把一条 id 所属的**整组**从快照里摘掉，回一份新快照（组语义仍只读 `groupOf`，这一条判据不另写一遍）。
+ * 「同批前一条已把这一组带走」的收缩就是它：调用方各自持有那份可变视图，本函数不记账。
+ */
+export declare function withoutGroup(rows: readonly TrashEntry[], id: string): TrashEntry[];
 /** 一条 id 在「原始快照 vs 当前视图」里的三态。判别联合：**只有 `fresh` 带当前这一组**——
  *  组语义只对"还在"的 id 有意义，carried / absent 没有可交的组，调用方也就无从误用。 */
 export type GroupClaim = {

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

@@ -2,11 +2,11 @@ import type { TrashEntry } from './entry.js';
 /** 回收站清单的 **raw 索引端口**：只给 `src/trash/ledger.ts` 与对账实现；动词与路由只认 ledger，
  *  不认 storage domain 的形状。`list()` 不保证与 `session-trash/` 目录一致（对账在 ledger 的 `list()`）。 */
 export interface ManifestPort {
-    list(): Promise<TrashEntry[]>;
-    add(e: TrashEntry): Promise<void>;
-    remove(id: string): Promise<void>;
+    /** 属性声明：`list` 会被摘下来转交给对账（`manifest: { list: manifest.list, … }`），实现不读 `this`。 */
+    list: () => Promise<TrashEntry[]>;
+    add: (e: TrashEntry) => Promise<void>;
+    remove: (id: string) => Promise<void>;
 }
-export declare function createMemoryManifest(seed?: TrashEntry[]): ManifestPort;
 /** 宿主 storage domain 的最小面。这是**接缝**，不是对宿主 API 的断言：
  *  探针只枚举到 `ctx.storageDomain` 有 `open` / `get` / `domains` / `reserved` 等成员，
  *  **没有**枚举 `open()` 返回的 domain 句柄面 ⇒ 真实绑定由 `src/trash/storage-manifest.ts` 的

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

@@ -3,8 +3,6 @@ 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 = {
@@ -14,7 +12,7 @@ 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/live-admission.d.ts

@@ -2,7 +2,7 @@
  * 活体准入：删除 / 永久删除 / 孤儿清理之前，逐个问会话是否在宿主内存里 attach 着；
  * 任一在跑就整组拒绝、零副作用（ADR-0008）。
  *
- * 边界：什么时候查归调用方——永久删除的准入在计划里、任何写之前（ADR-0006）；
+ * 边界：什么时候查归调用方——永久删除在计划里查一次、执行器第一笔写前用计划里的会话名单再查一次（ADR-0027）；
  * 本模块只拥有「查什么、怎么判、怎么说」。
  */
 import type { HostIdentityPort } from '../ports/host-port.js';

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

@@ -15,7 +15,9 @@ import type { Journal, JournalUndo } from './member-journal.js';
 /** 本模块实际用到的三条宿主能力。`Pick` 此刻覆盖 `HostPresencePort` 的三条方法，仍留着它当闸：
  *  将来端口多出第四条时，这里不会被动跟着变宽——能力面只暴露这三条，批量通告的编排归 `verbs/batch.ts`。 */
 export type MemberPresenceHost = Pick<HostPresencePort, 'evictLive' | 'announceRemoved' | 'announceRestored'>;
-/** 本仓的在场能力实现：端口形状住 `src/ports/presence-port.ts`，这里只做三态与真值表。
+/** 本仓的在场能力实现，也是**全仓唯一的盖章处**：端口形状住 `src/ports/presence-port.ts`，这里只做
+ *  三态与真值表。品牌字段是类型层的（unique symbol 不导出、没有运行时值），所以只有这一处显式断言
+ *  能把三件方法盖成 `PresenceCapability`——手拼同样的三件满足不了那个面（`tests/deps.test.ts` 钉住）。
  *  `announceRestored` 直接交宿主那一手：能力面与宿主面同名同签名，再包一层只会多一个转调。 */
 export declare function createMemberPresence(host: MemberPresenceHost): PresenceCapability;
 /** 一次 undo 之后要发哪一条通告：`leave` = 成员已不在可见面，`return` = 已回到原可见状态。 */

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,4 +1,4 @@
-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, RemovalDeps } from '../deps.js';
@@ -27,8 +27,9 @@ 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[];
@@ -39,10 +40,15 @@ export declare function orphanGroupsOf(corpus: readonly SessionIdentity[], trash
  *
  *  `listSessions()` 回 `{ available: false }` 时**必须抛**：那是宿主的会话语料服务没挂，不是"这个家没有孤儿"。
  *  拿缺席当空语料 ⇒ 报告说"零条孤儿"、界面上一句"没有要清理的"，而盘上真有几百 MB——那是假话，
- *  所以这里按 `io` 响亮失败（AGENTS.md：`available: false` 意味着服务缺席，扫描方不许冒充读数）。 */
+ *  所以这里按 `io` 响亮失败（AGENTS.md：`available: false` 意味着服务缺席，扫描方不许冒充读数）。
+ *
+ *  `roots` 只收请求点名的那几组、**在量字节之前过滤**：`/orphans` 不传（报告全部），
+ *  `orphan-clean` 传这次的根——否则点一组会把整个家所有孤儿的树都递归量一遍。 */
 export declare function loadOrphanGroups(deps: CoreDeps, 
 /** 调用方选好并交来的清册行：`/orphans` 交 `read.rows()`，`orphan-clean` 交 `ledger.list()`。 */
-trash: readonly TrashEntry[]): Promise<readonly OrphanGroup[]>;
+trash: readonly TrashEntry[], 
+/** 只要这些根（两边都去 `session-` 前缀再比）；缺席 = 全量扫描。 */
+roots?: readonly string[]): Promise<readonly OrphanGroup[]>;
 /** 把一组组收成那份报告：根清单 + 闭包总数/总字节 + 失踪父的**去重计数** + 按项目目录的分摊。
  *  `groups` 按字节从多到少排（界面上"哪家还剩得最多"要看第一行）。 */
 export declare function reportOrphans(groups: readonly OrphanGroup[]): OrphanReportWire;

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

@@ -1,6 +1,10 @@
 /**
  * 永久删除的测量、计划与执行：先记录目录/字节/账本归属，再按计划动盘。
- * 计划函数只读；活体准入在计划阶段、任何写之前完成。
+ * 计划函数只读；活体准入在计划阶段、任何写之前完成，执行器动第一笔写前再查一次。
+ *
+ * 测量与补账本归属**分家**：`/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';
@@ -11,8 +15,8 @@ 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;
@@ -25,6 +29,21 @@ export declare function measureMemberDir(deps: CoreDeps, member: {
     readonly sessionId: string;
     readonly projectDir: string;
 }): Promise<MeasuredMemberDir | undefined>;
+/** 一条成员的**测量**读数：身份两格 + 目录 + 实测字节。没有账本归属那一格——归属是删除动词才要
+ *  读的账本事实（见 {@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<MeasuredMember[]>;
 /** 回收站里的一条要删的行：目录、在不在、实测字节（缺席 = 0）。purge 与 `/list` 都由它量。 */
 export interface PlannedTrashRow {
     readonly entry: TrashEntry;
@@ -32,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;
@@ -46,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[]>;
 /** 一次永久删除的只读计划：哪些目录要删、各自实测多少字节、哪些会话要先摘归档集。
@@ -67,7 +88,8 @@ export interface RemovalPlan {
 }
 /**
  * purge 的删除计划：`targets` 由调用方按组语义（`trash/groups.ts`）选好，这里只量、只筛、只查活体。
- * **计划函数就是执行前的闸**——调用方拿到计划才允许写，所以准入必须发生在任何写之前。
+ * **计划函数是执行前的第一道闸**——调用方拿到计划才允许写；计划与第一笔写之间的窗口由
+ * `executeRemoval` 在首笔写前复查（见该函数头注）。
  *
  * - `trash` 按 targets 原序逐个实测（目录缺席的行 `present:false` / 0 字节，但清册行仍要摘）。
  * - 盘上后代经 `selectStrandedMembers` 选出（一次问全部 targets、排除全部清册 id、bare id 全局只计划一次）。
@@ -76,7 +98,7 @@ export interface RemovalPlan {
  * - `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>;
@@ -96,8 +118,15 @@ 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`：
+ * 它覆盖所有会被删目录的会话（回收站行与盘上成员），目录已不在的成员没有可删的东西。
  *
  * 顺序：整批摘归档集 → 摘有账本的成员的账本 → 逐条回收站行
  * （在才删目录 → 摘清册行 → 通告成员离场）→ 逐条盘上成员（删目录 → 通告成员离场）→ 逐条附件对象。

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;