dsh-plugin-prompt-tool 3.0.1 → 3.1.0

package/lib/index.mjs

@@ -17,6 +17,7 @@ import { Uint8ArrayReader, Uint8ArrayWriter, ZipReader, ZipWriter } from "@zip.j
 import { inflateSync } from "node:zlib";
 import SystemPrompt, { PERSONA_PREFIX_SECTION, PERSONA_SUFFIX_SECTION } from "@deepseek-ai/dsh-system-prompt";
 import { FileSystemSkillProvider } from "@deepseek-ai/dsh-skill-filesystem";
+import "@deepseek-ai/cordis";
 //#region src/shared/persona-section.ts
 const FIELDS$1 = [
 	"prefix",
@@ -426,7 +427,10 @@ const MODULE_TOOL_NAMES = {
 	fileRead: "module_file_read",
 	fileAppend: "module_file_append",
 	manifest: "module_manifest",
-	variables: "module_variables"
+	variables: "module_variables",
+	soulLedger: "soul_ledger",
+	search: "module_search",
+	open: "module_open"
 };
 const MODULE_TOOL_CAPABILITIES = {
 	[MODULE_TOOL_NAMES.import]: "module-import-tools",
@@ -435,7 +439,10 @@ const MODULE_TOOL_CAPABILITIES = {
 	[MODULE_TOOL_NAMES.fileRead]: "module-file-tools",
 	[MODULE_TOOL_NAMES.fileAppend]: "module-file-tools",
 	[MODULE_TOOL_NAMES.manifest]: "module-manifest-tools",
-	[MODULE_TOOL_NAMES.variables]: "module-variable-tools"
+	[MODULE_TOOL_NAMES.variables]: "module-variable-tools",
+	[MODULE_TOOL_NAMES.soulLedger]: "soul-ledger",
+	[MODULE_TOOL_NAMES.search]: "retrieval",
+	[MODULE_TOOL_NAMES.open]: "retrieval"
 };
 /** 旧公开类型名只作输入兼容。 */
 /**
@@ -816,8 +823,7 @@ function canonicalModulesRoot(root, allowMissing = false) {
 	if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) throw new Error(`预设根不是普通目录：${absoluteRoot}`);
 	return realpathSync(absoluteRoot);
 }
-/** 根与目标先解析真实路径，拒绝链接目录及定义身份不一致。 */
-function assertModuleDirectory(root, id, allowMissing = false) {
+function assertModuleDirectoryPath(root, id, allowMissing = false) {
 	assertModuleId(id);
 	const canonicalRoot = canonicalModulesRoot(root, allowMissing);
 	const target = join(canonicalRoot, id);
@@ -828,6 +834,12 @@ function assertModuleDirectory(root, id, allowMissing = false) {
 	const stat = lstatSync(target);
 	if (stat.isSymbolicLink() || !stat.isDirectory() || dirname(realpathSync(target)) !== canonicalRoot) throw new Error(`预设路径包含链接或越界：${id}`);
 	if (!readdirSync(canonicalRoot).includes(id)) throw new Error(`预设目录身份不匹配：${id}`);
+	return target;
+}
+/** 根与目标先解析真实路径，拒绝链接目录及定义身份不一致。 */
+function assertModuleDirectory(root, id, allowMissing = false) {
+	const target = assertModuleDirectoryPath(root, id, allowMissing);
+	if (allowMissing && !modulePathExists(target)) return target;
 	const definition = join(target, MODULE_DEFINITION_FILE);
 	const fileStat = lstatSync(definition);
 	if (fileStat.isSymbolicLink() || !fileStat.isFile()) throw new Error(`预设定义不是普通文件：${id}`);
@@ -837,6 +849,24 @@ function assertModuleDirectory(root, id, allowMissing = false) {
 	if (declared !== void 0 && declared !== id) throw new Error(`预设定义身份不匹配：${id}`);
 	return target;
 }
+/** 派生快照允许定义暂时损坏；路径、文件类型与可读的声明身份仍须可信。 */
+function assertModuleSnapshotSource(root, id) {
+	const target = assertModuleDirectoryPath(root, id);
+	const definition = join(target, MODULE_DEFINITION_FILE);
+	const fileStat = lstatSync(definition, { throwIfNoEntry: false });
+	if (!fileStat) return target;
+	if (fileStat.isSymbolicLink() || !fileStat.isFile()) throw new Error(`预设定义不是普通文件：${id}`);
+	let doc;
+	try {
+		doc = parseDocument(readFileSync(definition, "utf8"), { logLevel: "silent" });
+	} catch {
+		return target;
+	}
+	if (doc.errors.length > 0 || !(doc.contents instanceof YAMLMap)) return target;
+	const declared = doc.get("id");
+	if (declared !== void 0 && declared !== id) throw new Error(`预设定义身份不匹配：${id}`);
+	return target;
+}
 /** 复制和物化只接受自有普通文件；不跟随任意层级链接读取根外数据。 */
 function assertModuleTree(dir) {
 	const stat = lstatSync(dir);
@@ -1109,6 +1139,20 @@ function parsePromoteOn(pluginName, value) {
 	if (value === "tool-call" || value === "assistant-message") return PROMOTE_EVENTS[value];
 	throw new TypeError(`${pluginName}: promoteOn must be one of "tool-call", "assistant-message", "either"; got ${JSON.stringify(value)}`);
 }
+/** Validate an optional boolean config flag with a default. */
+function booleanOption(pluginName, value, field, fallback) {
+	if (value === void 0) return fallback;
+	if (typeof value !== "boolean") throw new TypeError(`${pluginName}: ${field} must be a boolean`);
+	return value;
+}
+/**
+* 必填整数配置：缺键 / 非整数 / 越界一律 fail loud。
+* 默认值归模板与预设（组合源 yml 的 config 或本预设 moduleConfigs），引擎不兜底。
+*/
+function requiredInt(pluginName, value, field, minimum) {
+	if (!Number.isSafeInteger(value) || value < minimum) throw new TypeError(`${pluginName}: ${field} must be an integer >= ${minimum}`);
+	return value;
+}
 /** Validate the shared config envelope and unknown-key contract. */
 function validateConfig(pluginName, source, allowedKeys) {
 	const config = source === void 0 ? {} : source;
@@ -1279,6 +1323,34 @@ function sessionState(ctx, create, { weak = false, limit = MAX_TRACKED_SESSIONS,
 }
 //#endregion
 //#region engine/fields.mjs
+/**
+* fields — 配置字段类型系统（B2 配置契约统一的底座）。
+*
+* 把「每个模块自己写白名单、自己写归一化、自己决定缺省语义」收敛为
+* 「一份字段声明 + 一个校验运行时」：
+*
+*   const { allowedKeys, parse } = defineConfig({
+*     enabled: bool({ default: false }),
+*     envKeys: stringList({ trim: true, dedupe: true, message: '...', emptyMessage: '...' }),
+*   })
+*   const config = parse(source, name)   // 未知键 / 类型错 / 缺必填一律 fail loud
+*
+* 硬约束（B2）：**逐字段的校验结果与错误消息必须与迁移前逐字一致**，
+* 唯一允许的行为变更是 `enabled` 的 fail loud（见 PLAN T3）。因此：
+*   - 缺省语义由每个字段**显式声明**，不再有隐式 `undefined` / `[]` / `new Set()` 的混用；
+*   - 底层复用 shared.mjs 的既有 helper（`booleanOption` / `requiredInt` / `requiredText` /
+*     `validateConfig`），不复制它们的逻辑，默认消息也就自动逐字相同；
+*   - 模块需要用别的措辞时，用 `message` / `emptyMessage` 覆盖（模板里的 `{plugin}`、
+*     `{field}` 会被替换）。
+*
+* 字段类型与它替代的历史 helper：
+*   bool(...)        ← booleanOption                        （缺省 → default）
+*   int({min,...})   ← requiredInt / optionalPositiveInt     （required 缺键即抛）
+*   text(...)        ← requiredText / requiredStageField     （requiredText 的空串 → undefined）
+*   stringList(...)  ← nameSet / allowKindList / sourceList / deferredList / stringList /
+*                      stringListOrEmpty / normalizeEnvKeys（返回数组或 Set、可选 dedupe/trim）
+*   enumOf(...)      ← 枚举白名单（如 promoteOn 一族）
+*/
 /** 把 `{plugin}` / `{field}` 占位替换进消息模板。 */
 const format = (template, plugin, field) => String(template).replaceAll("{plugin}", plugin).replaceAll("{field}", field);
 /**
@@ -1292,6 +1364,41 @@ const makeField = (spec) => {
 	if (spec === null || typeof spec !== "object" || typeof spec.parse !== "function") throw new TypeError("fields: a field must be produced by bool()/int()/text()/stringList()/enumOf()");
 	return spec;
 };
+/** 布尔开关：缺省返回 default；非布尔一律 fail loud。 */
+function bool({ default: fallback = false, message } = {}) {
+	return makeField({
+		kind: "bool",
+		default: fallback,
+		parse: (value, plugin, field) => {
+			if (message === void 0) return booleanOption(plugin, value, field, resolveDefault(fallback));
+			if (value === void 0) return resolveDefault(fallback);
+			if (typeof value !== "boolean") throw new TypeError(format(message, plugin, field));
+			return value;
+		}
+	});
+}
+/**
+* 整数：`required: true` 时缺键即抛（消息与 shared.requiredInt 逐字一致）；
+* 否则缺键返回 default。`max` 只在声明了才检查。
+*/
+function int$2({ min = 0, default: fallback, required = false, message } = {}) {
+	if (!Number.isSafeInteger(min)) throw new TypeError("fields: int({min}) must be a safe integer");
+	return makeField({
+		kind: "int",
+		default: fallback,
+		parse: (value, plugin, field) => {
+			if (value === void 0) {
+				if (required) requiredInt(plugin, value, field, min);
+				return resolveDefault(fallback);
+			}
+			if (message !== void 0) {
+				if (!Number.isSafeInteger(value) || value < min) throw new TypeError(format(message, plugin, field));
+				return value;
+			}
+			return requiredInt(plugin, value, field, min);
+		}
+	});
+}
 /**
 * 字符串列表：
 *  - `required: true` 时缺键即抛；否则缺键返回 default（可给工厂，如 `() => new Set()`）；
@@ -1329,6 +1436,60 @@ function stringList$1({ required = false, default: fallback, dedupe = false, tri
 		}
 	});
 }
+/**
+* 直通字段：**只登记白名单**，值的归一化交给模块自己的 parse —— 用于旧代码里刻意存在的
+* 「非法值即静默取默认」语义（如 `typeof x === 'string' && x.length > 0 ? x : 默认值`）。
+* 换用严格字段类型会把这些静默降级变成挂载期报错，而那是 B2 未授权的行为变更，
+* 所以这类键一律用 passthrough 保住原语义，并在模块里注明依据。
+*/
+function passthrough(parse, { default: fallback } = {}) {
+	if (typeof parse !== "function") throw new TypeError("fields: passthrough(parse) requires a function");
+	return makeField({
+		kind: "passthrough",
+		default: fallback,
+		parse
+	});
+}
+/** 枚举：值必须落在 `values` 里；`required: true` 时缺键即抛。 */
+function enumOf(values, { default: fallback, required = false, message } = {}) {
+	const allowed = [...values];
+	if (allowed.length === 0) throw new TypeError("fields: enumOf(values) must not be empty");
+	const template = message ?? `{plugin}: {field} must be one of ${allowed.map((item) => JSON.stringify(item)).join(", ")}`;
+	return makeField({
+		kind: "enum",
+		default: fallback,
+		parse: (value, plugin, field) => {
+			if (value === void 0) {
+				if (required) throw new TypeError(format(template, plugin, field));
+				return resolveDefault(fallback);
+			}
+			if (!allowed.includes(value)) throw new TypeError(format(template, plugin, field));
+			return value;
+		}
+	});
+}
+/**
+* 由字段声明派生 `{ allowedKeys, parse }`：
+*  - `allowedKeys` 取代手写 `ALLOWED_KEYS`（未知键的报错格式沿用 shared.validateConfig）；
+*  - `parse(source, plugin)` 先做信封校验再逐字段归一化，返回**只含声明键**的对象。
+*/
+function defineConfig(fields) {
+	if (fields === null || typeof fields !== "object" || Array.isArray(fields)) throw new TypeError("fields: defineConfig(fields) requires an object of field declarations");
+	const entries = Object.entries(fields);
+	for (const [key, spec] of entries) makeField(spec);
+	const allowedKeys = new Set(entries.map(([key]) => key));
+	const parse = (source, plugin) => {
+		const config = validateConfig(plugin, source, allowedKeys);
+		const normalized = {};
+		for (const [key, spec] of entries) normalized[key] = spec.parse(config[key], plugin, key);
+		return normalized;
+	};
+	return {
+		allowedKeys,
+		parse,
+		fields
+	};
+}
 //#endregion
 //#region engine/actions/shared.mjs
 const RUN_CODE = "run_code";
@@ -1361,19 +1522,27 @@ function createMask(source, label, plugin, allowExtra) {
 		/** 动态白名单的落点（活集合，由调用方每轮重填）；未声明 allowFrom 时不存在。 */
 		allowExtra,
 		/**
-		* fail-open 兜底开关（**可选**，缺省 false）：原 `tool-bootstrap` 的语义是
-		* 「keep 名单里的工具在本次装配目录里一个都不存在 → 放弃裁剪、暴露完整目录」，而原
-		* `tool-filter` 的同名场景是**照名单裁成空目录**。两种语义都真实存在，所以这里
-		* **不设默认**——要兜底的声明自己写 `requireMatch: true`。把某一个模块的特有语义当成
-		* 通用默认，会让另一个声明路径的行为被悄悄改掉（这正是对拍抓出来的）。
+		* fail-open 兜底开关（**可选**，缺省 false）：判据是「这份名单与装配面整体错位」——
+		* 名单里的名字**一个都不存在**时放弃裁剪、暴露完整目录；部分缺失只留诊断，收窄照常
+		* 生效（提供方被替换或关闭是正常部署差异，见 {@link toolSurfacePlan}）。原
+		* `tool-bootstrap` 的同名语义就是「一个都不存在 → 放弃裁剪」，而原 `tool-filter` 是
+		* 「永远照名单裁」；两种语义都真实存在，所以这里**不设默认**——要兜底的声明自己写
+		* `requireMatch: true`。把某一个模块的特有语义当成通用默认，会让另一个声明路径的行为
+		* 被悄悄改掉（这正是对拍抓出来的）。
 		*/
 		requireMatch: source?.requireMatch === true,
-		/** 与 tool-filter 的名单判据 / Layer.admits 同一判据（tool-filter 模块已删除，判据保留）。 */
-		blocks: (toolName) => {
+		/**
+		* 与 tool-filter 的名单判据 / Layer.admits 同一判据（tool-filter 模块已删除，判据保留）。
+		*
+		* 第二个参数是**解锁项快照**：allowExtra 是跨 agent 共享的活集合，每次装配都会 clear 后
+		* 按当前会话重填；执行闸在该装配之后才被调用，必须读自己会话的冻结快照，否则别的会话
+		* （或探针装配）会把本会话的解锁名抹掉。缺省仍是活集合，供同一次装配内的裁剪使用。
+		*/
+		blocks: (toolName, extra = allowExtra) => {
 			if (typeof toolName !== "string" || toolName.length === 0) return false;
 			if (toolName === "run_code") return false;
 			if (deny !== void 0 && deny.has(toolName)) return true;
-			if (allowExtra?.has(toolName) === true) return false;
+			if (extra?.has(toolName) === true) return false;
 			return (allow !== void 0 || allowExtra !== void 0) && allow?.has(toolName) !== true;
 		}
 	};
@@ -1381,14 +1550,21 @@ function createMask(source, label, plugin, allowExtra) {
 /**
 * 工具可见面的单一判据：装配目录、`tools:sdk` 正文与执行闸共用同一份 fail-open 决定。
 *
-* `available` = 目录名 ∪ SDK 正文名；`required` = 静态 allow ∪ 动态解锁项，再剔掉
+* `available` = 目录名 ∪ SDK 正文名；`required` 只取**静态 allow**，再剔掉
 * `run_code`（保留传输）与 `mask.blocks()` 为真的名字（deny 覆盖者不该被要求存在）。
-* 缺项时三面必须一起放宽——只放宽一面会让模型看到的与能调的不一致。
+*
+* 放宽条件是「名单里的名字**一个都不存在**」：那才说明装配面与声明整体错位（换了一套
+* 部署/平台）。只缺一部分是提供方被替换或关掉的正常部署差异——照常收窄，缺的工具由发现
+* 通道补位，替换提供方的名字由部署层名单登记。解锁名（allowExtra）**不参与判定**：它是只做
+* 加法的提示，若参与，模型解锁一个拼错或已改名的工具就能关掉收窄。
+*
+* 放宽时三面必须一起放宽——只放宽一面会让模型看到的与能调的不一致。
 */
 function toolSurfacePlan(mask, available) {
-	const missing = (mask.requireMatch ? [.../* @__PURE__ */ new Set([...mask.allow ?? [], ...mask.allowExtra ?? []])].filter((name) => name !== "run_code" && !mask.blocks(name)) : []).filter((name) => !available.has(name));
+	const required = mask.requireMatch ? [...new Set(mask.allow ?? [])].filter((name) => name !== "run_code" && !mask.blocks(name)) : [];
+	const missing = required.filter((name) => !available.has(name));
 	return {
-		failOpen: missing.length > 0,
+		failOpen: required.length > 0 && missing.length === required.length,
 		missing
 	};
 }
@@ -1490,7 +1666,7 @@ const ACTION_KINDS = Object.freeze({
 		],
 		degrade: ACTION_DEGRADE.keep,
 		timing: "system-prompt/assemble 的下游结算之后：按当前条件重算目录、SDK 正文与执行闸；条件翻转时撤销上一轮注册的闸。",
-		note: "一份声明拥有工具的可见面：allow/deny 名单、requireMatch、发现工具。名单语义对齐官方 ToolRestriction 的 and/or（同时给时先按 allow 保留、再按 deny 剔除）。deny 走 guard（本层与晚到工具）与 restrict（继承的全局工具）；allow 只有 restrict 能覆盖全局工具，本层注册无法在执行层「只保留」——这是官方 restrict 的边界，不是本动作的取舍。"
+		note: "一份声明拥有工具的可见面：allow/deny 名单、requireMatch、发现工具。名单语义对齐官方 ToolRestriction 的 and/or（同时给时先按 allow 保留、再按 deny 剔除）。deny 走 guard（本层与晚到工具）与 restrict（继承的全局工具）；allow 只有 restrict 能覆盖全局工具，本层注册无法在执行层「只保留」——这是官方 restrict 的边界，不是本动作的取舍。requireMatch 表达「名单与装配面整体错位」：名单里的名字一个都不存在才整面放宽，部分缺失只留诊断；解锁名不参与判定。"
 	},
 	"request-params": {
 		title: "改模型请求参数",
@@ -7635,6 +7811,29 @@ function parse$1(src, reviver, options) {
 	return doc.toJS(Object.assign({ reviver: _reviver }, options));
 }
 //#endregion
+//#region engine/tool-scope.mjs
+/**
+* tool-scope — 工具面的作用域快照，避免各消费方把全局视图当成模型可见面。
+*
+* 返回两个字段，各自只服务一个调用方：
+* - visible：带 agent 的 `tools.schemas(agent)`，包含预设/祖先/本层工具；模型可见面。
+* - globalNames：不带 scope 的 `tools.schemas()` 名字集合；只供 `restrict` 过滤已知名。
+*
+* 全局原始 schema 与 visible-only 差集不外露；等真实诊断消费方出现再加字段。
+*/
+const schemaList = (tools, scope) => {
+	if (typeof tools?.schemas !== "function") return [];
+	const schemas = tools.schemas(scope);
+	return Array.isArray(schemas) ? schemas : [];
+};
+function toolScopeSnapshot(tools, agent) {
+	const global = schemaList(tools);
+	return {
+		visible: agent === void 0 ? global : schemaList(tools, agent),
+		globalNames: new Set(global.map((schema) => schema?.name).filter((name) => typeof name === "string"))
+	};
+}
+//#endregion
 //#region engine/machine-paths.mjs
 /**
 * 机器路径事实的**唯一取值来源**：`DSH_HOME` / `CWD` / `WORKSPACE` 三个键怎么推导，只在这里定。
@@ -8308,6 +8507,10 @@ function resolveRealWithin(target, roots, label = "path") {
 const PRE_STEP_COORDINATOR_SERVICE = "promptToolPreStep";
 /** 发现引擎注册表：宿主 root provide，adapter 行按 agent 注册，动作按 agent 解析。 */
 const DISCOVERY_SERVICE = "promptToolDiscovery";
+const SOUL_SELF_SERVICE = "promptToolSoulSelf";
+const SOUL_MAINTENANCE_SERVICE = "promptToolSoulMaintenance";
+/** 模块清单 checks 事实：宿主提供，宿主装配读取后经挂载 options 传给谓词。 */
+const MANIFEST_CHECK_SERVICE = "promptToolManifestCheck";
 /** 五个模块工具外壳的服务名：`pt-<引擎模块 id>`。前缀是本函数的内部细节。 */
 function toolServiceName(engineModuleId) {
 	return `pt-${engineModuleId}`;
@@ -8476,14 +8679,29 @@ function createInstructionHintResolver(config = {}) {
 //#region engine/fillers.mjs
 /**
 * fillers — 引擎内置的动态填充器(strategy=placeholder 的数据源)。
-* 全部遵循同一铁律:服务缺失或列表失败时返回 null(跳过该配置),绝不伤及会话。
+* 按本次求值读取宿主能力；失败由填充器或调用方诊断并跳过该配置。
 */
 const name$5 = "prompt-config-engine";
 function explicitTemplate(config) {
 	const texts = Array.isArray(config.texts) ? config.texts : typeof config.text === "string" ? [config.text] : [];
 	return texts.length > 0 ? texts.join("\n\n") : typeof config.params?.text === "string" ? config.params.text : "";
 }
-/** 只读同规则工具面声明；文案、条件和投递仍归普通注入动作。 */
+/**
+* 只读同规则工具面声明；文案、条件和投递仍归普通注入动作。
+* RESIDENT_TOOLS 只列**当前可见**的常驻工具：部署层名单可以登记替换提供方（如 dsh-ops 的
+* ops_bash），但该插件未必安装；向模型宣告一个不存在的常驻工具会把「解锁」变成错误前提。
+* 观测到工具面但一个常驻名都不在时（requireMatch 全缺/放宽场景）跳过提示；
+* 观测不到工具面（服务缺失或读取失败）才回落声明名单——「没看到」不等于「都没有」。
+*/
+function visibleToolNames(ctx, agent) {
+	try {
+		const tools = getService(ctx, "tools");
+		if (tools === void 0 || typeof tools.schemas !== "function") return void 0;
+		return new Set(toolScopeSnapshot(tools, agent).visible.map((schema) => schema?.name));
+	} catch {
+		return;
+	}
+}
 function createToolCatalogResolver(config) {
 	if (config.params?.templateEvaluation === true) throw new TypeError("tool-catalog is read-only and does not support templateEvaluation");
 	if (typeof config.params?.action !== "string" || config.params.action.trim().length === 0) throw new TypeError("tool-catalog requires params.action referencing a tool-visibility action");
@@ -8493,9 +8711,16 @@ function createToolCatalogResolver(config) {
 		const source = config.toolCatalogSource;
 		if (source === void 0) throw new TypeError("tool-catalog requires a same-rule tool-visibility action");
 		const deny = new Set(source.deny ?? []);
-		const resident = [...new Set(source.allow)].filter((tool) => !deny.has(tool));
+		const declared = [...new Set(source.allow)].filter((tool) => !deny.has(tool));
 		const adapter = source.discovery === void 0 ? void 0 : getService(ctx, DISCOVERY_SERVICE)?.get?.(agent, source.discovery.kind);
 		if (source.discovery !== void 0 && typeof adapter?.tool !== "string") throw new Error(`tool-catalog discovery adapter ${source.discovery.kind} is unavailable`);
+		let resident = declared;
+		const visible = visibleToolNames(ctx, agent);
+		if (visible !== void 0) {
+			const present = declared.filter((name) => visible.has(name));
+			if (present.length === 0) return null;
+			resident = present;
+		}
 		return {
 			text,
 			variables: {
@@ -8632,12 +8857,20 @@ function createSkillCatalogResolver(config) {
 		}
 	};
 }
+function createSoulSelfResolver(config) {
+	return ({ ctx, agent, signal }) => {
+		const service = getService(ctx, SOUL_SELF_SERVICE);
+		if (typeof service?.render !== "function") throw new Error("SELF dependency missing");
+		return { text: service.render(config.sourceModuleId, agent, signal) };
+	};
+}
 /** 动态填充器:strategy=placeholder 时按 fill 键在注入点填充内容。 */
 const FILLERS = {
 	"instruction-hint": (config) => createInstructionHintResolver(config),
 	"env-facts": (config) => createEnvFactsResolver(config),
 	"skill-catalog": (config) => createSkillCatalogResolver(config),
-	"tool-catalog": (config) => createToolCatalogResolver(config)
+	"tool-catalog": (config) => createToolCatalogResolver(config),
+	"soul-self": (config) => createSoulSelfResolver(config)
 };
 function createPlaceholderResolver(config) {
 	const make = FILLERS[config.fill];
@@ -9087,7 +9320,8 @@ const KNOWN_FILLS = /* @__PURE__ */ new Set([
 	"instruction-hint",
 	"env-facts",
 	"skill-catalog",
-	"tool-catalog"
+	"tool-catalog",
+	"soul-self"
 ]);
 /** 层能力矩阵：每个字段只在对应注入层生效。客户端表单据此动态渲染。 */
 const LAYER_FIELD_POLICIES = Object.fromEntries(LAYER_DEFINITIONS.map((definition) => [definition.layer, definition.fields]));
@@ -10347,7 +10581,7 @@ function textLayerGroups(configs) {
 	return groups;
 }
 /** system-section:注册静态 system prompt 段(支持官方 {{variable}} 渲染与 merged 拼接)。 */
-function wireSystemSections(ctx, configs, registry, warnOnce, keep, ordered) {
+function wireSystemSections(ctx, configs, registry, warnOnce, keep, ordered, sourceError) {
 	const systemPrompt = getService(ctx, "systemPrompt");
 	if (systemPrompt === void 0 || typeof systemPrompt.section !== "function") {
 		if (configs.length > 0) warnOnce(`${name$2}: systemPrompt service unavailable — system-section configs skipped`);
@@ -10370,6 +10604,7 @@ function wireSystemSections(ctx, configs, registry, warnOnce, keep, ordered) {
 			ordered.sections.push(orderedEntry(entryName, base));
 			if (base.params?.suppressRuntimeContext === true) keep(systemPrompt.suppressRuntimeContext(), `${name$2}: suppressRuntimeContext ${base.id}`);
 		} catch (error) {
+			if (sourceError !== void 0) throw sourceError(error, base.sourceModuleId);
 			warnOnce(`${name$2}: system-section config ${base.id} failed: ${String(error?.message ?? error)}`);
 		}
 	}
@@ -10406,7 +10641,7 @@ async function resolvedContextText(ctx, config, context, registry, warnOnce) {
 	return officialChannelText(config.texts.length > 0 ? interpolateVariables(config.texts.join("\n\n"), variables, session, void 0, config.id) : typeof resolved.text === "string" ? interpolateVariables(resolved.text, variables, session, void 0, config.id) : "", `runtime-context ${config.id}`, registry, warnOnce);
 }
 /** 条件化文本保留官方排序占位；仅在本次真实 assembly 填充，不缓存 context 身份。 */
-function wireRuleTextContributions(ctx, configs, registry, warnOnce, keep, on, ordered) {
+function wireRuleTextContributions(ctx, configs, registry, warnOnce, keep, on, ordered, sourceError) {
 	if (!configs.length) return [];
 	const systemPrompt = getService(ctx, "systemPrompt");
 	if (systemPrompt === void 0) {
@@ -10421,15 +10656,32 @@ function wireRuleTextContributions(ctx, configs, registry, warnOnce, keep, on, o
 		const section = layer === "system-section";
 		const base = group[0];
 		const entryName = textRegistrationName(base, section ? "sectionName" : "contextName");
-		keep(systemPrompt[section ? "section" : "context"]({
-			name: entryName,
-			order: base.order,
-			text: marker
-		}), `${name$2}: conditional ${entryName}`);
+		const holders = section ? void 0 : /* @__PURE__ */ new WeakMap();
+		const sharedHolder = section ? void 0 : { text: "" };
+		const holderOf = section ? void 0 : (context) => {
+			const key = context?.agent;
+			if (key === void 0 || key === null) return sharedHolder;
+			let holder = holders.get(key);
+			if (holder === void 0) {
+				holder = { text: "" };
+				holders.set(key, holder);
+			}
+			return holder;
+		};
+		try {
+			keep(systemPrompt[section ? "section" : "context"]({
+				name: entryName,
+				order: base.order,
+				text: section ? marker : (context) => holderOf(context).text
+			}), `${name$2}: conditional ${entryName}`);
+		} catch (error) {
+			throw sourceError === void 0 ? error : sourceError(error, base.sourceModuleId);
+		}
 		bindings.push({
 			group,
 			name: entryName,
-			collection: section ? "sections" : "contexts"
+			collection: section ? "sections" : "contexts",
+			holderOf
 		});
 		ordered[section ? "sections" : "contexts"].push(orderedEntry(entryName, base));
 	}
@@ -10440,9 +10692,11 @@ function wireRuleTextContributions(ctx, configs, registry, warnOnce, keep, on, o
 	return [on("system-prompt/assemble", async (assembly, context, next, invocation) => {
 		const frame = invocation ?? ruleFrame("system-prompt/assemble", [assembly, context], warnOnce);
 		for (const binding of bindings) {
-			const entry = assembly[binding.collection].find((item) => item.name === binding.name && item.text === marker);
+			const entry = binding.collection === "sections" ? assembly.sections.find((item) => item.name === binding.name && item.text === marker) : assembly.contexts.find((item) => item.name === binding.name);
 			if (entry === void 0) continue;
+			const holder = binding.holderOf === void 0 ? void 0 : binding.holderOf(context);
 			entry.text = "";
+			if (holder !== void 0) holder.text = "";
 			const blocks = [];
 			for (const config of binding.group) {
 				if (!active || context.signal?.aborted || !actionMatches(config, frame) || !matchesAgentScope(config, context.agent)) continue;
@@ -10453,13 +10707,16 @@ function wireRuleTextContributions(ctx, configs, registry, warnOnce, keep, on, o
 					warnOnce(`${name$2}: rule text ${config.id} failed: ${String(error?.message ?? error)}`);
 				}
 			}
-			if (active && !context.signal?.aborted) entry.text = blocks.join("\n\n");
+			if (active && !context.signal?.aborted) {
+				entry.text = blocks.join("\n\n");
+				if (holder !== void 0) holder.text = entry.text;
+			}
 		}
 		return next();
 	})];
 }
 /** runtime-context:注册运行时上下文；静态文本支持 merged，动态策略在官方 assembly waterfall 中填充。 */
-function wireRuntimeContexts(ctx, configs, registry, warnOnce, keep, on, ordered) {
+function wireRuntimeContexts(ctx, configs, registry, warnOnce, keep, on, ordered, sourceError) {
 	const disposers = [];
 	const systemPrompt = getService(ctx, "systemPrompt");
 	if (systemPrompt === void 0 || typeof systemPrompt.context !== "function") {
@@ -10483,41 +10740,60 @@ function wireRuntimeContexts(ctx, configs, registry, warnOnce, keep, on, ordered
 			}), `${name$2}: context ${base.id}`);
 			ordered.contexts.push(orderedEntry(entryName, base));
 		} catch (error) {
+			if (sourceError !== void 0) throw sourceError(error, base.sourceModuleId);
 			if (base.linkedDelivery) throw error;
 			warnOnce(`${name$2}: runtime-context config ${base.id} failed: ${String(error?.message ?? error)}`);
 		}
 	}
 	const placeholders = configs.filter(needsResolver).sort(compareTextPlacement);
 	if (placeholders.length === 0) return disposers;
-	const slotVariable = `pt_runtime_${newMessageId("context").replace(/[^a-z0-9_]/gi, "_").toLowerCase()}`;
-	const slotText = `{{${slotVariable}}}`;
 	const registered = /* @__PURE__ */ new Map();
 	let active = true;
 	keep(() => {
 		active = false;
 	}, `${name$2}: runtime-context lifecycle`);
-	keep(systemPrompt.variable(slotVariable, () => ""), `${name$2}: runtime-context placeholder`);
 	for (const config of placeholders) try {
 		const contextName = textRegistrationName(config, "contextName");
+		const holders = /* @__PURE__ */ new WeakMap();
+		const sharedHolder = { text: "" };
+		const holderOf = (context) => {
+			const key = context?.agent;
+			if (key === void 0 || key === null) return sharedHolder;
+			let holder = holders.get(key);
+			if (holder === void 0) {
+				holder = { text: "" };
+				holders.set(key, holder);
+			}
+			return holder;
+		};
 		keep(systemPrompt.context({
 			name: contextName,
 			order: config.order,
-			text: slotText
+			text: (context) => holderOf(context).text
 		}), `${name$2}: context ${config.id}`);
-		registered.set(contextName, config);
+		registered.set(contextName, {
+			config,
+			holderOf
+		});
 		ordered.contexts.push(orderedEntry(contextName, config));
 	} catch (error) {
+		if (sourceError !== void 0) throw sourceError(error, config.sourceModuleId);
 		warnOnce(`${name$2}: runtime-context placeholder ${config.id} failed: ${String(error?.message ?? error)}`);
 	}
 	disposers.push(on("system-prompt/assemble", async (assembly, context, next) => {
-		const entries = assembly.contexts.filter((entry) => registered.has(entry.name) && entry.text === slotText);
+		const entries = assembly.contexts.filter((entry) => registered.has(entry.name));
 		for (const entry of entries) {
-			const config = registered.get(entry.name);
+			const { config, holderOf } = registered.get(entry.name);
+			const holder = holderOf(context);
 			entry.text = "";
+			holder.text = "";
 			if (!active || context.signal?.aborted) continue;
 			try {
 				const text = await resolvedContextText(ctx, config, context, registry.get(config), warnOnce);
-				if (active && !context.signal?.aborted) entry.text = text;
+				if (active && !context.signal?.aborted) {
+					entry.text = text;
+					holder.text = text;
+				}
 			} catch (error) {
 				warnOnce(`${name$2}: runtime-context ${config.id} resolve failed: ${String(error?.message ?? error)}`);
 			}
@@ -10848,9 +11124,9 @@ function wireLayers(ctx, configs, warnOnce, options = {}) {
 		const registry = registerOfficialVariables(ctx, configs.filter((config) => config.layer === "system-section" || config.layer === "runtime-context"), warnOnce, keep);
 		const conditional = configs.filter((config) => ["system-section", "runtime-context"].includes(config.layer) && (typeof config.rule?.when === "function" || typeof config.actionWhen === "function" || (config.rule !== void 0 || config.params?.templateEvaluation === true) && config.params?.complete !== true && config.params?.suppressRuntimeContext !== true));
 		const regular = configs.filter((config) => !conditional.includes(config));
-		wireSystemSections(ctx, regular.filter((config) => config.layer === "system-section"), registry, warnOnce, keep, ordered);
-		wireRuntimeContexts(ctx, regular.filter((config) => config.layer === "runtime-context"), registry, warnOnce, keep, on, ordered);
-		wireRuleTextContributions(ctx, conditional, registry, warnOnce, keep, on, ordered);
+		wireSystemSections(ctx, regular.filter((config) => config.layer === "system-section"), registry, warnOnce, keep, ordered, options.sourceError);
+		wireRuntimeContexts(ctx, regular.filter((config) => config.layer === "runtime-context"), registry, warnOnce, keep, on, ordered, options.sourceError);
+		wireRuleTextContributions(ctx, conditional, registry, warnOnce, keep, on, ordered, options.sourceError);
 		wireTurnStops(ctx, configs.filter((config) => config.layer === "turn-stop"), warnOnce, on, options.turnStopBudgets);
 		wireSubagentEvents(ctx, configs.filter((config) => config.layer === "subagent-start" || config.layer === "subagent-end"), warnOnce, on);
 		for (const collection of ["sections", "contexts"]) registerDeliveryOrder(ctx, keep, collection, orderedNamesOf(ordered[collection]));
@@ -12777,29 +13053,6 @@ function stripSdkDeclarations(text, names) {
 	}
 }
 //#endregion
-//#region engine/tool-scope.mjs
-/**
-* tool-scope — 工具面的作用域快照，避免各消费方把全局视图当成模型可见面。
-*
-* 返回两个字段，各自只服务一个调用方：
-* - visible：带 agent 的 `tools.schemas(agent)`，包含预设/祖先/本层工具；模型可见面。
-* - globalNames：不带 scope 的 `tools.schemas()` 名字集合；只供 `restrict` 过滤已知名。
-*
-* 全局原始 schema 与 visible-only 差集不外露；等真实诊断消费方出现再加字段。
-*/
-const schemaList = (tools, scope) => {
-	if (typeof tools?.schemas !== "function") return [];
-	const schemas = tools.schemas(scope);
-	return Array.isArray(schemas) ? schemas : [];
-};
-function toolScopeSnapshot(tools, agent) {
-	const global = schemaList(tools);
-	return {
-		visible: agent === void 0 ? global : schemaList(tools, agent),
-		globalNames: new Set(global.map((schema) => schema?.name).filter((name) => typeof name === "string"))
-	};
-}
-//#endregion
 //#region engine/discovery.mjs
 /**
 * discovery —— 发现引擎：搜索、排序、截断渲染与「适配器注册表」的唯一实现。
@@ -12902,8 +13155,10 @@ function assertDiscoveryRows(rules, moduleIds, moduleId) {
 *
 * 名单语义对齐官方 ToolRestriction（deepseek-harness packages/core/tools/src/index.ts:701-706）：
 * allow 与 deny 可以同时给，判据是「先按 allow 保留，再按 deny 剔除」。requireMatch 只在
-* allow 模式有意义：名单里任一工具在目录与 SDK 正文的并集里都找不到，就放弃裁剪、暴露完整目录（fail-open）并告警——
-* 收窄错了会让当前工作流调不到工具，比多花上下文严重。
+* allow 模式有意义，判据是「这份名单与装配面整体错位」：名单里的名字**一个都不在**目录与
+* SDK 正文的并集里，才放弃裁剪、暴露完整目录（fail-open）并告警。只缺一部分是提供方被
+* 替换或关闭的正常部署差异，收窄照常生效、缺项只留一条诊断；解锁名是只做加法的提示，
+* 不参与这个判定。
 *
 * 执行边界：deny 同时用 restrict（继承面）与 guard（本层/晚到）；allow 不用 restrict——
 * 它的 allow 只能收继承面名字，而 `schemas()` 全局视图会漏掉预设/祖先层，局部 allow 会
@@ -12972,7 +13227,10 @@ function prepareToolVisibility(action, plugin) {
 		const capability = createAgentCapability((agent) => {
 			const tools = agent?.ctx?.tools;
 			if (tools === void 0) return void 0;
-			const state = { failOpen: false };
+			const state = {
+				failOpen: false,
+				unlocked: void 0
+			};
 			const disposers = [];
 			try {
 				const known = toolScopeSnapshot(tools).globalNames;
@@ -12991,7 +13249,10 @@ function prepareToolVisibility(action, plugin) {
 						const toolName = exec?.name;
 						if (toolName === "run_code" || typeof toolName !== "string" || toolName.length === 0) return void 0;
 						if (deny?.has(toolName)) return `${label}: tool ${JSON.stringify(toolName)} is denied by tool-visibility`;
-						if (mask.allow !== void 0 && !state.failOpen && mask.blocks(toolName)) return `${label}: tool ${JSON.stringify(toolName)} is not allowed by tool-visibility`;
+						if (mask.allow !== void 0 && !state.failOpen && mask.blocks(toolName, state.unlocked)) {
+							const hint = discovery === void 0 ? "the allow list is the only path; this action has no discovery source" : `unlock it with tool_search({"toolNames":[${JSON.stringify(toolName)}]}); the gate allows unlocked tools from the next request on`;
+							return `${label}: tool ${JSON.stringify(toolName)} is not allowed by tool-visibility; ${hint}`;
+						}
 					}));
 				}
 			} catch (error) {
@@ -13002,8 +13263,8 @@ function prepareToolVisibility(action, plugin) {
 				data: state
 			};
 		});
-		const syncGate = (agent) => {
-			const key = `${maskKey(mask)}|unlock:${allowExtra === void 0 ? "" : [...allowExtra].sort().join(",")}`;
+		const syncGate = (agent, unlocked) => {
+			const key = `${maskKey(mask)}|unlock:${unlocked === void 0 ? "" : [...unlocked].sort().join(",")}`;
 			capability.sync(agent, key);
 		};
 		collect(capability.releaseAll);
@@ -13026,8 +13287,9 @@ function prepareToolVisibility(action, plugin) {
 					fillUnlocked(allowExtra, context?.session ?? context?.agent?.session, unlock.tool, unlock.key, warnOnce, plugin, label);
 				}
 			}
+			const unlocked = allowExtra === void 0 ? void 0 : new Set(allowExtra);
 			try {
-				syncGate(context?.agent);
+				syncGate(context?.agent, unlocked);
 			} catch (error) {
 				warnOnce(`${plugin}: tool-visibility action ${label} failed to sync execution gate: ${String(error?.message ?? error)}`);
 			}
@@ -13039,11 +13301,15 @@ function prepareToolVisibility(action, plugin) {
 				if (!Array.isArray(result.tools) && sdkSection === void 0) return result;
 				const plan = toolSurfacePlan(mask, available);
 				const state = capability.get(context?.session ?? context?.agent?.session);
-				if (state !== void 0) state.data.failOpen = plan.failOpen;
-				if (plan.failOpen) warnOnce(`${plugin}: tool-visibility action ${label}: requireMatch tools absent (${plan.missing.join(", ")}) — exposing the full tool set (fail-open)`, `${plugin}: tool-visibility action ${label}: requireMatch fail-open`);
+				if (state !== void 0) {
+					state.data.failOpen = plan.failOpen;
+					state.data.unlocked = unlocked;
+				}
+				if (plan.failOpen) warnOnce(`${plugin}: tool-visibility action ${label}: none of the resident tools exist (${plan.missing.join(", ")}) — exposing the full tool set (fail-open)`, `${plugin}: tool-visibility action ${label}: requireMatch fail-open`);
 				else {
+					if (plan.missing.length > 0) warnOnce(`${plugin}: tool-visibility action ${label}: resident tools absent (${plan.missing.join(", ")}) — narrowing continues; register replacement providers in the deployment allow list`, `${plugin}: tool-visibility action ${label}: resident tools absent`);
 					if (Array.isArray(result.tools)) {
-						const kept = result.tools.filter((tool) => !mask.blocks(tool?.name));
+						const kept = result.tools.filter((tool) => !mask.blocks(tool?.name, unlocked));
 						if (kept.length !== result.tools.length) result = {
 							...result,
 							tools: kept
@@ -13058,7 +13324,7 @@ function prepareToolVisibility(action, plugin) {
 								present ??= new Set(sdkToolNames(section.text));
 								return present;
 							};
-							const names = mask.allow === void 0 ? mask.deny : new Set([...presentNames()].filter((name) => mask.blocks(name)));
+							const names = mask.allow === void 0 ? mask.deny : new Set([...presentNames()].filter((name) => mask.blocks(name, unlocked)));
 							if (names === void 0 || names.size === 0) return section;
 							const stripped = stripSdkDeclarations(section.text, names);
 							if (stripped === section.text) return section;
@@ -13152,22 +13418,27 @@ function prepareAction(action, options = {}) {
 			} catch {}
 		};
 		const on = withWhen(options.on ?? channelBinder(ctx, kind, plugin, options.prepend === true), options.when, warnOnce, phase, missAll);
-		if (budget !== void 0) collect(ctx.on("session/event", (session, event) => budget.observe(session, event)));
 		const take = (subject) => budget?.take(subject) ?? true;
-		bind?.(ctx, {
-			warnOnce,
-			on,
-			collect,
-			take,
-			onMiss,
-			agent: options.agent
-		});
 		const dispose = () => {
 			for (const release of disposers.splice(0)) try {
 				release();
 			} catch {}
 		};
-		keepDisposer(ctx, dispose, `${plugin}: action ${labelOf(action)}`);
+		try {
+			if (budget !== void 0) collect(ctx.on("session/event", (session, event) => budget.observe(session, event)));
+			bind?.(ctx, {
+				warnOnce,
+				on,
+				collect,
+				take,
+				onMiss,
+				agent: options.agent
+			});
+			keepDisposer(ctx, dispose, `${plugin}: action ${labelOf(action)}`);
+		} catch (error) {
+			dispose();
+			throw error;
+		}
 		dispose.miss = missHandlers.length === 0 ? void 0 : missAll;
 		return dispose;
 	};
@@ -13563,6 +13834,12 @@ function resolveHostPackage(id, entry, self) {
 async function importHostPackage(id, entry, self) {
 	return import(pathToFileURL(resolveHostPackage(id, entry, self)).href);
 }
+Object.freeze([
+	"@deepseek-ai/dsh-compaction-basic",
+	"@deepseek-ai/dsh-compaction-tool-result-pruner",
+	"@deepseek-ai/dsh-compaction",
+	"@deepseek-ai/dsh-llm"
+]);
 //#endregion
 //#region engine/conditions/preset.mjs
 const AGENT_PRESETS_PACKAGE = "@deepseek-ai/dsh-agent-preset-registry";
@@ -13836,6 +14113,34 @@ function createVariablePredicate(options = {}, context = {}) {
 	return predicate;
 }
 //#endregion
+//#region engine/conditions/manifest.mjs
+/**
+* manifest 谓词：规则读取来源模块 `assets/manifest.yml` 的 checks 事实。
+*
+* 读取器由宿主装配经 options 在挂载期绑定，结果缓存 1000ms，清单戳变化提前失效；
+* 读取器缺失、清单缺失/损坏都判 UNAVAILABLE——不能经 not 反转，也不能当「检查失败」。
+*/
+/**
+* @param {{ ok?: boolean }} options
+* @param {{ manifestCheck?: { read: (moduleId: string) => boolean | undefined }, moduleId?: string }} [context]
+*/
+function createManifestPredicate(options = {}, context = {}) {
+	const unknown = Object.keys(options).filter((key) => key !== "ok");
+	if (unknown.length > 0) throw new TypeError(`predicates: manifest does not take ${unknown.join(", ")}`);
+	if (typeof options.ok !== "boolean") throw new TypeError("predicates: manifest ok must be a boolean");
+	const expected = options.ok;
+	const reader = context.manifestCheck;
+	const moduleId = context.moduleId;
+	const predicate = () => {
+		if (reader === void 0 || typeof reader.read !== "function") return UNAVAILABLE;
+		if (typeof moduleId !== "string" || moduleId.length === 0) return UNAVAILABLE;
+		const observed = reader.read(moduleId);
+		return typeof observed === "boolean" ? observed === expected : UNAVAILABLE;
+	};
+	predicate.kind = "manifest";
+	return predicate;
+}
+//#endregion
 //#region engine/conditions/operators.mjs
 /** 条件树组合算子的唯一清单：纯 ESM，无宿主 import，client 可打包。 */
 const COMPOSITE_OPERATORS = Object.freeze(Object.values(MATCH_LOGIC));
@@ -13911,7 +14216,8 @@ const PREDICATE_FACTORIES = Object.freeze({
 	preset: createPresetPredicate,
 	scope: createScopePredicate,
 	anchor: createAnchorPredicate,
-	variable: createVariablePredicate
+	variable: createVariablePredicate,
+	manifest: createManifestPredicate
 });
 const objectOrUndefined = (value, label) => {
 	if (value === void 0 || value === null) return void 0;
@@ -13948,6 +14254,10 @@ function compileWhen(node, context = {}) {
 		store: context.variableStore,
 		moduleId: context.moduleId
 	});
+	if (key === "manifest") return createManifestPredicate(options, {
+		manifestCheck: context.manifestCheck,
+		moduleId: context.moduleId
+	});
 	return withAvailableInput(key, options, factory(options));
 }
 //#endregion
@@ -14061,7 +14371,8 @@ const PREDICATE_EXAMPLES = {
 		op: "lte",
 		value: "0",
 		scope: "effective"
-	}
+	},
+	manifest: { ok: true }
 };
 //#endregion
 //#region engine/record.mjs
@@ -14489,7 +14800,7 @@ function normalizeActionGates(action, execution) {
 /** options.promptConfigOptions 拥有模板/策略路径；configOrder 使用规则 id，moduleId 只标记来源。 */
 function compileRules(specs, options = {}) {
 	if (!Array.isArray(specs)) throw new TypeError("rules must be an array");
-	const { ctx: _ctx, standingMountFor: _standingMountFor, variableStore: _variableStore, ...conditionOptions } = options;
+	const { ctx: _ctx, standingMountFor: _standingMountFor, variableStore: _variableStore, manifestCheck: _manifestCheck, ...conditionOptions } = options;
 	const ids = /* @__PURE__ */ new Set();
 	const pendingConfigs = [];
 	const moduleId = options.moduleId ?? options.sourceModuleId;
@@ -14649,6 +14960,7 @@ function needsMountContext(node) {
 	if (Array.isArray(node)) return node.some(needsMountContext);
 	if (Object.hasOwn(node, "preset")) return true;
 	if (Object.hasOwn(node, "variable")) return true;
+	if (Object.hasOwn(node, "manifest")) return true;
 	if (Object.hasOwn(node, "phase") && node.phase?.subscribe !== false) return true;
 	if (node.anchor?.after !== void 0) return true;
 	return Object.values(node).some(needsMountContext);
@@ -14743,7 +15055,7 @@ function stable(value) {
 	if (Array.isArray(value)) return value.map(stable);
 	return record$7(value) ? Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])])) : value;
 }
-const digest = (value) => revisionOf$4(JSON.stringify(stable(value)));
+const digest$2 = (value) => revisionOf$4(JSON.stringify(stable(value)));
 const yaml = (value) => new Document(value).toString();
 /** 两级持久变量共用边界；错误只标识键，不输出变量内容。 */
 function assertVariableValues(value) {
@@ -14858,7 +15170,7 @@ function projection(source, directory, sourceRevision, validation = {}) {
 			...exclusive === void 0 ? {} : { exclusive }
 		};
 		files[`${rule.id}.yml`] = yaml(content);
-		ruleRevisions[rule.id] = digest(content);
+		ruleRevisions[rule.id] = digest$2(content);
 	}
 	files[RULES_VARIABLES_FILE] = yaml(variables);
 	const state = {
@@ -14867,8 +15179,8 @@ function projection(source, directory, sourceRevision, validation = {}) {
 	};
 	const revisions = {
 		rules: ruleRevisions,
-		settings: digest(state),
-		variables: digest(variables)
+		settings: digest$2(state),
+		variables: digest$2(variables)
 	};
 	files[RULES_SETTINGS_FILE] = yaml({
 		...state,
@@ -19945,6 +20257,36 @@ function createBridgeRuntime(options) {
 		publicationPending: pendingVariableSettings.has(dir),
 		...pendingVariableSettings.has(dir) ? { publicationError: pendingVariableSettings.get(dir) } : {}
 	});
+	const refreshVariableSettings = async (dir) => {
+		if (!pendingVariableSettings.has(dir)) return;
+		try {
+			await deps.overridesChanged?.(basename(dir));
+			pendingVariableSettings.delete(dir);
+		} catch (error) {
+			pendingVariableSettings.set(dir, `变量开关已保存，但运行发布失败：${String(error)}`);
+		}
+	};
+	const saveVariables = async (dir, request) => {
+		const settingsChanged = request.enabled !== void 0 && request.enabled !== loadModuleDefinition(dir).variablesEnabled;
+		const committed = editModuleVariables(dir, request);
+		if (settingsChanged) pendingVariableSettings.set(dir, "变量开关已保存，等待运行发布");
+		if (committed.publicationPending) return {
+			...committed,
+			...published(committed.publicationError ?? "变量已保存，等待运行发布")
+		};
+		if (settingsChanged) await refreshVariableSettings(dir);
+		return {
+			...committed,
+			...published(pendingVariableSettings.get(dir))
+		};
+	};
+	const refreshVariables = async (dir) => {
+		await refreshVariableSettings(dir);
+		return {
+			...variableView(dir),
+			...published(pendingVariableSettings.get(dir))
+		};
+	};
 	return {
 		deps,
 		ns,
@@ -19969,7 +20311,6 @@ function createBridgeRuntime(options) {
 		},
 		capabilityQueue: createSerialQueue(),
 		moduleOrderQueue: createSerialQueue(),
-		pendingVariableSettings,
 		finishModuleChange,
 		runOverridesChange,
 		refreshModuleList,
@@ -19979,7 +20320,9 @@ function createBridgeRuntime(options) {
 		collectDescribeExtras,
 		readParamOverrides,
 		readParamEffective,
-		variableView
+		variableView,
+		saveVariables,
+		refreshVariables
 	};
 }
 //#endregion
@@ -22432,18 +22775,9 @@ function registerParams(runtime) {
 			if (record.refreshOnly === true) {
 				if (runtime.gate(tx, "moduleVariables").authorize() === void 0) return;
 				if (typeof record.expectedModuleId !== "string") throw new ModuleWriteError("刷新变量必须提供 expectedModuleId");
-				if (runtime.pendingVariableSettings.has(dir)) try {
-					await runtime.deps.overridesChanged?.(basename(dir));
-					runtime.pendingVariableSettings.delete(dir);
-				} catch (error) {
-					runtime.pendingVariableSettings.set(dir, `变量开关已保存，但运行发布失败：${String(error)}`);
-				}
 				tx.write(200, {
 					ok: true,
-					value: {
-						...runtime.variableView(dir),
-						...published(runtime.pendingVariableSettings.get(dir))
-					}
+					value: await runtime.refreshVariables(dir)
 				});
 				return;
 			}
@@ -22464,36 +22798,15 @@ function registerParams(runtime) {
 				module: definition.revisions.variables,
 				...record.enabled === void 0 ? {} : { settings: definition.revisions.settings }
 			};
-			const settingsChanged = record.enabled !== void 0 && record.enabled !== loadModuleDefinition(dir).variablesEnabled;
-			const committed = editModuleVariables(dir, {
+			const committed = await runtime.saveVariables(dir, {
 				scope: record.scope,
 				expectedRevisions,
 				...record.variables === void 0 ? {} : { values: record.variables },
 				...record.enabled === void 0 ? {} : { enabled: record.enabled }
 			});
-			if (settingsChanged) runtime.pendingVariableSettings.set(dir, "变量开关已保存，等待运行发布");
-			if (committed.publicationPending) {
-				tx.write(200, {
-					ok: true,
-					value: {
-						...committed,
-						...published(committed.publicationError ?? "变量已保存，等待运行发布")
-					}
-				});
-				return;
-			}
-			if (settingsChanged) try {
-				await runtime.deps.overridesChanged?.(basename(dir));
-				runtime.pendingVariableSettings.delete(dir);
-			} catch (error) {
-				runtime.pendingVariableSettings.set(dir, `变量开关已保存，但运行发布失败：${String(error)}`);
-			}
 			tx.write(200, {
 				ok: true,
-				value: {
-					...committed,
-					...published(runtime.pendingVariableSettings.get(dir))
-				}
+				value: committed
 			});
 		} catch (error) {
 			if (error instanceof ModuleWriteError && error.persisted) {
@@ -25708,6 +26021,7 @@ function readModuleFile(moduleDir, path) {
 * data/ 目录缺失时只建这一级；单次 1 MiB、账本文件 8 MiB。
 */
 function appendModuleLine(moduleDir, path, line) {
+	if (["data/02-soul.jsonl", "data/02-墨.jsonl"].includes(path.normalize("NFC").toLowerCase())) throw new Error("账本只能通过 soul_ledger 追加，不能使用通用文件接口");
 	if (typeof line !== "string") throw new TypeError("追加内容必须是字符串");
 	const isMemory = path === "memory.md";
 	if (!isMemory && !path.startsWith("data/")) throw new Error(`只能追加到 memory.md 或 data/：${path}`);
@@ -25855,7 +26169,7 @@ function stringList(value, label) {
 	if (!Array.isArray(value) || value.some((item) => !nonempty(item))) throw new Error(`assets/manifest.yml ${label} 必须是字符串数组`);
 	return value;
 }
-function parseManifest(moduleDir) {
+function readModuleManifest(moduleDir) {
 	const file = resolveModuleFilePath(moduleDir, MANIFEST_PATH, ["assets"]);
 	if (!modulePathExists(file)) throw new Error("模块缺少 assets/manifest.yml");
 	const doc = parseDocument(readFileSync(file, "utf8"), { logLevel: "silent" });
@@ -26002,7 +26316,7 @@ function ensureDirectory(moduleDir, path) {
 * shortcut: 装配无锁且逐文件写入，并发调用可能留下部分结果；等需要回滚或并发保证时升级成事务。
 */
 function runModuleManifest(moduleDir, action) {
-	const manifest = parseManifest(moduleDir);
+	const manifest = readModuleManifest(moduleDir);
 	if (action === "next") {
 		const entry = nextEntry(moduleDir, manifest);
 		return {
@@ -26279,66 +26593,879 @@ function registerModuleVariableTools(ctx, host) {
 	};
 }
 //#endregion
-//#region engine/promotion-pool.mjs
-/**
-* 晋升相位追踪器池：同一挂载内按配置复用追踪器，事件由池**统一喂**。
-*
-* 为什么需要池：`createEpochPromotion` 自己不订阅任何事件（它的 ctx 参数完全用不到，
-* 见 `compaction-epoch.mjs` 的条目容器注释），初始相位靠 `status()` 触发的**全量冷扫**建立。
-* 此前 `executor` 每次 pre-step apply 建两份、`phase` 每个编译谓词建一份、
-* `instruction-hint` 每次 apply 建一份，各自订阅、各自喂——重复建的代价就是重复冷扫。
-*
-* **池自己订阅**：订阅随池的归属走（自建池随所在挂载释放，注入池由创建者释放），
-* 调用方不需要记住「注入时谁来喂事件」——忘了就是相位停在冷扫那一刻的静默失效。
-*
-* 状态仍按 `session.id` 分条（追踪器内部的 `sessionState`）：池只合并**实例与订阅**，
-* 不共享会话状态，也不改变「状态是快路径、真相在事件流」这条纪律。
-*/
-/**
-* 进缓存的选项键：**任何影响判定的配置都必须登记**，否则同 key 会掩盖不同行为。
-* 与 `createEpochPromotion` 读取的选项一一对应。
-*/
-const KEYED_OPTIONS = [
-	"includeSubagents",
-	"promoteGate",
-	"promoteAfterFirstResponse",
-	"reasoningPattern",
-	"reasoningNegativePattern",
-	"reasoningFlags",
-	"maxPromoteSteps"
+//#region src/host/soul-ledger.ts
+/** soul 账本业务 owner：身份来自宿主，历史只追加。 */
+const SOUL_LEDGER_PATH = "data/02-soul.jsonl";
+const SOUL_LEDGER_TYPES = [
+	"lead",
+	"promise",
+	"fact",
+	"shelved",
+	"gain",
+	"loss",
+	"persona",
+	"container"
 ];
-const trackKey = (promoteEvents, options) => JSON.stringify([[...promoteEvents].sort(), KEYED_OPTIONS.map((key) => [key, options[key]])]);
-/**
-* @param {object} ctx 归属上下文（`ctx.on` 用来订阅 `session/event`）
-* @returns {{ tracker: (promoteEvents: readonly string[], options?: object) => object, dispose: () => void }}
-*/
-function createPromotionPool(ctx) {
-	const trackers = /* @__PURE__ */ new Map();
-	let disposed = false;
-	const release = ctx.on("session/event", (session, event) => {
-		for (const tracker of trackers.values()) tracker.observe(session, event);
+function rowsOf(content) {
+	return content.split("\n").filter((line) => line.trim()).map((line, index) => {
+		const row = JSON.parse(line);
+		if (!row || typeof row !== "object" || Array.isArray(row)) throw new Error(`账本第 ${index + 1} 行不是对象`);
+		const value = row;
+		const summary = value["概要"] ?? value.text;
+		if (typeof value.by !== "string" || typeof value.type !== "string" || typeof value.t !== "string" || typeof summary !== "string") throw new Error(`账本第 ${index + 1} 行缺少有效身份或概要`);
+		return {
+			...value,
+			"概要": summary
+		};
 	});
-	return {
-		/** 按配置取追踪器：同配置复用、异配置分建（配置不同就是不同的相位语义）。 */
-		tracker(promoteEvents, options = {}) {
-			const key = trackKey(promoteEvents, options);
-			let tracker = trackers.get(key);
-			if (tracker === void 0) {
-				tracker = createEpochPromotion(promoteEvents, options);
-				trackers.set(key, tracker);
-			}
-			return tracker;
-		},
-		/** 释放订阅并丢弃实例；追踪器本身没有 disposer（状态随闭包回收）。 */
-		dispose() {
-			if (disposed) return;
-			disposed = true;
-			trackers.clear();
-			release?.();
-		}
-	};
 }
-//#endregion
+function readSoulLedger(moduleDir, options = {}) {
+	const limit = options.limit ?? 30;
+	if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) throw new Error("账本读取 limit 必须为 1–100");
+	if (options.type !== void 0 && !SOUL_LEDGER_TYPES.includes(options.type)) throw new Error("未知账本类型");
+	const all = rowsOf(readModuleFile(moduleDir, SOUL_LEDGER_PATH).content);
+	const rows = options.type === void 0 ? all : all.filter((row) => row.type === options.type);
+	const entries = rows.slice(-limit);
+	if (Buffer.byteLength(JSON.stringify(entries)) > 65536) throw new Error("账本读取结果超过 64 KiB，请降低 limit");
+	return {
+		entries,
+		total: rows.length
+	};
+}
+function appendSoulLedger(moduleDir, input, caller) {
+	if (!caller.sessionId?.trim()) throw new Error("账本写入需要真实会话身份");
+	if (!input || typeof input !== "object" || Array.isArray(input) || Object.keys(input).some((key) => ![
+		"type",
+		"text",
+		"概要",
+		"ref",
+		"feel"
+	].includes(key))) throw new Error("账本写入包含未知字段，作者和时间由宿主提供");
+	if (!SOUL_LEDGER_TYPES.includes(input.type)) throw new Error("未知账本类型");
+	if (input.text !== void 0 === (input["概要"] !== void 0)) throw new Error("账本写入需要 text 或 概要 之一");
+	const summary = input["概要"] ?? input.text;
+	if (typeof summary !== "string" || !summary.trim() || Buffer.byteLength(summary) > 8192) throw new Error("账本概要必须为非空且不超过 8 KiB 的字符串");
+	for (const key of ["ref", "feel"]) if (input[key] !== void 0 && (typeof input[key] !== "string" || Buffer.byteLength(input[key]) > 8192)) throw new Error(`账本 ${key} 必须为不超过 8 KiB 的字符串`);
+	return withModuleLock(dirname(moduleDir), basename(moduleDir), () => {
+		caller.signal?.throwIfAborted();
+		const previous = readModuleFile(moduleDir, SOUL_LEDGER_PATH).content;
+		const rows = rowsOf(previous);
+		if (input.type === "promise" && rows.findLast((row) => row.type === "lead")?.by !== caller.sessionId) throw new Error("只有最后一条 lead 署名的主导会话可以写 promise");
+		const entry = {
+			t: (/* @__PURE__ */ new Date()).toISOString(),
+			by: caller.sessionId,
+			type: input.type,
+			"概要": summary,
+			...input.ref === void 0 ? {} : { ref: input.ref },
+			...input.feel === void 0 ? {} : { feel: input.feel }
+		};
+		const line = (previous.length > 0 && !previous.endsWith("\n") ? "\n" : "") + JSON.stringify(entry) + "\n";
+		if (Buffer.byteLength(previous) + Buffer.byteLength(line) > 8388608) throw new Error("账本超过 8 MiB");
+		ensureDataDirectory(moduleDir);
+		const file = resolveModuleFilePath(moduleDir, SOUL_LEDGER_PATH, ["data"]);
+		caller.signal?.throwIfAborted();
+		appendFileSync(file, line, "utf8");
+		return { entry };
+	});
+}
+//#endregion
+//#region src/runtime/soul-ledger-tools.ts
+function registerSoulLedgerTools(ctx, host) {
+	const fiber = ctx.inject(["tools"], (toolsCtx) => {
+		const offGate = toolsCtx.on("tools/pre-execute", async (exec, next) => {
+			const decision = await next();
+			const args = exec.arguments;
+			if (decision.kind !== "allow" || exec.name !== MODULE_TOOL_NAMES.soulLedger || args?.action !== "append" || args?.type !== "lead") return decision;
+			exec.signal.throwIfAborted();
+			return {
+				kind: "ask",
+				reason: "变更 soul 账本主导会话，需要用户明确指定"
+			};
+		});
+		const offTool = toolsCtx.tools.register(defineTool({
+			name: MODULE_TOOL_NAMES.soulLedger,
+			description: "读取或追加模块只追加账本。作者和时间来自真实执行会话；promise 仅当前 lead 署名者能写。lead 必须由用户指定并附 ref；text 与概要二选一，feel 有感受才写。",
+			parameters: {
+				moduleId: MODULE_ID_PARAM,
+				action: {
+					type: "string",
+					enum: ["list", "append"],
+					required: true
+				},
+				type: {
+					type: "string",
+					enum: [...SOUL_LEDGER_TYPES]
+				},
+				text: { type: "string" },
+				"概要": { type: "string" },
+				ref: { type: "string" },
+				feel: { type: "string" },
+				limit: { type: "integer" }
+			},
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						entry: {
+							type: "object",
+							additionalProperties: true
+						},
+						entries: {
+							type: "array",
+							items: {
+								type: "object",
+								additionalProperties: true
+							}
+						},
+						total: { type: "integer" }
+					}
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: JSON.stringify(value)
+				}]
+			},
+			execute: async (args, exec) => {
+				if (Object.keys(args).some((key) => ![
+					"moduleId",
+					"action",
+					"type",
+					"text",
+					"概要",
+					"ref",
+					"feel",
+					"limit"
+				].includes(key))) throw new Error("账本工具含未知字段，不能指定作者或覆盖历史");
+				exec.signal.throwIfAborted();
+				const target = host.target(exec, args.moduleId);
+				if (args.action === "list") {
+					if (args.text !== void 0 || args["概要"] !== void 0 || args.ref !== void 0 || args.feel !== void 0) throw new Error("读取账本不接受写入字段");
+					return readSoulLedger(target.dir, {
+						limit: args.limit,
+						type: args.type
+					});
+				}
+				if (args.limit !== void 0 || args.type === void 0) throw new Error("追加账本需要 type 且不接受 limit");
+				if (args.type === "lead" && !args.ref?.trim()) throw new Error("lead 必须提供用户指定主导的 ref");
+				return appendSoulLedger(target.dir, {
+					type: args.type,
+					...args.text === void 0 ? {} : { text: args.text },
+					...args["概要"] === void 0 ? {} : { "概要": args["概要"] },
+					...args.ref === void 0 ? {} : { ref: args.ref },
+					...args.feel === void 0 ? {} : { feel: args.feel }
+				}, {
+					sessionId: exec.agent?.session.id,
+					signal: exec.signal
+				});
+			}
+		}));
+		return () => {
+			offGate();
+			offTool();
+		};
+	});
+	return () => {
+		fiber.dispose();
+	};
+}
+//#endregion
+//#region src/host/soul-self.ts
+/** SELF 派生快照：骨架与事实共享，运行身份只在模型出口加入。 */
+const SOUL_SELF_SOURCE = "data/SELF.src.md";
+const SOUL_SELF_SNAPSHOT = "data/.soul/SELF.md";
+function seal(text) {
+	return text.replace(/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY-----|$)/g, "[凭据已屏蔽]").split("\n").map((line) => /sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|Bearer\s+\S+|(?:api[_-]?key|token|secret|password|passwd|pwd|cookie)["']?\s*[:=]/i.test(line) ? "[凭据已屏蔽]" : line).join("\n");
+}
+function validateSelfBudget(value = 12288) {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1024 || value > 65536) throw new Error("SELF 预算必须为 1024–65536 字节");
+	return value;
+}
+function readSoulSelfSnapshot(moduleDir) {
+	const file = join(moduleDir, SOUL_SELF_SNAPSHOT);
+	assertNoModuleLinks(file);
+	if (!modulePathExists(file)) return {
+		content: "",
+		revision: null
+	};
+	const content = readModuleFile(moduleDir, SOUL_SELF_SNAPSHOT).content;
+	return {
+		content,
+		revision: revisionOf$4(content)
+	};
+}
+function refreshSoulSelf(moduleDir, index, options) {
+	const budget = validateSelfBudget(options.budgetBytes);
+	options.signal?.throwIfAborted();
+	const source = readModuleFile(moduleDir, SOUL_SELF_SOURCE).content;
+	if (!source.trim()) throw new Error("SELF 骨架缺失：data/SELF.src.md");
+	const ledger = readSoulLedger(moduleDir, { limit: 1 });
+	const lead = readSoulLedger(moduleDir, {
+		type: "lead",
+		limit: 1
+	}).entries[0];
+	const promises = readSoulLedger(moduleDir, {
+		type: "promise",
+		limit: 3
+	});
+	const shelved = readSoulLedger(moduleDir, {
+		type: "shelved",
+		limit: 3
+	});
+	const count = (key) => {
+		const value = index[key] ?? 0;
+		if (!Number.isSafeInteger(value) || value < 0) throw new Error("SELF 索引状态无效");
+		return value;
+	};
+	const content = seal([
+		source.split("## 活体")[0].trim(),
+		"",
+		"## 活体（自动装配）",
+		`- 装配时刻：${(/* @__PURE__ */ new Date()).toISOString()}`,
+		`- 账本：共 ${ledger.total} 条；未结 ${promises.total + shelved.total} 条`,
+		...lead ? [`- 最后主导记录：${lead["概要"]}`] : ["- 主导：尚无 lead 记录"],
+		...[...promises.entries, ...shelved.entries].sort((a, b) => a.t.localeCompare(b.t)).slice(-3).map((row) => `- [${row.type}] ${row["概要"]}`),
+		`- 索引：${index.state}；文件 ${count("files")}；会话 ${count("sessions")}；事件 ${count("events")}`,
+		""
+	].join("\n"));
+	if (Buffer.byteLength(content) > budget - 512) throw new Error("SELF 超预算，需精简骨架或账本内容；旧快照保留");
+	return withModuleLock(dirname(moduleDir), basename(moduleDir), () => {
+		options.signal?.throwIfAborted();
+		if (readSoulSelfSnapshot(moduleDir).revision !== options.expectedRevision) throw new Error("SELF 快照版本冲突");
+		if (readModuleFile(moduleDir, "data/SELF.src.md").content !== source) throw new Error("SELF 骨架版本冲突");
+		const data = ensureDataDirectory(moduleDir), stateDir = join(data, ".soul");
+		assertNoModuleLinks(stateDir);
+		mkdirSync(stateDir, { recursive: true });
+		const target = resolveModuleFilePath(moduleDir, SOUL_SELF_SNAPSHOT, ["data"]);
+		const temp = join(stateDir, ".self-" + randomUUID() + ".tmp");
+		try {
+			writeFileSync(temp, content, {
+				flag: "wx",
+				encoding: "utf8"
+			});
+			options.signal?.throwIfAborted();
+			if (readSoulSelfSnapshot(moduleDir).revision !== options.expectedRevision) throw new Error("SELF 快照版本冲突");
+			renameSync(temp, target);
+		} finally {
+			rmSync(temp, { force: true });
+		}
+		return {
+			state: "ready",
+			revision: revisionOf$4(content),
+			bytes: Buffer.byteLength(content)
+		};
+	});
+}
+function renderSoulSelf(moduleDir, agent, signal, budgetBytes = 12288) {
+	signal?.throwIfAborted();
+	if (!agent?.session?.id) throw new Error("SELF 缺少实际 Agent 身份");
+	const snapshot = readSoulSelfSnapshot(moduleDir);
+	const text = `${snapshot.revision === null ? "[SELF missing：等待骨架初始化与维护]" : seal(snapshot.content)}\n## 当前运行身份\n- 本会话：${agent.session.id}\n- 受众：${(agent.session.header?.delegationDepth ?? 0) > 0 ? "子代理" : "主会话"}\n`;
+	if (Buffer.byteLength(text) > validateSelfBudget(budgetBytes)) throw new Error("SELF 动态上下文超预算");
+	return seal(text);
+}
+//#endregion
+//#region engine/retrieval-reference.mjs
+const MAX_REFERENCE_CHARS = 8192;
+/** seq 是持久日志身份；不排序为数值区间，也不以相同正文替代。 */
+function sessionReferenceText(events, seqs) {
+	if (!Array.isArray(seqs) || seqs.length === 0 || seqs.length > 2048 || new Set(seqs).size !== seqs.length || seqs.some((seq) => !Number.isSafeInteger(seq) || seq < 0)) throw new Error("检索引用事件身份无效");
+	const bySeq = new Map(events.map((event) => [event.seq, event]));
+	let bytes = 0;
+	return seqs.map((seq) => {
+		const event = bySeq.get(seq);
+		if (!event) throw new Error("检索引用已失效");
+		const text = JSON.stringify(event);
+		bytes += Buffer.byteLength(text);
+		if (bytes > 67108864) throw new Error("检索引用来源超过64 MiB上限");
+		return text;
+	}).join("\n");
+}
+function makeSessionReference(moduleId, sessionId, events, seqs, range = {}) {
+	if (typeof moduleId !== "string" || !moduleId || typeof sessionId !== "string" || !sessionId) throw new Error("检索引用缺少真实来源身份");
+	const text = sessionReferenceText(events, seqs);
+	const start = range.start ?? 0, end = range.end ?? Math.min(text.length, start + 8192);
+	if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end <= start || end > text.length || end - start > 8192) throw new Error("检索引用范围无效");
+	return {
+		kind: "session",
+		moduleId,
+		sessionId,
+		seqs: [...seqs],
+		revision: createHash("sha256").update(text).digest("hex"),
+		start,
+		end
+	};
+}
+//#endregion
+//#region src/host/module-retrieval.ts
+/** 检索只读权威来源；引用携定位和版本，不携访问权限。 */
+const digest$1 = (value) => createHash("sha256").update(value).digest("hex");
+const MAX_CHUNK = MAX_REFERENCE_CHARS;
+function fileContent(scope, path) {
+	if (!scope.paths.some((allowed) => allowed === path || allowed.endsWith("/") && path.startsWith(allowed))) throw new Error("检索来源未授权");
+	resolveModuleFilePath(scope.dir, path, ["assets", "data"], { allowRootMemory: true });
+	return readModuleFile(scope.dir, path).content;
+}
+function filePaths(scope) {
+	const paths = /* @__PURE__ */ new Set();
+	let total = 0;
+	const walk = (path) => {
+		const resolved = resolveModuleFilePath(scope.dir, path, ["assets", "data"], { allowRootMemory: true });
+		if (!modulePathExists(resolved)) return;
+		const stat = lstatSync(resolved);
+		if (stat.isDirectory()) for (const entry of readdirSync(resolved).sort()) walk(path + "/" + entry);
+		else {
+			if (!stat.isFile()) throw new Error("检索来源不是普通文件");
+			if (!paths.has(path)) total += stat.size;
+			paths.add(path);
+			if (paths.size > 2048 || total > 67108864) throw new Error("检索来源超过数量或总大小上限");
+		}
+	};
+	for (const path of scope.paths) {
+		const selected = path.endsWith("/") ? path.slice(0, -1) : path;
+		const resolved = resolveModuleFilePath(scope.dir, selected, ["assets", "data"], { allowRootMemory: true });
+		if (!modulePathExists(resolved)) continue;
+		if (lstatSync(resolved).isDirectory() && !path.endsWith("/")) throw new Error("检索目录白名单必须以 / 结尾");
+		walk(selected);
+	}
+	return [...paths];
+}
+function createModuleRetrieval(scopeOf, loadSession) {
+	const indexes = /* @__PURE__ */ new Map();
+	const assertSessionAuthorized = (scope, id) => {
+		const current = scopeOf();
+		if (current.moduleId !== scope.moduleId || current.session?.id !== id && !current.sessions?.includes(id)) throw new Error("检索会话未授权");
+	};
+	async function authorizedSession(scope, id) {
+		assertSessionAuthorized(scope, id);
+		if (scope.session?.id === id) return scope.session;
+		if (!scope.sessions?.includes(id)) throw new Error("检索会话未授权");
+		let session;
+		try {
+			session = await loadSession?.(id);
+		} catch {
+			throw new Error("授权会话不可读取");
+		}
+		assertSessionAuthorized(scope, id);
+		if (!session || session.id !== id) throw new Error("授权会话不可读取");
+		return session;
+	}
+	async function indexSession(scope, id) {
+		const events = [...(await authorizedSession(scope, id)).snapshotEvents()];
+		assertSessionAuthorized(scope, id);
+		const prior = indexes.get(id);
+		const appendOnly = prior !== void 0 && events.length >= prior.events.length && prior.events.every((event, i) => events[i] === event);
+		const rows = appendOnly ? [...prior.rows] : [];
+		for (const event of events.slice(appendOnly ? prior.events.length : 0)) {
+			if (!Number.isSafeInteger(event.seq) || event.seq < 0) throw new Error("授权会话事件身份无效");
+			rows.push({
+				seq: event.seq,
+				content: JSON.stringify(event)
+			});
+		}
+		if (new Set(rows.map((row) => row.seq)).size !== rows.length) throw new Error("授权会话事件身份重复");
+		if (rows.reduce((bytes, row) => bytes + Buffer.byteLength(row.content), 0) > 67108864) throw new Error("授权会话检索超过64 MiB上限");
+		indexes.set(id, {
+			events,
+			rows
+		});
+		return {
+			events,
+			rows
+		};
+	}
+	const sessionIds = (scope) => /* @__PURE__ */ new Set([...scope.session ? [scope.session.id] : [], ...scope.sessions ?? []]);
+	const resultOf = (scope, hits) => {
+		const current = scopeOf();
+		if (current.moduleId !== scope.moduleId || current.dir !== scope.dir) throw new Error("检索模块未授权");
+		for (const { reference } of hits) if (reference.kind === "session") assertSessionAuthorized(current, reference.sessionId);
+		else if (digest$1(fileContent(current, reference.path)) !== reference.revision) throw new Error("检索引用已失效，请重新搜索");
+		return { hits };
+	};
+	return {
+		async search(input) {
+			if (typeof input.query !== "string" || input.query.trim().length === 0 || input.query.length > 1024) throw new Error("检索 query 必须为1–1024字符");
+			const limit = input.limit ?? 20;
+			if (!Number.isSafeInteger(limit) || limit < 1 || limit > 50) throw new Error("检索 limit 必须为1–50");
+			const scope = scopeOf(), query = input.query.toLowerCase(), hits = [];
+			for (const path of filePaths(scope)) {
+				const content = fileContent(scope, path), revision = digest$1(content);
+				let offset = 0;
+				for (const line of content.split("\n")) {
+					for (let part = 0; part < line.length; part += MAX_CHUNK) {
+						const text = line.slice(part, part + MAX_CHUNK);
+						if (!text.toLowerCase().includes(query)) continue;
+						hits.push({
+							reference: {
+								kind: "file",
+								moduleId: scope.moduleId,
+								path,
+								revision,
+								start: offset + part,
+								end: offset + part + text.length
+							},
+							content: text
+						});
+						if (hits.length === limit) return resultOf(scope, hits);
+					}
+					offset += line.length + 1;
+				}
+			}
+			for (const id of sessionIds(scope)) {
+				const { events, rows } = await indexSession(scope, id);
+				for (const row of rows) {
+					const match = row.content.toLowerCase().indexOf(query);
+					if (match < 0) continue;
+					const start = Math.max(0, match - 128), end = Math.min(row.content.length, start + MAX_CHUNK);
+					const reference = makeSessionReference(scope.moduleId, id, events, [row.seq], {
+						start,
+						end
+					});
+					hits.push({
+						reference,
+						content: row.content.slice(start, end)
+					});
+					if (hits.length === limit) return resultOf(scope, hits);
+				}
+			}
+			return resultOf(scope, hits);
+		},
+		async open(reference) {
+			const scope = scopeOf();
+			if (!reference || reference.moduleId !== scope.moduleId) throw new Error("检索引用未授权或无效");
+			if (Object.keys(reference).some((key) => ![
+				"kind",
+				"moduleId",
+				"path",
+				"revision",
+				"start",
+				"end",
+				"sessionId",
+				"seqs"
+			].includes(key))) throw new Error("检索引用含未知字段");
+			if (reference.kind === "session") {
+				const session = await authorizedSession(scope, reference.sessionId), events = session.snapshotEvents();
+				assertSessionAuthorized(scope, reference.sessionId);
+				const content = sessionReferenceText(events, reference.seqs);
+				if (digest$1(content) !== reference.revision) throw new Error("检索引用已失效，请重新搜索");
+				if (makeSessionReference(scope.moduleId, session.id, events, reference.seqs, reference).revision !== reference.revision) throw new Error("检索引用已失效，请重新搜索");
+				const nextReference = reference.end < content.length ? makeSessionReference(scope.moduleId, session.id, events, reference.seqs, { start: reference.end }) : void 0;
+				return {
+					reference,
+					content: content.slice(reference.start, reference.end),
+					totalChars: content.length,
+					...nextReference ? { nextReference } : {}
+				};
+			}
+			if (reference.kind !== "file") throw new Error("检索引用无效");
+			const content = fileContent(scope, reference.path);
+			if (digest$1(content) !== reference.revision) throw new Error("检索引用已失效，请重新搜索");
+			if (!Number.isSafeInteger(reference.start) || !Number.isSafeInteger(reference.end) || reference.start < 0 || reference.end <= reference.start || reference.end > content.length || reference.end - reference.start > MAX_CHUNK) throw new Error("检索引用范围无效");
+			return {
+				reference,
+				content: content.slice(reference.start, reference.end)
+			};
+		},
+		async refresh() {
+			const scope = scopeOf(), files = filePaths(scope);
+			for (const path of files) fileContent(scope, path);
+			let events = 0;
+			const ids = sessionIds(scope);
+			for (const id of ids) events += (await indexSession(scope, id)).rows.length;
+			for (const id of indexes.keys()) if (!ids.has(id)) indexes.delete(id);
+			return {
+				state: "ready",
+				files: files.length,
+				sessions: ids.size,
+				events
+			};
+		}
+	};
+}
+//#endregion
+//#region src/runtime/module-retrieval-tools.ts
+/** 调用方已确认 tools 就绪；同步注册使初始化错误回到当前能力的挂载路径。 */
+function registerModuleRetrievalTools(ctx, retrievalOf) {
+	const tools = ctx.get("tools");
+	if (tools === void 0) throw new Error("检索工具注册需要 tools 服务");
+	const disposers = [];
+	const dispose = () => {
+		for (const off of disposers.splice(0).reverse()) off();
+	};
+	try {
+		disposers.push(tools.register(defineTool({
+			name: MODULE_TOOL_NAMES.search,
+			description: "搜索 moduleId 声明模块已授权的文件、账本或历史会话。结果中的 reference 可交 module_open 回取相同原文。",
+			parameters: {
+				moduleId: MODULE_ID_PARAM,
+				query: {
+					type: "string",
+					required: true
+				},
+				limit: { type: "number" }
+			},
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: true
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: JSON.stringify(value)
+				}]
+			},
+			execute: async (args, exec) => {
+				if (Object.keys(args).some((key) => ![
+					"moduleId",
+					"query",
+					"limit"
+				].includes(key))) throw new Error("检索请求含未知字段");
+				exec.signal?.throwIfAborted();
+				const value = await retrievalOf(exec, args.moduleId).search({
+					query: args.query,
+					limit: args.limit
+				});
+				exec.signal?.throwIfAborted();
+				retrievalOf(exec, args.moduleId);
+				return value;
+			}
+		})));
+		disposers.push(tools.register(defineTool({
+			name: MODULE_TOOL_NAMES.open,
+			description: "回取 module_search 返回的引用。每次重新检查来源授权与版本；引用不是访问凭据。",
+			parameters: {
+				moduleId: MODULE_ID_PARAM,
+				reference: {
+					type: "object",
+					additionalProperties: true,
+					required: true
+				}
+			},
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: true
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: JSON.stringify(value)
+				}]
+			},
+			execute: async (args, exec) => {
+				if (Object.keys(args).some((key) => !["moduleId", "reference"].includes(key))) throw new Error("回取请求含未知字段");
+				exec.signal?.throwIfAborted();
+				const value = await retrievalOf(exec, args.moduleId).open(args.reference);
+				exec.signal?.throwIfAborted();
+				retrievalOf(exec, args.moduleId);
+				return value;
+			}
+		})));
+	} catch (error) {
+		dispose();
+		throw error;
+	}
+	return dispose;
+}
+function createModuleRetrievalProvider(host, loadSession) {
+	const agents = /* @__PURE__ */ new WeakMap();
+	const retrievalFor = (state, moduleId, agent) => {
+		let retrieval = state.indexes.get(moduleId);
+		if (retrieval === void 0) {
+			retrieval = createModuleRetrieval(() => {
+				const current = [...state.modules.get(moduleId)?.values() ?? []].at(-1);
+				if (!current) throw new Error("检索模块未授权");
+				return {
+					moduleId,
+					dir: current.dir,
+					paths: current.config.paths,
+					sessions: current.config.sessions,
+					session: agent.session
+				};
+			}, loadSession);
+			state.indexes.set(moduleId, retrieval);
+		}
+		return retrieval;
+	};
+	return {
+		async refresh(agent, moduleId, signal) {
+			signal?.throwIfAborted();
+			const state = agents.get(agent);
+			if (!state?.modules.has(moduleId)) throw new Error("检索模块未授权");
+			const result = await retrievalFor(state, moduleId, agent).refresh();
+			signal?.throwIfAborted();
+			if (!state.modules.has(moduleId)) throw new Error("检索模块未授权");
+			return result;
+		},
+		mount(_ctx, config, options) {
+			const { agent, sourceModuleId, sourceModuleDir } = options;
+			if (!agent?.ctx || !sourceModuleId || !sourceModuleDir) throw new Error("检索缺少宿主来源模块身份");
+			if (!Array.isArray(config.paths) || config.paths.length > 2048 || config.paths.some((path) => typeof path !== "string") || !Array.isArray(config.sessions) || config.sessions.length > 128 || config.sessions.some((id) => typeof id !== "string" || !id || id.length > 256)) throw new Error("检索来源白名单无效或超限");
+			let state = agents.get(agent);
+			if (state === void 0) {
+				const modules = /* @__PURE__ */ new Map();
+				const indexes = /* @__PURE__ */ new Map();
+				const dispose = registerModuleRetrievalTools(agent.ctx, (exec, moduleId) => {
+					if (exec.agent !== agent) throw new Error("检索 Agent 未授权");
+					const target = host.target(exec, moduleId);
+					const declaration = [...modules.get(target.id)?.values() ?? []].at(-1);
+					if (!declaration || declaration.dir !== target.dir) throw new Error("检索模块未授权");
+					return retrievalFor({
+						modules,
+						indexes,
+						dispose
+					}, target.id, agent);
+				});
+				state = {
+					modules,
+					indexes,
+					dispose
+				};
+				agents.set(agent, state);
+			}
+			let declarations = state.modules.get(sourceModuleId);
+			if (declarations === void 0) {
+				declarations = /* @__PURE__ */ new Map();
+				state.modules.set(sourceModuleId, declarations);
+			}
+			const token = Symbol(sourceModuleId);
+			declarations.set(token, {
+				config,
+				dir: sourceModuleDir
+			});
+			const owner = state;
+			return () => {
+				if (!declarations.delete(token)) return;
+				if (declarations.size === 0) {
+					owner.modules.delete(sourceModuleId);
+					owner.indexes.delete(sourceModuleId);
+				}
+				if (owner.modules.size === 0) {
+					owner.dispose();
+					agents.delete(agent);
+				}
+			};
+		}
+	};
+}
+//#endregion
+//#region src/runtime/soul-maintenance.ts
+function createSoulMaintenanceProvider(options) {
+	const states = /* @__PURE__ */ new Map();
+	const status = (id) => {
+		const state = states.get(id);
+		return state ? {
+			state: state.state,
+			...state.error ? { error: state.error } : {}
+		} : { state: "disabled" };
+	};
+	const tick = (id) => {
+		const state = states.get(id);
+		if (!state || !state.members.size) return Promise.resolve();
+		if (state.running) return state.running;
+		if (state.timer) clearTimeout(state.timer);
+		const owner = [...state.members].at(-1);
+		const controller = new AbortController();
+		let signal = controller.signal;
+		state.controller = controller;
+		state.owner = owner;
+		state.state = "running";
+		delete state.error;
+		const valid = () => !signal.aborted && states.get(id) === state && state.members.has(owner);
+		state.running = Promise.resolve().then(async () => {
+			try {
+				if (!valid()) return;
+				await owner.agent.runMaintenance(async (activitySignal) => {
+					signal = AbortSignal.any([controller.signal, activitySignal]);
+					signal.throwIfAborted();
+					const revision = readSoulSelfSnapshot(owner.sourceModuleDir).revision;
+					const index = await options.refreshRetrieval(owner.agent, id, signal);
+					if (!valid()) return;
+					refreshSoulSelf(owner.sourceModuleDir, index, {
+						expectedRevision: revision,
+						signal,
+						budgetBytes: owner.config.budgetBytes
+					});
+				});
+				if (!valid()) return;
+				state.state = "ready";
+				if (owner.config.wake) owner.agent.followup(pluginMessage("soul-maintenance", "书房索引与 SELF 已维护。请核对当前未结事项；无需重复写入已有事实。", "书房维护心跳"));
+			} catch (error) {
+				if (valid()) {
+					state.state = "failed";
+					state.error = error instanceof Error ? error.message : String(error);
+				}
+			} finally {
+				state.running = void 0;
+				state.owner = void 0;
+				if (state.state === "running") state.state = signal.aborted ? "cancelled" : "idle";
+				if (states.get(id) === state && state.members.size) {
+					const current = [...state.members].at(-1);
+					state.timer = setTimeout(() => {
+						tick(id);
+					}, current.config.intervalMs);
+					state.timer.unref();
+				}
+			}
+		});
+		return state.running;
+	};
+	const mount = (_ctx, config, source) => {
+		const audience = (source.agent.session.header.delegationDepth ?? 0) > 0 ? "subagent" : "main";
+		if (!config.enabled || config.audience !== "all" && config.audience !== audience) return () => {};
+		if (!Number.isSafeInteger(config.intervalMs) || config.intervalMs < 1e3 || config.intervalMs > 2147483647) throw new Error("心跳间隔必须为 1000–2147483647ms");
+		const id = source.sourceModuleId;
+		let state = states.get(id);
+		if (!state) {
+			state = {
+				members: /* @__PURE__ */ new Set(),
+				state: "idle"
+			};
+			states.set(id, state);
+		}
+		if ([...state.members].some((member) => member.sourceModuleDir !== source.sourceModuleDir)) throw new Error("心跳模块目录身份冲突");
+		const member = {
+			...source,
+			config
+		};
+		state.members.add(member);
+		if (!state.running && !state.timer) tick(id);
+		return () => {
+			state.members.delete(member);
+			if (state.owner === member) state.controller?.abort();
+			if (state.members.size) return;
+			state.controller?.abort();
+			if (state.timer) clearTimeout(state.timer);
+			if (states.get(id) === state) states.delete(id);
+		};
+	};
+	return {
+		mount,
+		tick,
+		status,
+		dispose: () => {
+			for (const state of states.values()) {
+				state.controller?.abort();
+				if (state.timer) clearTimeout(state.timer);
+				state.members.clear();
+			}
+			states.clear();
+		}
+	};
+}
+//#endregion
+//#region src/runtime/soul-runtime.ts
+/** Soul宿主接线：历史只读句柄、检索授权与SELF/维护共享owner。 */
+function installSoulRuntime(ctx, host, moduleIds) {
+	const budgets = /* @__PURE__ */ new Map();
+	const readSelfBudget = (dir) => {
+		const stat = statSync(join(dir, "module.yml"), { throwIfNoEntry: false });
+		const stamp = stat ? `${stat.mtimeMs}:${stat.size}` : "missing";
+		const hit = budgets.get(dir);
+		if (hit !== void 0 && hit.stamp === stamp && performance.now() - hit.checkedAt < 1e3) return hit.value;
+		let value = hit?.value ?? validateSelfBudget();
+		try {
+			const facts = readModuleFacts(dir);
+			if (facts.sourceMode !== "unknown") value = validateSelfBudget(facts.effectiveConfigs?.["soul-maintenance"]?.budgetBytes);
+		} catch {}
+		budgets.set(dir, {
+			stamp,
+			checkedAt: performance.now(),
+			value
+		});
+		return value;
+	};
+	const retrieval = createModuleRetrievalProvider(host, async (id) => {
+		const live = ctx.get("sessions")?.get(id);
+		if (live) return live;
+		const persistence = ctx.get("sessionPersistence");
+		if (!persistence) throw new Error("历史会话持久服务不可用");
+		const handle = await persistence.open(id, "read");
+		try {
+			const { events } = await handle.read(0, 100001);
+			if (events.length > 1e5 || Buffer.byteLength(JSON.stringify(events)) > 33554432) throw new Error("授权会话超出检索预算");
+			return {
+				id,
+				snapshotEvents: () => events
+			};
+		} finally {
+			await handle.close();
+		}
+	});
+	const maintenance = createSoulMaintenanceProvider({ refreshRetrieval: (agent, id, signal) => retrieval.refresh(agent, id, signal) });
+	ctx.provide(toolServiceName("retrieval"), retrieval);
+	ctx.provide(SOUL_MAINTENANCE_SERVICE, maintenance);
+	ctx.provide(SOUL_SELF_SERVICE, { render: (id, agent, signal) => {
+		signal?.throwIfAborted();
+		if (!moduleIds(agent.id).includes(id)) throw new Error("SELF来源模块未参与本Agent装配");
+		const dir = assertModuleSnapshotSource(host.root, id);
+		return renderSoulSelf(dir, agent, signal, readSelfBudget(dir));
+	} });
+	ctx.effect(() => () => {
+		maintenance.dispose();
+		budgets.clear();
+	});
+}
+//#endregion
+//#region engine/promotion-pool.mjs
+/**
+* 晋升相位追踪器池：同一挂载内按配置复用追踪器，事件由池**统一喂**。
+*
+* 为什么需要池：`createEpochPromotion` 自己不订阅任何事件（它的 ctx 参数完全用不到，
+* 见 `compaction-epoch.mjs` 的条目容器注释），初始相位靠 `status()` 触发的**全量冷扫**建立。
+* 此前 `executor` 每次 pre-step apply 建两份、`phase` 每个编译谓词建一份、
+* `instruction-hint` 每次 apply 建一份，各自订阅、各自喂——重复建的代价就是重复冷扫。
+*
+* **池自己订阅**：订阅随池的归属走（自建池随所在挂载释放，注入池由创建者释放），
+* 调用方不需要记住「注入时谁来喂事件」——忘了就是相位停在冷扫那一刻的静默失效。
+*
+* 状态仍按 `session.id` 分条（追踪器内部的 `sessionState`）：池只合并**实例与订阅**，
+* 不共享会话状态，也不改变「状态是快路径、真相在事件流」这条纪律。
+*/
+/**
+* 进缓存的选项键：**任何影响判定的配置都必须登记**，否则同 key 会掩盖不同行为。
+* 与 `createEpochPromotion` 读取的选项一一对应。
+*/
+const KEYED_OPTIONS = [
+	"includeSubagents",
+	"promoteGate",
+	"promoteAfterFirstResponse",
+	"reasoningPattern",
+	"reasoningNegativePattern",
+	"reasoningFlags",
+	"maxPromoteSteps"
+];
+const trackKey = (promoteEvents, options) => JSON.stringify([[...promoteEvents].sort(), KEYED_OPTIONS.map((key) => [key, options[key]])]);
+/**
+* @param {object} ctx 归属上下文（`ctx.on` 用来订阅 `session/event`）
+* @returns {{ tracker: (promoteEvents: readonly string[], options?: object) => object, dispose: () => void }}
+*/
+function createPromotionPool(ctx) {
+	const trackers = /* @__PURE__ */ new Map();
+	let disposed = false;
+	const release = ctx.on("session/event", (session, event) => {
+		for (const tracker of trackers.values()) tracker.observe(session, event);
+	});
+	return {
+		/** 按配置取追踪器：同配置复用、异配置分建（配置不同就是不同的相位语义）。 */
+		tracker(promoteEvents, options = {}) {
+			const key = trackKey(promoteEvents, options);
+			let tracker = trackers.get(key);
+			if (tracker === void 0) {
+				tracker = createEpochPromotion(promoteEvents, options);
+				trackers.set(key, tracker);
+			}
+			return tracker;
+		},
+		/** 释放订阅并丢弃实例；追踪器本身没有 disposer（状态随闭包回收）。 */
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			trackers.clear();
+			release?.();
+		}
+	};
+}
+//#endregion
 //#region src/runtime/official-instruction-filter.ts
 /** 官方待注入消息的逐文件过滤；不读取或改写会话历史。 */
 const isRecord$1 = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
@@ -26688,6 +27815,156 @@ function planPersonaSections(options) {
 	};
 }
 //#endregion
+//#region src/host/module-data-import.ts
+/** 显式选择的书房数据：只读预览、只补缺失、完整候选交换。 */
+const digest = (value) => createHash("sha256").update(value).digest("hex");
+const dataPath = (path) => "data/" + (path === "02-墨.jsonl" ? "02-soul.jsonl" : path);
+function prepare(moduleDir, input) {
+	if (!input || typeof input !== "object" || Array.isArray(input) || Object.keys(input).some((key) => ![
+		"moduleId",
+		"sourceDirectory",
+		"paths",
+		"initialize",
+		"expectedRevision"
+	].includes(key))) throw new Error("数据导入包含未知字段或不是对象");
+	assertNoModuleLinks(moduleDir);
+	if (!isEditableModuleDir(moduleDir)) throw new Error("只能导入用户模块私有数据");
+	const dir = assertModuleDirectory(dirname(moduleDir), input.moduleId);
+	if (dir !== resolve(moduleDir) || basename(dir) !== input.moduleId) throw new Error("数据导入模块主语不一致");
+	if (input.initialize !== void 0 && input.initialize !== true) throw new Error("initialize 只能是 true");
+	if (input.initialize && (input.sourceDirectory !== void 0 || input.paths !== void 0)) throw new Error("初始化与外部来源选择不能混用");
+	if (!input.initialize && (typeof input.sourceDirectory !== "string" || !isAbsolute(input.sourceDirectory))) throw new Error("来源目录必须是用户显式选择的绝对路径");
+	const sourceDirectory = input.initialize ? dir : resolve(input.sourceDirectory);
+	assertNoModuleLinks(sourceDirectory);
+	if (!lstatSync(sourceDirectory).isDirectory()) throw new Error("来源不是普通目录");
+	if (!input.initialize && (!Array.isArray(input.paths) || input.paths.length === 0 || input.paths.length > 2048)) throw new Error("必须选择有界的来源文件列表");
+	if (input.expectedRevision !== void 0 && (typeof input.expectedRevision !== "string" || !/^[a-f0-9]{64}$/.test(input.expectedRevision))) throw new Error("数据导入版本无效");
+	const version = directoryVersionOf(dir);
+	const seen = /* @__PURE__ */ new Set();
+	let total = 0;
+	const manifest = input.initialize ? readModuleManifest(dir) : void 0;
+	const selected = manifest ? [...manifest.dirs.map((path) => ({
+		source: path,
+		path,
+		kind: "dir"
+	})), ...manifest.files.map((file) => ({
+		source: file.from,
+		path: file.to,
+		kind: "file"
+	}))] : input.paths.map((path) => ({
+		source: path,
+		path: dataPath(path),
+		kind: "file"
+	}));
+	if (selected.length > 2048) throw new Error("来源文件超过数量上限");
+	const files = selected.map(({ source: path, path: targetPath, kind }) => {
+		assertSafeRelativePath(path);
+		assertSafeRelativePath(targetPath);
+		if (targetPath === "data/02-soul.jsonl" && modulePathExists(join(dir, "data", "02-墨.jsonl"))) throw new Error("目标已有旧账本 data/02-墨.jsonl，请先显式核对并迁移，拒绝创建第二账本");
+		const key = targetPath.normalize("NFC").toLowerCase();
+		if (seen.has(key)) throw new Error("重复或冲突的目标路径：" + targetPath);
+		seen.add(key);
+		const source = join(sourceDirectory, path);
+		let bytes = Buffer.alloc(0);
+		if (kind === "file") {
+			assertNoModuleLinks(source);
+			const stat = lstatSync(source);
+			if (!stat.isFile()) throw new Error("来源不是普通文件：" + path);
+			if (stat.size > 8388608) throw new Error("来源文件超过 8 MiB：" + path);
+			bytes = readFileSync(source);
+		}
+		total += bytes.length;
+		if (bytes.length > 8388608 || total > 67108864) throw new Error("来源数据超过大小上限");
+		new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+		const target = join(dir, targetPath);
+		assertNoModuleLinks(target);
+		let state = "create";
+		if (modulePathExists(target)) {
+			const targetStat = lstatSync(target);
+			if (kind === "dir") {
+				if (!targetStat.isDirectory()) throw new Error("目标不是普通目录：" + targetPath);
+				state = "skip";
+			} else {
+				if (!targetStat.isFile()) throw new Error("目标不是普通文件：" + targetPath);
+				state = targetStat.size === bytes.length && readFileSync(target).equals(bytes) ? "skip" : "conflict";
+			}
+		}
+		return {
+			source: path,
+			path: targetPath,
+			kind,
+			state,
+			bytes
+		};
+	});
+	return {
+		dir,
+		version,
+		files,
+		revision: digest(JSON.stringify([
+			"module-data-import/1",
+			dir,
+			version,
+			sourceDirectory,
+			files.map((file) => [
+				file.source,
+				file.path,
+				file.kind,
+				digest(file.bytes)
+			])
+		])),
+		entries: files.map((file) => ({
+			source: file.source,
+			path: file.path,
+			kind: file.kind,
+			state: file.state,
+			bytes: file.bytes.length
+		}))
+	};
+}
+function previewModuleDataImport(moduleDir, input) {
+	const { revision, entries } = prepare(moduleDir, input);
+	return {
+		revision,
+		entries
+	};
+}
+function applyModuleDataImport(moduleDir, input) {
+	const plan = prepare(moduleDir, input);
+	if (input.expectedRevision !== plan.revision) throw new Error("数据导入预览已过期，请重新预览");
+	if (!plan.files.some((file) => file.state === "create")) return {
+		revision: plan.revision,
+		entries: plan.entries,
+		installed: false
+	};
+	const outcome = installModuleDirectory({
+		root: dirname(plan.dir),
+		id: input.moduleId,
+		expectedVersion: plan.version,
+		build: (candidate) => {
+			cpSync(plan.dir, candidate, { recursive: true });
+			for (const file of plan.files) {
+				if (file.state !== "create") continue;
+				const target = join(candidate, file.path);
+				if (file.kind === "dir") {
+					mkdirSync(target, { recursive: true });
+					continue;
+				}
+				mkdirSync(dirname(target), { recursive: true });
+				writeFileSync(target, file.bytes, { flag: "wx" });
+			}
+		}
+	});
+	if (outcome.state === "conflict") throw new Error("数据导入预览已过期，请重新预览");
+	if (outcome.state === "recovery-required") throw new Error("数据导入恢复失败，原目录备份保留在：" + outcome.backupPath);
+	return {
+		revision: plan.revision,
+		entries: plan.entries,
+		installed: true,
+		...outcome.leftoverStage ? { leftoverStage: outcome.leftoverStage } : {}
+	};
+}
+//#endregion
 //#region src/runtime/tui.ts
 /** dsh-tui 全局开关：键名与 settings 路径一致（settings mutate）。 */
 const TUI_GLOBAL_SWITCHES = [["modulesEnabled", "模块运行总开关"]];
@@ -26771,14 +28048,32 @@ function registerTuiCommand(ctx, ns, getSource, getModelsState, getModelCatalog,
 		return sctx.commands.register({
 			name: "prompt-tool",
 			description: "提示词工具：查看或切换本插件开关",
-			input: { hint: "status | module [模块id] | on/off/toggle <开关> | skill <技能名> on/off/toggle | [module <模块id>] config <id> [on/off/toggle]" },
+			input: { hint: "status | module [模块id] | data-import <JSON> | on/off/toggle <开关> | skill <技能名> on/off/toggle | [module <模块id>] config <id> [on/off/toggle]" },
 			handler: async (invocation) => {
+				const dataImport = /^data-import\s+([\s\S]+)$/.exec(invocation.rawInput.trim());
+				if (dataImport) try {
+					const request = JSON.parse(dataImport[1]);
+					if (!request || typeof request.moduleId !== "string") throw new Error("数据导入必须显式声明 moduleId");
+					const dir = getModuleDirectory?.(request.moduleId);
+					if (!dir) throw new Error("未找到模块：" + request.moduleId);
+					const result = request.expectedRevision === void 0 ? previewModuleDataImport(dir, request) : applyModuleDataImport(dir, request);
+					return {
+						kind: "success",
+						text: JSON.stringify(result)
+					};
+				} catch (error) {
+					return {
+						kind: "error",
+						text: `数据导入失败：${error instanceof Error ? error.message : String(error)}`
+					};
+				}
 				const usage = () => ({
 					kind: "error",
 					text: `用法：/prompt-tool status
       /prompt-tool on|off|toggle <${[...TUI_GLOBAL_SWITCHES, ...TUI_PARAM_SWITCHES].map(([key]) => key).join("|")}>\n      /prompt-tool skill <frontmatter 技能名> on|off|toggle
       /prompt-tool module <模块id>（声明本次会话主语，随后命令都作用在它上面）
       /prompt-tool module（显示当前声明）
+      /prompt-tool data-import <JSON>（moduleId + sourceDirectory/paths 或 initialize:true；预览后带 expectedRevision 应用，只补缺失）
       /prompt-tool module <模块id> on|off|toggle <模块参数>（单条命令前声明并执行）
       /prompt-tool config <id>（id 可含空格）
       /prompt-tool config <id> on|off|toggle
@@ -27329,6 +28624,166 @@ function createModuleVariableAdapter(moduleRoot) {
 	};
 }
 //#endregion
+//#region src/runtime/module-initialization.ts
+const ACTIVE = 2;
+/** 只跟踪装配拥有的初始化后代；任务执行异常不经过 Fiber 生命周期。 */
+function createModuleInitialization(ctx) {
+	const groups = /* @__PURE__ */ new Map();
+	const tasks = /* @__PURE__ */ new Map();
+	const pruneDisposed = (group) => {
+		for (const [id, fiber] of group.fibers) if (fiber.uid === null) {
+			group.fibers.delete(id);
+			groups.delete(id);
+		}
+	};
+	const check = (group) => {
+		if (!group.active || group.failed) return;
+		pruneDisposed(group);
+		const task = Promise.resolve().then(async () => {
+			await Promise.all([...group.fibers.values()].filter((fiber) => fiber.uid !== null).map((fiber) => fiber.await()));
+			if (!group.active || group.failed) return;
+			pruneDisposed(group);
+			if ([...group.fibers.values()].every((fiber) => fiber.uid === null || fiber.state === ACTIVE)) group.owner.ready();
+		}).catch((error) => {
+			if (!group.active || group.failed) return;
+			group.failed = true;
+			group.owner.failed(error);
+		}).finally(() => {
+			tasks.delete(task);
+		});
+		tasks.set(task, group);
+	};
+	const listeners = [ctx.on("internal/plugin", (fiber) => {
+		const parentId = fiber.parent.fiber.uid;
+		const group = parentId === null ? void 0 : groups.get(parentId);
+		if (group === void 0 || !group.active) return;
+		if (fiber.uid === null) {
+			pruneDisposed(group);
+			return;
+		}
+		group.fibers.set(fiber.uid, fiber);
+		groups.set(fiber.uid, group);
+		check(group);
+	}, { global: true }), ctx.on("internal/status", (fiber) => {
+		const id = fiber.uid ?? fiber.parent.fiber.uid;
+		const group = id === null ? void 0 : groups.get(id);
+		if (group !== void 0) check(group);
+	}, { global: true })];
+	ctx.effect(() => () => {
+		for (const group of groups.values()) group.active = false;
+		groups.clear();
+		for (const off of listeners) off();
+	}, "prompt-tool module initialization");
+	return {
+		observe(root, owner) {
+			if (root.uid === null) return () => {};
+			const group = {
+				fibers: /* @__PURE__ */ new Map([[root.uid, root]]),
+				owner,
+				active: true,
+				failed: false
+			};
+			groups.set(root.uid, group);
+			check(group);
+			return () => {
+				group.active = false;
+				for (const id of group.fibers.keys()) groups.delete(id);
+				for (const [task, owner] of tasks) if (owner === group) tasks.delete(task);
+			};
+		},
+		async settled(roots) {
+			const selected = roots === void 0 ? void 0 : new Set(roots.flatMap((root) => root.uid === null ? [] : [groups.get(root.uid)]));
+			while (true) {
+				const pending = [...tasks].filter(([, group]) => group.active && (selected === void 0 || selected.has(group))).map(([task]) => task);
+				if (pending.length === 0) return;
+				await Promise.all(pending);
+			}
+		}
+	};
+}
+//#endregion
+//#region src/host/generation-recovery-state.ts
+/** 会话恢复额度的唯一持久owner，重挂不重置，先扣额再允许唤醒。 */
+function createGenerationRecoveryState(root = join(storageRoot(), "generation-recovery")) {
+	const keyOf = (sessionId) => {
+		if (typeof sessionId !== "string" || !sessionId.length || sessionId.length > 1024) throw new Error("恢复会话身份无效");
+		return createHash("sha256").update(sessionId).digest("hex");
+	};
+	const read = (sessionId) => {
+		const file = join(root, keyOf(sessionId) + ".json");
+		assertNoModuleLinks(file);
+		if (!existsSync(file)) return {
+			sessionId,
+			used: 0,
+			executions: []
+		};
+		if (!statSync(file).isFile() || statSync(file).size > 131072) throw new Error("恢复额度文件无效或超限");
+		const data = JSON.parse(readFileSync(file, "utf8"));
+		if (data.sessionId !== sessionId || !Number.isSafeInteger(data.used) || data.used < 0 || data.used > 1e3 || !Array.isArray(data.executions) || data.executions.length !== data.used || data.executions.some((value) => typeof value !== "string" || !/^\d+:\d+$/.test(value)) || new Set(data.executions).size !== data.used) throw new Error("恢复额度文件损坏，拒绝重置");
+		return data;
+	};
+	return {
+		read,
+		claim(sessionId, execution, limit) {
+			if (!/^\d+:\d+$/.test(execution) || !Number.isSafeInteger(limit) || limit < 0 || limit > 1e3) throw new Error("恢复执行身份或额度无效");
+			const key = keyOf(sessionId);
+			assertNoModuleLinks(root);
+			mkdirSync(root, { recursive: true });
+			return withModuleLock(root, key, () => {
+				const state = read(sessionId);
+				if (state.executions.includes(execution) || state.used >= limit) return {
+					claimed: false,
+					used: state.used,
+					limit
+				};
+				const file = join(root, key + ".json"), temporary = join(root, "." + randomUUID() + ".tmp");
+				try {
+					writeFileSync(temporary, JSON.stringify({
+						sessionId,
+						used: state.used + 1,
+						executions: [...state.executions, execution]
+					}), { flag: "wx" });
+					assertNoModuleLinks(file);
+					renameSync(temporary, file);
+				} finally {
+					rmSync(temporary, { force: true });
+				}
+				return {
+					claimed: true,
+					used: state.used + 1,
+					limit
+				};
+			});
+		}
+	};
+}
+//#endregion
+//#region engine/context-provenance.mjs
+const configObject = passthrough((value, plugin, field) => {
+	if (value === void 0) return {};
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${plugin}: ${field} must be an object`);
+	return value;
+});
+defineConfig({
+	enabled: bool({ default: false }),
+	audience: enumOf([
+		"all",
+		"main",
+		"subagent"
+	], { default: "all" }),
+	auto: bool({ default: true }),
+	modelSwitch: bool({ default: true }),
+	prune: bool({ default: true }),
+	basic: configObject,
+	pruner: configObject,
+	recoveryRetainTokens: int$2({
+		min: 0,
+		default: 1024
+	})
+});
+const runtimes = /* @__PURE__ */ new WeakMap();
+const contextRuntimeOf = (agent) => runtimes.get(agent);
+//#endregion
 //#region engine/rule-runtime.mjs
 const noNext = /* @__PURE__ */ new Set([
 	"agent/inbox/inserted",
@@ -27337,6 +28792,7 @@ const noNext = /* @__PURE__ */ new Set([
 	"subagent/end"
 ]);
 const compare = (a, b) => a.action.channelOrder - b.action.channelOrder || a.moduleId.localeCompare(b.moduleId) || a.ruleIndex - b.ruleIndex || a.action.actionIndex - b.action.actionIndex;
+const sourceError = (error, moduleId) => Object.assign(new Error(String(error?.message ?? error), { cause: error }), { sourceModuleId: moduleId });
 /** 所有来源只进入这个装配入口；受众限定固定效果要求 ctx 属于 options.agent 的 scope。 */
 function mountRuleSources(ctx, sources, options = {}) {
 	validateDeliverySources(sources);
@@ -27346,12 +28802,6 @@ function mountRuleSources(ctx, sources, options = {}) {
 	})();
 	const pool = options.promotionPool ?? coordinator?.promotionPool ?? createPromotionPool(ctx);
 	const ownsPool = options.promotionPool === void 0 && coordinator?.promotionPool === void 0;
-	rebindConditions(sources, {
-		ctx,
-		standingMountFor: options.standingMountFor,
-		promotionPool: pool,
-		variableStore: options.variableStore
-	});
 	const warnOnce = options.warnOnce ?? createWarnOnce(ctx, options.plugin ?? "rule-engine");
 	const report = options.onOutcome === void 0 ? void 0 : (() => {
 		const moduleOfRule = /* @__PURE__ */ new Map();
@@ -27373,15 +28823,6 @@ function mountRuleSources(ctx, sources, options = {}) {
 		configs: [],
 		ruleActions: []
 	}]));
-	const rules = sources.flatMap((source) => source.rules.filter((rule) => rule.enabled !== false));
-	const observer = wireTriggerObservers(ctx, [...rules, ...rules.flatMap((rule) => (rule.actions ?? []).filter((action) => typeof action.actionWhen?.observe === "function").map((action) => ({
-		id: action.id,
-		when: action.actionWhen
-	})))], {
-		plugin: options.plugin ?? "rule-engine",
-		warnOnce
-	});
-	if (observer) releases.push(observer);
 	let active = true;
 	const bind = (item, on) => prepareAction(item.action, {
 		plugin: options.plugin,
@@ -27390,6 +28831,26 @@ function mountRuleSources(ctx, sources, options = {}) {
 		on
 	})(ctx);
 	try {
+		for (const source of sources) try {
+			rebindConditions([source], {
+				ctx,
+				standingMountFor: options.standingMountFor,
+				promotionPool: pool,
+				variableStore: options.variableStore,
+				manifestCheck: options.manifestCheck
+			});
+		} catch (error) {
+			throw sourceError(error, source.moduleId);
+		}
+		const rules = sources.flatMap((source) => source.rules.filter((rule) => rule.enabled !== false));
+		const observer = wireTriggerObservers(ctx, [...rules, ...rules.flatMap((rule) => (rule.actions ?? []).filter((action) => typeof action.actionWhen?.observe === "function").map((action) => ({
+			id: action.id,
+			when: action.actionWhen
+		})))], {
+			plugin: options.plugin ?? "rule-engine",
+			warnOnce
+		});
+		if (observer) releases.push(observer);
 		for (const source of sources) for (const [ruleIndex, rule] of source.rules.entries()) {
 			if (rule.enabled === false) continue;
 			for (const action of rule.actions) {
@@ -27419,6 +28880,7 @@ function mountRuleSources(ctx, sources, options = {}) {
 				releases.push(wireLayers(ctx, textConfigs, warnOnce, {
 					agent: options.agent,
 					turnStopBudgets,
+					sourceError,
 					on: (channel, handler) => {
 						if (channel !== point.channel) throw new TypeError(`rule action registered outside ${point.channel}: ${channel}`);
 						handlers.push({ handler });
@@ -27465,7 +28927,12 @@ function mountRuleSources(ctx, sources, options = {}) {
 					created.push(entry);
 					return () => {};
 				};
-				const dispose = bind(item, on);
+				let dispose;
+				try {
+					dispose = bind(item, on);
+				} catch (error) {
+					throw sourceError(error, moduleId);
+				}
 				if (typeof dispose?.miss === "function") for (const entry of created) entry.miss = dispose.miss;
 				releases.push(dispose);
 			}
@@ -27759,7 +29226,13 @@ function duplicateDedupeIdentities(prepared) {
 }
 function createAgentAssembly(ctx, options) {
 	const variableStore = createModuleVariableAdapter(options.moduleRoot);
+	const manifestCheck = ctx.get(MANIFEST_CHECK_SERVICE);
+	const recoveryState = createGenerationRecoveryState(join(dirname(options.moduleRoot), "generation-recovery"));
 	const ruleDiagnostics = createRuleDiagnosticsLedger();
+	const initialization = createModuleInitialization(ctx);
+	const lastGood = /* @__PURE__ */ new WeakMap();
+	const sourceVersions = /* @__PURE__ */ new WeakMap();
+	const rejectedVersions = /* @__PURE__ */ new WeakMap();
 	const mounts = /* @__PURE__ */ new Map();
 	const knownAgents = /* @__PURE__ */ new Set();
 	const watched = /* @__PURE__ */ new Map();
@@ -27850,9 +29323,69 @@ function createAgentAssembly(ctx, options) {
 		mounts.delete(sessionId);
 		await current.fiber.dispose();
 	};
+	const reject = (agent, item) => {
+		let rejected = rejectedVersions.get(agent);
+		if (rejected === void 0) {
+			rejected = /* @__PURE__ */ new Map();
+			rejectedVersions.set(agent, rejected);
+		}
+		let versions = rejected.get(item.moduleId);
+		if (versions === void 0) {
+			versions = /* @__PURE__ */ new Set();
+			rejected.set(item.moduleId, versions);
+		}
+		versions.add(sourceVersions.get(item) ?? "");
+		if (lastGood.get(agent)?.get(item.moduleId) === item) lastGood.get(agent)?.delete(item.moduleId);
+	};
 	const mount = async (agent, prepared, plan, duplicateIdentities = [], stamp = "", content = "") => {
+		let mounted = false, live = true;
+		const initializationErrors = [];
+		const waiting = new Map(prepared.map((item) => [item, /* @__PURE__ */ new Set()]));
+		const observers = [];
+		const initializationRoots = [];
+		const promote = () => {
+			if (!live || !mounted || !active || disposed.has(agent)) return;
+			let good = lastGood.get(agent);
+			if (good === void 0) {
+				good = /* @__PURE__ */ new Map();
+				lastGood.set(agent, good);
+			}
+			for (const item of prepared) if (waiting.get(item)?.size === 0 && !initializationErrors.some((failure) => failure.owners.includes(item))) good.set(item.moduleId, item);
+		};
+		const observe = (child, owners) => {
+			initializationRoots.push(child);
+			const token = {};
+			for (const item of owners) waiting.get(item)?.add(token);
+			observers.push(initialization.observe(child, {
+				ready: () => {
+					for (const item of owners) waiting.get(item)?.delete(token);
+					promote();
+				},
+				failed: (error) => {
+					if (!live || !active || disposed.has(agent)) return;
+					initializationErrors.push({
+						owners,
+						error
+					});
+					if (!mounted) return;
+					for (const item of owners) reject(agent, item);
+					serial(async () => {
+						if (!live || !active || disposed.has(agent)) return;
+						try {
+							await replace([agent]);
+						} catch (failure) {
+							warn(failure);
+						}
+					});
+					warn(new Error(`模块 ${owners.map((item) => item.moduleId).join("、")} 初始化失败：${failureReason(error)}`, { cause: error }));
+				}
+			}));
+		};
 		const services = /* @__PURE__ */ new Set();
-		for (const item of prepared) for (const name of item.services) services.add(name);
+		for (const item of prepared) for (const name of item.services) {
+			if (agent.ctx.get(name) === void 0) throw Object.assign(/* @__PURE__ */ new Error(`模块 ${item.moduleId} 挂载所需宿主能力不可用：${name}`), { sourceModuleId: item.moduleId });
+			services.add(name);
+		}
 		const personaActive = plan.sections.length > 0 || plan.suppressRuntimeContext;
 		if (personaActive) services.add("systemPrompt");
 		const fiber = agent.ctx.plugin({
@@ -27872,7 +29405,8 @@ function createAgentAssembly(ctx, options) {
 					agent,
 					onOutcome: ruleDiagnostics.record,
 					variableStore,
-					standingMountFor
+					standingMountFor,
+					manifestCheck
 				}));
 				if (personaActive) {
 					const capture = options.personaCapture;
@@ -27895,20 +29429,68 @@ function createAgentAssembly(ctx, options) {
 						return rollback;
 					}, "prompt-tool persona");
 				}
+				const applyCapability = async (capabilityCtx, item, module) => {
+					const result = await module.apply(capabilityCtx, module.config, {
+						agent,
+						sourceModuleId: item.moduleId,
+						sourceModuleDir: resolveModuleDir(item.moduleId, options.moduleRoot),
+						recoveryState,
+						contextRuntimeOf
+					});
+					if (typeof result === "function") capabilityCtx.effect(() => result, module.id);
+				};
+				const ownTokens = new Map(prepared.map((item) => [item, {}]));
+				for (const item of prepared) waiting.get(item)?.add(ownTokens.get(item));
+				for (const item of prepared) {
+					const capabilities = item.modules.filter((module) => PRIVATE_SERVICES[module.id] === void 0 || module.id === "retrieval");
+					if (capabilities.length === 0) continue;
+					const child = scopeCtx.plugin({
+						name: `prompt-tool-module:${item.moduleId}`,
+						apply: async (moduleCtx) => {
+							for (const module of capabilities) await applyCapability(moduleCtx, item, module);
+						}
+					});
+					observe(child, [item]);
+					try {
+						await child;
+					} catch (error) {
+						await child.dispose();
+						throw Object.assign(new Error(`模块 ${item.moduleId} 挂载失败：${failureReason(error)}`, { cause: error }), { sourceModuleId: item.moduleId });
+					}
+				}
 				const privateMounted = /* @__PURE__ */ new Set();
 				for (const item of prepared) for (const module of item.modules) {
-					if (PRIVATE_SERVICES[module.id] !== void 0) {
-						if (privateMounted.has(module.id)) continue;
-						privateMounted.add(module.id);
+					if (PRIVATE_SERVICES[module.id] === void 0 || module.id === "retrieval" || privateMounted.has(module.id)) continue;
+					const owners = prepared.filter((source) => source.modules.some((candidate) => candidate.id === module.id));
+					const child = scopeCtx.plugin({
+						name: `prompt-tool-shared:${module.id}`,
+						apply: async (sharedCtx) => {
+							await applyCapability(sharedCtx, item, module);
+						}
+					});
+					observe(child, owners);
+					try {
+						await child;
+					} catch (error) {
+						throw Object.assign(new Error(`模块 ${owners.map((owner) => owner.moduleId).join("、")} 共享能力 ${module.id} 初始化失败：${failureReason(error)}`, { cause: error }), { sourceModuleIds: owners.map((owner) => owner.moduleId) });
 					}
-					const result = await module.apply(scopeCtx, module.config, { agent });
-					if (typeof result === "function") scopeCtx.effect(() => result, module.id);
+					privateMounted.add(module.id);
 				}
+				for (const item of prepared) waiting.get(item)?.delete(ownTokens.get(item));
 			}
 		});
-		const disposeFiber = ctx.effect(() => () => fiber.dispose(), `prompt-tool assembly ${agent.id}`);
+		const disposeFiber = ctx.effect(() => () => {
+			live = false;
+			for (const off of observers) off();
+			return fiber.dispose();
+		}, `prompt-tool assembly ${agent.id}`);
 		try {
 			await fiber;
+			await initialization.settled(initializationRoots);
+			if (initializationErrors.length > 0) {
+				const failure = initializationErrors[0];
+				throw Object.assign(new Error(`模块 ${failure.owners.map((item) => item.moduleId).join("、")} 初始化失败：${failureReason(failure.error)}`, { cause: failure.error }), { sourceModuleIds: failure.owners.map((item) => item.moduleId) });
+			}
 		} catch (error) {
 			await disposeFiber();
 			throw error;
@@ -27928,11 +29510,18 @@ function createAgentAssembly(ctx, options) {
 			content,
 			plan
 		});
+		mounted = true;
+		promote();
 	};
 	const assemblyStamp = (ids, personas) => JSON.stringify(personas) + readModulesRevision(options.moduleRoot, ids);
-	const contentSignature = (ids, personas) => JSON.stringify([ids.map((id) => {
-		const { variables: _variables, ...definition } = loadModuleSpec(assertModuleDirectory(options.moduleRoot, id));
-		return [id, definition];
+	const contentSignature = (ids, personas, previous = "") => JSON.stringify([ids.map((id) => {
+		try {
+			const { variables: _variables, ...definition } = loadModuleSpec(assertModuleDirectory(options.moduleRoot, id));
+			return [id, definition];
+		} catch (error) {
+			warnOnce(`模块 ${id} 读取失败：${failureReason(error)}`);
+			return (previous === "" ? void 0 : JSON.parse(previous)[0].find((entry) => entry[0] === id)) ?? [id, { readError: failureReason(error) }];
+		}
 	}), personas]);
 	const watchSources = (ids, personas) => {
 		const files = /* @__PURE__ */ new Set([enableTablePath(options.moduleRoot), ...[...ids, ...(personas ?? []).map((item) => item.moduleId)].map((id) => {
@@ -27954,35 +29543,59 @@ function createAgentAssembly(ctx, options) {
 			}, listener);
 		}
 	};
-	const replace = async (targets) => {
+	const replace = async (targets, retry = false) => {
+		readGlobalLayerSettings(options.moduleRoot);
 		const ids = [...options.enabledModules()];
 		const personaModules = options.personaModules?.();
 		watchSources(ids, personaModules);
 		const live = targets.filter((agent) => active && !disposed.has(agent));
-		const prepared = [];
-		for (const id of ids) prepared.push(await prepareAssembly(options.moduleRoot, id, (name) => live.every((agent) => agent.ctx.get(name) !== void 0)));
+		const failures = [];
+		const candidates = [];
+		for (const agent of live) {
+			const previous = mounts.get(agent.id);
+			if (retry === true) rejectedVersions.delete(agent);
+			else if (typeof retry === "string") rejectedVersions.get(agent)?.delete(retry);
+			const good = lastGood.get(agent);
+			const goodSnapshot = good === void 0 ? void 0 : new Map(good);
+			const prepared = [];
+			for (const id of ids) try {
+				const item = await prepareAssembly(options.moduleRoot, id, (name) => agent.ctx.get(name) !== void 0);
+				const version = contentSignature([id], void 0);
+				sourceVersions.set(item, version);
+				if (rejectedVersions.get(agent)?.get(id)?.has(version)) {
+					const fallback = good?.get(id);
+					if (fallback !== void 0) prepared.push(fallback);
+				} else {
+					rejectedVersions.get(agent)?.delete(id);
+					prepared.push(item);
+				}
+			} catch (error) {
+				failures.push(new Error(`模块 ${id}（Agent ${agent.id}）准备失败：${failureReason(error)}`, { cause: error }));
+				const fallback = good?.get(id);
+				if (fallback !== void 0) prepared.push(fallback);
+			}
+			candidates.push({
+				agent,
+				prepared,
+				previous,
+				goodSnapshot
+			});
+		}
 		const stamp = assemblyStamp(ids, personaModules);
-		const content = contentSignature(ids, personaModules);
-		for (const item of prepared) for (const id of item.skippedOfficialRows) warnOnce(`模块 ${item.moduleId} 声明官方 recipe 行 ${id}；该行只能由会话原有预设提供，本插件不挂载官方包`);
-		const candidates = live.map((agent) => ({
-			agent,
-			prepared,
-			previous: mounts.get(agent.id)
-		}));
+		for (const item of candidates.flatMap((candidate) => candidate.prepared)) for (const id of item.skippedOfficialRows) warnOnce(`模块 ${item.moduleId} 声明官方 recipe 行 ${id}；该行只能由会话原有预设提供，本插件不挂载官方包`);
 		if (!active) return;
-		const effectivePersonas = personaModules ?? prepared;
 		if (options.personaModules !== void 0) await readPersonaKnowledge();
-		const sections = {
-			main: completeSectionsOf(prepared, "main"),
-			subagent: completeSectionsOf(prepared, "subagent")
-		};
-		for (const [audience, complete] of Object.entries(sections)) if (complete.length > 1) throw new Error(`${audience} 有多个生效 complete 段：${complete.join("、")}`);
-		const appendModules = {
-			main: prepared.filter((item) => hasSectionAppend(item.rules, "main")).map((item) => item.moduleId),
-			subagent: prepared.filter((item) => hasSectionAppend(item.rules, "subagent")).map((item) => item.moduleId)
-		};
-		const plans = candidates.map(({ agent }) => {
-			const plan = personaPlanFor(agent, effectivePersonas);
+		const planFor = (agent, prepared) => {
+			const sections = {
+				main: completeSectionsOf(prepared, "main"),
+				subagent: completeSectionsOf(prepared, "subagent")
+			};
+			for (const [audience, complete] of Object.entries(sections)) if (complete.length > 1) throw new Error(`${audience} 有多个生效 complete 段：${complete.join("、")}`);
+			const appendModules = {
+				main: prepared.filter((item) => hasSectionAppend(item.rules, "main")).map((item) => item.moduleId),
+				subagent: prepared.filter((item) => hasSectionAppend(item.rules, "subagent")).map((item) => item.moduleId)
+			};
+			const plan = personaPlanFor(agent, personaModules ?? prepared);
 			const audience = isDelegated(agent.session) ? "subagent" : "main";
 			const plannedPrefix = plan.sections.find((section) => section.name === PERSONA_PREFIX_SECTION);
 			const scope = scopeOf(agent.ctx);
@@ -27991,21 +29604,43 @@ function createAgentAssembly(ctx, options) {
 			if (personaComplete && sections[audience].length > 0) throw new Error(`Agent ${agent.id} 的 ${audience} 有多个生效 complete 段：人设与 ${sections[audience].join("、")}`);
 			if (appendModules[audience].length > 0 && (personaComplete || sections[audience].length > 0)) throw new Error(`Agent ${agent.id} 的 ${audience} 同时声明了 sections.append（${appendModules[audience].join("、")}）与 complete；请在同一受众二选一`);
 			return plan;
-		});
+		};
+		const plans = candidates.map(({ agent, prepared }) => planFor(agent, prepared));
 		const changed = [];
 		try {
 			for (const [index, candidate] of candidates.entries()) {
 				if (!active || disposed.has(candidate.agent)) continue;
 				changed.push(candidate);
 				await release(candidate.agent.id);
-				await mount(candidate.agent, candidate.prepared, plans[index], duplicateDedupeIdentities(candidate.prepared), stamp, content);
+				const content = contentSignature(ids, personaModules, candidate.previous?.content);
+				let plan = plans[index];
+				while (true) try {
+					await mount(candidate.agent, candidate.prepared, plan, duplicateDedupeIdentities(candidate.prepared), stamp, content);
+					break;
+				} catch (error) {
+					const sourceIds = error !== null && typeof error === "object" ? "sourceModuleIds" in error && Array.isArray(error.sourceModuleIds) ? error.sourceModuleIds : "sourceModuleId" in error ? [error.sourceModuleId] : [] : [];
+					const failed = candidate.prepared.filter((item) => sourceIds.includes(item.moduleId));
+					if (failed.length === 0) throw error;
+					for (const item of failed) {
+						failures.push(new Error(`模块 ${item.moduleId}（Agent ${candidate.agent.id}）发布失败：${failureReason(error)}`, { cause: error }));
+						reject(candidate.agent, item);
+					}
+					candidate.prepared = candidate.prepared.flatMap((item) => {
+						if (!failed.includes(item)) return [item];
+						const fallback = lastGood.get(candidate.agent)?.get(item.moduleId);
+						return fallback !== void 0 && fallback !== item ? [fallback] : [];
+					});
+					plan = planFor(candidate.agent, candidate.prepared);
+				}
 			}
 		} catch (error) {
 			const restoreErrors = [];
-			for (const { agent, previous } of changed.reverse()) {
+			for (const { agent, previous, goodSnapshot } of changed.reverse()) {
 				if (!active || disposed.has(agent)) continue;
 				try {
 					await release(agent.id);
+					if (goodSnapshot === void 0) lastGood.delete(agent);
+					else lastGood.set(agent, new Map(goodSnapshot));
 					if (previous?.agent === agent) await mount(agent, previous.prepared, previous.plan, [], previous.stamp, previous.content);
 				} catch (restoreError) {
 					restoreErrors.push(restoreError);
@@ -28014,6 +29649,11 @@ function createAgentAssembly(ctx, options) {
 			if (restoreErrors.length > 0) throw new AggregateError([error, ...restoreErrors], `切换装配失败（${failureReason(error)}），且恢复原有装配也失败（${restoreErrors.map(failureReason).join("；")}）`);
 			throw error;
 		}
+		for (const { agent } of candidates) {
+			const good = lastGood.get(agent);
+			for (const id of good?.keys() ?? []) if (!ids.includes(id)) good?.delete(id);
+		}
+		if (failures.length > 0) throw new AggregateError(failures, failures.map(failureReason).join("；"));
 	};
 	const install = async (agent) => {
 		knownAgents.add(agent);
@@ -28030,7 +29670,7 @@ function createAgentAssembly(ctx, options) {
 			const stamp = assemblyStamp(ids, personas);
 			const current = mounts.get(agent.id);
 			if (current?.stamp !== stamp) {
-				if (current?.content === contentSignature(ids, personas)) current.stamp = stamp;
+				if (current?.content === contentSignature(ids, personas, current?.content)) current.stamp = stamp;
 				else await replace([agent]);
 			}
 			lastReadError = void 0;
@@ -28084,7 +29724,14 @@ function createAgentAssembly(ctx, options) {
 		warn(error);
 	}
 	return {
-		settled: () => pending,
+		settled: async () => {
+			let previous;
+			do {
+				await initialization.settled();
+				previous = pending;
+				await previous;
+			} while (previous !== pending);
+		},
 		hasMounted: (sessionId) => mounts.has(sessionId),
 		moduleIds: (sessionId) => mounts.get(sessionId)?.moduleIds ?? [],
 		ruleDiagnostics: () => active ? ruleDiagnostics.snapshot() : emptyRuleDiagnostics(),
@@ -28097,7 +29744,7 @@ function createAgentAssembly(ctx, options) {
 						const current = mounts.get(agent.id);
 						return options.personaModules !== void 0 || moduleId === void 0 || current === void 0 || current.moduleIds.includes(moduleId) || enabled.includes(moduleId);
 					});
-					await replace(targets);
+					await replace(targets, moduleId ?? true);
 				});
 			} catch (error) {
 				throw new AggregateError([error], `运行时配装更新失败：${failureReason(error)}`);
@@ -28115,6 +29762,63 @@ function createAgentAssembly(ctx, options) {
 	};
 }
 //#endregion
+//#region src/host/module-manifest-check.ts
+/** 清单 checks 的运行期事实：只读，缓存 1000ms，manifest 戳变化提前失效。 */
+/** manifest 配置戳；同戳等长改写由缓存到期后的完整检查识别。 */
+const stampOf = (path) => {
+	const stat = statSync(path, { throwIfNoEntry: false });
+	return stat === void 0 ? void 0 : `${stat.mtimeMs}:${stat.size}`;
+};
+/**
+* check 本身保持只读：这里只把结果缓存成规则可读的事实。
+* 清单缺失、坏 YAML、模块目录不合法都是 undefined（UNAVAILABLE），不是「检查失败」。
+*/
+function createManifestCheckReader(moduleRoot) {
+	const dirs = /* @__PURE__ */ new Map();
+	const results = /* @__PURE__ */ new Map();
+	const dirOf = (moduleId) => {
+		const hit = dirs.get(moduleId);
+		if (hit !== void 0) return hit;
+		try {
+			const dir = assertModuleDirectory(moduleRoot, moduleId);
+			dirs.set(moduleId, dir);
+			return dir;
+		} catch {
+			return;
+		}
+	};
+	const read = (moduleId) => {
+		const dir = dirOf(moduleId);
+		if (dir === void 0) return void 0;
+		let stamp;
+		try {
+			stamp = stampOf(join(dir, "assets", "manifest.yml"));
+		} catch {
+			results.delete(dir);
+			return;
+		}
+		if (stamp === void 0) {
+			results.delete(dir);
+			return;
+		}
+		const hit = results.get(dir);
+		if (hit !== void 0 && hit.stamp === stamp && performance.now() - hit.checkedAt < 1e3) return hit.ok;
+		let ok;
+		try {
+			ok = runModuleManifest(dir, "check").ok;
+		} catch {
+			ok = void 0;
+		}
+		results.set(dir, {
+			stamp,
+			checkedAt: performance.now(),
+			ok
+		});
+		return ok;
+	};
+	return { read };
+}
+//#endregion
 //#region src/index.ts
 const name = "prompt-tool";
 const inject = [
@@ -28229,6 +29933,7 @@ function apply(ctx, configIn) {
 		target: (exec, moduleId) => resolveModuleToolTarget(exec, modulesDir(), (sessionId) => assembly?.moduleIds(sessionId) ?? [], moduleId),
 		rebuild: (id) => refreshModuleRuntime(id)
 	};
+	installSoulRuntime(ctx, moduleToolHost, (id) => assembly?.moduleIds(id) ?? []);
 	ctx.provide(toolServiceName("module-import-tools"), { mount: (scopeCtx) => registerModuleImportTools(scopeCtx, {
 		...moduleToolHost,
 		rebuild: async (id) => {
@@ -28238,7 +29943,9 @@ function apply(ctx, configIn) {
 	ctx.provide(toolServiceName("module-rule-tools"), { mount: (scopeCtx) => registerModuleRuleTools(scopeCtx, moduleToolHost) });
 	ctx.provide(toolServiceName("module-file-tools"), { mount: (scopeCtx) => registerModuleFileTools(scopeCtx, moduleToolHost) });
 	ctx.provide(toolServiceName("module-manifest-tools"), { mount: (scopeCtx) => registerModuleManifestTools(scopeCtx, moduleToolHost) });
+	ctx.provide(toolServiceName("soul-ledger"), { mount: (scopeCtx) => registerSoulLedgerTools(scopeCtx, moduleToolHost) });
 	ctx.provide(DISCOVERY_SERVICE, createDiscoveryRegistry());
+	ctx.provide(MANIFEST_CHECK_SERVICE, createManifestCheckReader(modulesDir()));
 	ctx.provide(toolServiceName("module-variable-tools"), { mount: (scopeCtx) => registerModuleVariableTools(scopeCtx, moduleToolHost) });
 	import(new URL("../engine/skill-search.mjs", import.meta.url).href).then((mod) => {
 		if (typeof mod.apply !== "function") return;
@@ -28254,7 +29961,7 @@ function apply(ctx, configIn) {
 	const personaCapture = installPersonaCapture(ctx);
 	ctx.effect(function* () {
 		yield () => personaCapture.dispose();
-		const agentsFiber = ctx.inject(["agents"], (actx) => {
+		const agentsFiber = ctx.inject(["agents", MANIFEST_CHECK_SERVICE], (actx) => {
 			const mounted = createAgentAssembly(actx, {
 				moduleRoot: modulesDir(),
 				enabledModules: () => runtime.modulesEnabled ? enabledModuleIds(modulesDir()) : [],