dsh-plugin-tool-management 0.10.0 → 0.11.0

package/lib/sessions/history.js

@@ -0,0 +1,323 @@
+// 归档会话域（原 index.ts apply() 闭包内六段，2026-09-19 抽出）。
+//
+// 这一域管的是「归档会话的外围」：侧车账本的落点与搬迁、保留期设置、到期清扫、
+// 批量操作目标的校验、归档列表的分组视图。会话本身的归档 / 恢复 / 删除走宿主
+// 注册表（./workspace.ts 的 ArchiveWorkspaceRegistry），这里只做围绕它的记账与投影。
+//
+// 为什么抽出来：这些内容此前散在 apply() 闭包的六个不相邻段落里（1041 / 1093 /
+// 1152 / 1172 / 1683 / 1711），彼此靠闭包隐式共享 `sessions` 实例与侧车路径。抽成
+// 工厂后私有状态（实例、目录存在性缓存）收在内部，只经返回对象的七个出口暴露；
+// 对外依赖（config / pluginRoot / message / ctx）改为显式入参。
+//
+// 一处必须守住的语义：侧车三件套放 hub 根（`$DSH_HOME/tool-management/`）而**不是**
+// 插件目录 —— npm 安装下 `dsh plugin update` 会整体替换插件目录，账本一丢，保留期
+// 基线就从 archivedAt 退回 createdAt，归档会话会被提前清掉。旧位置启动时一次性搬入。
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { hubPath, hubRoot, relocateEntries } from '../hub.js';
+import { ArchiveWorkspaceRegistry as SessionsService, workspaceBaseName, workspacePathKey } from './workspace.js';
+/**
+ * 建归档会话域。副作用（构造注册表实例、首次清扫、挂周期定时器）都在工厂内完成 ——
+ * 它们原本就写在 apply() 的同一位置，语义是「这个服务自己的启动逻辑」，不是组装层的接线。
+ */
+export function createHistoryDomain(deps) {
+    const { ctx, config, pluginRoot, message } = deps;
+    // ---------- independent history facade ----------
+    // Keep the active workspaceRegistry/sessionProjectionCache instances intact.
+    // Native archive extensions are delegated by capability, not package name.
+    // Official gaps use a checked adapter (sessions/bridge.ts); no service or
+    // storage-domain replacement. Retention uses the existing sidecar ledger.
+    // 历史侧车三件套（归档时刻账本 / 保留期设置 / 工作区登记快照）统一放 hub 根
+    // （`$DSH_HOME/tool-management/`），**不放插件目录**：npm 安装下插件目录会被
+    // `dsh plugin update` 整体替换，放那里等于"升级即丢账本"——账本一丢，保留期基线
+    // 就从 archivedAt 退回 createdAt，归档会话会被提前清掉（v0.4 把提示词预设
+    // 搬进 hub 是同一条理由，见上方注释；这三个是当时漏掉的）。
+    // 旧位置（插件目录 data/）在启动时一次性搬入：只搬不删、绝不覆盖、失败下次再试。
+    const historyArchivedAtFile = String(config?.archivedAtFile || hubPath('history-archived-at.json'));
+    const historyWorkspaceSnapshotFile = String(config?.workspaceSnapshotFile || hubPath('history-workspaces.json'));
+    const historyRetentionPath = String(config?.historyRetentionPath || hubPath('history-retention.json'));
+    const historySidecarFiles = new Set(['history-archived-at.json', 'history-retention.json', 'history-workspaces.json']);
+    const historyStandby = relocateEntries(join(pluginRoot, 'data'), hubRoot(), (name) => historySidecarFiles.has(name))
+        .catch(() => 0);
+    const sweepIntervalMs = Number(config?.sweepIntervalMs || 0) || 6 * 60 * 60 * 1000;
+    let sessions;
+    ctx.effect(() => {
+        const registry = ctx.get('workspaceRegistry');
+        if (registry && typeof registry.archiveSession === 'function') {
+            sessions = new SessionsService(ctx, registry, {
+                archivedAtFile: historyArchivedAtFile,
+                workspaceSnapshotFile: historyWorkspaceSnapshotFile,
+                ready: historyStandby,
+            });
+        }
+        return async () => { const current = sessions; sessions = undefined; await current?.dispose(); };
+    }, 'dsh-plugin-tool-management: independent history');
+    function getSessionsRegistry() {
+        return sessions;
+    }
+    /**
+     * 恢复归档后的**归属恢复**（best-effort，绝不阻断恢复本身）：按会话 cwd 找到或重建
+     * 工作区登记，并把会话挂回该登记的 `sessionIds`。恢复成功但归属恢复失败时返回 undefined，
+     * 由客户端按"会话已恢复、工作区归属未恢复"如实呈现。
+     */
+    async function restoreWorkspaceAccounting(sessionIds) {
+        const registry = getSessionsRegistry();
+        if (!registry || typeof registry.ensureWorkspaceAccounting !== 'function' || !sessionIds.length)
+            return undefined;
+        try {
+            return await registry.ensureWorkspaceAccounting(sessionIds);
+        }
+        catch (e) {
+            ctx.logger?.warn?.(`history: workspace accounting after restore failed: ${message(e)}`);
+            return undefined;
+        }
+    }
+    async function readHistoryRetention() {
+        try {
+            await historyStandby;
+            const raw = await readFile(historyRetentionPath, 'utf8');
+            const obj = JSON.parse(raw);
+            const days = Number((obj && obj.retentionDays) ?? 0);
+            const updatedAt = Number((obj && obj.updatedAt) ?? 0);
+            return {
+                retentionDays: Number.isFinite(days) && days >= 0 ? days : 0,
+                updatedAt: Number.isFinite(updatedAt) && updatedAt > 0 ? updatedAt : 0,
+            };
+        }
+        catch {
+            return { retentionDays: 0, updatedAt: 0 };
+        }
+    }
+    async function writeHistoryRetention(retentionDays) {
+        await historyStandby;
+        const dir = dirname(historyRetentionPath);
+        await mkdir(dir, { recursive: true });
+        // updatedAt = 修改时刻：每次改保留期，已归档会话的到期基线重置为此时刻。
+        await writeFile(historyRetentionPath, JSON.stringify({ retentionDays, updatedAt: Date.now() }), 'utf8');
+    }
+    /**
+     * 计算到期应删的归档会话。基线 = max(archivedAt（账本）?? createdAt（元数据),
+     * updatedAt（最近一次修改保留期的时刻）)。改保留期即重置倒计时：到期时刻从
+     * 修改时刻起按新天数重新计算；updatedAt 缺失（旧配置）时退回归档时刻语义。
+     * retentionDays <= 0 表示永久不删除，返回空集。纯函数：便于测试。
+     */
+    /** 一天的毫秒数（保留期按"天"配置，比较按毫秒）。 */
+    const MS_PER_DAY = 24 * 60 * 60 * 1000;
+    function expiredArchivedIds(items, retentionDays, now, updatedAt = 0) {
+        if (!(retentionDays > 0))
+            return [];
+        const cutoff = now - retentionDays * MS_PER_DAY;
+        const out = [];
+        for (const it of items) {
+            const archived = (typeof it.archivedAt === 'number' && Number.isFinite(it.archivedAt))
+                ? it.archivedAt
+                : (typeof it.createdAt === 'number' && Number.isFinite(it.createdAt) ? it.createdAt : undefined);
+            if (archived === undefined)
+                continue;
+            const baseline = updatedAt > 0 ? Math.max(archived, updatedAt) : archived;
+            if (baseline <= cutoff)
+                out.push(it.sessionId);
+        }
+        return out;
+    }
+    async function sweepHistory() {
+        const registry = getSessionsRegistry();
+        if (!registry)
+            return { swept: [] };
+        const { retentionDays, updatedAt } = await readHistoryRetention();
+        if (!(retentionDays > 0))
+            return { swept: [] };
+        try {
+            const details = (typeof registry.archivedSessionDetails === 'function')
+                ? (await registry.archivedSessionDetails()).items
+                : (await registry.archivedSessionMetadata()).items.map((i) => ({ sessionId: i.sessionId, createdAt: i.createdAt, archivedAt: registry.archivedAt?.(i.sessionId) }));
+            const expired = expiredArchivedIds(details, retentionDays, Date.now(), updatedAt);
+            if (expired.length === 0)
+                return { swept: [] };
+            const res = await registry.deleteArchivedSessions({ scope: 'sessions', sessionIds: expired });
+            return { swept: res.deletedSessionIds || [] };
+        }
+        catch (e) {
+            console.error('[dsh-plugin-tool-management] history sweep failed:', message(e));
+            return { swept: [] };
+        }
+    }
+    // 启动时扫一次，再周期复跑。fake-ctx 测试里 ctx.effect 立即调用并 dispose，
+    // interval 未提供时退化为不挂钟（不阻塞测试）。
+    try {
+        void sweepHistory();
+    }
+    catch { /* 非致命 */ }
+    try {
+        ctx.effect(() => {
+            const timer = ctx;
+            const fn = typeof timer.interval === 'function' ? timer.interval : (typeof timer.setInterval === 'function' ? timer.setInterval : undefined);
+            if (!fn)
+                return () => { };
+            return fn(() => { void sweepHistory(); }, sweepIntervalMs);
+        }, 'dsh-plugin-tool-management: history sweep');
+    }
+    catch { /* timer 缺失时静默 */ }
+    // 批量操作目标校验：scope 白名单；sessions 需非空 sessionIds；workspace 需
+    // workspaceId。与 ArchiveWorkspaceRegistry.archivedBatchTargetSchema 语义一致。
+    function parseHistoryBatchTarget(raw) {
+        const t = raw && typeof raw === 'object' ? raw : null;
+        if (!t)
+            return { ok: false, error: '缺少 target' };
+        const scope = t.scope;
+        if (scope !== 'all' && scope !== 'ungrouped' && scope !== 'sessions' && scope !== 'workspace') {
+            return { ok: false, error: 'target.scope 不合法' };
+        }
+        if (scope === 'sessions') {
+            if (!Array.isArray(t.sessionIds) || t.sessionIds.length === 0 ||
+                t.sessionIds.some((id) => typeof id !== 'string' || !String(id).trim())) {
+                return { ok: false, error: 'scope=sessions 需要非空的 sessionIds 数组' };
+            }
+        }
+        if (scope === 'workspace' && !(typeof t.workspaceId === 'string' && String(t.workspaceId).trim())) {
+            return { ok: false, error: 'scope=workspace 需要 workspaceId' };
+        }
+        return {
+            ok: true,
+            target: {
+                scope,
+                ...(scope === 'sessions' ? { sessionIds: t.sessionIds.map((s) => String(s).trim()) } : {}),
+                ...(scope === 'workspace' ? { workspaceId: String(t.workspaceId).trim() } : {}),
+            },
+        };
+    }
+    /**
+     * 归档会话的归属解析（三级，宿主侧算好再给客户端）：
+     *   1. 活登记的 sessionIds 命中            → 组 = 该登记；
+     *   2. 未命中但规范路径命中某活登记        → 组 = 该登记（会话不在其记账里，属正常）；
+     *   3. 没有任何活登记                      → 按会话目录重建分组（`path:<归一化路径>`），
+     *      目录仍在则可一键重新登记（写回宿主），目录已不在则退到 header 里的原始 cwd。
+     * 宿主删除工作区是硬删、不留墓碑，登记一没，`workspaceId` 就再也查不到；但会话目录
+     * （`registry.sessionPaths` / header.cwd）还在，所以归属可以按目录重建、并在目录回来时
+     * 自动并回同一组。除插件自己 `data/` 下的「见过的登记」快照外，本函数不写任何宿主状态。
+     * 任何一步失败都降级为「不分组」，绝不阻断列表。
+     */
+    async function buildHistoryGroups(registry, items) {
+        const groups = [];
+        const workspaces = {};
+        try {
+            const groupsById = new Map();
+            const liveByPath = new Map();
+            const owned = new Map();
+            const liveRecords = [];
+            const table = typeof registry.requireTable === 'function' ? registry.requireTable() : undefined;
+            const state = typeof registry.requireState === 'function' ? registry.requireState() : undefined;
+            if (table) {
+                const ids = state && Array.isArray(state.workspaceIds) && state.workspaceIds.length
+                    ? state.workspaceIds
+                    : [...table.entries()].map(([id]) => id);
+                for (const wid of ids) {
+                    const rec = table.get(wid);
+                    if (!rec || !Array.isArray(rec.sessionIds))
+                        continue;
+                    const path = typeof rec.path === 'string' && rec.path ? rec.path : undefined;
+                    const title = (rec.title && String(rec.title)) || (path ? workspaceBaseName(path) : String(wid));
+                    for (const sid of rec.sessionIds)
+                        if (!owned.has(sid))
+                            owned.set(sid, wid);
+                    if (path) {
+                        liveByPath.set(workspacePathKey(path), wid);
+                        liveRecords.push({ id: String(wid), path, title });
+                    }
+                    const view = { id: 'ws:' + wid, title, kind: 'live', registered: true, ...(path ? { path } : {}) };
+                    groupsById.set(view.id, view);
+                    groups.push(view);
+                    workspaces[wid] = { title, ...(path ? { path } : {}) };
+                }
+            }
+            // 「见过的登记」快照：登记被删后仍能给出原命名，并区分「已移除」与「从未登记」。
+            const snapshot = typeof registry.workspaceSnapshot === 'function' ? await registry.workspaceSnapshot() : undefined;
+            if (liveRecords.length && typeof registry.rememberWorkspaces === 'function') {
+                try {
+                    await registry.rememberWorkspaces(liveRecords);
+                }
+                catch { /* 快照写失败不影响分组 */ }
+            }
+            const sessionPaths = registry.sessionPaths instanceof Map ? registry.sessionPaths : undefined;
+            const headers = registry.headers instanceof Map ? registry.headers : undefined;
+            // 「目录真实存在」检查缓存：canRegister 从「宿主 sessionPaths 命中」放宽为
+            // 「目录存在」时，同一目录只 stat 一次；结果按归一化键缓存，避免每次刷新重复探盘。
+            const dirExistsCache = new Map();
+            async function directoryExists(p) {
+                const k = workspacePathKey(p);
+                const hit = dirExistsCache.get(k);
+                if (hit !== undefined)
+                    return hit;
+                let ok = false;
+                try {
+                    ok = (await stat(p)).isDirectory();
+                }
+                catch {
+                    ok = false;
+                }
+                dirExistsCache.set(k, ok);
+                return ok;
+            }
+            for (const it of items) {
+                const sid = it.sessionId;
+                let wid = owned.get(sid);
+                const canonical = sessionPaths ? sessionPaths.get(sid) : undefined;
+                if (wid === undefined && typeof canonical === 'string' && canonical) {
+                    const byPath = liveByPath.get(workspacePathKey(canonical));
+                    if (byPath !== undefined)
+                        wid = byPath;
+                }
+                if (wid !== undefined) {
+                    it.workspaceId = wid;
+                    it.groupId = 'ws:' + wid;
+                    continue;
+                }
+                let path = typeof canonical === 'string' && canonical ? canonical : undefined;
+                if (path === undefined && it.cwd)
+                    path = it.cwd;
+                if (path === undefined && headers) {
+                    const cwd = headers.get(sid)?.cwd;
+                    if (typeof cwd === 'string' && cwd)
+                        path = cwd;
+                }
+                if (!path)
+                    continue;
+                const key = 'path:' + workspacePathKey(path);
+                it.groupId = key;
+                const known = snapshot ? snapshot.get(workspacePathKey(path)) : undefined;
+                const existing = groupsById.get(key);
+                if (existing) {
+                    // 同目录的多个会话：宿主索引命中，或磁盘目录真实存在，即可重新登记。
+                    if (canonical !== undefined || (await directoryExists(path))) {
+                        existing.canRegister = true;
+                        existing.dirMissing = false;
+                    }
+                    continue;
+                }
+                const canRegister = canonical !== undefined || (await directoryExists(path));
+                const view = {
+                    id: key,
+                    title: known?.title || workspaceBaseName(path) || path,
+                    kind: 'detached',
+                    registered: known !== undefined,
+                    canRegister,
+                    dirMissing: !canRegister,
+                    path: known?.path || path,
+                };
+                groupsById.set(key, view);
+                groups.push(view);
+            }
+        }
+        catch { /* 分组是增强：任何异常都退回扁平列表 */ }
+        return { groups, workspaces };
+    }
+    return {
+        getSessionsRegistry,
+        restoreWorkspaceAccounting,
+        readHistoryRetention,
+        writeHistoryRetention,
+        sweepHistory,
+        parseHistoryBatchTarget,
+        buildHistoryGroups,
+    };
+}

package/lib/{history → sessions}/tombstone.js

@@ -1,7 +1,7 @@
 //#region lib/types/tombstone.js
 /**
  * 通用墓碑簿记：登记一个已删除 id，并按 FIFO 在上限处淘汰最旧项。
- * 工作区注册表（lib/history/workspace.js）在用；淘汰策略集中在这里，避免各处拷贝分叉。
+ * 工作区注册表（lib/sessions/workspace.js）在用；淘汰策略集中在这里，避免各处拷贝分叉。
  */
 /**
  * 登记已删除 id 并执行上限淘汰。

package/lib/{history → sessions}/workspace.js

@@ -1,5 +1,5 @@
 import { lstat, mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import { CapabilityRefusalError, createHistoryBridge, requiredSessionCapabilities } from "./bridge.js";
+import { CapabilityRefusalError, createSessionsBridge, requiredSessionCapabilities } from "./bridge.js";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { hubPath } from "../hub.js";
 import { sessionDir } from "@deepseek-ai/dsh-spill-local";
@@ -13,7 +13,7 @@ import { trackTombstone } from "./tombstone.js";
  * ——全量 grep `archivedSessionDetails` / `deleteArchivedSessions` / `unarchiveSessions`
  * 均不存在，`@michengai/dsh-archive-manager` 也未安装。因此下面所有
  * `typeof this.registry.X === "function"` 的委托分支在当前环境**都是死代码**，
- * 实际执行路径永远是 history/bridge.js 的私有适配（依赖官方声明为 private 的方法，
+ * 实际执行路径永远是 sessions/bridge.ts 的私有适配（依赖官方声明为 private 的方法，
  * 并直接改 registry.headers / sessionPaths / invalidSessionPaths）。
  * 所以「不再替换服务、不再与外部插件争注册」成立，但**不能由此推出耦合下降或零侵入**。
  * 另：改为门面后新增的墓碑 indexHeader 守卫只覆盖本门面的调用；宿主自身的
@@ -128,6 +128,7 @@ const deletedSchema = {
     },
 };
 const archivedBatchTargetSchema = {
+    // 校验通过后原样返回记录，调用方按 scope 判别式收窄（宿主返回值校验器，故返回 any）。
     parse(value) {
         if (typeof value !== "object" || value === null || Array.isArray(value))
             throw new TypeError("target must be an object");
@@ -229,7 +230,14 @@ function defaultWorkspaceSnapshotFile() {
 /**
  * 路径比较键：工作区的唯一性在宿主侧是 realpath 字符串相等（dsh-workspace
  * `realpathNormalize`），Windows 盘符大小写与分隔符拼写却可能不同，因此比较前
- * 先归一化。仅用于**分组与快照索引**，不参与任何写入或归属判定。
+ * 先归一化。
+ *
+ * ⚠ 它不是"只用于分组"：它决定**哪些会话被挂回哪条登记** —— `registerWorkspace` 会调
+ * `attachKnownSessions`，后者按这个键挑选会话并写宿主记账（`sessionIds`）；
+ * `ensureWorkspaceAccounting` 也拿它当去重键后 `host.create` + 挂回。
+ * 而且它比宿主更宽：宿主 `realpathNormalize` 只是 `fs.realpath`（**不做大小写归一**），
+ * 本函数在 Windows 上 `toLowerCase()` ⇒ `C:\Proj` 与 `c:\proj` 在插件里同组、在宿主里
+ * 可以是两条登记。挂回前应以宿主 `resolveByPath` 实际返回的 id 复核，而不是按归一字符串匹配。
  * @param {string} path - 原始路径。
  * @returns {string} 归一化后的比较键（空路径返回空串）。
  */
@@ -263,6 +271,16 @@ function workspaceBaseName(path) {
 // Standalone facade over the existing registry. Never instantiate/register a
 // second WorkspaceRegistry, and never open another copy of its storage domain.
 var ArchiveWorkspaceRegistry = class {
+    /** 宿主注入的上下文（服务读取按动态面处理，见 `HostContext`）。 */
+    ctx;
+    /** 宿主注册表实例；构造期由入参收窄，随后被 bridge 收窄后的实例覆盖。 */
+    registry;
+    /** sessions/bridge.ts 的适配句柄（能力门禁 + 私有接口包装）。 */
+    bridge;
+    /** 账本写入串行链（保证读-改-写不互相覆盖）。 */
+    ledgerTail;
+    /** 删除中的会话 id 集合（防 SUBAGENT 级联自环），首次用到才建。 */
+    deleting;
     /** 本进程内已物理删除的会话；阻止父类把 stale list() 重新编入索引。 */
     deletedSessionIds = /* @__PURE__ */ new Set();
     /** 墓碑插入顺序，用于在上限处淘汰最旧项。 */
@@ -272,8 +290,8 @@ var ArchiveWorkspaceRegistry = class {
     /** 被删生命周期的日志身份（createdAt/cwd）：冷复用探针区分“同 id 新会话”与 stale list() 的依据。 */
     deletedIdentities = /* @__PURE__ */ new Map();
     /** 会话 → 归档时刻（epoch ms）；保留期自动删除的基线。 */
-    archivedAtMap = /* @__PURE__ */ new Map();
-    archivedAtFile = null;
+    archivedAtMap = new Map();
+    archivedAtFile;
     archivedAtLoaded = false;
     /**
      * 「见过的登记」快照：归一化路径 → { path, title, id, at }。
@@ -282,8 +300,8 @@ var ArchiveWorkspaceRegistry = class {
      * 使按目录重建的分组仍能显示用户命名，并能区分「曾经登记过、现在被移除」
      * 与「从未登记过的目录」。只读辅助信息，不参与任何归属判定或写入。
      */
-    workspaceSnapshotMap = /* @__PURE__ */ new Map();
-    workspaceSnapshotFile = null;
+    workspaceSnapshotMap = new Map();
+    workspaceSnapshotFile;
     workspaceSnapshotLoaded = false;
     /** 快照上限：足够覆盖常见工作区数，又避免长驻进程无限增长。 */
     workspaceSnapshotLimit = 200;
@@ -293,7 +311,11 @@ var ArchiveWorkspaceRegistry = class {
      */
     ready = Promise.resolve();
     constructor(ctx, registry, config = {}) {
+        // 注入的 `sessionPersistence` 不在官方 `Context` 声明里（index.ts 的 inject 列表里有它），
+        // 因此这里按本文件的使用面收窄（其余成员仍走官方 `Context`）。
         this.ctx = ctx;
+        // 入参按「官方声明可见的公开面」声明（四个索引 Map 在官方 `WorkspaceRegistry` 里是 private，
+        // 运行时存在且由 bridge 的形状检查兜底），因此此处收窄为本文件实际使用的注册表面。
         this.registry = registry;
         this.archivedAtFile = config.archivedAtFile || defaultArchivedAtFile();
         this.workspaceSnapshotFile = config.workspaceSnapshotFile || defaultWorkspaceSnapshotFile();
@@ -301,7 +323,8 @@ var ArchiveWorkspaceRegistry = class {
             this.ready = Promise.resolve(config.ready).then(() => undefined, () => undefined);
         }
         this.ledgerTail = Promise.resolve();
-        this.bridge = createHistoryBridge(ctx, registry, (id, at) => this.recordArchive(id, at));
+        this.bridge = createSessionsBridge(ctx, registry, (id, at) => this.recordArchive(id, at));
+        // bridge 收窄后的注册表同样只声明运行时形状，这里还原为本文件的注册表面。
         this.registry = this.bridge.registry;
         this.bridge.observe();
     }
@@ -366,6 +389,7 @@ var ArchiveWorkspaceRegistry = class {
         this.archivedAtLoaded = true;
         try {
             const raw = await readFile(this.archivedAtFile, "utf8");
+            // 账本文件由本文件写出（id → epoch ms）；非有限值在下面逐个跳过。
             const obj = JSON.parse(raw);
             if (obj && typeof obj === "object") {
                 for (const [k, v] of Object.entries(obj)) {
@@ -514,6 +538,7 @@ var ArchiveWorkspaceRegistry = class {
                 cwd = header && typeof header.cwd === "string" && header.cwd ? header.cwd : undefined;
             }
             catch (error) {
+                // 宿主/文件系统抛出的错误按动态形状读 message（strict 下 catch 变量为 unknown）。
                 result.skipped.push({ sessionId, reason: `读不到会话头部：${String(error?.message ?? error)}` });
                 continue;
             }
@@ -541,6 +566,7 @@ var ArchiveWorkspaceRegistry = class {
                     result.registered.push(record);
                 }
                 catch (error) {
+                    // 宿主 realpath 拒绝的原始错误按动态形状读 message。
                     entry.failure = `无法解析工作区目录「${cwd}」：${String(error?.message ?? error)}`;
                 }
             }
@@ -560,6 +586,7 @@ var ArchiveWorkspaceRegistry = class {
                     result.attached.push(sessionId);
             }
             catch (error) {
+                // 宿主 attachSession 拒绝原因按动态形状读 message。
                 result.skipped.push({ sessionId, reason: String(error?.message ?? error) });
             }
         }
@@ -596,6 +623,7 @@ var ArchiveWorkspaceRegistry = class {
         const created = entity === undefined;
         if (created)
             entity = await host.create(target, typeof title === "string" && title.trim() ? title.trim() : undefined);
+        // 解析不到即走上面的 create 分支，此后 entity 必定已定义（类型层无法表达该不变式）。
         const record = {
             id: String(entity.id),
             path: String(entity.path ?? target),
@@ -633,6 +661,7 @@ var ArchiveWorkspaceRegistry = class {
                 attached.push(sessionId);
             }
             catch (error) {
+                // 宿主 attachSession 拒绝原因按动态形状读 message。
                 attachSkipped.push({ sessionId, reason: String(error?.message ?? error) });
             }
         }
@@ -917,12 +946,15 @@ var ArchiveWorkspaceRegistry = class {
         }
         return this.enqueueOperation(async () => {
             const requestedSessionIds = this.archivedSessionIdsForTarget(target);
+            // 批首取一次权威快照：批内每一条删除都要一次全库 `listStoredHeaders()`（含逐会话
+            // 读首行），这批复用同一份。取不到就退回逐条取 —— 快照失败不该废掉整批。
+            const storedIndex = await this.storedHeaderIndex().catch(() => undefined);
             const deletedSessionIds = [];
             const skippedSessionIds = [];
             const failures = [];
             for (const sessionId of requestedSessionIds) {
                 try {
-                    await this.deleteSessionCore(sessionId);
+                    await this.deleteSessionCore(sessionId, storedIndex);
                     deletedSessionIds.push(sessionId);
                 }
                 catch (error) {
@@ -963,6 +995,11 @@ var ArchiveWorkspaceRegistry = class {
             // 等待删除期间可能已进入的写回观察到墓碑并完成补删，再允许
             // 同 id 的未来新生命周期写入缓存。
             await projCache.whenIdle?.();
+            // 预留位：宿主**没有** `clearTombstone` 入口（全官方树 grep 零命中），
+            // 所以这里命中的是本插件 `bridge` guard 的墓碑（blocked.delete）——
+            // "已删会话会不会被误复活" 100% 取决于插件自己的两份内存墓碑
+            //（workspace 侧 FIFO-4096 + guard.blocked 无上限），插件重载即全清。
+            // 将来宿主补了 delete+whenIdle 时 bridge 会提前 return，这行才退化成对宿主对象的空转。
             projCache.clearTombstone?.(sessionId);
         }
         await this.cleanSpill(sessionId);
@@ -1017,8 +1054,9 @@ var ArchiveWorkspaceRegistry = class {
         }
         return this.enqueueOperation(() => this.deleteSessionCore(sessionId));
     }
-    /** 串行化后的删除主体（级联路径复用：它已持有操作链，绝不能再入队）。 */
-    async deleteSessionCore(sessionId) {
+    /** 串行化后的删除主体（级联路径复用：它已持有操作链，绝不能再入队）。
+     * @param storedIndex - 可选的批首 `id → header` 快照，见 {@link storedHeaderIndex}。 */
+    async deleteSessionCore(sessionId, storedIndex) {
         if (typeof this.registry.deleteSession === "function")
             return this.registry.deleteSession(sessionId);
         if (this.deleting?.has(sessionId))
@@ -1026,10 +1064,12 @@ var ArchiveWorkspaceRegistry = class {
         this.deleting ??= new Set();
         this.deleting.add(sessionId);
         try {
-            return await this.deleteLocalSession(sessionId);
+            return await this.deleteLocalSession(sessionId, storedIndex);
         }
         catch (error) {
             // Failed deletion must not permanently suppress a still-live session.
+            // （`clearTombstone` 是**预留位**：宿主无此入口，实际命中的是本插件 bridge guard
+            //  的墓碑 —— 说明见 `cleanupUnknownArchivedSession` 里那一处。）
             this.getProjectionCache()?.clearTombstone?.(sessionId);
             throw error;
         }
@@ -1037,8 +1077,8 @@ var ArchiveWorkspaceRegistry = class {
             this.deleting.delete(sessionId);
         }
     }
-    async deleteLocalSession(sessionId) {
-        if (!(await this.sessionKnown(sessionId)))
+    async deleteLocalSession(sessionId, storedIndex) {
+        if (!(await this.sessionKnown(sessionId, storedIndex)))
             throw new ArchiveUnknownSessionError(sessionId);
         const sessions = this.ctx.get("sessions");
         // 快速失败：删掉的顺序（flush → detach → 清缓存 → 删目录 → 清记账）里，
@@ -1061,8 +1101,13 @@ var ArchiveWorkspaceRegistry = class {
             // 持久化屏障先行：不能有未落盘的转录写入与目录删除竞争
             //（持久化后端按批关闭句柄，flush 过的会话不再持有打开的文件）。
             await sessions.flush(live);
-            // 从存储分离；`session/disposed` 同步触发，驱动浏览器端的
-            // `host/session-removed` 帧并启动投影缓存的最终写后落盘。
+            // 从存储分离；`session/disposed` 同步触发（payload 是 **Session 对象**），
+            // 由官方 `dsh-api-session-controller` 降级成 `api-session/removed`（payload 已降为
+            // **SessionId 字符串**）再转发到浏览器，并启动投影缓存的最终写后落盘。
+            // 名字别写成 `host/session-removed` —— 那个帧名在整个已安装树里不存在
+            //（`host/…` 是 cordis 服务/槽位名的前缀，不是线上帧命名空间）。
+            // 注意 `api-session/removed` 也是"发布回滚"与"作用域剪枝"发出的同一事件
+            //（官方 `dsh-session/lib/types/index.d.ts`），所以收到它**不能**等同于"用户删了会话"。
             const entry = sessions.liveEntryFor(live);
             sessions.detachEntered(entry);
         }
@@ -1074,7 +1119,7 @@ var ArchiveWorkspaceRegistry = class {
         await projCache?.whenIdle?.();
         if (projCache !== void 0)
             await projCache.delete(sessionId);
-        await this.deleteDescendants(sessionId);
+        await this.deleteDescendants(sessionId, storedIndex);
         await this.cleanSpill(sessionId);
         await this.removeTranscriptDirectory(sessionId);
         // 只有物理工件删除成功后才能提交记账清理；否则批量目标会因归档标记
@@ -1116,6 +1161,7 @@ var ArchiveWorkspaceRegistry = class {
             this.deletedSessionOrder.splice(idx, 1);
         // workspace 与 projection-cache 共同描述同一删除生命周期；新生命周期
         // 被接纳时必须同步撤销两处墓碑，否则缓存写入仍会永久被拦截。
+        // 右侧那处同样是**预留位**（宿主无 `clearTombstone`，命中的是 bridge guard 的墓碑）。
         this.getProjectionCache()?.clearTombstone?.(sessionId);
     }
     forgetIndexedSession(sessionId) {
@@ -1129,7 +1175,7 @@ var ArchiveWorkspaceRegistry = class {
      * 已删除会话对归档/删除入口都视为未知。实时复用同一 id 时撤墓碑，
      * 避免挡住新会话。
      */
-    async sessionKnown(id) {
+    async sessionKnown(id, storedIndex) {
         if (this.ctx.get("sessions")?.get(id) !== void 0) {
             this.clearTombstone(id);
             return true;
@@ -1137,7 +1183,10 @@ var ArchiveWorkspaceRegistry = class {
         if (this.deletedSessionIds.has(id))
             return this.coldReuseKnown(id);
         // Refresh from authoritative persistence, not the host's stale header cache.
-        const header = (await this.listStoredHeaders()).find((item) => item.id === id);
+        // 批量删除会传入**批首快照**（同一批里 k 次全库 list() 是纯浪费）；不传就是逐条取新鲜数据。
+        const header = storedIndex !== void 0
+            ? storedIndex.get(id)
+            : (await this.listStoredHeaders()).find((item) => item.id === id);
         if (!header)
             return false;
         await this.indexHeader(header);
@@ -1186,6 +1235,19 @@ var ArchiveWorkspaceRegistry = class {
     async listStoredHeaders() {
         return (await this.ctx.sessionPersistence.list()).map((item) => item.header ?? item);
     }
+    /**
+     * `id → header` 索引，供**一次批量操作内部**复用：`listStoredHeaders()` 每次都是
+     * 全库遍历 + 逐会话读首行，批量里逐条调用就是 O(k·n)。
+     *
+     * 只在批内有效 —— 它不随删除自动剔除，也不代表"此刻磁盘上的最新"；需要后者做判据的
+     * 地方（`coldReuseKnown` 的同 id 新生命周期比对）仍然自己取新鲜数据。
+     */
+    async storedHeaderIndex() {
+        const index = new Map();
+        for (const header of await this.listStoredHeaders())
+            index.set(header.id, header);
+        return index;
+    }
     async indexHeaders(items) {
         for (const item of items)
             await this.indexHeader(item.header ?? item);
@@ -1236,6 +1298,7 @@ var ArchiveWorkspaceRegistry = class {
                         stat = await lstat(path);
                     }
                     catch (error) {
+                        // Node 文件系统错误的 code 按动态形状读取（此处只关心 ENOENT）。
                         if (error?.code === "ENOENT")
                             continue; // Already removed on an earlier attempt.
                         throw error;
@@ -1277,6 +1340,7 @@ var ArchiveWorkspaceRegistry = class {
                 sessionIds: current.sessionIds.filter((id) => id !== sessionId),
                 updatedAt: /* @__PURE__ */ new Date().toISOString(),
             }));
+            // 实体快照的形状由宿主 `WorkspaceEntity` 决定（`record` 是私有字段，运行时存在）。
             const entity = this.entities.get(workspaceId);
             if (entity !== void 0)
                 entity.record = next;
@@ -1284,8 +1348,9 @@ var ArchiveWorkspaceRegistry = class {
     }
     /** 尽力而为的级联删除：删除 `sessionId` 的 SUBAGENT 子会话。
      * 仅头部标记 `origin: "subagent"` 的会话参与：单凭 `parentSession` 有歧义
-     *（fork 分支也携带它），而 fork 分支是独立的用户会话，绝不能被级联删除。 */
-    async deleteDescendants(sessionId) {
+     *（fork 分支也携带它），而 fork 分支是独立的用户会话，绝不能被级联删除。
+     * @param storedIndex - 可选的批首 `id → header` 快照，见 {@link storedHeaderIndex}。 */
+    async deleteDescendants(sessionId, storedIndex) {
         try {
             const descendants = [];
             const sessions = this.ctx.get("sessions");
@@ -1295,7 +1360,10 @@ var ArchiveWorkspaceRegistry = class {
                         session.header.origin === "subagent")
                         descendants.push(session.id);
                 }
-            for (const header of await this.listStoredHeaders()) {
+            const headers = storedIndex !== void 0
+                ? [...storedIndex.values()]
+                : await this.listStoredHeaders();
+            for (const header of headers) {
                 if (header.parentSession === sessionId &&
                     header.origin === "subagent" &&
                     !descendants.includes(header.id))
@@ -1303,9 +1371,9 @@ var ArchiveWorkspaceRegistry = class {
             }
             for (const childId of descendants) {
                 try {
-                    if (!(await this.sessionKnown(childId)))
+                    if (!(await this.sessionKnown(childId, storedIndex)))
                         continue;
-                    await this.deleteSessionCore(childId);
+                    await this.deleteSessionCore(childId, storedIndex);
                 }
                 catch (error) {
                     if (error instanceof ArchiveUnknownSessionError)