@xrn1997/dsh-session-delete 0.4.0 → 0.6.0

package/lib/types/client/use-trash-selection.d.ts

@@ -9,22 +9,25 @@ export interface TrashSelection {
     /** 键盘 ↑↓ 与下钻走这个顺序：**只含展开的组**（折叠的行不在 DOM 里，方向键别停过去）。 */
     readonly ordered: readonly TrashEntryLike[];
     readonly allCollapsed: boolean;
-    isCollapsed(projectDir: string): boolean;
-    enterSelect(): void;
-    exitSelect(): void;
-    toggleGroup(projectDir: string): void;
-    toggleAllGroups(): void;
-    toggleCheck(entryId: string): void;
+    /** 方法一律写成**属性声明**：面板会把它们摘下来传给导航/行组件，实现体也都不读 `this`。
+     *  方法简写带来的隐式 `this: TrashSelection` 会让 `unbound-method` 误报，且会诱导调用点
+     *  为了消警报去包箭头函数——那会让 `TrashSelection` 每次渲染换新身份（见 ADR 外的回归教训）。 */
+    isCollapsed: (projectDir: string) => boolean;
+    enterSelect: () => void;
+    exitSelect: () => void;
+    toggleGroup: (projectDir: string) => void;
+    toggleAllGroups: () => void;
+    toggleCheck: (entryId: string) => void;
     /** 组头那颗：说的是"这个项目的全部会话"，折叠起来的条目也算。勾满再点 = 整组取消。 */
-    toggleGroupCheck(group: {
+    toggleGroupCheck: (group: {
         entries: readonly TrashEntryLike[];
-    }): void;
-    groupFullyChecked(group: {
+    }) => void;
+    groupFullyChecked: (group: {
         entries: readonly TrashEntryLike[];
-    }): boolean;
-    groupPartiallyChecked(group: {
+    }) => boolean;
+    groupPartiallyChecked: (group: {
         entries: readonly TrashEntryLike[];
-    }): boolean;
+    }) => boolean;
 }
 export declare function useTrashSelection({ entries, groups, }: {
     entries: readonly TrashEntryLike[] | null;

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

@@ -4,41 +4,57 @@
  * 收尾顺序住 `write-settlement.ts`（ADR-0013），面板的重读策略住 `use-trash-query.ts`；
  * 座位只拥有「这次是谁在写、交哪些材质、闸在哪」。
  *
- * 边界：不判回执、不决定收尾顺序、不拥有各面的本地状态；面板座位的闸由面板传入，不另造第二枚。
+ * 边界：不自己判读回执（verdict 判读住 `receipt.ts`，失败表怎么上屏归各写入面——撤销那一趟的
+ * 横幅改写住 `restoreFromUndo`）、不决定收尾顺序、不拥有各面的本地状态；面板座位的闸由面板传入，
+ * 不另造第二枚；闸挡回来的那一趟**什么都不落地**——座位交回 `undefined`，不伪造 outcome，
+ * 收尾留给在飞的那一趟。
  * 无主子会话清理**不是**座位：它只在插件设置页的维护卡里手动触发（ADR-0021），
  * 读数、闸与重查都归 `use-maintenance.ts`。
  */
+import type { Translate } from './copy.js';
 import type { BusyGate } from './busy-gate.js';
 import type { OneShotDeps, TrashEntryLike } from './remote.js';
+import { type UndoNotice } from './undo-notices.js';
 import { type WriteOutcome } from './write.js';
-/** 会话行菜单的单删座位：一条会话、`single` 读法、成功发单条撤销横幅。交回这条会话的失败原文。 */
+/** 会话行菜单的单删座位：一条会话、`single` 读法、成功发单条撤销横幅。交回这条会话的失败原文。
+ *  三种形状各有意思，不许互相冒充：字符串 = 这一条失败了（原文）；`null` = 跑了、这一条没有失败要说；
+ *  `undefined` = 闸把这一趟挡回来了、什么都没跑（框不收，等在飞那一趟的结论——先收就会把它的失败原文
+ *  落在已经卸载的确认框上）。 */
 export declare function deleteSessionFromMenu(deps: OneShotDeps, input: {
     sessionId: string;
     title: string;
-}, gate: BusyGate): Promise<string | null>;
+}, gate: BusyGate): Promise<string | null | undefined>;
 /** 批量删除座位（宿主会话列表的多选 → 批量确认框）：一次 `/apply`，撤销名单只收 ok 支的条目 id（跟着组走的幂等条不单列）。
- *  只收 id：标题是浮条的呈现，不参与这一次写入。 */
-export declare function deleteSessionsFromBatch(deps: OneShotDeps, ids: readonly string[], gate: BusyGate): Promise<ReadonlyMap<string, string>>;
-/** 外部恢复座位（撤销横幅）：没有 busy 面，不传闸；主视图重开归 settlement，这里只让清单失效。 */
-export declare function restoreFromUndo(deps: OneShotDeps, input: {
-    ids: readonly string[];
-    single: boolean;
-}): Promise<WriteOutcome<'restore'>>;
+ *  只收 id：标题是浮条的呈现，不参与这一次写入。**被闸挡回时交回 `undefined`**——这一趟没跑，
+ *  浮条与确认框都不许照着它收缩名单或关框（那会吞掉在飞那一趟的结果）。 */
+export declare function deleteSessionsFromBatch(deps: OneShotDeps, ids: readonly string[], gate: BusyGate): Promise<ReadonlyMap<string, string> | undefined>;
+/** 外部恢复座位：拥有整趟——ids 组装、runWrite、三种回执形状各改写一次横幅、成功收自己。
+ *  闸在调用方（横幅组件每条通知一枚）；座位不传闸（双套会让外层 busy 提前落）。
+ *  单条与批量都走**一次** `applyOutcomes('restore', ids)`（`runWrite` 判读；单条带 `single: true`，
+ *  null 是协议错）；失败就把原因换到同一条横幅上，不静默。多条逐条失败时横幅要说清**条数与各条
+ *  原因**（原因去重）——只显第一条会把条数与其余原因折没（issue #8 第 5 条）；单条失败仍原文上屏。
+ *  settlement 负责重开删除时被关掉的会话（只认 main-view 自己记过的）并让清单重读；
+ *  座位**不传 `dismissUndo`**——部分失败的回滚会让 settlement 先熄灭横幅，随后 `failNotice` 因
+ *  `ownsNotice` 落空而吞掉失败原文。 */
+export declare function restoreFromUndo(deps: OneShotDeps, notice: UndoNotice, t: Translate): Promise<void>;
 /** 面板两个 `/apply` 座位共用的那一半：依赖、条目 id、闸、重读与缓存失效。 */
 interface PanelWriteInput<A extends 'restore' | 'purge'> {
     deps: OneShotDeps;
     ids: readonly string[];
     gate: BusyGate;
-    refreshAfterWrite(outcome: WriteOutcome<A>): Promise<void>;
-    clearDetailCache(ids: readonly string[]): void;
+    /** 属性声明：这两枚回调被摘下来交给 `runWrite`（转交而不是当方法调），实现不读 `this`。 */
+    refreshAfterWrite: (outcome: WriteOutcome<A>) => Promise<void>;
+    clearDetailCache: (ids: readonly string[]) => void;
 }
 /** 面板恢复另要两样：单条读法，以及 already-gone 回执缺行时反查 sessionId 的当前清单。 */
 interface PanelRestoreInput extends PanelWriteInput<'restore'> {
     single?: boolean;
     entries: readonly TrashEntryLike[] | null;
 }
-/** 面板恢复座位：面板已替这条完成「回来」的结算 ⇒ `panelSeat`；撤销横幅与详情缓存都按落地条目收。 */
-export declare function restoreFromPanel(input: PanelRestoreInput): Promise<WriteOutcome<'restore'>>;
-/** 面板彻底删除座位：永久删除也让指向这些条目的撤销横幅熄灭（settlement 的 purge 支负责）。 */
-export declare function purgeFromPanel(input: PanelWriteInput<'purge'>): Promise<WriteOutcome<'purge'>>;
+/** 面板恢复座位：面板已替这条完成「回来」的结算 ⇒ `panelSeat`；撤销横幅与详情缓存都按落地条目收。
+ *  闸被面板那一趟占着时交回 `undefined`（连点不发第二条），面板照它什么都不改。 */
+export declare function restoreFromPanel(input: PanelRestoreInput): Promise<WriteOutcome<'restore'> | undefined>;
+/** 面板彻底删除座位：永久删除也让指向这些条目的撤销横幅熄灭（settlement 的 purge 支负责）。
+ *  与恢复座位同一条：闸被占着时交回 `undefined`，这一趟不改任何界面后果。 */
+export declare function purgeFromPanel(input: PanelWriteInput<'purge'>): Promise<WriteOutcome<'purge'> | undefined>;
 export {};

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

@@ -37,7 +37,7 @@ export interface SettledFacts<A extends ApplyAction> {
  */
 export type WritePresentationByAction = {
     delete: {
-        /** 外部写入座位：让回收站面板重读。面板写不传（自己的 `refreshAfterWrite` 就是重读）。 */
+        /** 外部写入座位：让回收站面板重读。面板写不传（自己的清单重读 `reload` 不走这条通告）。 */
         invalidate?(): void;
         /** 撤销发布：settlement 从回执摘要取出落地条目 id 与请求名单、组好形之后交来；名单**非空**——
          *  全被同批前一条带走时没有落点，settlement 不发布没有可撤销动作的横幅。座位只决定发布哪一形与那一形带的标题。 */

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

@@ -14,7 +14,8 @@
  * - `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';
@@ -40,7 +41,7 @@ export interface WriteInput<A extends ApplyAction> {
     readonly action: A;
     readonly ids: readonly string[];
     /** 单条写入面：把 N=1 模式交给 receipt 读法（null 折成协议错）。 */
-    readonly single?: boolean;
+    readonly single?: boolean | undefined;
     /** restore 的 already-gone 回执不带行，它的 sessionId 只能由调用方从当前清单里查。 */
     readonly sessionIdOfEntry?: (entryId: string) => string | undefined;
     /** 信封成功时交给 settlement 的呈现材质（摘要里的成功名单可能为空）；按 action 的收尾顺序住 `write-settlement.ts`。 */
@@ -51,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/config.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 可调项（Config，ADR-0037）：三只旋钮 + 本地 Standard Schema。
+ *
+ * 为什么不用 `@deepseek-ai/schemastery` 写 schema：那是宿主包，值 import 会破本仓「跨插件一律
+ * `import type`」的硬约束；Cordis 的 Config 接受 Standard Schema（`@standard-schema/spec`），
+ * 手写这一小段即可，不需要把宿主 schema 库搬进插件。代价是宿主配置页拿不到字段级 JSON Schema
+ * ——配置以 profile 的 `cordis.patch.yml` 为准（README「可调项」有示例）。
+ *
+ * 这里只做**默认值、归一与 schema**，不持有运行期现场：`apply` 归一一次，结果作为
+ * `CoreDeps.config` 注入；读方从自己的 deps 读，不 import 模块级单例。
+ * 客户端 6 秒撤销时长不在这里：它是浏览器半的产品决定，不跨半传。
+ */
+export interface SessionDeleteConfig {
+    /** 设置页维护卡「孤儿附件」预览清单最多列多少条（数量与字节仍按全量报告）。 */
+    readonly orphanPreviewLimit: number;
+    /** `GET /attachment` 单次响应字节上限（服务路径与直接 fs fallback 共用）。 */
+    readonly maxAttachmentBytes: number;
+    /** 附件引用扫描里单个 JSON 引用源的字节上限；超过就按「读不出」fail closed。 */
+    readonly maxJsonRefBytes: number;
+}
+export declare const DEFAULT_CONFIG: SessionDeleteConfig;
+/**
+ * 把 patch 里的 `config` 归一成完整配置：缺省取默认值，未知键 / 非整数 / 越界都抛。
+ * 抛错会让插件激活失败（响亮），而不是悄悄用半套配置跑。
+ */
+export declare function normalizeConfig(value: unknown): SessionDeleteConfig;
+/**
+ * 插件 Config：Cordis 接受 Standard Schema，`~standard.validate` 交回归一后的配置。
+ * 宿主在激活前校验；`apply` 再归一一次（同一份事实，不会漂）。
+ */
+export declare const Config: {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: "dsh-session-delete";
+        readonly validate: (value: unknown) => {
+            value: SessionDeleteConfig;
+            issues?: never;
+        } | {
+            issues: {
+                message: string;
+            }[];
+            value?: never;
+        };
+    };
+};

package/lib/types/deps.d.ts

@@ -1,16 +1,19 @@
 import type { CoreFsPort, FsPort } from './ports/fs-port.js';
 import type { HostCorePort } from './ports/host-port.js';
+import type { AttachmentsPort } from './ports/attachments-port.js';
 import type { PresenceCapability } from './ports/presence-port.js';
+import type { SessionDeleteConfig } from './config.js';
 import type { TrashLedger } from './trash/ledger.js';
 /** Node 半的基础依赖面：组合根只装配这一颗；动词之间不互相 import 依赖面 interface。
  *  `fs` 不含 `removeDir` / `removeFile`，`host` 不含在场三件——两条危险能力各走 {@link RemovalDeps} 与
- *  {@link CoreDeps.presence}。 */
+ *  {@link CoreDeps.presence}。`config` 是 `apply` 归一后的只读快照：读方从 deps 读，不 import 模块级单例。 */
 export interface CoreDeps {
     fs: CoreFsPort;
     host: HostCorePort;
     ledger: TrashLedger;
     home: string;
     presence: PresenceCapability;
+    config: SessionDeleteConfig;
 }
 /** 会话删除动词的依赖面：只多读时钟；它不删目录（回滚只把搬走的搬回）。 */
 export type DeleteSessionDeps = CoreDeps & {
@@ -21,5 +24,7 @@ export type RemovalDeps = CoreDeps & {
     fs: CoreFsPort & Pick<FsPort, 'removeDir' | 'removeFile'>;
 };
 /** 组合根装出的全量面：`/apply` 的分发同时够到删除的时钟与永久删除的 `removeDir` / `removeFile`
- *  （后者也供孤儿附件清理段使用）。 */
-export type DeleteDeps = DeleteSessionDeps & RemovalDeps;
+ *  （后者也供孤儿附件清理段使用）。`attachments` 只给 `attachment` 读段（ADR-0035）；动词不拿它。 */
+export type DeleteDeps = DeleteSessionDeps & RemovalDeps & {
+    readonly attachments: AttachmentsPort;
+};

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

@@ -0,0 +1,47 @@
+/**
+ * 会话闭包（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`：一条记录只归第一个认领它的根。
+ * 已被前一组收走的那条，连同它整支子树都不再出现在这一组里——后代在那一组已被全部认领，所以
+ * 「丢掉已认领的」与「不走进已认领的那支」交回的是同一个集合。环上的代价是「少数一条」，
+ * 不是把一次扫描挂死。组序与成员序都按语料原序。
+ *
+ * 后代也必须是 subagent 起源：普通 fork 的 `parentSession` 只是来源记录，它不进组、也不穿过它收孩子
+ * （否则从 subagent 分出去的分支会被当成孤儿永久删掉）。
+ */
+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

@@ -1,5 +1,8 @@
 import type { Context } from '@deepseek-ai/cordis';
+import { Config } from './config.js';
 export declare const name = "@xrn1997/dsh-session-delete";
+/** 可调项的 Config（Standard Schema）；为什么不用宿主 schema 库见 ADR-0037。 */
+export { Config };
 /**
  * 插件依赖：**只写字符串数组**（隔离数据根上实测：写成 `{ required, optional }` 会让插件停在
  * `pending (waiting for services: required, optional)`）。
@@ -14,24 +17,22 @@ export declare const name = "@xrn1997/dsh-session-delete";
  * - `agents`：只给 handle 捕获用（`ctx.get('agents')`；缺席时 `ctx.inject(['agents'])` 等服务就绪再装）。
  *   它同样可能晚于本插件激活，写进插件 inject 只会让整个插件 pending。
  *
- * `webServer` 是**浏览器半取数通道的承载者**（那条薄线）：插件用它注册 `/dsh-session-delete-api`
- * 前缀路由，浏览器半同源 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。
+ * `connection` 是浏览器半取数通道的唯一承载者：九段注册到 `connection.fetch.register` 的
+ * `/api/dsh-session-delete-api/*`，Host/Origin/浏览器认证由宿主 `/api` bridge 完成（ADR-0033）。
+ * 支持面是 web UI 与桌面端，二者的标准组合都装 `client-connection`；服务缺席时插件停在 pending
+ * ——可见的激活失败，而不是静默地没有入口。`webServer` 不再直接使用：exact route 仍由宿主的
+ * `connection` 挂在其 `/api` 前缀上，插件不需要自己碰物理服务器。
  *
  * 清册的三层各有各的家：raw 绑定 `src/trash/storage-manifest.ts`、读面（对账 + 读）`src/trash/ledger.ts`、
  * 数据根 `src/ports/home.ts`。这里只把它们接起来，任何一层都不在组合根里长判据。
  */
 export declare const inject: string[];
 /**
- * 装配顺序：**清单 → 端口 → 在场能力 → 动词依赖 → 前缀路由**（`DeleteDeps` 把这些依赖面合成一颗）。
+ * 装配顺序：**配置归一 → 清单 → 端口 → 在场能力 → 动词依赖 → 分发器 → exact Fetch 路由**
+ * （`DeleteDeps` 把这些依赖面合成一颗；`config` 是归一后的只读快照）。
  *
  * 路由用 `ctx.effect` 挂、disposer 归装载它的那根 fiber：插件卸载即摘路由（`register` 返回的
- * disposer 是官方契约）。**同一进程里只注册一次**这件事由宿主把住：重复的 `(kind, path)`
- * 在 `register` 里直接抛（`webserver: duplicate prefix route "…"`），响亮失败而不是悄悄覆盖。
+ * disposer 是官方契约）。**同一进程里只注册一次**这件事由宿主把住：重复的 `(path, method)`
+ * 在 `connection.fetch.register` 里直接抛，响亮失败而不是悄悄覆盖。
  */
-export declare function apply(ctx: Context): void;
+export declare function apply(ctx: Context, rawConfig?: unknown): void;

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

@@ -20,9 +20,8 @@
  * 的 zstd 版本（明文一大、FCS 上到 4 字节的 `0xa0` 就会算错），帧就切歪，会话日志直接读不出来。
  *
  * **尾巴那 4 字节按实测判据收，不按 descriptor 的 bit2**：规则是「跳过去必须正好撞上下一帧的 magic
- * 或到 EOF」——猜错不会静默切歪：末尾的自证与块界护栏会抛（护栏是必需的：块头越界时 `|` 读回 0，
- * 而 0 的 `Last_Block` 位没置位，少了它块循环每圈只 +3 字节却永不 break，整个进程会卡死；
- * 用例覆盖这一条）。
+ * 或到 EOF」——猜错不会静默切歪：末尾的自证与块界护栏会抛（护栏是必需的：块头可能被文件截断，
+ * 不抛的话块循环每圈只 +3 字节却永不 break，整个进程会卡死；用例覆盖这一条）。
  */
 export interface FrameRange {
     start: number;

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

@@ -0,0 +1,40 @@
+/**
+ * 宿主 `attachments` 服务的窄镜像（ADR-0035）：只声明本插件读取附件用到的两条。
+ *
+ * - 服务是**可选**的：`ctx.get('attachments')` 每次调用现查（服务可能晚于插件激活），
+ *   `available()` 为假时调用方退回旧的直接 fs 路径。
+ * - `readImage` 会按记录里的引用**校验字节**；`readFileStream` 校验并分块读出。
+ *   两者都不在本文件里重写校验逻辑。
+ * - 不 import 宿主 `attachments` 服务的类型包：形状按该服务的运行期契约抄成窄镜像。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export type ImageMediaTypeLike = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
+export interface ImageAttachmentRefLike {
+    readonly attachmentId: string;
+    readonly mediaType: ImageMediaTypeLike;
+    readonly bytes: number;
+    readonly width: number;
+    readonly height: number;
+    readonly name?: string;
+}
+export interface FileAttachmentRefLike {
+    readonly attachmentId: string;
+    readonly name: string;
+    readonly bytes: number;
+}
+export interface StoredImageAttachmentLike {
+    readonly ref: ImageAttachmentRefLike;
+    readonly data: Uint8Array;
+}
+export interface AttachmentsPort {
+    /** 服务在场且成员形状可用；调用方用它决定走服务还是直接 fs。 */
+    available(): boolean;
+    readImage(ref: ImageAttachmentRefLike): Promise<StoredImageAttachmentLike>;
+    readFileStream(ref: FileAttachmentRefLike): AsyncIterable<Uint8Array>;
+}
+/** 服务在 `available()` 之后消失/形状变了：调用方可以退回直接 fs，而不是把这次读取判成 io。 */
+export declare class AttachmentsUnavailableError extends Error {
+    constructor(message?: string);
+}
+/** 每次调用惰性解析服务：插件与 `attachments` 的激活顺序没有承诺。 */
+export declare function createAttachmentsPort(ctx: Context): AttachmentsPort;

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

@@ -1,28 +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>;
+    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>;
+    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>;
+    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<{
+    statFile: (p: string) => Promise<{
         size: number;
     }>;
     /** 删单个文件（不是目录）。危险能力，只挂到 `RemovalDeps` 上。 */
-    removeFile(p: string): Promise<void>;
+    removeFile: (p: string) => Promise<void>;
 }
-/** 动词的基础面：读与搬移都有，**不拿删除**。删目录与删单文件只挂在 `RemovalDeps` 上（ADR-0006）。 */
+/** 动词的基础面：读与搬移都有，**不拿删除**。删目录与删单文件只挂在 `RemovalDeps` 上（ADR-0027）。 */
 export type CoreFsPort = Omit<FsPort, 'removeDir' | 'removeFile'>;
 export declare function createFsPort(): FsPort;

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

@@ -19,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>;
 }
 /**
  * 角色二：**在场通告**——摘掉宿主内存里的活体，并如实通告客户端"这个会话没了 / 回来了"。
@@ -82,6 +82,7 @@ export interface SessionIdentity {
     readonly projectDir: string;
     readonly subagent: boolean;
 }
+/** 闭包里的一条后代：`sessionId` 是宿主交回的原写法（身份只认它，归一比对交给闭包部件）。 */
 export interface SubagentMember {
     readonly sessionId: string;
     readonly projectDir: string;
@@ -95,8 +96,6 @@ export declare const NO_CWD_PROJECT_DIR = "_no-cwd";
  *  → `--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;

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

@@ -3,12 +3,20 @@
  *
  * 生产实现住 `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` 的缺省），不再留第三种含义。 */
@@ -20,3 +28,4 @@ export interface PresenceCapability {
     /** 批量恢复的「回来了」通告；单条就是长度为 1 的批。 */
     announceRestored(ids: readonly string[]): Promise<void>;
 }
+export {};