@xrn1997/dsh-session-delete 0.3.1 → 0.5.0

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

@@ -12,39 +12,35 @@
  * - **面板恢复用 `panelSeat: true` 明说**（「缺席」不再承载语义）：外部恢复（撤销横幅）由 settlement
  *   调 `afterRestore` 重开；面板恢复自带「回来」的结算，只 `forgetMainView`、不重开、不抢焦点。
  *   判据住 `src/client/main-view.ts` 的 `forgetMainView`。
- * - **撤销名单由 settlement 算、座位发布**：delete 支把 `landedEntryIds` 与 `successIds.length` 算成
- *   `{ entryIds, n }` 交给座位，座位只决定发布哪一形（单条带标题、批量带条数）——那句文案与它的键
- *   住 `undo-toast.tsx` 与 `copy.ts`；purge 支在
+ * - **撤销名单由摘要给、座位发布**：delete 支从 `summary.landedIds`（域是条目 id）取名单、用
+ *   `summary.successIds.length` 作条数，组成 `{ entryIds, n }` 交给座位，座位只决定发布哪一形
+ *   （单条带标题、批量带条数）——那句文案与它的键住 `undo-toast.tsx` 与 `copy.ts`；purge 支在
  *   `anySuccess` 时熄灭指向这些条目的横幅——留着就是一条注定失败的「撤销」。
- * - **`count` 不结算**；`orphan-clean` 没有跨槽位收尾（清完由 query 自己的写后刷新收尾）。
+ * - **`count` 不结算**；`orphan-clean` 没有跨槽位收尾（维护卡的 `use-maintenance.ts` 清完自己重查）。
  *   不直接读 DOM、不问宿主：主视图收尾只经 `main-view.ts` 的 `afterDelete` / `afterRestore`
  *   （服务缺席或抛错都静默退回）；重读仍归各调用方的 `refresh`（面板那侧的最新票在 `use-trash-query.ts`）。
  */
 import type { ApplyAction } from '../shared/wire.js';
-import { type Receipt } from './receipt.js';
-/** 一次写入里与渲染无关的那部分：动作、请求 id、回执、成功名单与“至少一条落地”。 */
+import type { ReceiptSummary } from './receipt.js';
+/** 一次写入里与渲染无关的那部分：动作、请求 id、以及唯一的那份回执摘要。 */
 export interface SettledFacts<A extends ApplyAction> {
     readonly action: A;
     readonly ids: readonly string[];
-    readonly receipt: Receipt<A>;
-    /** 成功支（`ok` / `already-gone`）的请求 id，按请求顺序。 */
-    readonly successIds: readonly string[];
-    /** 至少一条真的落地（`ok` / `already-gone`；N=1 的协议空值不算）。 */
-    readonly anySuccess: boolean;
+    readonly summary: ReceiptSummary;
 }
 /**
  * 按 action 切开的一族呈现材质：每个座位只能拿到自己动作那几手，形状对不上的钩子在类型面就不存在。
- * - `delete` 的 `publishUndo` 存在即「这个座位要发撤销横幅」；它拿到的是 settlement 算好的落地名单。
+ * - `delete` 的 `publishUndo` 存在即「这个座位要发撤销横幅」；它拿到的是 settlement 从摘要取出并组好的落地名单。
  * - `restore` 的 `panelSeat: true` 才是「面板已替这条完成『回来』的结算」，不再靠缺席某个钩子暗示。
  * - `count` / `orphan-clean` 没有呈现材质（用 `noPresentation`）。
  * 钩子都是同步的：settlement 在 `refresh` 前一次跑完，不 await。
  */
 export type WritePresentationByAction = {
     delete: {
-        /** 外部写入座位：让回收站面板重读。面板写不传（自己的 `refreshAfterWrite` 就是重读）。 */
+        /** 外部写入座位：让回收站面板重读。面板写不传（自己的清单重读 `reload` 不走这条通告）。 */
         invalidate?(): void;
-        /** 撤销发布：settlement 把落地的条目 id 与请求名单算好后交来；名单**非空**——全被同批前一条带走时
-         *  没有落点，settlement 不发布没有可撤销动作的横幅。座位只决定发布哪一形与那一形带的标题。 */
+        /** 撤销发布：settlement 从回执摘要取出落地条目 id 与请求名单、组好形之后交来；名单**非空**——
+         *  全被同批前一条带走时没有落点，settlement 不发布没有可撤销动作的横幅。座位只决定发布哪一形与那一形带的标题。 */
         publishUndo?(landed: {
             readonly entryIds: readonly [string, ...string[]];
             readonly n: number;
@@ -56,8 +52,6 @@ export type WritePresentationByAction = {
         panelSeat?: true;
         dismissUndo?(entryIds: readonly string[]): void;
         clearDetailCache?(entryIds: readonly string[]): void;
-        /** already-gone 的回执不带行，它的 sessionId 只能由调用方从当前清单里查。 */
-        sessionIdOfEntry?(entryId: string): string | undefined;
     };
     purge: {
         dismissUndo?(entryIds: readonly string[]): void;

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

@@ -1,5 +1,5 @@
 /**
- * 一次逐条 `/apply` 写入的**唯一生命周期**：apply → 解信封 → `readReceipt` → settlement → refresh。
+ * 一次逐条 `/apply` 写入的**唯一生命周期**：apply → 解信封 → `readReceipt` → 回执摘要 → settlement → refresh。
  *
  * 收尾顺序与 `anySuccess` 门住 `src/client/write-settlement.ts`（为什么按 action 收见 ADR-0013）；
  * 这里只管时机、信封判读、整趟的闸与 `refresh` 的交法。清空回收站是聚合回执（`/empty`），收尾仍住
@@ -8,13 +8,14 @@
  * 五条判据：
  * - `ok` 只说**信封**成不成；逐条成败在 `failures` 里，调用方自己决定怎么上屏。
  * - 顶层失败把同一句原文铺到每个 id，不结算；`refresh` 照样交（成败都在 outcome 里）。
- * - **信封成功就结算**（逐条全失败也跑：批量写入的失效通告不能漏）；`anySuccess` 由这里算好，
- *   按 action 的呈现材质由 settlement 按它上闸。调用方只交呈现材质，再按 `outcome` 决定是否真的重读。
+ * - **信封成功就结算**（逐条全失败也跑：批量写入的失效通告不能漏）；`anySuccess` 与落地名单由
+ *   `receipt.ts` 的回执摘要算好，settlement 按它上闸。调用方只交呈现材质，再按 `outcome` 决定是否真的重读。
  *   结算在 `refresh` 之前：列表重读看得到收尾后的现场。
  * - `single: true` 时把 N=1 模式交给 `receipt.ts` 的读法；单条 null 在那一处折成 failed，
  *   这里不再重复守卫。
  * - **闸包住整趟**：给了 `gate` 就把 apply → settle → refresh 一起包进去——refresh 落在闸外时，
- *   旧清单还在屏上，同一个动作能被再点一次；调用方不再自己 `around`。
+ *   旧清单还在屏上，同一个动作能被再点一次；调用方不再自己 `around`。同一枚闸已有任务在飞时
+ *   这一趟**不跑**（连点不发第二条），交回 `undefined`：座位照它收「这一趟没跑」，不伪造 outcome。
  */
 import type { BusyGate } from './busy-gate.js';
 import { type OneShotDeps } from './remote.js';
@@ -22,7 +23,8 @@ 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。 */
+    /** 逐条失败原文（failed / neutral / missing），按 id。这是失败表的**唯一落点**：
+     *  摘要只带聚合与落地 id，不再复制一份逐条原文。 */
     readonly failures: ReadonlyMap<string, string>;
 };
 export interface WriteFailure<A extends ApplyAction> {
@@ -39,8 +41,10 @@ export interface WriteInput<A extends ApplyAction> {
     readonly action: A;
     readonly ids: readonly string[];
     /** 单条写入面：把 N=1 模式交给 receipt 读法（null 折成协议错）。 */
-    readonly single?: boolean;
-    /** 信封成功时交给 settlement 的呈现材质（`successIds` 可能为空）；按 action 的收尾顺序住 `write-settlement.ts`。 */
+    readonly single?: boolean | undefined;
+    /** restore 的 already-gone 回执不带行，它的 sessionId 只能由调用方从当前清单里查。 */
+    readonly sessionIdOfEntry?: (entryId: string) => string | undefined;
+    /** 信封成功时交给 settlement 的呈现材质（摘要里的成功名单可能为空）；按 action 的收尾顺序住 `write-settlement.ts`。 */
     readonly presentation?: WritePresentation<A>;
     /** 这一趟的闸：给了就把 apply → settle → refresh 整趟包进 busy。refresh 不许落在闸外。 */
     readonly gate?: BusyGate;
@@ -48,4 +52,13 @@ export interface WriteInput<A extends ApplyAction> {
      *  是否真的重读由调用方决定。 */
     readonly refresh?: (outcome: WriteOutcome<A>) => void | Promise<void>;
 }
-export declare function runWrite<A extends ApplyAction>(input: WriteInput<A>): Promise<WriteOutcome<A>>;
+/** 签名上的分岔就是判据：**没传闸 ⇒ 这一趟一定跑**，回真结果；**传了闸 ⇒ 可能被同一枚闸的在飞那一趟
+ *  挡回**，那时这一趟什么都没做、回 `undefined`。`runWrite` 不替调用方编造成果——挡回来的那趟怎么收尾
+ *  归座位与界面（判据住 `busy-gate.ts`）。第二支把 `gate` 钉成 `undefined`：`BusyGate | undefined`
+ *  这类"可能真有闸"的输入不许落到「一定跑完」那一支，否则类型会把挡回漏成 `WriteOutcome`。 */
+export declare function runWrite<A extends ApplyAction>(input: WriteInput<A> & {
+    readonly gate: BusyGate;
+}): Promise<WriteOutcome<A> | undefined>;
+export declare function runWrite<A extends ApplyAction>(input: WriteInput<A> & {
+    readonly gate?: undefined;
+}): Promise<WriteOutcome<A>>;

package/lib/types/deps.d.ts

@@ -1,14 +1,25 @@
-import type { FsPort } from './ports/fs-port.js';
-import type { HostPort } from './ports/host-port.js';
+import type { CoreFsPort, FsPort } from './ports/fs-port.js';
+import type { HostCorePort } from './ports/host-port.js';
+import type { PresenceCapability } from './ports/presence-port.js';
 import type { TrashLedger } from './trash/ledger.js';
-/** Node 半的基础依赖面：组合根只装配这一颗；动词之间不互相 import 依赖面 interface。 */
+/** Node 半的基础依赖面：组合根只装配这一颗；动词之间不互相 import 依赖面 interface。
+ *  `fs` 不含 `removeDir` / `removeFile`，`host` 不含在场三件——两条危险能力各走 {@link RemovalDeps} 与
+ *  {@link CoreDeps.presence}。 */
 export interface CoreDeps {
-    fs: FsPort;
-    host: HostPort;
+    fs: CoreFsPort;
+    host: HostCorePort;
     ledger: TrashLedger;
     home: string;
+    presence: PresenceCapability;
 }
-/** 只有删除读时钟；其余读 / 计划 / 恢复 / 永久删除只用 CoreDeps。 */
-export type DeleteDeps = CoreDeps & {
+/** 会话删除动词的依赖面：只多读时钟；它不删目录（回滚只把搬走的搬回）。 */
+export type DeleteSessionDeps = CoreDeps & {
     now(): number;
 };
+/** 永久删除的执行面：执行器及其分发拿得到 `removeDir` 与 `removeFile`；计划函数仍只收 `CoreDeps`（它们不写）。 */
+export type RemovalDeps = CoreDeps & {
+    fs: CoreFsPort & Pick<FsPort, 'removeDir' | 'removeFile'>;
+};
+/** 组合根装出的全量面：`/apply` 的分发同时够到删除的时钟与永久删除的 `removeDir` / `removeFile`
+ *  （后者也供孤儿附件清理段使用）。 */
+export type DeleteDeps = DeleteSessionDeps & RemovalDeps;

package/lib/types/domain/closure.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 会话闭包（session closure）的唯一实现：`session-` 前缀归一 + 传递闭包 + 首见去重。
+ *
+ * 为什么是零依赖纯部件：这三件事在仓里曾有两份闭包实现（端口的分层 BFS、无主子会话的整表 BFS）
+ * 与三处手写去重，同一口径靠注释担保——注释不会替代码挡漂移，所以把口径收进这里，一份实现；
+ * 端口与动词只做接线（逐层问宿主、SessionIdentity 映射留在各自那层，见各自的头注）。
+ * 不碰盘、不碰端口类型：本文件一个 import 都不许有。
+ */
+/** 闭包里的一个节点：本部件只认这两个字段；端口的后代记录与语料的 SessionIdentity 都满足它。 */
+export interface ClosureNode {
+    readonly sessionId: string;
+    readonly projectDir: string;
+}
+/** 会话 id 去掉 `session-` 前缀后的形状：同一个会话在两代宿主里写法不同（v3 代 id 不带前缀、
+ *  现行代带），归堆、成组、去重一律按这个形状比——两边都归一，不赌调用方传的是哪一代写法。 */
+export declare function bareSessionId(id: string): string;
+/** 一个 id 的全部可能写法，原写法在前：`session-x` → `[session-x, x]`；`x` → `[x, session-x]`。
+ *  逐层问宿主时按这些写法问：宿主那支按 `header.parentSession` 原文比，不替我们归一。 */
+export declare function sessionIdShapes(id: string): string[];
+/** parent(bare) 到 children 索引上的传递闭包：深度不设上限、防环、首见去重（都按 bare 归一后比）。
+ *  根的两种写法都认（内部归一次）；结果不含根自己。数据里真出现环时代价是「少数一条」，
+ *  不是把清单读挂死——环本来不该出现（parentSession 是一条有向边），出现就是手工改过日志或宿主 bug。 */
+export declare function closureOf<N extends ClosureNode>(children: ReadonlyMap<string, readonly N[]>, root: string): N[];
+/** 同一条记录两代写法只认第一次出现（保原序）。全局去重只有这一处实现：谁要按 bare 去重，
+ *  交一条列表进来，别在调用点再手写一个 seen 集合。 */
+export declare function firstByBare<N extends ClosureNode>(members: readonly N[]): N[];
+/**
+ * 整表语料 → 根闭包组：`parentSessionId` 不在 `known` 里的那些 subagent 各自成一组。`known` 两侧都
+ * 归一后再比（传原始 id 即可）。「已知父为什么排除在外」是调用方的领域判据（住
+ * `src/verbs/orphan-subagents.ts` 与 `CONTEXT.md` 的「无主子会话」），这一层不替它复述。
+ *
+ * 组内的后代仍走 `closureOf` 那一份闭包，只是多一条跨组的 `claimed`：一条记录只归第一个认领它的根。
+ * 已被前一组收走的那条，连同它整支子树都不再出现在这一组里——后代在那一组已被全部认领，所以
+ * 「丢掉已认领的」与「不走进已认领的那支」交回的是同一个集合。环上的代价是「少数一条」，
+ * 不是把一次扫描挂死。组序与成员序都按语料原序。
+ */
+export declare function orphanRootsOf<N extends ClosureNode & {
+    readonly parentSessionId?: string;
+    readonly subagent: boolean;
+}>(corpus: readonly N[], known: Iterable<string>): {
+    root: N;
+    parentSessionId: string;
+    members: N[];
+}[];

package/lib/types/index.d.ts

@@ -15,16 +15,20 @@ export declare const name = "@xrn1997/dsh-session-delete";
  *   它同样可能晚于本插件激活，写进插件 inject 只会让整个插件 pending。
  *
  * `webServer` 是**浏览器半取数通道的承载者**（那条薄线）：插件用它注册 `/dsh-session-delete-api`
- * 前缀路由，浏览器半同源 fetch 那六个段名。它是宿主 web 组成里的硬依赖（`dsh-host-webserver` 的
+ * 前缀路由，浏览器半同源 fetch 那九个段名。它是宿主 web 组成里的硬依赖（`dsh-host-webserver` 的
  * `super(ctx, "webServer")`），服务名与 `register({kind:'prefix', path, handler})` 的形状按
  * `dsh-host-webserver/lib/index.js` 与 `README.md` 原文读实，不是猜的。
  *
+ * `connection` 只喂请求栅栏的远程支（`src/api/request-trust.ts` ②），按 `ctx.get` 可选读：
+ * 服务缺席时插件照常激活，远程客户端 fail-closed。它不进 `inject`——写进去会让没有 web 组成的
+ * profile 整个停在 pending。
+ *
  * 清册的三层各有各的家：raw 绑定 `src/trash/storage-manifest.ts`、读面（对账 + 读）`src/trash/ledger.ts`、
  * 数据根 `src/ports/home.ts`。这里只把它们接起来，任何一层都不在组合根里长判据。
  */
 export declare const inject: string[];
 /**
- * 装配顺序：**清单 → 端口 → 动词依赖 → 前缀路由**（`DeleteDeps` 就是前两者的合一）。
+ * 装配顺序：**清单 → 端口 → 在场能力 → 动词依赖 → 前缀路由**（`DeleteDeps` 把这些依赖面合成一颗）。
  *
  * 路由用 `ctx.effect` 挂、disposer 归装载它的那根 fiber：插件卸载即摘路由（`register` 返回的
  * disposer 是官方契约）。**同一进程里只注册一次**这件事由宿主把住：重复的 `(kind, path)`

package/lib/types/log/session-log.d.ts

@@ -16,10 +16,11 @@ export interface SessionLogStats {
     /** 整条日志最后一个换行之后的字节数（>0 说明尾巴被切了一刀）。 */
     truncatedTailBytes: number;
 }
+/** 这个名字是不是规范日志（任意一代）。附件引用扫描用它区分"老一代日志"与"读不懂的旁文件"。 */
+export declare function isCanonicalSessionLogName(name: string): boolean;
 /**
- * 同一个会话目录里**可以并存多代日志**（宿主换代时把老代留在原地当历史语料，本机实测 7 个目录如此），
- * 而新代是老代的**迁移后超集**（实测：`firstTs` 与开头那条提问完全相同、记录更多、末尾更晚）
- * ⇒ 要读的是版本号最大的那一代，读旧代 = 读到一份截了尾巴的快照；把几代拼起来 = 重复计数。
+ * 同一个会话目录里可以并存多代日志；只读版本号最大的那代，因为新代包含旧代的记录且末尾更晚
+ * ⇒ 读旧代 = 一份截了尾巴的快照；把几代拼起来 = 重复计数。
  *
  * 明文（无 `.zstd`）不在此列：本插件的读法逐帧解 zstd，明文得走另一条解码路。
  */

package/lib/types/log/zstd-frames.d.ts

@@ -1,5 +1,5 @@
 /**
- * 多帧 zstd 流的**帧边界**（2026-10-15 实测）。
+ * 多帧 zstd 流的帧边界。
  *
  * 为什么要有这个文件：会话日志是一次次 append 出来的**帧序列**，而 Node 的 `zstdDecompressSync`
  * **与** `createZstdDecompress()` 流式**都只给第一帧**（实测：本机一个 3.8 MB 的文件，两个 API 都只回
@@ -8,15 +8,20 @@
  * 帧 = `magic(4) + Frame_Header_Descriptor(1) + [Window 1B 若 !single] + [DID 0/1/2/4] + [FCS]
  *       + 若干块（3B 块头 + 块体）+ [4B 尾巴]`。
  *
- * **真实产物的形态是量出来的**（本机 125 个文件 / 36 904 帧）：descriptor **恒 `0x04`**（单段 ⇒ 无
- * Window，FCS 1 字节，无字典，校验位没置位），块类型只有 `Compressed`(36 630) 与 `Raw`(620)，
- * 每帧 **1～120 块**（多数 1 块）——所以多块循环与 Raw 两条路都在生产上跑着，不是纸面分支。
+ * **真实产物的形态是量出来的**（本机 125 个文件 / 36 904 帧）：descriptor **恒 `0x04`**，按 RFC 8878
+ * 表 3 读作「非单段（带 1 字节 Window）+ 无 FCS + 无字典 + **校验位置位**」⇒ 帧头 6 字节，帧尾那 4 字节
+ * 就是声明好的 XXH32 Content_Checksum（实测：动它一个位，对面解不通过）。块类型只有
+ * `Compressed`(36 630) 与 `Raw`(620)，每帧 **1～120 块**（多数 1 块）——所以多块循环与 Raw 两条路都在
+ * 生产上跑着，不是纸面分支。
  * 类型 3 是规范的 Reserved 位（不是"未压缩块"）：产物里没出现过，Node 也当场拒解 ⇒ 遇到就抛。
  *
- * **尾巴那 4 字节按实测处理，不按 descriptor 的 bit5**：校验位从未置位，却每帧都带 4 字节；
- * 判"读不读这 4 字节"用的是「跳过去必须正好撞上下一帧的 magic 或到 EOF」——猜错不会静默切歪：
- * 末尾的自证与块界护栏会抛（护栏是必需的：块头越界时 `|` 读回 0，而 0 的 `Last_Block` 位没置位，
- * 少了它块循环每圈只 +3 字节却永不 break，整个进程卡死——2026-10-15 写用例时真卡死过一次）。
+ * **位段必须照表 3 取**（1-0 字典 / 2 校验 / 5 单段 / 7-6 FCS 尺寸）：Descriptor 的 64 个合法取值里，
+ * 取错位段会算错头长的有 48 个，剩下 16 个凑对纯属巧合——在产的 `0x04` 就在其中。换个宿主、换个写帧
+ * 的 zstd 版本（明文一大、FCS 上到 4 字节的 `0xa0` 就会算错），帧就切歪，会话日志直接读不出来。
+ *
+ * **尾巴那 4 字节按实测判据收，不按 descriptor 的 bit2**：规则是「跳过去必须正好撞上下一帧的 magic
+ * 或到 EOF」——猜错不会静默切歪：末尾的自证与块界护栏会抛（护栏是必需的：块头可能被文件截断，
+ * 不抛的话块循环每圈只 +3 字节却永不 break，整个进程会卡死；用例覆盖这一条）。
  */
 export interface FrameRange {
     start: number;

package/lib/types/ports/agent-handles.d.ts

@@ -1,5 +1,5 @@
 /** 捕获所需的 ctx 窄面：可选服务读法（`get`）与按依赖注入的子上下文（`inject`，晚挂载的 `agents` 靠它补装）。
- *  旧 ctx / 假件可以没有 `inject`——那就只在 apply 时 `get` 一次。 */
+ *  有些 ctx / 假件没有 `inject`——那就只在 apply 时 `get` 一次。 */
 export interface AgentCtxLike {
     get(name: string): unknown;
     inject?(names: readonly string[], callback: (child: {

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

@@ -0,0 +1,33 @@
+/**
+ * 宿主 `connection` 服务（`dsh-client-connection` 的 `HostConnectionService`，`super(ctx, "connection")`）
+ * 的窄镜像：`requestRejection(request)` 一次做宿主 `/api` 的那两道——Host/Origin 栅栏与「已认证 live peer」。
+ *
+ * **每次请求惰性解析服务**，不在激活时取一次：插件与 `client-connection` 的激活顺序没有承诺，取早了
+ * 会让远程支永远缺席（LAN 上全 403 且难排查）。`ctx.get` 是同步查表，代价可以忽略。
+ *
+ * **状态码在这里翻成裁决**（401 = 归属对、缺身份；403 = 归属不对；其余按归属不对处理），
+ * 调用方拿到的就是自己的词表，不需要知道宿主用哪个码表达哪件事。成员名与返回值按 asar
+ * `dsh-client-connection/lib/index.js` 原文读实。
+ */
+import type { IncomingMessage } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+export type ConnectionVerdict = {
+    readonly kind: 'allowed';
+}
+/** 组成里没有这个服务（无 web 组成 / 老代次）——调用方 fail-closed。 */
+ | {
+    readonly kind: 'absent';
+}
+/** 宿主认可归属，但这条请求没带已认证身份。 */
+ | {
+    readonly kind: 'unauthenticated';
+}
+/** 宿主不认可归属（Host/Origin 栅栏不过，或它给出的其余状态码）。 */
+ | {
+    readonly kind: 'untrusted';
+};
+export interface ConnectionPort {
+    verdictFor(req: IncomingMessage): ConnectionVerdict;
+}
+/** 成员抛错按「归属不对」拒绝（fail-closed）。 */
+export declare function createConnectionPort(ctx: Context): ConnectionPort;

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

@@ -1,16 +1,31 @@
 export interface FsPort {
-    exists(p: string): Promise<boolean>;
+    /** 全部成员写成属性声明：端口方法会被**解构出来单独调**（`const { sizeOfDir } = port`，见下方
+     *  模块级递归的注释），实现体一律不读 `this`。方法简写的隐式 `this: FsPort` 会让
+     *  `unbound-method` 把这种正常用法报成可疑；契约（返回的 Promise 形状）一字未动。 */
+    exists: (p: string) => Promise<boolean>;
     /** 建目录（含中间层）。首删时 `~/.dsh/session-trash/` 还不存在，而 `rename` 不建父目录。 */
-    ensureDir(p: string): Promise<void>;
-    rename(from: string, to: string): Promise<void>;
-    removeDir(p: string): Promise<void>;
-    sizeOfDir(p: string): Promise<number>;
+    ensureDir: (p: string) => Promise<void>;
+    /** 搬目录：**目标已存在一律失败**，跨卷（EXDEV）也失败并说清楚——不替换、也不偷偷改成复制。
+     *  Linux 的 `rename` 会静默替代空目录而 Windows 不会，这个差别不能交给操作系统决定。 */
+    rename: (from: string, to: string) => Promise<void>;
+    removeDir: (p: string) => Promise<void>;
+    sizeOfDir: (p: string) => Promise<number>;
     /** 目录下的条目名（**不递归**）。回收站详情要用它在那条目录里挑 `*.jsonl.zstd`。 */
-    listFiles(p: string): Promise<string[]>;
-    /** 目录下的**子目录**名（不递归）。回收站对账用它找出"清单里还没有行"的条目目录——
+    listFiles: (p: string) => Promise<string[]>;
+    /** 目录下的**子目录**名（不递归；**跟随软链**）。回收站对账用它找出"清单里还没有行"的条目目录——
      *  与 `listFiles` 分开是为了让"拒收文件"发生在挑选阶段（回收站根里落进来的杂散文件当外人）。 */
-    listDirs(p: string): Promise<string[]>;
+    listDirs: (p: string) => Promise<string[]>;
+    /** 解析符号链接后的真实路径。递归走目录时防环用：跟随软链之后，目录图不再是树。 */
+    realpath: (p: string) => Promise<string>;
     /** 整个文件读进内存。实测本机回收站里最大单文件 4.66 MB；**内存口径由逐帧解压把住**（见 `src/log/session-log.ts`），不在这里。 */
-    readFile(p: string): Promise<Buffer>;
+    readFile: (p: string) => Promise<Buffer>;
+    /** 只读的单文件读数：附件渲染与独占计划都用它（不递归、不跟随目录）。 */
+    statFile: (p: string) => Promise<{
+        size: number;
+    }>;
+    /** 删单个文件（不是目录）。危险能力，只挂到 `RemovalDeps` 上。 */
+    removeFile: (p: string) => Promise<void>;
 }
+/** 动词的基础面：读与搬移都有，**不拿删除**。删目录与删单文件只挂在 `RemovalDeps` 上（ADR-0027）。 */
+export type CoreFsPort = Omit<FsPort, 'removeDir' | 'removeFile'>;
 export declare function createFsPort(): FsPort;

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

@@ -1,23 +1,12 @@
 /** 摘内存的三种落地（见 {@link HostPort.evictLive}）：`not-live` / `evicted` 都意味着**宿主列表已经不含它**；
  *  `unknown` 意味着读不到或摘不掉，**不能**据此通告客户端（发了就是假话，重连后那一行会自己长回来）。 */
 export type EvictionOutcome = 'evicted' | 'not-live' | 'unknown';
-/**
- * 角色一：**身份与归属**——会话是谁、落在哪个项目/工作区、活不活/归档没有，以及账本与归档的写面。
- *
- * 为什么拆成角色：宿主能力的端口按角色切成三块，而不是一个什么都有的接口。调用方要的是
- * "一句话能说清的那一组能力"，而一个什么都有的端口让每条用例都得凑齐不相干的成员。
- * 这里只切**类型**，adapter 仍是同一颗对象。
- */
+/** 角色一：身份与归属——会话是谁、落在哪个项目/工作区、活不活/归档没有，以及账本与归档的写面。
+ *  只切类型，adapter 仍是同一颗对象。 */
 export interface HostIdentityPort {
     workspaceOf(sessionId: string): Promise<string | undefined>;
-    /** 账本里还有这个工作区吗。**只读的判别**（`registry.get(id) !== undefined`），不抛。
-     *
-     *  **为什么恢复需要它**：宿主的「删除工作区」只删**注册**、保留目录与每一份会话日志
-     *  （asar `WorkspaceRegistry.delete` 的 JSDoc 原文 "Delete one workspace registration while
-     *  retaining its directory and every session log"），那些会话之后显示在「未分组」下。回收站里
-     *  **删在工作区之前**的条目记着那个已被删掉的 `workspaceId`，恢复时若照旧 `attach` 就会
-     *  `workspace not found` 整条失败（会话留在回收站里，用户看起来就是"恢复报错"）。所以恢复
-     *  先问这一句：不在 ⇒ 不挂账本，照常回盘、归入「未分组」（与宿主自己处理这类会话一致）。 */
+    /** 账本里还有这个工作区吗：只读判别，不抛。
+     *  宿主的「删除工作区」只删注册、保留目录与日志；恢复这类会话时跳过 attach，归入「未分组」。 */
     workspaceExists(workspaceId: string): Promise<boolean>;
     /** 会话落盘的**项目目录名**（`<sessions>/<projectKey(cwd)>`）；账本里没有这个会话 ⇒ `undefined`。
      *  与 `workspaceOf` 同一口径：**未命中是正常的 no-op，不是故障**（存储真故障照抛）。 */
@@ -30,9 +19,9 @@ export interface HostIdentityPort {
     unarchive(sessionId: string): Promise<void>;
     detach(sessionId: string, workspaceId: string): Promise<void>;
     attach(sessionId: string, workspaceId: string): Promise<void>;
-    /** 归档是 registry **全局**的，与工作区账目无关 ⇒ `workspaceId` 只是调用点对称用的可选入参
-     *  （未分组的会话没有工作区可传）。 */
-    archive(sessionId: string, workspaceId?: string): Promise<void>;
+    /** 归档是 registry **全局**的，与工作区账目无关 ⇒ 只收 `sessionId`，没有工作区入参
+     *  （实现从不读工作区；未分组的会话同样只有这一条归档路）。 */
+    archive(sessionId: string): Promise<void>;
 }
 /**
  * 角色二：**在场通告**——摘掉宿主内存里的活体，并如实通告客户端"这个会话没了 / 回来了"。
@@ -69,7 +58,7 @@ export type CorpusRead<T> = {
  * 角色三：**会话语料**——整表身份与子会话闭包。
  *
  * 两个读面都把"这一趟看不见语料"写成显式的 {@link CorpusRead}：`{ available: false }` 与
- * "看见了、里面是空的"是两件事。**缺席之后怎么办归调用方，清单见 `CONTEXT.md` 的「语料缺席」**。
+ * "看见了、里面是空的"是两件事。**缺席之后怎么办归调用方，清单见 `docs/architecture.md` §2 的「语料缺席」**。
  */
 export interface HostCorpusPort {
     /** 整个会话语料（live ∪ persisted）的只读身份表。**服务缺席是显式的**：`sessionQuery` 没挂，或它的
@@ -84,50 +73,32 @@ export interface HostCorpusPort {
 }
 /** 复合别名：adapter（`createHostPort`）与调用方把这 15 个方法当一个端口用；三个角色是它的切面。 */
 export type HostPort = HostIdentityPort & HostPresencePort & HostCorpusPort;
+/** 动词的宿主面：身份与语料两片；不含在场三件。摘活体与通告只经 `CoreDeps.presence`（`PresenceCapability`）。
+ *  用交集而不是 `Omit` 黑名单：`HostPresencePort` 将来长出新方法时，不会自动漏进每个动词的 `host`。 */
+export type HostCorePort = HostIdentityPort & HostCorpusPort;
 export interface SessionIdentity {
     readonly sessionId: string;
     readonly parentSessionId?: string;
     readonly projectDir: string;
     readonly subagent: boolean;
 }
+/** 闭包里的一条后代：`sessionId` 是宿主交回的原写法（身份只认它，归一比对交给闭包部件）。 */
 export interface SubagentMember {
     readonly sessionId: string;
     readonly projectDir: string;
 }
-/** 无 cwd 的会话落在 `<sessions>/_no-cwd/`（asar `dsh-session-persistence-jsonl/lib/index.js`
- *  的 `projectDir(root, cwd)`：`if (cwd === void 0) return join(root, "_no-cwd");`）。
- *  `projectDirOf` 与回收站对账（`src/trash/reconcile.ts` 重建条目）共用这一个字面量。 */
+/** 无 cwd 的会话落在 `_no-cwd/`；`projectDirOf` 与回收站对账共用这个字面量。
+ *  出处：asar `dsh-session-persistence-jsonl/lib/index.js` 的 `projectDir`（`if (cwd === void 0) return join(root, "_no-cwd");`）。 */
 export declare const NO_CWD_PROJECT_DIR = "_no-cwd";
-/**
- * 宿主的**项目目录名**算法（`projectKey`）逐字镜像。
- *
- * 为什么是镜像而不是 import：它在 `@deepseek-ai/dsh-session-persistence-jsonl` 里面，是**宿主包**，
- * 跨插件值 import 是生态红线，它也不在本插件依赖里；宿主没有把这个名字暴露成任何服务
- * （`stat()`/`list()` 的返回只有 `{header, revision, sizeBytes}`，`locate()` 的 `{kind:'jsonl', path}` 只挂在错误上）。
- *
- * 原文（asar `dsh/node_modules/@deepseek-ai/dsh-session-persistence-jsonl/lib/index.js`）：
- * `function projectKey(cwd) { … if (ch === "/" || ch === "\\" || ch === ":") { if (!separatorRun) readable += "-"; separatorRun = true; }
- *  else if (ch !== "~" && /^[A-Za-z0-9._-]$/.test(ch)) { readable += ch; separatorRun = false; }
- *  else { readable += "~" + code.toString(16).toUpperCase().padStart(4, "0"); separatorRun = false; }
- *  return \`--${(readable.replace(/^-+/, "") || "root").slice(0, 251)}--\`; }`
- * 调用链：`locate(meta)` → `logPath(root, meta.cwd, meta.id, …)` → `projectDir(root, cwd)` → `projectKey(cwd)`。
- * 本机实测对得上：`D:/develop/GitHub/dsh-session-delete` → `--D-develop-GitHub-dsh-session-delete--`
- * （`~/.dsh/sessions` 下真有这个目录名；`D:/document/deepseek-harness/default-workspace` 同理）。
- *
- * **两个调用方共用这一份**：`projectDirOf`（删除时定位会话目录）与回收站对账的重建路径
- * （手工放进回收站的目录，从日志 header 的 `cwd` 反推它原本属于哪个项目目录）——算法只有这一处家。
- */
+/** 宿主 `projectKey(cwd)` 的逐字镜像：跨插件不能 import，宿主也没把它暴露成服务。
+ *  出处：asar `dsh-session-persistence-jsonl/lib/index.js` 的 `projectKey`；调用链
+ *  `locate` → `logPath` → `projectDir` → `projectKey`。本机实测 `D:/develop/GitHub/dsh-session-delete`
+ *  → `--D-develop-GitHub-dsh-session-delete--`。`projectDirOf` 与回收站对账重建共用这一份；
+ *  宿主换代先复核算法。 */
 export declare function projectKey(cwd: string): string;
-/** 会话 id 去掉 `session-` 前缀后的形状（同一个父在两代里写法不同，见 {@link HostCorpusPort.subagentMembersOf}）。 */
-export declare function bareSessionId(id: string): string;
 /** 这次失败是不是"账本里没那个工作区"（而不是另有故障）。恢复侧靠它把两种失败分开：
  *  前者按「未分组」收，后者照旧回滚报 `io`——不给真故障静默改归属的机会。 */
 export declare function isWorkspaceMissingError(error: unknown): boolean;
-/**
- * 宿主服务层的**真实绑定**：各方法把动词层的问题翻成宿主官方服务的调用。
- *
- * 每个方法的依据（服务 / 方法 / 入参）与原文切片见各自的实现处注释。
- * 出错一律**原样抛**（不在这里裹动词码）：动词层把原始错误挂在 `cause` 上，
- * `toRemoteFailure` 再按 `name` 把它映射回 `sessiondelete/<码>`（src/remote/map-error.ts 的两行映射）。
- */
+/** 宿主服务的真实绑定；出错原样抛，由 `toRemoteFailure` 按 name 映射。
+ *  各方法调用的服务与方法见上方成员注释；错误映射表住 `src/remote/map-error.ts`。 */
 export declare function createHostPort(ctx: unknown): HostPort;

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

@@ -0,0 +1,31 @@
+/**
+ * 在场能力：动词只拿到「成员离场 / 归位 / 一批归位」三条，不再拿到宿主的 `evictLive` / `announce*`。
+ *
+ * 生产实现住 `src/verbs/member-presence.ts`；组合根装配一次，挂在 `CoreDeps.presence`。这样
+ * “谁可以摘活体、谁可以发通告”由依赖面回答，而不是靠源码扫描维持。
+ *
+ * 能力面另带一枚**不导出的品牌字段**：形状对了但没盖章的对象满足不了 `PresenceCapability`
+ * （`tests/deps.test.ts` 钉住）。品牌是类型层的（`declare` 出来的 unique symbol 没有运行时值），
+ * 所以仓内不存在任何能"顺手带上这格"的出口——唯一的盖章处是 `createMemberPresence` 里那一处显式断言。
+ */
+declare const PRESENCE_BRAND: unique symbol;
+export interface MemberBackFacts {
+    readonly diskBack: boolean;
+    readonly workspaceBack: boolean;
+}
+export interface PresenceCapability {
+    /** 品牌字段：值不承载语义，只为让结构相似的手拼对象满足不了这一面——键名是不导出的 unique symbol，
+     *  别的模块连键都写不出来，唯一的盖章处住 `src/verbs/member-presence.ts`。 */
+    readonly [PRESENCE_BRAND]: true;
+    /** 成员已经不在宿主可见列表：摘活体；三态不是 unknown 时发 removed。
+     *  `backInTrash: false` 表示目录没退回回收站（恢复回滚失败），此时什么都不做；`facts` 缺席按
+     *  「正常退回」处理（`createMemberPresence` 的缺省），不再留第三种含义。 */
+    memberGone(sessionId: string, facts?: {
+        readonly backInTrash: boolean;
+    }): Promise<void>;
+    /** 成员已经回到原来的可见状态：目录与账本两件写都回去才发 added。 */
+    memberBack(sessionId: string, facts: MemberBackFacts): Promise<void>;
+    /** 批量恢复的「回来了」通告；单条就是长度为 1 的批。 */
+    announceRestored(ids: readonly string[]): Promise<void>;
+}
+export {};