@shgroup/dsh-serenity-hooks 1.69.2 → 1.69.4

package/dsh.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "dsh-serenity-hooks",
-  "version": "1.69.2",
+  "version": "1.69.4",
   "main": "lib/index.js",
   "description": "宁静号 ACC harness（Native Cordis 插件）：给 DSH 装一个「AI 工作区」——14 个工具（container_fs/cognitive_trajectory/dashboard/container_git/msm/praxis/ontology/serenity-skill-creator/cheap-worker/localstore/container_admin；另三个 im-bridge/acc-diag/diagram 按配置条件出现）+ 机械约束（安全模式/工作区围墙/密钥守卫）+ 认知轨迹日志与原地重建 + 网页登录入口/微信桥/子角色/官方 ACP 面/认知轨迹唤醒注册表。适配 DSH 0.1.7-rc.1 / 0.2.0-rc.1 / 0.2.1-rc.1（三档，deepseek-ai/deepseek-harness）。",
   "engines": {

package/lib/index.js

@@ -13574,6 +13574,97 @@ const EXCLUSIVE_TOOL_NAMES = ["acc-diag"];
 /** `${sessionId}::${toolName}` → restrict disposer */
 const exclusiveRestrictions = /* @__PURE__ */ new Map();
 /**
+* `sessionId` → { signature, dispose }（角色工具面 restrict 状态）
+*
+* `signature` = 本轮实际发出的 deny 清单（排序后 join）。用它做**幂等判据**：
+* 每次 pre-step 都重算白名单，只有**算出来的结果变了**才重新发 restrict
+* —— 配置不变就不重复发（restrict 会重建 schema，没必要每步都做）。
+*/
+const skiffRoleRestrictions = /* @__PURE__ */ new Map();
+/**
+* 同步 **Skiff 会话的工具面**：把角色白名单之外的工具**从 schema 移除**（不是"看得到但被拒"）。
+*
+* ## 为什么必须有这条（owner 2026-10-19：「工具清单也要热加载」）
+*
+* 在它之前，skiff 角色白名单**只由运行时守卫拦截**（`decideGuard` 的 skiff 分支）：
+* 工具全部出现在模型 schema 里，调用时才被 `tool not allowed in this skiff role` 打回。
+* ⇒ 两个真实后果：
+*  ① **模型看得见它不该有的工具** —— 它会去试，试了才撞墙（一轮白烧，且错误文案泛化，
+*     看不出"是不在清单里"还是"临时性拒绝"）；
+*  ② **配置变动在 schema 上永远不生效** —— 改 `skiff.roles.<r>.tools` 只影响"调用是否放行"，
+*     不影响"模型看得见什么"。这正是 owner 报的"工具清单不热加载"。
+*
+* ## 判据与降级
+*
+* - deny 集合 = **`REGISTERED_TOOLS` − 角色白名单**（只对**我们自己注册的**工具算，
+*   不去动宿主的工具 —— 宿主的工具由各自的条件同步管）。
+* - ⚠️ **未注册的名字会让整次 restrict 失败**（宿主契约逐字 "unknown names … fail"），
+*   而 `diagram` 是按开关注册的 ⇒ 与 `hideAllFor` 同款**两档尝试**（先全覆盖，失败退常驻段）。
+* - 读不到角色（配置删了/角色被移除）⇒ **不动**（fail-open）：此时守卫仍会拦，
+*   最坏是"又变成看得见但调不动"，而不是把工具全删光。
+* - 幂等：算出来的 deny 签名不变就跳过（不每步重建 schema）。
+*
+* @param agent 目标会话
+* @param root  CCC 根
+*/
+function syncSkiffRoleToolVisibility(agent, root) {
+	const sessionId = agent.session.id ?? "global";
+	if (!isSkiffSessionId(sessionId)) return;
+	const roleName = skiffRoleFor$1(sessionId);
+	if (!roleName) return;
+	let allowed;
+	try {
+		const role = readSkiffRoles(root).get(roleName);
+		if (!role) return;
+		allowed = roleToolWhitelist(role);
+	} catch {
+		return;
+	}
+	const resident = REGISTERED_TOOLS.slice(0, REGISTERED_TOOLS.length - 3);
+	const tiers = [REGISTERED_TOOLS, resident];
+	const existing = skiffRoleRestrictions.get(sessionId);
+	for (const names of tiers) {
+		const deny = names.filter((n) => !allowed.has(n));
+		const signature = [...deny].sort().join(",");
+		if (existing !== void 0 && existing.signature === signature) return;
+		if (deny.length === 0) {
+			if (existing !== void 0) {
+				try {
+					existing.dispose();
+				} catch {}
+				skiffRoleRestrictions.delete(sessionId);
+			}
+			return;
+		}
+		try {
+			if (existing !== void 0) {
+				try {
+					existing.dispose();
+				} catch {}
+				skiffRoleRestrictions.delete(sessionId);
+			}
+			const dispose = agent.ctx.tools.restrict({ deny: [...deny] });
+			skiffRoleRestrictions.set(sessionId, {
+				signature,
+				deny,
+				dispose
+			});
+			return;
+		} catch {
+			continue;
+		}
+	}
+}
+/** 会话销毁清理（lifecycle 调用） */
+function forgetSkiffRoleToolVisibility(sessionId) {
+	const existing = skiffRoleRestrictions.get(sessionId);
+	if (!existing) return;
+	try {
+		existing.dispose();
+	} catch {}
+	skiffRoleRestrictions.delete(sessionId);
+}
+/**
 * 同步专属工具可见性（v1.33）。
 *
 * 判据 = CCC 配置 `exclusiveTools`（`readExclusiveTools`）：
@@ -13818,6 +13909,13 @@ const DEFAULT_COMPACTION_TOOLS = [
 */
 const DEFAULT_ANCHOR_MESSAGES = ["You are the operator agent of Serenity — a cognitive container governed by the Abstract Cognitive Container (ACC) protocol.\nWe operate under the Explicit Abstraction Principle (EAP): the functional value of a thought equals its external reconstructability — every output we produce must be explicit (E↑), reconstructable (R↓), and stable (S↑).\nThe personal pronoun is us/we.\nWe anchor first, then act: the abstract layer precedes the concrete.\nPlease simply reply \"acknowledge\" — no action needed.", "Before we proceed, align on how we work:\n1. We read before we write — every decision grounds in what already exists in the container.\n2. Every output records its reasoning (R↓): decisions carry reasons and alternatives.\n3. We never jump levels — abstract layer first, then specifics.\n4. Every artifact we create is a durable cognitive anchor for the work that follows.\n5. We keep the container's state coherent (SESSION.md) as we advance.\nPlease simply reply \"acknowledge\" — no action needed."];
 /**
+* 锚定交换里「模型那半」的回复文本。
+*
+* 只写一个词：锚定话语明确要求 `reply "acknowledge" — no action needed`，
+* 伪造一条更长的回复反而与提示词不符（模型会据历史学样）。
+*/
+const ANCHOR_ACK_TEXT = "acknowledge";
+/**
 * 会话里是否已有模型回复（= 已经不是首轮）。
 *
 * 🔴 这是锚定的**形状判据**（v1.62）：锚定只能在**首轮**造。
@@ -13833,14 +13931,24 @@ function hasAssistantHistory(session) {
 *
 * ## 🔴 两条硬约束（宿主 v4 格式校验器，实测逐条踩过）
 *
-* **约束 A — 只能写 `user/message`**：`system/message` 与 `assistant/message` 都在
-*   `STEP_EVENT_TYPES` 里 ⇒ 必须过 `requireStep()`（`data.turn`/`data.step` 精确匹配
-*   **当前打开的** turn 与 step，且为 null 时同样拒绝）。而本函数在 `agent/pre-step`
-*   前后被调用时 **turn/step 都还没打开**（`turn/start` 在 preStep 之前，`step/start`
-*   在 preStep 之后）⇒ 代写它们**结构性非法**。
-*   ⚠️ 症状：写通道不校验 ⇒ **首轮正常**；**重新进入**时重放才抛
-*   `system/message does not match an open turn and step` ⇒ 会话 corrupt、界面空白。
-*   ⇒ **v1.60 那版「先写占位 system 等宿主 replace」的整套方案因此作废**。
+* **约束 A — `system/message` 绝不能代写；`assistant/message` 可以，但必须落在已打开的 turn/step 内**。
+*
+*   🔴 **D140 的理由已由本文件 `tests/anchor-history-shape.test.ts` 当场更正**（探针直调宿主
+*   `assertReleasedV4Relationships()`，不靠读源码推断）：
+*   原记「`system/message` 与 `assistant/message` 都在 `STEP_EVENT_TYPES` 里」—— **只对前半**。
+*   实测 `STEP_EVENT_TYPES` = `{ system/message, developer/message, assistant/attempt }`，
+*   **`assistant/message` 不在其中**。它仍要过 `requireStep`，但走的是另一条路
+*   （`Relationships.accept()` → `case "assistant/message"` → `tool()` → `requireStep`）。
+*
+*   ⇒ **结论保留、理由作废**：`assistant/message` 在**该 system/message 之前**写是非法的
+*   （那时 turn/step 尚未打开）；而在**之后**写是**合法的**（那时两者都已打开）。
+*   探针三态实测：A（仅 user）✅ ／ **B（user ＋ assistant 交替，turn/step 匹配）✅** ／
+*   C（assistant 落在未打开的 turn/step）❌ `does not match an open turn and step`。
+*
+*   ⚠️ 症状（不许省这条）：写通道不校验 ⇒ **首轮看着正常**；**重新进入**时重放才抛
+*   `does not match an open turn and step` ⇒ 会话 corrupt、界面空白。
+*   ⇒ **v1.60 那版「先写占位 system 等宿主 replace」的整套方案仍然作废**
+*     （它写的是 `system/message`，那**确实**在 `STEP_EVENT_TYPES` 里）。
 *
 * **约束 B — 必须写在宿主提交 `system/message` 之后**：格式层有 `protectedHead`
 *   机制 —— `foldSurface()` 里 `system/message` 若在 **surface 非空且尚无 protectedHead**
@@ -13853,38 +13961,69 @@ function hasAssistantHistory(session) {
 * ⇒ 因此调用时机 = **`session/event` 里看到该会话第一条 `system/message` 之后**（见下方注册处），
 *   而不是 `agent/inbox/inserted`（那太早）。
 *
-* ## 为什么去掉 assistant 那半不损失什么
+* ## 为什么必须成对（user ＋ assistant ack）—— v1.69.4 修正
+*
+* 只造 user 的那一版在**界面上读不成对话**：两条"用户"消息连排在模型回复之前，
+* 看起来像用户自己连说了两句协议、而模型没理。owner 2026-10-19 报的两点
+* （「助手的回应也需要造出来」＋「用户的怎么跑到第一个了」）其实是**同一个缺陷的两面**。
+* ⇒ 造**成对交换**：每条锚定话语后面跟一条 `acknowledge` 回复。
 *
-* 锚定话语的**唯一目的**是让模型认为自己已经同意过协作协议。
-* 保留 **2 条 `user/message`** 即可达成；丢掉的只是"模型自己的 ack 回复"——
-* 而那原本也是**我们伪造的**，不是模型真说过的。
+* 🔴 **前提条件**：`assistant/message` 必须落在**已打开**的 turn/step 内
+*   （探针 S3/S4 实测：未打开/已关闭都抛 `does not match an open turn and step`）。
+*   本函数由 `session/event` 的 `system/message` 分支触发，而**那条事件自己就带着
+*   `data.turn` / `data.step`** —— 且实测此刻 turn/step 确实处于打开态
+*   （真机日志：`step/start` → `system/message` → 锚定写入 → `step/end`）。
+*   ⇒ turn/step **从触发事件透传进来**，不自己猜。
+*
+* ⚠️ **拿不到 turn/step 时退回只造 user**（不抛、不阻断）：宁可少伪造一条 ack，
+*   也绝不在非法坐标上写 `assistant/message` —— 那会让会话在重放时 corrupt。
 *
 * ## 判据（改这个函数前后都必须跑）
 *
-* ① 单测钉形状（只许 user/message）；
-* ② **容器内真跑一轮 → 重启宿主 → 重新进入该会话** —— 只有这条路能证明日志合法
+* ① 形状判据 = `tests/anchor-history-shape.test.ts`（直调宿主校验器，正控 ＋ 两种负控）；
+* ② 单测钉事件序列（user/assistant 交替、turn/step 逐条匹配）；
+* ③ **容器内真跑一轮 → 重启宿主 → 重新进入该会话** —— 只有这条路能证明日志合法
 *   （前两次修复都是"单测全绿 + 首轮正常"却仍然 corrupt）。
-* ③ 直接调宿主自己的 `assertReleasedV4Relationships()` 判形状，**不要自写复刻**。
 *
 * @param session 会话（需有 append）
 * @param anchorMessages 锚定话语序列（缺省协议固有两条）
+* @param slot 触发本轮 `system/message` 所在的 turn/step（缺省或非法 ⇒ 只造 user）
 * @returns 是否成功写入
 */
-function appendAnchorHistory(session, anchorMessages = DEFAULT_ANCHOR_MESSAGES) {
+function appendAnchorHistory(session, anchorMessages = DEFAULT_ANCHOR_MESSAGES, slot) {
 	const target = session;
 	if (typeof target?.append !== "function") return false;
 	const append = target.append.bind(target);
 	const rid = (prefix) => `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+	const turn = typeof slot?.turn === "number" ? slot.turn : 0;
+	const step = typeof slot?.step === "number" ? slot.step : 0;
+	const canPlaceAck = turn > 0 && step > 0;
 	try {
-		for (let i = 0; i < anchorMessages.length; i++) append("user/message", {
-			id: rid(`anchor-user-${i + 1}`),
-			role: "user",
-			content: [{
-				type: "text",
-				text: anchorMessages[i]
-			}],
-			source: { kind: "user" }
-		}, { surfaceOp: "append" });
+		for (let i = 0; i < anchorMessages.length; i++) {
+			append("user/message", {
+				id: rid(`anchor-user-${i + 1}`),
+				role: "user",
+				content: [{
+					type: "text",
+					text: anchorMessages[i]
+				}],
+				source: { kind: "user" }
+			}, { surfaceOp: "append" });
+			if (!canPlaceAck) continue;
+			append("assistant/message", {
+				turn,
+				step,
+				message: {
+					id: rid(`anchor-ack-${i + 1}`),
+					role: "assistant",
+					content: [{
+						type: "text",
+						text: ANCHOR_ACK_TEXT
+					}],
+					source: { kind: "model" }
+				}
+			}, { surfaceOp: "append" });
+		}
 		return anchorMessages.length > 0;
 	} catch {
 		return false;
@@ -14061,24 +14200,30 @@ function registerBootstrap(ctx) {
 			const root = cccRootForCwd(cwd);
 			if (!root) return;
 			trackerFor(root).observe(session, event);
-			if (event.type === "system/message") setTimeout(() => {
-				try {
-					maybeAnchor(session, root);
-				} catch {}
-			}, 0);
+			if (event.type === "system/message") {
+				const slot = event.data;
+				setTimeout(() => {
+					try {
+						maybeAnchor(session, root, slot);
+					} catch {}
+				}, 0);
+			}
 		} catch {}
 	});
 	/** 造锚定历史（幂等；防重靠 `anchoredSessions`）。 */
-	const maybeAnchor = (session, _root) => {
+	const maybeAnchor = (session, _root, slot) => {
 		const s = session;
 		s?.header?.delegationDepth;
 		const sid = typeof s?.id === "string" ? s.id : void 0;
 		if (sid !== void 0 && anchoredSessions.has(sid)) return;
 		if (sid !== void 0 && (sid.startsWith("cheap-worker-") || isSkiffSessionId(sid))) return;
 		if (hasAssistantHistory(session)) return;
-		const wrote = appendAnchorHistory(session, SETTINGS.anchorMessages);
+		const wrote = appendAnchorHistory(session, SETTINGS.anchorMessages, slot);
 		if (wrote && sid !== void 0) anchoredSessions.add(sid);
-		if (wrote) warnOnce(`anchor history fabricated: ${SETTINGS.anchorMessages.length} 条 user 消息（不再真跑）`);
+		if (wrote) {
+			const paired = typeof slot?.turn === "number" && typeof slot?.step === "number" && slot.turn > 0 && slot.step > 0;
+			warnOnce(`anchor history fabricated: ${SETTINGS.anchorMessages.length} 条 user 消息` + (paired ? ` ＋ ${SETTINGS.anchorMessages.length} 条 ack（turn ${String(slot.turn)} / step ${String(slot.step)}）` : "（无打开坐标 ⇒ 未造 ack）") + "（不再真跑）");
+		}
 	};
 	ctx.on("agent/inbox/inserted", ({ agent, message }) => {
 		try {
@@ -14750,6 +14895,9 @@ function registerContext(ctx, opts = {}) {
 		const root = cccRootForCwd(cwd);
 		const key = agentKey(agent);
 		const downstream = await next();
+		if (root) try {
+			syncSkiffRoleToolVisibility(agent, root);
+		} catch {}
 		if (isSkiffSessionId(key)) return downstream;
 		try {
 			syncCccToolVisibility(agent, root);
@@ -21759,6 +21907,9 @@ function cleanupSessionState(sessionId) {
 	try {
 		forgetHostScheduleToolHiding(sessionId);
 	} catch {}
+	try {
+		forgetSkiffRoleToolVisibility(sessionId);
+	} catch {}
 	try {
 		forgetLogbookCompactionState(sessionId);
 	} catch {}

package/lib/seams/bootstrap.d.ts

@@ -50,6 +50,13 @@ export declare const DEFAULT_COMPACTION_TOOLS: string[];
  * 文本 = 原 home-serenity CCC 配置（anchorMessages），随零配置化固化进代码。
  */
 export declare const DEFAULT_ANCHOR_MESSAGES: string[];
+/**
+ * 锚定交换里「模型那半」的回复文本。
+ *
+ * 只写一个词：锚定话语明确要求 `reply "acknowledge" — no action needed`，
+ * 伪造一条更长的回复反而与提示词不符（模型会据历史学样）。
+ */
+export declare const ANCHOR_ACK_TEXT = "acknowledge";
 /**
  * 根会话锚定重入判定（v1.28.1 提取导出以便单测）：会话是否已有真实用户消息。
  * resume/续跑的会话已有对话历史 → **不重锚**（first-anchor 只注入一次）。
@@ -73,14 +80,24 @@ export declare function hasAssistantHistory(session: unknown): boolean;
  *
  * ## 🔴 两条硬约束（宿主 v4 格式校验器，实测逐条踩过）
  *
- * **约束 A — 只能写 `user/message`**：`system/message` 与 `assistant/message` 都在
- *   `STEP_EVENT_TYPES` 里 ⇒ 必须过 `requireStep()`（`data.turn`/`data.step` 精确匹配
- *   **当前打开的** turn 与 step，且为 null 时同样拒绝）。而本函数在 `agent/pre-step`
- *   前后被调用时 **turn/step 都还没打开**（`turn/start` 在 preStep 之前，`step/start`
- *   在 preStep 之后）⇒ 代写它们**结构性非法**。
- *   ⚠️ 症状：写通道不校验 ⇒ **首轮正常**；**重新进入**时重放才抛
- *   `system/message does not match an open turn and step` ⇒ 会话 corrupt、界面空白。
- *   ⇒ **v1.60 那版「先写占位 system 等宿主 replace」的整套方案因此作废**。
+ * **约束 A — `system/message` 绝不能代写；`assistant/message` 可以，但必须落在已打开的 turn/step 内**。
+ *
+ *   🔴 **D140 的理由已由本文件 `tests/anchor-history-shape.test.ts` 当场更正**（探针直调宿主
+ *   `assertReleasedV4Relationships()`，不靠读源码推断）：
+ *   原记「`system/message` 与 `assistant/message` 都在 `STEP_EVENT_TYPES` 里」—— **只对前半**。
+ *   实测 `STEP_EVENT_TYPES` = `{ system/message, developer/message, assistant/attempt }`，
+ *   **`assistant/message` 不在其中**。它仍要过 `requireStep`，但走的是另一条路
+ *   （`Relationships.accept()` → `case "assistant/message"` → `tool()` → `requireStep`）。
+ *
+ *   ⇒ **结论保留、理由作废**：`assistant/message` 在**该 system/message 之前**写是非法的
+ *   （那时 turn/step 尚未打开）；而在**之后**写是**合法的**（那时两者都已打开）。
+ *   探针三态实测：A（仅 user）✅ ／ **B（user ＋ assistant 交替，turn/step 匹配）✅** ／
+ *   C（assistant 落在未打开的 turn/step）❌ `does not match an open turn and step`。
+ *
+ *   ⚠️ 症状（不许省这条）：写通道不校验 ⇒ **首轮看着正常**；**重新进入**时重放才抛
+ *   `does not match an open turn and step` ⇒ 会话 corrupt、界面空白。
+ *   ⇒ **v1.60 那版「先写占位 system 等宿主 replace」的整套方案仍然作废**
+ *     （它写的是 `system/message`，那**确实**在 `STEP_EVENT_TYPES` 里）。
  *
  * **约束 B — 必须写在宿主提交 `system/message` 之后**：格式层有 `protectedHead`
  *   机制 —— `foldSurface()` 里 `system/message` 若在 **surface 非空且尚无 protectedHead**
@@ -93,24 +110,39 @@ export declare function hasAssistantHistory(session: unknown): boolean;
  * ⇒ 因此调用时机 = **`session/event` 里看到该会话第一条 `system/message` 之后**（见下方注册处），
  *   而不是 `agent/inbox/inserted`（那太早）。
  *
- * ## 为什么去掉 assistant 那半不损失什么
+ * ## 为什么必须成对（user ＋ assistant ack）—— v1.69.4 修正
+ *
+ * 只造 user 的那一版在**界面上读不成对话**：两条"用户"消息连排在模型回复之前，
+ * 看起来像用户自己连说了两句协议、而模型没理。owner 2026-10-19 报的两点
+ * （「助手的回应也需要造出来」＋「用户的怎么跑到第一个了」）其实是**同一个缺陷的两面**。
+ * ⇒ 造**成对交换**：每条锚定话语后面跟一条 `acknowledge` 回复。
+ *
+ * 🔴 **前提条件**：`assistant/message` 必须落在**已打开**的 turn/step 内
+ *   （探针 S3/S4 实测：未打开/已关闭都抛 `does not match an open turn and step`）。
+ *   本函数由 `session/event` 的 `system/message` 分支触发，而**那条事件自己就带着
+ *   `data.turn` / `data.step`** —— 且实测此刻 turn/step 确实处于打开态
+ *   （真机日志：`step/start` → `system/message` → 锚定写入 → `step/end`）。
+ *   ⇒ turn/step **从触发事件透传进来**，不自己猜。
  *
- * 锚定话语的**唯一目的**是让模型认为自己已经同意过协作协议。
- * 保留 **2 条 `user/message`** 即可达成；丢掉的只是"模型自己的 ack 回复"——
- * 而那原本也是**我们伪造的**，不是模型真说过的。
+ * ⚠️ **拿不到 turn/step 时退回只造 user**（不抛、不阻断）：宁可少伪造一条 ack，
+ *   也绝不在非法坐标上写 `assistant/message` —— 那会让会话在重放时 corrupt。
  *
  * ## 判据（改这个函数前后都必须跑）
  *
- * ① 单测钉形状（只许 user/message）；
- * ② **容器内真跑一轮 → 重启宿主 → 重新进入该会话** —— 只有这条路能证明日志合法
+ * ① 形状判据 = `tests/anchor-history-shape.test.ts`（直调宿主校验器，正控 ＋ 两种负控）；
+ * ② 单测钉事件序列（user/assistant 交替、turn/step 逐条匹配）；
+ * ③ **容器内真跑一轮 → 重启宿主 → 重新进入该会话** —— 只有这条路能证明日志合法
  *   （前两次修复都是"单测全绿 + 首轮正常"却仍然 corrupt）。
- * ③ 直接调宿主自己的 `assertReleasedV4Relationships()` 判形状，**不要自写复刻**。
  *
  * @param session 会话（需有 append）
  * @param anchorMessages 锚定话语序列（缺省协议固有两条）
+ * @param slot 触发本轮 `system/message` 所在的 turn/step（缺省或非法 ⇒ 只造 user）
  * @returns 是否成功写入
  */
-export declare function appendAnchorHistory(session: unknown, anchorMessages?: string[]): boolean;
+export declare function appendAnchorHistory(session: unknown, anchorMessages?: string[], slot?: {
+    turn?: unknown;
+    step?: unknown;
+}): boolean;
 interface PromotionStatus {
     /** 最后一次 compaction/end 的 seq（-1 = 未压缩过） */
     boundary: number;

package/lib/seams/guards.d.ts

@@ -95,6 +95,40 @@ export declare function forgetHostScheduleToolHiding(sessionId: string): void;
 export declare function getExclusiveToolsDiagnostics(): {
     hidden: string[];
 };
+/** Skiff 角色工具面诊断（排查"某工具为什么不在 skiff 的清单里"） */
+export declare function getSkiffRoleVisibilityDiagnostics(): {
+    keys: string[];
+    denyByKey: Record<string, string[]>;
+};
+/**
+ * 同步 **Skiff 会话的工具面**：把角色白名单之外的工具**从 schema 移除**（不是"看得到但被拒"）。
+ *
+ * ## 为什么必须有这条（owner 2026-10-19：「工具清单也要热加载」）
+ *
+ * 在它之前，skiff 角色白名单**只由运行时守卫拦截**（`decideGuard` 的 skiff 分支）：
+ * 工具全部出现在模型 schema 里，调用时才被 `tool not allowed in this skiff role` 打回。
+ * ⇒ 两个真实后果：
+ *  ① **模型看得见它不该有的工具** —— 它会去试，试了才撞墙（一轮白烧，且错误文案泛化，
+ *     看不出"是不在清单里"还是"临时性拒绝"）；
+ *  ② **配置变动在 schema 上永远不生效** —— 改 `skiff.roles.<r>.tools` 只影响"调用是否放行"，
+ *     不影响"模型看得见什么"。这正是 owner 报的"工具清单不热加载"。
+ *
+ * ## 判据与降级
+ *
+ * - deny 集合 = **`REGISTERED_TOOLS` − 角色白名单**（只对**我们自己注册的**工具算，
+ *   不去动宿主的工具 —— 宿主的工具由各自的条件同步管）。
+ * - ⚠️ **未注册的名字会让整次 restrict 失败**（宿主契约逐字 "unknown names … fail"），
+ *   而 `diagram` 是按开关注册的 ⇒ 与 `hideAllFor` 同款**两档尝试**（先全覆盖，失败退常驻段）。
+ * - 读不到角色（配置删了/角色被移除）⇒ **不动**（fail-open）：此时守卫仍会拦，
+ *   最坏是"又变成看得见但调不动"，而不是把工具全删光。
+ * - 幂等：算出来的 deny 签名不变就跳过（不每步重建 schema）。
+ *
+ * @param agent 目标会话
+ * @param root  CCC 根
+ */
+export declare function syncSkiffRoleToolVisibility(agent: Agent, root: string): void;
+/** 会话销毁清理（lifecycle 调用） */
+export declare function forgetSkiffRoleToolVisibility(sessionId: string): void;
 /**
  * 同步专属工具可见性（v1.33）。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shgroup/dsh-serenity-hooks",
-  "version": "1.69.2",
+  "version": "1.69.4",
   "description": "宁静号 ACC harness（Native Cordis 插件）——给 DeepSeek Harness 装一个「AI 工作区」：14 个工具（container_fs/cognitive_trajectory/dashboard/container_git/msm/praxis/ontology/serenity-skill-creator/cheap-worker/localstore/container_admin；另三个 im-bridge/acc-diag/diagram 按配置条件出现）+ 机械约束（安全模式/工作区围墙/密钥守卫/对外输出守卫）+ 认知轨迹日志与原地重建 + 网页登录入口/微信桥/子角色/官方 ACP 面/认知轨迹唤醒注册表。适配 DSH 0.1.7-rc.1 / 0.2.0-rc.1 / 0.2.1-rc.1（三档）。",
   "license": "MIT",
   "repository": {