dsh-plugin-tool-management 0.10.0 → 0.12.0

package/lib/scene-prompt-sync.js

@@ -127,7 +127,7 @@ export function createScenePromptSync(deps) {
             warn(`scene-prompt: refs probe (scenes) failed: ${String(e)}`);
         }
         try {
-            const cur = await deps.agentsMd.getCurrent();
+            const cur = await deps.prompts.getCurrent();
             if (!cur || cur.ok !== true)
                 complete = false;
             else if (cur.presetId)
@@ -159,7 +159,7 @@ export function createScenePromptSync(deps) {
             // 基线始终是"进场景之前"那一份）。
             const saved = await readBaseline();
             if (!saved || saved.content === null) {
-                const cur = await deps.agentsMd.getCurrent();
+                const cur = await deps.prompts.getCurrent();
                 await writeBaseline({
                     v: 1,
                     at: Date.now(),
@@ -167,7 +167,7 @@ export function createScenePromptSync(deps) {
                     content: cur && cur.ok && cur.exists ? String(cur.content) : null,
                 });
             }
-            const res = await deps.agentsMd.apply(current.presetId);
+            const res = await deps.prompts.apply(current.presetId);
             if (res && res.ok === false)
                 return { error: String(res.error || '写入 AGENTS.md 失败') };
             return { applied: current.presetId };
@@ -176,7 +176,7 @@ export function createScenePromptSync(deps) {
         const saved = await readBaseline();
         if (!saved || saved.content === null)
             return { unchanged: true };
-        const res = await deps.agentsMd.restore(saved.content);
+        const res = await deps.prompts.restore(saved.content);
         if (res && res.ok === false)
             return { error: String(res.error || '恢复 AGENTS.md 失败') };
         await writeBaseline({ v: 1, at: Date.now(), presetId: null, content: null });

package/lib/scenes/candidates.js

@@ -0,0 +1,344 @@
+// 场景 / 表单的**候选源** —— 界面要"选一个"的地方，数据从哪来。
+//
+// 2026-09-19 从 index.ts 的 apply 闭包原样抽出（10 段，约 260 行）。为什么单独一个文件：
+// 这些函数是**只读的取数**，彼此只有缓存关系，与"写补丁 / 改场景"完全无关；此前散在
+// apply 闭包的四个角落（286 / 425 / 532 / 833 / 1924-2133），改一处要在 3000 行里找。
+//
+// 三组候选，各自的失效模式不同：
+//   * **技能 / 记忆 / 场景**（skillRows / memoryCandidates / memorySceneCandidates）——
+//     直接读各自 service 的 op，无缓存；
+//   * **预设工具**（presetToolCandidates / presetToolNames）—— 枚举会为预设建立 standing
+//     mount（官方语义：每进程一次），所以按 PRESET_ENUM_CACHE_MS 缓存，不能每次重枚举；
+//   * **模型**（modelCandidates）—— 只读宿主 LLM 目录，**不发网络请求**。
+//
+// 依赖全部经 deps 显式传入。注意 \`toolKeyParts\` 留在 index.ts：场景档案引擎也在用它，
+// 放进本文件会让两个域互相引用。
+import { presetRosterOf } from '../compat/preset-reach.js';
+import { injectionFactsOf, readCompositionFacts } from '../compat/preset-reach.js';
+export function createCandidates(deps) {
+    // 外部能力一次解构成局部名：块内代码逐字搬来，保持原样最不容易出错。
+    const { get, tools, mcp, skillsService, memoriesService, toolKeyParts } = deps;
+    const ctx = { get };
+    // Agent 预设名单（@deepseek-ai/dsh-agent-presets）：同样是可选服务，按需取用。
+    // 读它只为了回答"当前预设下本插件注入的东西到不到得了模型"——只读，不挂载任何预设。
+    const presetRoster = () => presetRosterOf(ctx);
+    async function toolStates() {
+        const disabled = await mcp.readDisabledTools();
+        const states = {};
+        let schemas = [];
+        try {
+            schemas = await tools.schemas();
+        }
+        catch { /* 无 live 工具 → 仅启停表 */ }
+        const liveByServer = {};
+        for (const s of schemas) {
+            const p = toolKeyParts(String((s && s.name) || ''));
+            if (!p)
+                continue;
+            const list = liveByServer[p.server] || (liveByServer[p.server] = []);
+            if (list.indexOf(p.tool) < 0)
+                list.push(p.tool);
+        }
+        for (const [server, list] of Object.entries(disabled)) {
+            // 整台停用（['*']）：在 live 工具上展开成具体键，不产出 `server/*` 伪键（那会污染勾选器）。
+            if (list.indexOf('*') >= 0) {
+                for (const t of (liveByServer[server] || []))
+                    states[server + '/' + t] = false;
+                continue;
+            }
+            for (const t of list)
+                states[server + '/' + t] = false;
+        }
+        for (const [server, list] of Object.entries(liveByServer)) {
+            for (const t of list)
+                if (!(server + '/' + t in states))
+                    states[server + '/' + t] = true;
+        }
+        return states;
+    }
+    /**
+     * 场景档案「技能集」的技能行 —— 技能名与来源名**分开**给出。
+     *
+     * 界面早先直接渲染 `key`（形如 `<来源 key>/<技能名>`），而自定义目录的来源 key 是
+     * `custom-<sha256-16>`，于是导入的技能在场景档案里显示成一串哈希（用户 2026-09-15 报的）。
+     * 这里把来源的 label / localeKey 一并带上，界面就能显示「技能名 · 来源名」。
+     *
+     * 含被覆盖的副本（`shadowed`）：场景允许勾选任意一条技能，用生效集校验会把合法勾选判成 stale。
+     */
+    async function skillRows() {
+        const rows = [];
+        try {
+            const r = await skillsService.ops['skill-state']({});
+            for (const root of ((r && r.data && r.data.roots) || [])) {
+                const rootKey = String((root && root.key) || '');
+                if (!rootKey)
+                    continue;
+                for (const sk of ((root && root.skills) || [])) {
+                    const name = String((sk && (sk.declaredName || sk.name)) || '');
+                    if (!name)
+                        continue;
+                    rows.push({
+                        key: rootKey + '/' + name,
+                        name,
+                        enabled: sk.enabled === true && !sk.shadowedBy,
+                        shadowed: !!sk.shadowedBy,
+                        loadable: sk.loadable !== false,
+                        rootKey,
+                        rootLabel: String((root && root.label) || rootKey),
+                        ...(root && root.localeKey ? { rootLocaleKey: String(root.localeKey) } : {}),
+                        ...(root && root.kind ? { rootKind: String(root.kind) } : {}),
+                    });
+                }
+            }
+        }
+        catch { /* 技能状态读不到 → 空列表（界面如实显示"没有可选项"） */ }
+        // 平铺列表按技能名排（同名再按来源），比按来源聚在一起更好找。
+        return rows.sort((a, b) => a.name.localeCompare(b.name) || a.rootKey.localeCompare(b.rootKey));
+    }
+    // 注入判定要的两条预设事实（压制型？挂得到 AGENTS.md 通道？）。读取走 TTL 缓存：
+    // 组合文件可以随时被编辑（patchReload: live），但每个 step 读一次盘没有必要。
+    const PRESET_FACTS_TTL_MS = 15_000;
+    const presetFactsCache = new Map();
+    async function presetFactsForAgent(agent) {
+        const roster = presetRoster();
+        if (!roster || typeof roster.composedPreset !== 'function' || typeof roster.read !== 'function')
+            return undefined;
+        let presetId = '';
+        try {
+            presetId = String(roster.composedPreset(agent?.ctx) ?? '');
+        }
+        catch {
+            return undefined;
+        }
+        if (presetId === '')
+            return undefined;
+        const hit = presetFactsCache.get(presetId);
+        if (hit && Date.now() - hit.at < PRESET_FACTS_TTL_MS)
+            return hit.value;
+        try {
+            const text = String((await roster.read(presetId)) ?? '');
+            const value = injectionFactsOf(readCompositionFacts(text));
+            presetFactsCache.set(presetId, { at: Date.now(), value });
+            return value;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * 记忆候选（档案编辑器第 4 段「记忆」）：`[{ id, scene, name, description }]`。
+     * 只读、不读正文（勾选集只存 id）；任何异常降级为空列表，不让档案弹窗崩掉。
+     */
+    async function memoryCandidates() {
+        try {
+            const r = await memoriesService.ops['rules-list']({});
+            if (!r || r.ok === false)
+                return [];
+            return (r.rules || [])
+                .filter((x) => !x.shadowed)
+                .map((x) => ({
+                id: String(x.id),
+                scene: String(x.group || ''),
+                name: String(x.name || ''),
+                description: String(x.description || ''),
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+    /** 场景候选（档案编辑器第 4 段的分组维度）：`[{ name, label, description, count, global }]`。 */
+    async function memorySceneCandidates() {
+        try {
+            const r = await memoriesService.ops['rules-list']({});
+            if (!r || r.ok === false)
+                return [];
+            return (r.scenes || []).map((s) => ({
+                name: String(s.name),
+                label: String(s.label || s.name),
+                description: String(s.description || ''),
+                count: Number(s.count || 0),
+                global: s.global === true,
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * 工具候选（人设的「工具白名单 / 黑名单」选择器）：
+     * 取**全体 Agent 预设工具名的并集**——人设可能在任意预设下被子代理复用，
+     * 只列当前会话的工具会让换预设后的子代理启动失败（官方 `toolFilter` 对未知名直接拒绝）。
+     * 同时标注 `current`：当前会话可见的工具（其余只是「本预设可用，当前会话看不到」）。
+     *
+     * 每次调用都会为尚未挂载的预设建立 standing mount（官方语义：一个预设在本进程内只挂一次，
+     * 正常创建会话时同样会挂），因此结果会按需缓存 PRESET_ENUM_CACHE_MS，避免频繁枚举。
+     */
+    // 两个预设枚举缓存（全体候选 / 单个预设）共用这个 TTL：枚举的代价是"给预设建立
+    // standing mount"，与内容变化无关，所以只要别刷得太勤就行。
+    const PRESET_ENUM_CACHE_MS = 60_000;
+    let presetToolsCache = null;
+    async function presetToolCandidates() {
+        if (presetToolsCache && Date.now() - presetToolsCache.at < PRESET_ENUM_CACHE_MS)
+            return presetToolsCache.value;
+        const byName = new Map();
+        const presets = [];
+        // 当前会话的可见工具（用于标 current）；拿不到就全部按「非当前」处理。
+        const currentNames = new Set();
+        try {
+            const schemas = await tools.schemas();
+            for (const s of schemas || [])
+                currentNames.add(String(s.name));
+        }
+        catch { /* 无 live 工具 → current 全 false */ }
+        const agentPresets = (typeof ctx.get === 'function' ? ctx.get('agentPresets') : undefined);
+        if (agentPresets && typeof agentPresets.list === 'function') {
+            try {
+                // roster 顺序 = 官方的展示顺序（preset.yml 的 order：标准 1 / PTC 2 / 极简 3 / 创造 4，
+                // 自建预设排在其后）。人设编辑器的四行照抄这个顺序，**不要**再按 id 排序。
+                const roster = await agentPresets.list();
+                for (const p of roster || []) {
+                    const id = String((p && p.id) || '');
+                    if (!id)
+                        continue;
+                    // MCP 工具名形如 `mcp__<server>__<tool>`：面向上百个条目，噪声大于价值 → 不进候选。
+                    // 子代理照样能用当前在跑的 MCP —— 那份名单在 decideToolFilter 里运行时并进白名单。
+                    const names = (await presetToolNames(id)).filter((name) => !name.startsWith('mcp__'));
+                    presets.push({
+                        id,
+                        name: String((p && (p.name || p.id)) || id),
+                        trust: String((p && p.trust) || 'user'),
+                        broken: typeof (p && p.broken) === 'string',
+                        tools: names,
+                    });
+                    for (const name of names) {
+                        const rec = byName.get(name) || { name, presets: new Set(), current: false };
+                        rec.presets.add(id);
+                        byName.set(name, rec);
+                    }
+                }
+            }
+            catch { /* 预设服务不可用 → 退回「仅当前会话工具」 */ }
+        }
+        // 当前会话的工具即便没有任何预设可枚举，也要出现在候选里（否则选择器是空的）。
+        for (const name of currentNames) {
+            if (name.startsWith('mcp__'))
+                continue;
+            const rec = byName.get(name) || { name, presets: new Set(), current: false };
+            byName.set(name, rec);
+        }
+        for (const rec of byName.values())
+            rec.current = currentNames.has(rec.name);
+        const value = {
+            tools: [...byName.values()]
+                .map((r) => ({ name: r.name, presets: [...r.presets].sort(), current: r.current }))
+                .sort((a, b) => a.name.localeCompare(b.name)),
+            // 保持 roster 顺序（官方的展示顺序），前端四行直接照用。
+            presets,
+        };
+        presetToolsCache = { at: Date.now(), value };
+        return value;
+    }
+    /**
+     * 单个预设的工具名（列表里含 MCP 与宿主平面的工具，因为子代理的可见集合是
+     * "宿主平面 ∪ 该预设"的并集）。枚举会为该预设建立 standing mount —— 官方语义：
+     * 一个预设每进程只挂一次，正常创建会话时同样会挂，所以这里按 id 缓存 PRESET_ENUM_CACHE_MS；
+     * `subagent_manager_run` 每次委派都要用它校验名单，不能每次都重新枚举。
+     */
+    const presetNamesCache = new Map();
+    async function presetToolNames(id) {
+        const hit = presetNamesCache.get(id);
+        if (hit && Date.now() - hit.at < PRESET_ENUM_CACHE_MS)
+            return hit.names;
+        const agentPresets = (typeof ctx.get === 'function' ? ctx.get('agentPresets') : undefined);
+        let scopeKey;
+        try {
+            scopeKey = agentPresets && typeof agentPresets.standingKeyFor === 'function'
+                ? await agentPresets.standingKeyFor(id)
+                : undefined;
+        }
+        catch {
+            scopeKey = undefined;
+        }
+        let names = [];
+        try {
+            names = ((await tools.schemas(scopeKey)) || []).map((s) => String(s.name)).filter(Boolean);
+        }
+        catch {
+            names = [];
+        }
+        presetNamesCache.set(id, { at: Date.now(), names });
+        return names;
+    }
+    /** 预设名单的名字投影（只读 roster，不挂载任何预设）：场景页显示模式名用。 */
+    async function presetNames() {
+        const agentPresets = (typeof ctx.get === 'function' ? ctx.get('agentPresets') : undefined);
+        if (!agentPresets || typeof agentPresets.list !== 'function')
+            return [];
+        try {
+            const roster = await agentPresets.list();
+            return (roster || [])
+                .map((p) => ({ id: String((p && p.id) || ''), name: String((p && (p.name || p.id)) || ''), trust: String((p && p.trust) || 'user') }))
+                .filter((p) => p.id !== '');
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * 模型候选（人设的「模型」下拉）：宿主已注册的 provider + 各 provider 能宣告的模型。
+     * 只读宿主 LLM 目录，**不发起网络请求**（`discoverModels` 会打端点，这里不用）；
+     * 拿不到就返回空列表，UI 退回手填（跨来源模型如 sensenova 的手工条目仍需手填兜底）。
+     * 返回扁平列表：DSH 的模型路由是 (provider, model) 一对，两个键必须同时给。
+     */
+    async function modelCandidates() {
+        const llm = (typeof ctx.get === 'function' ? ctx.get('llm') : undefined);
+        if (!llm || typeof llm.listProviders !== 'function')
+            return { models: [] };
+        let list = [];
+        try {
+            list = llm.listProviders() || [];
+        }
+        catch {
+            return { models: [] };
+        }
+        const models = [];
+        const seen = new Set();
+        for (const p of list) {
+            const provider = String((p && (p.id || p.provider)) || '');
+            if (!provider)
+                continue;
+            const providerName = String((p && (p.name || p.displayName)) || provider);
+            let discovered = [];
+            try {
+                // 适配器可选提供 listModels（官方 LlmAdapter 契约）；未提供时该 provider 只报名字。
+                if (typeof llm.listModels === 'function')
+                    discovered = (await llm.listModels(provider)) || [];
+            }
+            catch { /* 该 provider 的目录读失败 → 只报 provider 本身 */ }
+            for (const m of discovered) {
+                const id = String((m && (m.id || m.model)) || '');
+                if (!id)
+                    continue;
+                const key = provider + '\u0000' + id;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                models.push({ provider, providerName, id, name: String((m && m.name) || id) });
+            }
+        }
+        return { models };
+    }
+    return {
+        presetRoster,
+        presetFactsForAgent,
+        toolStates,
+        skillRows,
+        presetToolCandidates,
+        presetToolNames,
+        presetNames,
+        modelCandidates,
+        memoryCandidates,
+        memorySceneCandidates,
+    };
+}

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

@@ -1,6 +1,7 @@
 import { symbols } from "@deepseek-ai/cordis";
 import { workspaceDomainSpec } from "@deepseek-ai/dsh-workspace";
 import { assessHost, routeFor, refusalsFor, CapabilityRefusalError } from "../compat/probe.js";
+import { noteRuntime } from "../compat/runtime-notes.js";
 export { CapabilityRefusalError };
 // No Service subclass, no ctx.provide(), no second storage-domain owner.
 // The official API lacks unarchive and a cache deletion barrier, so this file
@@ -17,7 +18,11 @@ export { CapabilityRefusalError };
 // 禁令针对的对象（包文件与宿主机制的永久改写）不同层。若用户裁定该解释不成立，
 // 撤掉 acquire/releaseCacheGuard 即可整体退回「无删除屏障」的降级形态。
 const cacheGuards = new WeakMap();
-const raw = (value) => value?.[symbols.original] ?? value;
+const raw = (value) => {
+    // cordis 的 traceable 代理在 [symbols.original] 上挂原始对象；无代理时原样返回
+    const holder = value;
+    return holder?.[symbols.original] ?? value;
+};
 const sameLifecycle = (a, b) => a && b && a.createdAt === b.createdAt && (a.cwd ?? null) === (b.cwd ?? null);
 /**
  * Install the write barrier around the host's projection cache when (and only
@@ -32,16 +37,39 @@ const sameLifecycle = (a, b) => a && b && a.createdAt === b.createdAt && (a.cwd
  * @throws {CapabilityRefusalError} when the cache cannot support a safe delete.
  */
 function acquireCacheGuard(cache) {
-    let guard = cacheGuards.get(cache);
-    if (guard) {
-        guard.users += 1;
-        return guard;
+    const existing = cacheGuards.get(cache);
+    // 复用前先验「装着的确实是我们的包装器」：release 时被第三方接管过的那条路会留下一个
+    // 「在册但没装」的 guard，复用它等于墓碑拦截静默失效（缓存行可能复活）。
+    if (existing && existing.users > 0 && existing.installed()) {
+        existing.users += 1;
+        return existing;
     }
+    if (existing)
+        cacheGuards.delete(cache);
     const missing = ["put", "write", "requireTable"].filter((name) => typeof cache[name] !== "function");
     if (missing.length > 0) {
         throw new CapabilityRefusalError("delete", refusalsFor({ findings: [{ id: "projection.write", label: "投影缓存写入路径", kind: "write", owner: "projectionCache", fallback: "disable-destructive", state: "missing-member", detail: `宿主投影缓存缺少 ${missing.join(", ")}`, missing }] }, ["projection.write"]));
     }
-    const table = cache.requireTable();
+    let table;
+    try {
+        table = cache.requireTable();
+    }
+    catch (error) {
+        // 安装期就抛：此刻还没动 put/write（不可能有半状态），但必须上报 —— 删除屏障没在岗。
+        noteRuntime({
+            id: "projection-cache-adapter",
+            label: "投影缓存删除屏障",
+            kind: "delete",
+            fallback: "inform-only",
+            detail: `投影缓存适配未完成（requireTable 抛错）：${String(error?.message ?? error)}；宿主对象未被改动。`,
+        });
+        throw new CapabilityRefusalError("delete", [{
+                id: "projection.table-delete",
+                label: "投影缓存行删除",
+                detail: `宿主投影缓存的 requireTable() 抛错：${String(error?.message ?? error)}`,
+                recovery: "请更新本插件到与本机 DSH 匹配的版本（先运行 node scripts/doctor.mjs 查看差异）。",
+            }]);
+    }
     if (typeof table?.delete !== "function") {
         throw new CapabilityRefusalError("delete", [{
                 id: "projection.table-delete",
@@ -86,29 +114,46 @@ function acquireCacheGuard(cache) {
             return serial(id, async () => {
                 if (isBlocked(id, expected))
                     return;
-                await originals.put.call(cache, id, expected, detached);
-                if (isBlocked(id, expected)) {
-                    const stored = table.get(id);
-                    if (stored && sameLifecycle(stored.identity, expected))
-                        await table.delete(id);
+                try {
+                    await originals.put.call(cache, id, expected, detached);
+                    if (isBlocked(id, expected)) {
+                        const stored = table.get(id);
+                        if (stored && sameLifecycle(stored.identity, expected))
+                            await table.delete(id);
+                    }
+                }
+                catch (error) {
+                    // 形状变了才会是 TypeError（与本仓库探针同一条口径：受控 Error 不算适配失败）。
+                    // 撤掉包装、绝不让宿主留在"半个包装器"状态下，并上报 —— 下一次删除会重装。
+                    if (error instanceof TypeError)
+                        retire("failed");
+                    throw error;
                 }
             });
         },
         write(session) {
             // Track the flush await before put as well as put itself. Otherwise a
             // delayed write could outlive disposal and bypass the restored method.
+            let task;
             try {
-                return track(Promise.resolve(originals.write.call(cache, session)));
+                task = track(Promise.resolve(originals.write.call(cache, session)));
             }
             catch (error) {
+                if (error instanceof TypeError)
+                    retire("failed");
                 return Promise.reject(error);
             }
+            return task.catch((error) => { if (error instanceof TypeError)
+                retire("failed"); throw error; });
         },
     };
     cache.put = wrappers.put;
     cache.write = wrappers.write;
-    guard = {
+    const self = {
         users: 1,
+        // 两个都得是我们的才算"在岗"：只装着一个就等于另一半的写入不受墓碑约束（缓存行会复活）。
+        // 半个的情形由 acquire 的重建路径处理（覆盖掉那半个外来包装），并在退役时已上报过。
+        installed: () => cache.put === wrappers.put && cache.write === wrappers.write,
         begin(id, header) { blocked.set(id, header ?? null); },
         clearTombstone(id) { blocked.delete(id); },
         async whenIdle() { while (pending.size)
@@ -128,26 +173,55 @@ function acquireCacheGuard(cache) {
             await this.whenIdle();
             if (this.users > 0)
                 return;
-            let restored = true;
-            for (const name of ["put", "write"]) {
-                // Never overwrite a later third-party wrapper.
-                if (cache[name] !== wrappers[name]) {
-                    restored = false;
-                    continue;
-                }
-                if (descriptors[name])
-                    Object.defineProperty(cache, name, descriptors[name]);
-                else
-                    delete cache[name];
-            }
-            if (restored) {
-                blocked.clear();
-                cacheGuards.delete(cache);
-            }
+            const clean = restoreWrappers();
+            retire(clean ? "idle" : "taken-over");
         },
     };
-    cacheGuards.set(cache, guard);
-    return guard;
+    let retired = false;
+    /** 撤包装：第三方装了的话**不动它**（返回 false 表示没撤干净）。 */
+    function restoreWrappers() {
+        let clean = true;
+        for (const name of ["put", "write"]) {
+            // Never overwrite a later third-party wrapper.
+            if (cache[name] !== wrappers[name]) {
+                clean = false;
+                continue;
+            }
+            if (descriptors[name])
+                Object.defineProperty(cache, name, descriptors[name]);
+            else
+                delete cache[name];
+        }
+        return clean;
+    }
+    /**
+     * 退役这个 guard：摘出 WeakMap（之后 acquire 会重建）、撤包装、清墓碑；非正常退役要上报。
+     *
+     * 三种退役理由对应三条真实路径：`idle` = 引用归零的正常释放（不上报）；
+     * `taken-over` = 第三方在我们的包装器之上又包了一层（release 撤不干净，下次删除重建）；
+     * `failed` = 首次使用抛 TypeError（宿主形状变了，已恢复原方法）。
+     */
+    function retire(reason) {
+        if (retired)
+            return;
+        retired = true;
+        if (cacheGuards.get(cache) === self)
+            cacheGuards.delete(cache);
+        blocked.clear();
+        if (reason === "idle")
+            return;
+        noteRuntime({
+            id: "projection-cache-adapter",
+            label: "投影缓存删除屏障",
+            kind: "delete",
+            fallback: "inform-only",
+            detail: reason === "taken-over"
+                ? "宿主缓存的 put/write 已被第三方包装接管：本插件的删除屏障这一轮已退役（缓存行删除少了墓碑拦截），下一次删除会重新安装。"
+                : "投影缓存适配在首次使用时抛错（宿主形状可能变了）：已恢复宿主原方法，下一次删除会重新安装并再探一次。",
+        });
+    }
+    cacheGuards.set(cache, self);
+    return self;
 }
 /**
  * Live-session members the delete sequence needs, split by branch.
@@ -168,10 +242,12 @@ export function requiredSessionCapabilities(hasLiveSession) {
         ? ["sessions.detach-live"]
         : ["sessions.cold-announce"];
 }
-export function createHistoryBridge(ctx, suppliedRegistry, onArchive) {
+export function createSessionsBridge(ctx, suppliedRegistry, onArchive) {
     // Cordis returns a fresh traceable method proxy on access. Compare and adapt
     // the original object, not proxies; calls retain the service owner's context.
     const registry = raw(suppliedRegistry);
+    // 官方声明把 put/requireTable 标为 private（运行时存在，见文件头「纪律边界」），
+    // 因此按本文件实际调用面收窄，不改动宿主对象本身。
     const cache = raw(ctx.get("sessionProjectionCache"));
     let guard;
     let stopObserving;
@@ -216,7 +292,9 @@ export function createHistoryBridge(ctx, suppliedRegistry, onArchive) {
     const method = (name, ...args) => {
         if (typeof registry[name] !== "function")
             throw new Error(`宿主缺少归档兼容接口 ${name}，操作已停止`);
-        return registry[name](...args);
+        // 动态成员名：先收窄为可调用类型，再以 registry 为 receiver 调用，
+        // 与 registry[name](...args) 的 this 绑定完全一致。
+        return registry[name].call(registry, ...args);
     };
     /**
      * The adapter route needs the registry's read/write/delegate members. This is
@@ -256,9 +334,11 @@ export function createHistoryBridge(ctx, suppliedRegistry, onArchive) {
             // from the official sidebar or an external archive manager. No monkey
             // patch of archiveSession and no competing writer of its ledger.
             stopObserving = ctx.on("domain/changed", (change) => {
-                if (change?.domain !== workspaceDomainSpec.name || change.table !== "" || !Array.isArray(change.value?.archivedSessionIds))
+                // 官方事件类型把 value 声明为 unknown（载荷形状由 workspace 域规范决定）。
+                const payload = change.value;
+                if (change?.domain !== workspaceDomainSpec.name || change.table !== "" || !Array.isArray(payload?.archivedSessionIds))
                     return;
-                const next = new Set(change.value.archivedSessionIds);
+                const next = new Set(payload.archivedSessionIds);
                 const at = Date.now();
                 for (const id of next)
                     if (!previous.has(id))
@@ -291,7 +371,15 @@ export function createHistoryBridge(ctx, suppliedRegistry, onArchive) {
                     }]);
             if (typeof cache.delete === "function" && typeof cache.whenIdle === "function")
                 return;
-            guard ??= acquireCacheGuard(cache);
+            // 本地这份 guard 可能已经退役（第三方接管 / 首次使用抛错）：退役时已从 WeakMap 摘掉自己，
+            // 这里也得换掉它 —— 拿一个不在岗的屏障去挡墓碑，正是"缓存行静默复活"那条路。
+            const next = acquireCacheGuard(cache);
+            if (next !== guard) {
+                const previous = guard;
+                guard = next;
+                if (previous)
+                    await previous.release().catch(() => undefined);
+            }
             guard.begin(id, header);
         },
         cache() { return guard ?? cache; },