@xrn1997/dsh-session-delete 0.5.0 → 0.6.1

package/lib/types/client/ui/MenuItemButton.d.ts

@@ -2,7 +2,7 @@
  * `MenuItemButton`（**照抄** `@deepseek-ai/dsh-client-ui-primitives@0.2.0-rc.2` 的同名组件，出处与三条
  * 改写规则见 `ui.css` 头注）：菜单里的一行，宿主菜单容器渲染它、键盘巡游也认它。
  *
- * **形状必须与宿主自己那四行（pin/rename/fork/archive）逐字同构**：`<div class=itemWrap>` 里先是可选
+ * **形状必须与宿主自己的官方菜单行（pin/rename/fork/archive/session-id）逐字同构**：`<div class=itemWrap>` 里先是可选
  * 的发丝线（`role="separator"`），再是 `<button type="button" role="menuitem">`，按钮内是
  * 图标位 + 标签位（+ 官方的快捷键位）。少一层、换个标签，这一行就会在键盘顺序、hover 底色或
  * `.itemLabel` 的省略号上跟邻行错开。

package/lib/types/client/ui/Toast.d.ts

@@ -13,6 +13,7 @@
  * **砍掉的**：`anchor`（把横幅对齐到某个元素的水平中心——本插件的撤销提示就是窗口居中）、
  * `actions[].prefix`（动作文案前的连接词，本插件只用「撤销」两个字）。**没砍 `text`/`icon`/`tone`/
  * `holdMs`/`actions`/`onDone`**：唯一的调用点这几样都在用。
+ * **本插件加的**：`paused`（撤销在飞时冻结停留与淡出，失败原文要落回同一条横幅；官方没有这个开关）。
  */
 import { type ReactElement, type ReactNode } from 'react';
 import './styles.js';
@@ -32,7 +33,9 @@ export interface ToastProps {
     holdMs?: number;
     /** 句尾的行内动作（照着句子的顺序排）。 */
     actions?: readonly ToastAction[] | undefined;
+    /** 暂停自动熄灭：这一趟还有下文（撤销在飞），先把横幅留着——失败原文要靠它上屏。 */
+    paused?: boolean | undefined;
     /** 淡出完成时调用一次：在这里卸载。 */
     onDone: () => void;
 }
-export declare function Toast({ text, icon, tone, holdMs, actions, onDone }: ToastProps): ReactElement;
+export declare function Toast({ text, icon, tone, holdMs, actions, paused, onDone }: ToastProps): ReactElement;

package/lib/types/client/use-trash-panel-controller.d.ts

@@ -43,7 +43,7 @@ export interface TrashPanelController {
     readonly detailNav: DetailNav;
     /** 打开一个孩子（父详情子会话段点进来）：读它的详情，但清单选中不动。 */
     openChild(child: TrashEntryWire): Promise<void>;
-    /** 回到父详情（宽档头部那颗「返回父会话」；窄档 back/Esc 的第一程也走它）。 */
+    /** 回到父详情（详情顶部那颗「返回父会话」；窄档 back/Esc 的第一程也走它）。 */
     closeChild(): void;
     readonly drilled: boolean;
     readonly detail: TrashDetailState;

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

@@ -33,6 +33,9 @@ export declare function firstByBare<N extends ClosureNode>(members: readonly N[]
  * 已被前一组收走的那条，连同它整支子树都不再出现在这一组里——后代在那一组已被全部认领，所以
  * 「丢掉已认领的」与「不走进已认领的那支」交回的是同一个集合。环上的代价是「少数一条」，
  * 不是把一次扫描挂死。组序与成员序都按语料原序。
+ *
+ * 后代也必须是 subagent 起源：普通 fork 的 `parentSession` 只是来源记录，它不进组、也不穿过它收孩子
+ * （否则从 subagent 分出去的分支会被当成孤儿永久删掉）。
  */
 export declare function orphanRootsOf<N extends ClosureNode & {
     readonly parentSessionId?: string;

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)`）。
@@ -7,31 +10,30 @@ export declare const name = "@xrn1997/dsh-session-delete";
  * 三项都是在隔离数据根上实测注入成功、且本插件真正用到的宿主服务。**不进 inject 的**：
  * - `remote`：那是**浏览器半**的服务（asar `dsh-api-gateway/lib/client.js`：`super(ctx, "remote")`），
  *   Node 半挂的是 `ctx.typertGateway`。把它写进 Node 半的 inject 会让插件永远 pending（同 `slots` 那次的形状）。
- * - `sessions` / `sessionProjectionCache`：两者都按 `ctx.get(...)` **可选读**——`sessions` 只给 `evictLive`
- *   用（活跃判据走 waterfall，见 src/ports/host-port.ts；服务缺席回 `unknown`），`sessionProjectionCache` 是标题的尽力读面。
- *   inject 一个可能没挂的服务 = 整个插件 pending。
- *   它取不到时 `titleOf` 返回空串，正是契约允许的降级。
+ * - `sessions` / `sessionProjectionCache` / `sessionPersistence`：都按 `ctx.get(...)` **可选读**——
+ *   `sessions` 给 `evictLive` 和 live header 用（活跃判据走 waterfall，见 src/ports/host-port.ts；
+ *   服务缺席回 `unknown`），`sessionProjectionCache` 是标题的投影读面，`sessionPersistence` 是
+ *   `projectDirOf` / `titleOf` 的公开 header 读面（workspaceRegistry 硬注入它，标准组合必有）。
+ *   inject 一个可能没挂的服务 = 整个插件 pending；标题取不到时 `titleOf` 返回空串，正是契约允许的降级。
  * - `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/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,7 +1,17 @@
+/**
+ * **缺席**只认 ENOENT 与 ENOTDIR（"路径中间有一截不是目录"与"不存在"是同一种回答）。
+ *
+ * EACCES / EIO / ELOOP / 断挂载**不是缺席**：这些读数说明"我们看不见"，不是"那里没有"。
+ * 破坏性动作（删目录、删附件对象、按"没有引用"清共享图）据此做决定，把读不出折成没有
+ * 就是数据消失；ADR-0039 是这条判据的裁决。
+ */
+export declare function isAbsentPath(error: unknown): boolean;
 export interface FsPort {
     /** 全部成员写成属性声明：端口方法会被**解构出来单独调**（`const { sizeOfDir } = port`，见下方
      *  模块级递归的注释），实现体一律不读 `this`。方法简写的隐式 `this: FsPort` 会让
      *  `unbound-method` 把这种正常用法报成可疑；契约（返回的 Promise 形状）一字未动。 */
+    /** 路径在不在。**只有 ENOENT / ENOTDIR 回 `false`**；权限、盘挂、I/O 等读错误照抛——
+     *  调用方拿它当"缺席"判据时，读不出必须是失败，不是"没有"（ADR-0039）。 */
     exists: (p: string) => Promise<boolean>;
     /** 建目录（含中间层）。首删时 `~/.dsh/session-trash/` 还不存在，而 `rename` 不建父目录。 */
     ensureDir: (p: string) => Promise<void>;

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

@@ -9,10 +9,12 @@ export interface HostIdentityPort {
      *  宿主的「删除工作区」只删注册、保留目录与日志；恢复这类会话时跳过 attach，归入「未分组」。 */
     workspaceExists(workspaceId: string): Promise<boolean>;
     /** 会话落盘的**项目目录名**（`<sessions>/<projectKey(cwd)>`）；账本里没有这个会话 ⇒ `undefined`。
-     *  与 `workspaceOf` 同一口径：**未命中是正常的 no-op，不是故障**（存储真故障照抛）。 */
+     *  header 走公开 live/持久化读面；与 `workspaceOf` 同一口径：**未命中是正常的 no-op，不是故障**
+     *  （存储真故障照抛）。 */
     projectDirOf(sessionId: string): Promise<string | undefined>;
     /** 删除时**尽力**取的会话标题；取不到返回空串，绝不因此让删除失败。
-     *  标题只存在于宿主自己的账本/缓存里（`FsPort` 不直读文件）⇒ 取数面归宿主端口，接官方投影缓存 API。 */
+     *  标题只存在于宿主自己的账本/缓存里（`FsPort` 不直读文件）⇒ 取数面归宿主端口，接官方投影缓存 API；
+     *  header 与 `projectDirOf` 走同一个公开读面。 */
     titleOf(sessionId: string): Promise<string>;
     isLive(sessionId: string): Promise<boolean>;
     isArchived(sessionId: string): Promise<boolean>;

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

@@ -6,13 +6,18 @@
  * 信封 {ok:true,value} / {ok:false,error:{code,message,details?}} 也是两半的共同契约。
  */
 /**
- * 插件专属前缀。
+ * 插件专属前缀（九段相对它命名）。
  *
- * 为什么必须带插件名：宿主 web server 的 `register({kind:'prefix', path})` 对**重复的 (kind, path)
- * 直接抛错**（`dsh-host-webserver` 原文 `webserver: duplicate ${route.kind} route "${route.path}"`），
- * 撞了就是整棵插件树 boot 失败——所以这条路径是与生态的硬边界，不是显示好不好看的问题。
+ * 为什么必须带插件名：宿主 `connection.fetch.register` 对**重复的精确路径**直接抛错
+ * （`connection: exact Fetch route "…" is already registered`），撞了就是整棵插件树 boot 失败——
+ * 所以这条路径是与生态的硬边界，不是显示好不好看的问题。
  */
 export declare const SESSION_DELETE_API_PREFIX = "/dsh-session-delete-api";
+/**
+ * 唯一的取数基础路径：宿主 `/api` + 插件前缀。九段 exact Fetch 路由、客户端探测与附件 URL
+ * 都从它起；`SESSION_DELETE_API_PREFIX` 只作为段名的相对前缀与错误原文。
+ */
+export declare const OFFICIAL_SESSION_DELETE_API_PREFIX = "/api/dsh-session-delete-api";
 /** 九个段名（相对前缀）。**每项 `{ path, method }` 两键**：某段用什么方法也是线上形状的一部分
  *  （ADR-0003），家就在这一张表——路由记录（`src/api/route-table.ts`）逐行投影（`ROUTES.x.method`），
  *  浏览器半的 GET 段同样投影、写段把 `ROUTES.x.method` 交给 `src/client/remote.ts` 的 `post()`，
@@ -251,7 +256,8 @@ export interface AttachmentOrphanItemWire {
     bytes: number;
 }
 /** 孤儿附件报告（`GET /attachment-orphans`）：数量、总字节与对象清单。
- *  清单只带 id/bytes（不含路径/文件名），供设置页预览缩略图，最多 200 条；数量与字节按全量算。
+ *  清单只带 id/bytes（不含路径/文件名），供设置页预览缩略图；条数由 Node 半配置
+ *  （`src/config.ts` 的 `orphanPreviewLimit`，默认 200），数量与字节按全量算。
  *  读不出任何一处引用源时**不返回这一形状**，而是 `io` 失败——不拿 0 冒充"没有孤儿"。 */
 export interface AttachmentOrphanReportWire {
     count: number;
@@ -297,6 +303,13 @@ export declare const PARAMS: {
     readonly attachmentId: "id";
     readonly attachmentKind: "kind";
     readonly attachmentName: "name";
+    /** 图片引用的媒体类型 / 宽高：只给宿主 `attachments.readImage` 做引用校验，不参与路径拼接。 */
+    readonly attachmentMediaType: "mediaType";
+    /** 字节数：图片支与文件支都带——它是宿主读面的引用一部分，并先过 `maxAttachmentBytes` 闸
+     *  （别为一张已知超限的图让宿主整份读出来）。 */
+    readonly attachmentBytes: "bytes";
+    readonly attachmentWidth: "width";
+    readonly attachmentHeight: "height";
 };
 /**
  * 失败信封的**线上形状**（本文件）：`code` 是判别依据、`message` 是上屏原文、

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

@@ -1,4 +1,6 @@
+import { isAbsentPath } from '../ports/fs-port.js';
 import type { FsPort } from '../ports/fs-port.js';
+import type { SessionDeleteConfig } from '../config.js';
 import { type AttachmentCleanupWire } from '../shared/wire.js';
 export interface ImageRef {
     kind: 'image';
@@ -21,8 +23,10 @@ export type AttachmentRef = ImageRef | FileRef;
  *  假支若按「是 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;
+/** 路径缺席的判据只有一处：`src/ports/fs-port.ts` 的 `isAbsentPath`（ENOENT / ENOTDIR）。
+ *  `statFile` / `readFile` / `sizeOfDir` 的读错误里，"不在"只认这两枚；权限、盘挂、I/O 错误
+ *  都必须露成读不出（ADR-0039），别在这里另写一份只有 ENOENT 的抄本。 */
+export declare const isMissing: typeof isAbsentPath;
 /** 合法附件 ID → 宿主附件库里的绝对路径。`name` 不参与拼接。 */
 export declare function attachmentPathOf(home: string, kind: 'image' | 'file', id: string): string;
 /** 一条消息的 `content[]` 里的附件块；畸形 id / 非附件段一律跳过。 */
@@ -30,6 +34,7 @@ export declare function attachmentsInContent(content: unknown): AttachmentRef[];
 export interface AttachmentReadDeps {
     fs: Pick<FsPort, 'exists' | 'listFiles' | 'listDirs' | 'readFile' | 'statFile' | 'realpath'>;
     home: string;
+    config: Pick<SessionDeleteConfig, 'maxJsonRefBytes'>;
 }
 export interface AttachmentRemovalDeps extends AttachmentReadDeps {
     fs: Pick<FsPort, 'exists' | 'listFiles' | 'listDirs' | 'readFile' | 'statFile' | 'realpath' | 'removeFile'>;
@@ -65,6 +70,16 @@ export interface ImageRemovalPlan {
  * 剩余引用源读不出 ⇒ 整体跳过；候选日志读不出 / 附件对象 stat 失败 ⇒ 只跳过那一部分，其余照常。
  */
 export declare function planImageAttachmentRemoval(deps: AttachmentReadDeps, removedDirs: readonly string[]): Promise<ImageRemovalPlan>;
+/**
+ * 执行期复核：计划与真删对象之间隔着一整趟目录删除（秒级），这期间别的会话可能把同一张图
+ * （内容寻址 ⇒ 同一个 sha256 id）再引用一次，或派生存储新写一条引用。计划是数据、会过期；
+ * 删对象之前用同一套剩余引用扫描再判一次，**只删这一刻仍无引用的那些**（ADR-0041）。
+ *
+ * 调用时机：会话 / 回收站目录已经删掉之后、`executeImageAttachmentRemoval` 之前——那时被删的
+ * 引用源已经不在了，扫到的就是真正的"剩余"。读不出照旧 fail closed：回空计划 + `skipped`，
+ * 宁可留下孤儿也不删共享。空计划直接返回（不为零删付一次全 home 扫描）。
+ */
+export declare function recheckImageRemovalExclusivity(deps: AttachmentReadDeps, plan: ImageRemovalPlan): Promise<ImageRemovalPlan>;
 /**
  * 逐文件删；ENOENT 由端口的 `force` 吞掉；其他错误计数并继续。
  *

package/lib/types/verbs/errors.d.ts

@@ -21,5 +21,7 @@ export declare function routeError(code: RouteCode, httpStatus: number, message:
 export declare function rollbackReason(label: string, error: unknown): string;
 /** 原错误保留，回滚失败作为 `details.rollbackFailures` 上线；码仍按原错误的动词码，
  *  没有可继承的就落 io。**内层的回滚失败要并进来**：一个成员自己退失败、兄弟也退失败时，
- *  两份失败都得在 details 里，消息也不能出现第二个「回滚未完成」。 */
+ *  两份失败都得在 details 里，消息也不能出现第二个「回滚未完成」。
+ *  **原错误 details 的其余键原样保留**：孤儿清理的部分回执（`removed` / `freedBytes` /
+ *  `failedSessionId`）就挂在它上面，整份替换会把已经发生的删除报成 0。 */
 export declare function withRollbackFailures(error: unknown, failures: readonly string[]): VerbError;

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

@@ -27,8 +27,9 @@ interface RawGroup {
  * 彻底删除（组语义见 `src/trash/groups.ts`），把它的根当孤儿删掉就是**替用户做了一个没人点过的决定**。孤儿只
  * 有一种来路：父被彻底删掉了（或被手工从盘上清掉了），清册里再也没有这一行。
  *
- * 根按**传递闭包**收全部后代（与 `HostCorpusPort.subagentMembersOf` 同一实现：闭包核心住
- * `src/domain/closure.ts` 的 `orphanRootsOf`，孩子与孙代都算，深度不设上限），同一条记录只归一组
+ * 根按**传递闭包**收全部 subagent 后代（与 `HostCorpusPort.subagentMembersOf` 同一实现：闭包核心住
+ * `src/domain/closure.ts` 的 `orphanRootsOf`，孩子与孙代都算，深度不设上限；普通 fork 不是成员、
+ * 也不穿过它收后代），同一条记录只归一组
  * （`claimed`）——数据里真出现环时结果是"少数一条"，不是把一个会话删两遍。
  * 归堆与去重**两边都去 `session-` 前缀**：同一个父在两代宿主里写法不同（见 `bareSessionId` 的来历）。
  */

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

@@ -130,15 +130,20 @@ export declare function planOrphanRemoval(deps: CoreDeps, members: readonly {
  *
  * 顺序：整批摘归档集 → 摘有账本的成员的账本 → 逐条回收站行
  * （在才删目录 → 摘清册行 → 通告成员离场）→ 逐条盘上成员（删目录 → 通告成员离场）→ 逐条附件对象。
- * 目录删掉就没有"退回去"这回事，中途失败**不回滚**；已经删掉的由下面的计数器如实交回。
- *
- * 附件清理排在**所有会话目录删完之后**：对象只在会话真的没了之后才动；单文件失败只进
- * `attachments.failed`，不影响（也不回滚）会话删除的回执。
+ * 目录删掉就没有"退回去"这回事，中途失败**不回滚目录**；已经删掉的由下面的计数器如实交回。
+ * **归档态回滚**：`unarchive` 排在所有删除之前（免得留下"会话没了、归档集还挂着"的幽灵 id），
+ * 所以中途失败时目录还在、归档位却已经摘了。失败出口把**目录还在**的那些（这一趟没删掉、也不是计划时
+ * 就缺席）按删除前的读数重新归档（`isArchived` 先读过一次，不是按 `wasArchived` 猜）；目录不在的跳过
+ * ——那时恢复归档只会造幽灵 id。
+ * 回滚自己的失败走 `details.rollbackFailures`，不让它把原错误吞掉（ADR-0040）。
+ * **附件计划在执行期复核**：计划到删对象之间的窗口里新增的引用会让计划过期；删对象前用同一套
+ * 剩余引用扫描重判一次，只删这一刻仍无引用的对象（ADR-0041）。
  *
  * 失败形状：
  * - `kind:'orphan'`（orphan-clean）⇒ `io` + `{removed, freedBytes, failedSessionId}`，不伪装成整组没动；
  * - `kind:'trash'`（purge）⇒ 同一个标签、不带 details；
- * - orphan-clean 的 unarchive / detach 原样抛出。
+ * - orphan-clean 的归档实况预读 / unarchive / detach 原样抛出；
+ * - 归档态回滚不干净时，原错误带 `details.rollbackFailures`（码仍按原错误的动词码）。
  *
  * 通告只经 `member-presence`（摘活体三态 + `api-session/removed`），不在这里另写一份。
  */

package/locale/en.json

@@ -1,6 +1,6 @@
-{
-  "meta": {
-    "title": "Session Delete",
-    "description": "Delete sessions: delete moves them to a recoverable trash, with an explicit permanent delete."
-  }
-}
+{
+  "meta": {
+    "title": "Session Delete",
+    "description": "Delete sessions: delete moves them to a recoverable trash, with an explicit permanent delete."
+  }
+}

package/locale/zh.json

@@ -1,6 +1,6 @@
-{
-  "meta": {
-    "title": "会话删除",
-    "description": "删除会话：删除 = 移入回收站（可恢复），另设显式的彻底删除。"
-  }
-}
+{
+  "meta": {
+    "title": "会话删除",
+    "description": "删除会话：删除 = 移入回收站（可恢复），另设显式的彻底删除。"
+  }
+}