dsh-plugin-prompt-tool 3.1.3 → 3.1.5

package/lib/index.mjs

@@ -1,6 +1,6 @@
 import { createRequire } from "node:module";
 import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
-import { Document, Pair, Scalar, YAMLMap, YAMLSeq, isMap, isScalar, isSeq, parse, parseDocument, stringify, visit } from "yaml";
+import { Document, Pair, Scalar, YAMLMap, YAMLSeq, isAlias, isMap, isScalar, isSeq, parse, parseDocument, stringify, visit } from "yaml";
 import { accessSync, appendFileSync, chmodSync, constants, cpSync, createWriteStream, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, unwatchFile, watchFile, writeFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { homedir } from "node:os";
@@ -15,9 +15,9 @@ import { Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { Uint8ArrayReader, Uint8ArrayWriter, ZipReader, ZipWriter } from "@zip.js/zip.js";
 import { inflateSync } from "node:zlib";
+import "@deepseek-ai/cordis";
 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",
@@ -429,6 +429,7 @@ const MODULE_TOOL_NAMES = {
 	manifest: "module_manifest",
 	variables: "module_variables",
 	soulLedger: "soul_ledger",
+	soulState: "soul_state",
 	search: "module_search",
 	open: "module_open"
 };
@@ -441,6 +442,7 @@ const MODULE_TOOL_CAPABILITIES = {
 	[MODULE_TOOL_NAMES.manifest]: "module-manifest-tools",
 	[MODULE_TOOL_NAMES.variables]: "module-variable-tools",
 	[MODULE_TOOL_NAMES.soulLedger]: "soul-ledger",
+	[MODULE_TOOL_NAMES.soulState]: "soul-ledger",
 	[MODULE_TOOL_NAMES.search]: "retrieval",
 	[MODULE_TOOL_NAMES.open]: "retrieval"
 };
@@ -2086,7 +2088,7 @@ const PAIR = Symbol.for("yaml.pair");
 const SCALAR$1 = Symbol.for("yaml.scalar");
 const SEQ = Symbol.for("yaml.seq");
 const NODE_TYPE = Symbol.for("yaml.node.type");
-const isAlias = (node) => !!node && typeof node === "object" && node[NODE_TYPE] === ALIAS;
+const isAlias$1 = (node) => !!node && typeof node === "object" && node[NODE_TYPE] === ALIAS;
 const isDocument = (node) => !!node && typeof node === "object" && node[NODE_TYPE] === DOC;
 const isMap$1 = (node) => !!node && typeof node === "object" && node[NODE_TYPE] === MAP;
 const isPair = (node) => !!node && typeof node === "object" && node[NODE_TYPE] === PAIR;
@@ -2281,7 +2283,7 @@ function callVisitor(key, node, visitor, path) {
 	if (isSeq$1(node)) return visitor.Seq?.(key, node, path);
 	if (isPair(node)) return visitor.Pair?.(key, node, path);
 	if (isScalar$1(node)) return visitor.Scalar?.(key, node, path);
-	if (isAlias(node)) return visitor.Alias?.(key, node, path);
+	if (isAlias$1(node)) return visitor.Alias?.(key, node, path);
 }
 function replaceNode$1(key, path, node) {
 	const parent = path[path.length - 1];
@@ -2291,7 +2293,7 @@ function replaceNode$1(key, path, node) {
 		else parent.value = node;
 	} else if (isDocument(parent)) parent.contents = node;
 	else {
-		const pt = isAlias(parent) ? "alias" : "scalar";
+		const pt = isAlias$1(parent) ? "alias" : "scalar";
 		throw new Error(`Cannot replace node with ${pt} parent`);
 	}
 }
@@ -2634,7 +2636,7 @@ var Alias = class extends NodeBase {
 		else {
 			nodes = [];
 			visit$2(doc, { Node: (_key, node) => {
-				if (isAlias(node) || hasAnchor(node)) nodes.push(node);
+				if (isAlias$1(node) || hasAnchor(node)) nodes.push(node);
 			} });
 			if (ctx) ctx.aliasResolveCache = nodes;
 		}
@@ -2683,7 +2685,7 @@ var Alias = class extends NodeBase {
 	}
 };
 function getAliasCount(doc, node, anchors) {
-	if (isAlias(node)) {
+	if (isAlias$1(node)) {
 		const source = node.resolve(doc);
 		const anchor = anchors && source && anchors.get(source);
 		return anchor ? anchor.count * anchor.aliasCount : 0;
@@ -3321,7 +3323,7 @@ function stringifyProps(node, tagObj, { anchors, doc }) {
 }
 function stringify$1(item, ctx, onComment, onChompKeep) {
 	if (isPair(item)) return item.toString(ctx, onComment, onChompKeep);
-	if (isAlias(item)) {
+	if (isAlias$1(item)) {
 		if (ctx.doc.directives) return item.toString(ctx);
 		if (ctx.resolvedAliases?.has(item)) throw new TypeError(`Cannot stringify circular structure without alias nodes`);
 		else {
@@ -3448,11 +3450,11 @@ const merge = {
 const isMergeKey = (ctx, key) => (merge.identify(key) || isScalar$1(key) && (!key.type || key.type === Scalar$1.PLAIN) && merge.identify(key.value)) && ctx?.doc.schema.tags.some((tag) => tag.tag === merge.tag && tag.default);
 function addMergeToJSMap(ctx, map, value) {
 	const source = resolveAliasValue(ctx, value);
-	if (isSeq$1(source)) for (const it of source.items) mergeValue(ctx, map, it);
-	else if (Array.isArray(source)) for (const it of source) mergeValue(ctx, map, it);
-	else mergeValue(ctx, map, source);
+	if (isSeq$1(source)) for (const it of source.items) mergeValue$1(ctx, map, it);
+	else if (Array.isArray(source)) for (const it of source) mergeValue$1(ctx, map, it);
+	else mergeValue$1(ctx, map, source);
 }
-function mergeValue(ctx, map, value) {
+function mergeValue$1(ctx, map, value) {
 	const source = resolveAliasValue(ctx, value);
 	if (!isMap$1(source)) throw new Error("Merge sources must be maps or map aliases");
 	const srcMap = source.toJSON(null, ctx, Map);
@@ -3468,7 +3470,7 @@ function mergeValue(ctx, map, value) {
 	return map;
 }
 function resolveAliasValue(ctx, value) {
-	return ctx && isAlias(value) ? value.resolve(ctx.doc, ctx) : value;
+	return ctx && isAlias$1(value) ? value.resolve(ctx.doc, ctx) : value;
 }
 //#endregion
 //#region engine/vendor/yaml/dist/nodes/addPairToJSMap.js
@@ -8861,7 +8863,8 @@ 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) };
+		const text = service.render(config.sourceModuleId, agent, signal);
+		return typeof text?.then === "function" ? text.then((value) => ({ text: value })) : { text };
 	};
 }
 /** 动态填充器:strategy=placeholder 时按 fill 键在注入点填充内容。 */
@@ -10346,6 +10349,7 @@ function ruleFrame(channel, args, warnOnce = () => {}, ctx, onOutcome) {
 		subject: subjectOf(channel, args, warnOnce, ctx),
 		decisions: /* @__PURE__ */ new Map(),
 		actionDecisions: /* @__PURE__ */ new Set(),
+		reminders: /* @__PURE__ */ new Map(),
 		warnOnce,
 		onOutcome
 	};
@@ -10381,7 +10385,8 @@ function decideRule(rule, frame) {
 	}
 	const decided = {
 		hit,
-		outcome
+		outcome,
+		reminders: hit ? rule.when?.soulReminders ?? [] : []
 	};
 	frame.decisions.set(rule, decided);
 	return decided;
@@ -10407,7 +10412,11 @@ function ruleMatches(rule, frame) {
 * `hit` 再记 `miss`。没有分支的动作最终判定就是规则级判定，沿用规则级上报。
 */
 function actionMatches(entry, frame) {
-	if (!(entry.actionWhen !== void 0 || entry.bypassRuleWhen === true)) return ruleMatches(entry.rule, frame);
+	if (!(entry.actionWhen !== void 0 || entry.bypassRuleWhen === true)) {
+		const hit = ruleMatches(entry.rule, frame);
+		frame.reminders.set(entry, hit ? decideRule(entry.rule, frame).reminders ?? [] : []);
+		return hit;
+	}
 	const ruled = entry.bypassRuleWhen === true ? {
 		hit: true,
 		outcome: "hit"
@@ -10427,8 +10436,20 @@ function actionMatches(entry, frame) {
 		frame.actionDecisions.add(entry);
 		report(frame, entry.rule, outcome);
 	}
+	frame.reminders.set(entry, hit ? [...ruled.reminders ?? [], ...entry.actionWhen?.soulReminders ?? []] : []);
 	return hit;
 }
+/** 只关联实际命中路径的正向Soul事实；普通分支没有提醒戳。 */
+function actionSoulReminder(entry, frame) {
+	return frame.reminders.get(entry)?.[0];
+}
+function recheckSoulReminder(entry, frame, expected) {
+	if (expected === void 0) return true;
+	const current = ruleFrame(frame.channel, frame.args, frame.warnOnce, void 0);
+	if (!actionMatches(entry, current)) return false;
+	const fact = actionSoulReminder(entry, current);
+	return fact?.predicate === expected.predicate && fact.moduleId === expected.moduleId && fact.pendingVersion === expected.pendingVersion && fact.epoch === expected.epoch;
+}
 //#endregion
 //#region engine/layers.mjs
 /**
@@ -10716,8 +10737,18 @@ function wireRuleTextContributions(ctx, configs, registry, warnOnce, keep, on, o
 			for (const config of binding.group) {
 				if (!active || context.signal?.aborted || !actionMatches(config, frame) || !matchesAgentScope(config, context.agent)) continue;
 				try {
+					const reminder = actionSoulReminder(config, frame);
 					const text = config.layer === "runtime-context" && (config.strategy === "placeholder" || !KNOWN_STRATEGIES.has(config.strategy)) ? await resolvedContextText(ctx, config, context, registry.get(config), warnOnce) : configText(config, registry, warnOnce, context);
-					if (text.length) blocks.push(text);
+					if (!recheckSoulReminder(config, frame, reminder)) continue;
+					if (text.length) {
+						const stamp = reminder === void 0 ? "" : `\n<!-- soul-reminder:${Buffer.from(JSON.stringify({
+							moduleId: config.sourceModuleId,
+							sessionId: context.agent.session.id,
+							pendingVersion: reminder.pendingVersion,
+							epoch: reminder.epoch
+						})).toString("base64")} -->`;
+						blocks.push(text + stamp);
+					}
 				} catch (error) {
 					warnOnce(`${name$2}: rule text ${config.id} failed: ${String(error?.message ?? error)}`);
 				}
@@ -12117,6 +12148,7 @@ async function runPromptConfigBatch(options) {
 			if (config.dedupe === "session") {
 				if (alreadyDelivered(config, session, memo)) continue;
 			} else if (config.dedupe === "batch" && hasInBatch(config, messages)) continue;
+			const reminder = actionSoulReminder(config, options.ruleFrame);
 			const signal = options.payload?.signal;
 			if (signal?.aborted) continue;
 			const resolved = await config.resolve({
@@ -12130,7 +12162,15 @@ async function runPromptConfigBatch(options) {
 			});
 			if (signal?.aborted) continue;
 			if (resolved === null || resolved === void 0) continue;
+			if (!recheckSoulReminder(config, options.ruleFrame, reminder)) continue;
 			const patched = { ...resolved };
+			if (reminder !== void 0) patched.source = {
+				...patched.source,
+				soulReminder: {
+					pendingVersion: reminder.pendingVersion,
+					epoch: reminder.epoch
+				}
+			};
 			const mergedVars = {
 				...config["variablesDisabled"] === true ? {} : config.params?.templateEvaluation !== true && [patched.text, ...config.texts].some((text) => typeof text === "string" && text.includes("{{")) ? config.variableStore?.read(config.sourceModuleId).effective ?? config.variables : config.variables,
 				...resolved.variables !== null && typeof resolved.variables === "object" ? resolved.variables : {}
@@ -14256,6 +14296,24 @@ function createManifestPredicate(options = {}, context = {}) {
 	return predicate;
 }
 //#endregion
+//#region engine/conditions/soul.mjs
+function createSoulPredicate(options = {}, context = {}) {
+	if (Object.keys(options).some((key) => key !== "pending") || options.pending !== true) throw new TypeError("predicates: soul requires pending: true");
+	const predicate = (payload) => {
+		predicate.soulReminders = [];
+		if (typeof context.soulReminder?.read !== "function" || !context.moduleId) return UNAVAILABLE;
+		const fact = context.soulReminder.read(context.moduleId, agentOf(payload));
+		if (fact?.due === true) predicate.soulReminders = [{
+			...fact,
+			predicate,
+			moduleId: context.moduleId
+		}];
+		return typeof fact?.due === "boolean" ? fact.due : UNAVAILABLE;
+	};
+	predicate.kind = "soul";
+	return predicate;
+}
+//#endregion
 //#region engine/conditions/operators.mjs
 /** 条件树组合算子的唯一清单：纯 ESM，无宿主 import，client 可打包。 */
 const COMPOSITE_OPERATORS = Object.freeze(Object.values(MATCH_LOGIC));
@@ -14284,21 +14342,29 @@ function composite(node) {
 	const children = list.map(composite);
 	const predicate = {
 		[MATCH_LOGIC.ANY]: (payload) => {
+			predicate.soulReminders = [];
 			let unknown = false;
 			for (const child of children) {
 				const result = child(payload);
 				if (result === UNAVAILABLE) unknown = true;
-				else if (result) return true;
+				else if (result) {
+					predicate.soulReminders = child.soulReminders ?? [];
+					return true;
+				}
 			}
 			return unknown ? UNAVAILABLE : false;
 		},
 		[MATCH_LOGIC.ALL]: (payload) => {
+			predicate.soulReminders = [];
+			const reminders = [];
 			let unknown = false;
 			for (const child of children) {
 				const result = child(payload);
 				if (result === UNAVAILABLE) unknown = true;
 				else if (!result) return false;
+				if (result === true) reminders.push(...child.soulReminders ?? []);
 			}
+			if (!unknown) predicate.soulReminders = reminders;
 			return unknown ? UNAVAILABLE : true;
 		},
 		[MATCH_LOGIC.NOT_ANY]: (payload) => {
@@ -14332,7 +14398,8 @@ const PREDICATE_FACTORIES = Object.freeze({
 	scope: createScopePredicate,
 	anchor: createAnchorPredicate,
 	variable: createVariablePredicate,
-	manifest: createManifestPredicate
+	manifest: createManifestPredicate,
+	soul: createSoulPredicate
 });
 const objectOrUndefined = (value, label) => {
 	if (value === void 0 || value === null) return void 0;
@@ -14373,6 +14440,7 @@ function compileWhen(node, context = {}) {
 		manifestCheck: context.manifestCheck,
 		moduleId: context.moduleId
 	});
+	if (key === "soul") return createSoulPredicate(options, context);
 	return withAvailableInput(key, options, factory(options));
 }
 //#endregion
@@ -14487,7 +14555,8 @@ const PREDICATE_EXAMPLES = {
 		value: "0",
 		scope: "effective"
 	},
-	manifest: { ok: true }
+	manifest: { ok: true },
+	soul: { pending: true }
 };
 //#endregion
 //#region engine/record.mjs
@@ -14707,6 +14776,7 @@ const RULE_FIELDS = /* @__PURE__ */ new Set([
 	"do"
 ]);
 const nonempty$1 = (value) => typeof value === "string" && value.trim().length > 0;
+const hasSoulCondition = (node) => node !== null && typeof node === "object" && (Object.hasOwn(node, "soul") || Object.values(node).some(hasSoulCondition));
 /** `prepend` 退役文案（动作层与 `inject-text.config` 共用）：等价档只有「注册到最外层」一档，而 `inject-text` 连它也不接受。 */
 const PREPEND_RETIRED = "`prepend` 已取消 — 它是未文档化的注册后门（executor 直读 config.prepend），作用只有「注册到最外层」一档：非 inject-text 动作改用 `waterfallPosition: outermost`；`inject-text` 不接受该字段，没有等价写法";
 /**
@@ -14915,7 +14985,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, manifestCheck: _manifestCheck, ...conditionOptions } = options;
+	const { ctx: _ctx, standingMountFor: _standingMountFor, variableStore: _variableStore, manifestCheck: _manifestCheck, soulReminder: _soulReminder, ...conditionOptions } = options;
 	const ids = /* @__PURE__ */ new Set();
 	const pendingConfigs = [];
 	const moduleId = options.moduleId ?? options.sourceModuleId;
@@ -14959,7 +15029,10 @@ function compileRules(specs, options = {}) {
 			if (source.prepend !== void 0) throw new TypeError(`rule ${spec.id}: action ${source.id}: ${PREPEND_RETIRED}`);
 			if (source.match !== void 0) throw new TypeError(`rule ${spec.id}: action ${source.id}.match 已取消 — 声明路径写不了函数，条件改用 rule.if`);
 			const action = structuredClone(source);
-			if (action.kind === "inject-text") action.config = injectionConfigSpec(spec, action, options);
+			if (action.kind === "inject-text") {
+				action.config = injectionConfigSpec(spec, action, options);
+				if ((hasSoulCondition(ruleIf) || conditions.some(hasSoulCondition)) && !["pre-step", "runtime-context"].includes(action.config.layer)) throw new TypeError("soul reminder conditions support only pre-step or runtime-context delivery");
+			}
 			const execution = ruleActionExecution(action);
 			normalizeActionGates(action, execution);
 			validateConfig(`rule ${spec.id}: action ${action.id}`, action, ACTION_FIELDS[action.kind]);
@@ -15076,6 +15149,7 @@ function needsMountContext(node) {
 	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, "soul")) 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);
@@ -26723,6 +26797,125 @@ const SOUL_LEDGER_TYPES = [
 	"persona",
 	"container"
 ];
+const METADATA_PATH = "data/.soul-ledger-v2.json";
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+const ledgerIdentity = (moduleDir) => hash(canonicalDirectory(moduleDir));
+function boundaryOf(moduleDir, content) {
+	const stored = readModuleFile(moduleDir, METADATA_PATH).content;
+	if (!stored) return void 0;
+	const value = JSON.parse(stored);
+	if (value.version !== 2 || typeof value.identity !== "string" || !/^[a-f0-9]{64}$/.test(value.identity) || !Number.isSafeInteger(value.length) || value.length < 0 || value.length > content.length || value.prefix !== hash(content.slice(0, value.length))) throw new Error("账本历史分界不匹配，拒绝使用被替换的来源");
+	return value;
+}
+function initializeBoundary(moduleDir, content) {
+	if (boundaryOf(moduleDir, content)) return;
+	ensureDataDirectory(moduleDir);
+	const file = resolveModuleFilePath(moduleDir, METADATA_PATH, ["data"]);
+	const temporary = file + "." + randomUUID() + ".tmp";
+	try {
+		writeFileSync(temporary, JSON.stringify({
+			version: 2,
+			identity: ledgerIdentity(moduleDir),
+			length: content.length,
+			prefix: hash(content)
+		}), { flag: "wx" });
+		renameSync(temporary, file);
+	} finally {
+		rmSync(temporary, { force: true });
+	}
+}
+function readSoulLedgerProjection(moduleDir) {
+	const content = readModuleFile(moduleDir, SOUL_LEDGER_PATH).content;
+	const parsed = rowsOf(content);
+	const boundary = boundaryOf(moduleDir, content);
+	let prefix = hash(ledgerIdentity(moduleDir) + ":" + (boundary?.identity ?? ledgerIdentity(moduleDir)));
+	let offset = 0;
+	let index = 0;
+	const items = [];
+	const closed = /* @__PURE__ */ new Set();
+	let currentLead;
+	const entries = content.split("\n").flatMap((line) => {
+		const position = offset;
+		offset += line.length + 1;
+		prefix = hash(prefix + ":" + line);
+		if (!line.trim()) return [];
+		const entry = {
+			...parsed[index++],
+			id: prefix
+		};
+		if (entry.type === "lead") currentLead = entry.by;
+		if (entry.type === "close") {
+			const target = items.find((item) => item.id === entry.targetId);
+			if (!target || closed.has(target.id) || !["completed", "cancelled"].includes(String(entry.outcome)) || !entry["概要"].trim() || entry.by !== currentLead && (target.entry.type === "promise" || target.entry.by !== entry.by)) throw new Error("账本收口事件无效或未获授权");
+			closed.add(target.id);
+		}
+		if (entry.type === "promise" || entry.type === "shelved") items.push({
+			id: prefix,
+			entry,
+			status: !boundary || position < boundary.length ? "pending-review" : "open"
+		});
+		return [entry];
+	});
+	const pending = items.filter((item) => !closed.has(item.id));
+	const open = pending.filter((item) => item.status === "open").length;
+	return {
+		revision: hash(content),
+		initialized: !!boundary,
+		total: entries.length,
+		entries,
+		items: pending,
+		open,
+		pendingReview: pending.length - open,
+		pendingVersion: hash(JSON.stringify(pending.map((item) => [item.id, item.status]))),
+		lead: entries.findLast((entry) => entry.type === "lead")
+	};
+}
+function closeSoulLedger(moduleDir, input, caller) {
+	if (!caller.sessionId?.trim()) throw new Error("账本写入需要真实会话身份");
+	if (Object.keys(input).some((key) => ![
+		"targetId",
+		"outcome",
+		"reason",
+		"ref"
+	].includes(key))) throw new Error("收口包含未知字段");
+	if (typeof input.targetId !== "string" || !/^[a-f0-9]{64}$/.test(input.targetId)) throw new Error("账本引用无效");
+	if (!["completed", "cancelled"].includes(input.outcome)) throw new Error("收口结果必须为 completed 或 cancelled");
+	if (typeof input.reason !== "string" || !input.reason.trim() || Buffer.byteLength(input.reason) > 8192) throw new Error("收口依据必须为非空且不超过 8 KiB");
+	if (input.ref !== void 0 && (typeof input.ref !== "string" || Buffer.byteLength(input.ref) > 8192)) throw new Error("收口 ref 超过 8 KiB");
+	return withModuleLock(dirname(moduleDir), basename(moduleDir), () => {
+		caller.signal?.throwIfAborted();
+		const projection = readSoulLedgerProjection(moduleDir);
+		const target = projection.entries.find((entry) => entry.id === input.targetId);
+		if (!target || !["promise", "shelved"].includes(target.type)) throw new Error("账本引用不存在或不是可收口事项");
+		if (projection.lead?.by !== caller.sessionId && (target.type === "promise" || target.by !== caller.sessionId)) throw new Error("只有当前主导可收口 promise；shelved 允许原作者或当前主导");
+		const existing = projection.entries.find((entry) => entry.type === "close" && entry.targetId === input.targetId);
+		if (existing) {
+			if (existing.outcome !== input.outcome) throw new Error("事项已收口，不能更改结果");
+			const { id: _id, ...entry } = existing;
+			return { entry };
+		}
+		const previous = readModuleFile(moduleDir, SOUL_LEDGER_PATH).content;
+		const entry = {
+			t: (/* @__PURE__ */ new Date()).toISOString(),
+			by: caller.sessionId,
+			type: "close",
+			"概要": input.reason,
+			targetId: input.targetId,
+			outcome: input.outcome,
+			...input.ref === void 0 ? {} : { ref: input.ref }
+		};
+		persistEntry(moduleDir, previous, entry, caller.signal);
+		return { entry };
+	});
+}
+function persistEntry(moduleDir, previous, entry, signal) {
+	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");
+	initializeBoundary(moduleDir, previous);
+	const file = resolveModuleFilePath(moduleDir, SOUL_LEDGER_PATH, ["data"]);
+	signal?.throwIfAborted();
+	appendFileSync(file, line, "utf8");
+}
 function rowsOf(content) {
 	return content.split("\n").filter((line) => line.trim()).map((line, index) => {
 		const row = JSON.parse(line);
@@ -26739,14 +26932,47 @@ function rowsOf(content) {
 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);
+	if (options.type !== void 0 && ![...SOUL_LEDGER_TYPES, "close"].includes(options.type)) throw new Error("未知账本类型");
+	const view = options.view ?? "history";
+	if (![
+		"history",
+		"pending",
+		"open",
+		"pending-review"
+	].includes(view)) throw new Error("未知账本视图");
+	const projection = readSoulLedgerProjection(moduleDir);
+	const all = view === "history" ? projection.entries : projection.items.filter((item) => view === "pending" || item.status === view).map((item) => item.entry);
 	const rows = options.type === void 0 ? all : all.filter((row) => row.type === options.type);
-	const entries = rows.slice(-limit);
+	const filter = JSON.stringify([
+		view,
+		options.type ?? null,
+		limit
+	]);
+	let offset = view === "history" && options.cursor === void 0 ? Math.max(0, rows.length - limit) : 0;
+	if (options.cursor !== void 0) {
+		if (typeof options.cursor !== "string" || options.cursor.length > 2048) throw new Error("账本游标无效");
+		let cursor;
+		try {
+			cursor = JSON.parse(Buffer.from(options.cursor, "base64url").toString("utf8"));
+		} catch {
+			throw new Error("账本游标无效");
+		}
+		if (!cursor || Object.keys(cursor).sort().join(",") !== "filter,offset,revision" || cursor.revision !== projection.revision || cursor.filter !== filter || !Number.isSafeInteger(cursor.offset) || cursor.offset < 0 || cursor.offset >= rows.length) throw new Error("账本游标已失效或不匹配");
+		offset = cursor.offset;
+	}
+	const entries = rows.slice(offset, offset + limit);
 	if (Buffer.byteLength(JSON.stringify(entries)) > 65536) throw new Error("账本读取结果超过 64 KiB，请降低 limit");
+	const nextCursor = offset + limit < rows.length ? Buffer.from(JSON.stringify({
+		revision: projection.revision,
+		filter,
+		offset: offset + limit
+	})).toString("base64url") : void 0;
 	return {
 		entries,
-		total: rows.length
+		total: rows.length,
+		initialized: projection.initialized,
+		revision: projection.revision,
+		...nextCursor ? { nextCursor } : {}
 	};
 }
 function appendSoulLedger(moduleDir, input, caller) {
@@ -26766,7 +26992,7 @@ function appendSoulLedger(moduleDir, input, caller) {
 	return withModuleLock(dirname(moduleDir), basename(moduleDir), () => {
 		caller.signal?.throwIfAborted();
 		const previous = readModuleFile(moduleDir, SOUL_LEDGER_PATH).content;
-		const rows = rowsOf(previous);
+		const rows = readSoulLedgerProjection(moduleDir).entries;
 		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(),
@@ -26776,12 +27002,7 @@ function appendSoulLedger(moduleDir, input, caller) {
 			...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");
+		persistEntry(moduleDir, previous, entry, caller.signal);
 		return { entry };
 	});
 }
@@ -26801,18 +27022,38 @@ function registerSoulLedgerTools(ctx, host) {
 		});
 		const offTool = toolsCtx.tools.register(defineTool({
 			name: MODULE_TOOL_NAMES.soulLedger,
-			description: "读取或追加模块只追加账本。作者和时间来自真实执行会话；promise 仅当前 lead 署名者能写。lead 必须由用户指定并附 ref；text 与概要二选一，feel 有感受才写。",
+			description: "读取、追加或逐项收口模块账本。作者时间由真实会话提供；promise 仅当前 lead 可写/收口，shelved 原作者或当前 lead 可收口。close 用 targetId、completed/cancelled 和非空 reason；ref 是证据出处。pending/open/pending-review 视图支持版本游标分页。lead 必须用户指定并附 ref。",
 			parameters: {
 				moduleId: MODULE_ID_PARAM,
 				action: {
 					type: "string",
-					enum: ["list", "append"],
+					enum: [
+						"list",
+						"append",
+						"close"
+					],
 					required: true
 				},
+				targetId: { type: "string" },
+				outcome: {
+					type: "string",
+					enum: ["completed", "cancelled"]
+				},
+				reason: { type: "string" },
 				type: {
 					type: "string",
-					enum: [...SOUL_LEDGER_TYPES]
+					enum: [...SOUL_LEDGER_TYPES, "close"]
 				},
+				view: {
+					type: "string",
+					enum: [
+						"history",
+						"pending",
+						"open",
+						"pending-review"
+					]
+				},
+				cursor: { type: "string" },
 				text: { type: "string" },
 				"概要": { type: "string" },
 				ref: { type: "string" },
@@ -26835,7 +27076,14 @@ function registerSoulLedgerTools(ctx, host) {
 								additionalProperties: true
 							}
 						},
-						total: { type: "integer" }
+						total: { type: "integer" },
+						nextCursor: { type: "string" },
+						initialized: { type: "boolean" },
+						revision: { type: "string" },
+						derived: {
+							type: "object",
+							additionalProperties: true
+						}
 					}
 				},
 				render: (_args, value) => [{
@@ -26852,20 +27100,59 @@ function registerSoulLedgerTools(ctx, host) {
 					"概要",
 					"ref",
 					"feel",
-					"limit"
+					"limit",
+					"targetId",
+					"outcome",
+					"reason",
+					"view",
+					"cursor"
 				].includes(key))) throw new Error("账本工具含未知字段，不能指定作者或覆盖历史");
 				exec.signal.throwIfAborted();
 				const target = host.target(exec, args.moduleId);
+				const committed = (result) => {
+					try {
+						const owner = ctx.get?.(SOUL_SELF_SERVICE);
+						const derived = exec.agent && owner?.committed?.(target.id, exec.agent);
+						return {
+							...result,
+							...derived ? { derived } : {}
+						};
+					} catch {
+						return {
+							...result,
+							derived: {
+								state: "failed",
+								error: "账本已提交；派生状态通知失败，请用soul_state check核对，勿重放写入。"
+							}
+						};
+					}
+				};
+				if (args.action === "close") {
+					if (args.type !== void 0 || args.text !== void 0 || args["概要"] !== void 0 || args.feel !== void 0 || args.limit !== void 0 || args.view !== void 0 || args.cursor !== void 0) throw new Error("收口不接受追加或读取字段");
+					if (!args.targetId || !args.outcome || !args.reason) throw new Error("收口需要 targetId、outcome 与 reason");
+					return committed(closeSoulLedger(target.dir, {
+						targetId: args.targetId,
+						outcome: args.outcome,
+						reason: args.reason,
+						...args.ref === void 0 ? {} : { ref: args.ref }
+					}, {
+						sessionId: exec.agent?.session.id,
+						signal: exec.signal
+					}));
+				}
+				if (args.targetId !== void 0 || args.outcome !== void 0 || args.reason !== void 0) throw new Error("只有收口接受 targetId、outcome 与 reason");
 				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
+						type: args.type,
+						view: args.view,
+						cursor: args.cursor
 					});
 				}
-				if (args.limit !== void 0 || args.type === void 0) throw new Error("追加账本需要 type 且不接受 limit");
+				if (args.limit !== void 0 || args.view !== void 0 || args.cursor !== void 0 || args.type === void 0) throw new Error("追加账本需要 type 且不接受读取字段");
 				if (args.type === "lead" && !args.ref?.trim()) throw new Error("lead 必须提供用户指定主导的 ref");
-				return appendSoulLedger(target.dir, {
+				return committed(appendSoulLedger(target.dir, {
 					type: args.type,
 					...args.text === void 0 ? {} : { text: args.text },
 					...args["概要"] === void 0 ? {} : { "概要": args["概要"] },
@@ -26874,7 +27161,7 @@ function registerSoulLedgerTools(ctx, host) {
 				}, {
 					sessionId: exec.agent?.session.id,
 					signal: exec.signal
-				});
+				}));
 			}
 		}));
 		return () => {
@@ -26887,6 +27174,162 @@ function registerSoulLedgerTools(ctx, host) {
 	};
 }
 //#endregion
+//#region src/host/soul-state.ts
+/** 显式会话短状态；真实会话选路径，正文与账本事件分开持久。 */
+function statePath(moduleDir, sessionId) {
+	if (typeof sessionId !== "string" || !sessionId.trim() || sessionId.length > 256) throw new Error("Soul状态缺少实际会话身份");
+	assertModuleSnapshotSource(dirname(moduleDir), basename(moduleDir));
+	return `data/.soul/state-${revisionOf$4(sessionId)}.json`;
+}
+function readSoulState(moduleDir, sessionId) {
+	const path = statePath(moduleDir, sessionId);
+	const target = join(moduleDir, path);
+	assertNoModuleLinks(target);
+	if (!modulePathExists(target)) return {
+		mark: null,
+		revision: null
+	};
+	const source = readModuleFile(moduleDir, path);
+	if (source.bytes > 4096) throw new Error("Soul状态文件超过上限");
+	let value;
+	try {
+		value = JSON.parse(source.content);
+	} catch {
+		throw new Error("Soul状态文件损坏，不能重置");
+	}
+	if (!record$7(value) || value.version !== 1 || value.sessionId !== sessionId || !record$7(value.mark) || Object.keys(value).some((key) => ![
+		"version",
+		"sessionId",
+		"mark"
+	].includes(key)) || Object.keys(value.mark).some((key) => !["text", "recordedAt"].includes(key)) || typeof value.mark.text !== "string" || !value.mark.text.trim() || value.mark.text.length > 512 || Buffer.byteLength(value.mark.text) > 2048 || typeof value.mark.recordedAt !== "string" || !Number.isFinite(Date.parse(value.mark.recordedAt))) throw new Error("Soul状态文件无效或会话身份不匹配");
+	return {
+		mark: {
+			text: value.mark.text,
+			recordedAt: value.mark.recordedAt
+		},
+		revision: revisionOf$4(source.content)
+	};
+}
+function markSoulState(moduleDir, sessionId, input, signal) {
+	if (typeof input.text !== "string" || !input.text.trim() || input.text.length > 512 || Buffer.byteLength(input.text) > 2048) throw new Error("mark长度须为1–512字符且不超过2048字节");
+	if (input.expectedRevision !== null && (typeof input.expectedRevision !== "string" || !/^[a-f0-9]{64}$/.test(input.expectedRevision))) throw new Error("mark需要当前expectedRevision，首次为null");
+	const text = input.text, expected = input.expectedRevision;
+	assertModuleDirectory(dirname(moduleDir), basename(moduleDir));
+	const path = statePath(moduleDir, sessionId);
+	signal?.throwIfAborted();
+	return withModuleLock(dirname(moduleDir), basename(moduleDir), () => {
+		signal?.throwIfAborted();
+		assertModuleDirectory(dirname(moduleDir), basename(moduleDir));
+		const before = readSoulState(moduleDir, sessionId);
+		if (before.revision !== expected) throw new Error("mark版本冲突，请重读当前状态");
+		if (before.mark?.text === text) return before;
+		const data = ensureDataDirectory(moduleDir), stateDir = join(data, ".soul");
+		assertNoModuleLinks(stateDir);
+		mkdirSync(stateDir, { recursive: true });
+		const target = resolveModuleFilePath(moduleDir, path, ["data"]);
+		const temporary = join(stateDir, ".mark-" + randomUUID() + ".tmp");
+		const content = JSON.stringify({
+			version: 1,
+			sessionId,
+			mark: {
+				text,
+				recordedAt: (/* @__PURE__ */ new Date()).toISOString()
+			}
+		}) + "\n";
+		try {
+			writeFileSync(temporary, content, {
+				flag: "wx",
+				encoding: "utf8"
+			});
+			signal?.throwIfAborted();
+			if (readSoulState(moduleDir, sessionId).revision !== expected) throw new Error("mark版本冲突，请重读当前状态");
+			renameSync(temporary, target);
+		} finally {
+			rmSync(temporary, { force: true });
+		}
+		return readSoulState(moduleDir, sessionId);
+	});
+}
+//#endregion
+//#region src/runtime/soul-state-tools.ts
+function registerSoulStateTools(ctx, host, observe) {
+	const fiber = ctx.inject(["tools"], (toolsCtx) => toolsCtx.tools.register(defineTool({
+		name: MODULE_TOOL_NAMES.soulState,
+		description: "读取真实当前会话Soul状态或只读运行诊断；check显式includeUpgrade=true才展开完整升级文件候选。mark记录短状态及时间，需要status版本，首次null；标记时间不代表实际活动，不关闭账本事项。",
+		parameters: {
+			moduleId: MODULE_ID_PARAM,
+			action: {
+				type: "string",
+				enum: [
+					"status",
+					"mark",
+					"check"
+				],
+				required: true
+			},
+			text: { type: "string" },
+			expectedRevision: { oneOf: [{ type: "string" }, { type: "null" }] },
+			includeUpgrade: { type: "boolean" }
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					sessionId: { type: "string" },
+					revision: { oneOf: [{ type: "string" }, { type: "null" }] },
+					mark: { oneOf: [{ type: "null" }, {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							text: { type: "string" },
+							recordedAt: { type: "string" }
+						}
+					}] },
+					observation: { type: "json" }
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: JSON.stringify(value)
+			}]
+		},
+		execute: async (args, exec) => {
+			if (Object.keys(args).some((key) => ![
+				"moduleId",
+				"action",
+				"text",
+				"expectedRevision",
+				"includeUpgrade"
+			].includes(key))) throw new Error("Soul状态请求含未知字段，不能指定其他会话");
+			if (args.includeUpgrade !== void 0 && (typeof args.includeUpgrade !== "boolean" || args.action !== "check")) throw new Error("只有check接受布尔includeUpgrade");
+			exec.signal.throwIfAborted();
+			const target = host.target(exec, args.moduleId), sessionId = exec.agent?.session.id;
+			if (!sessionId) throw new Error("Soul状态缺少实际会话身份");
+			if (args.action === "mark") return {
+				sessionId,
+				...markSoulState(target.dir, sessionId, {
+					text: args.text,
+					expectedRevision: args.expectedRevision
+				}, exec.signal)
+			};
+			if (args.action !== "status" && args.action !== "check") throw new Error("Soul状态action无效");
+			if (args.text !== void 0 || args.expectedRevision !== void 0) throw new Error("Soul状态读取不接受写入字段");
+			const observation = observe ? await observe[args.action](exec, target.id, args.includeUpgrade) : void 0;
+			exec.signal.throwIfAborted();
+			if (host.target(exec, args.moduleId).dir !== target.dir || exec.agent?.session.id !== sessionId) throw new Error("Soul状态来源或会话已变化");
+			return {
+				sessionId,
+				...readSoulState(target.dir, sessionId),
+				...observation === void 0 ? {} : { observation }
+			};
+		}
+	})));
+	return () => {
+		fiber.dispose();
+	};
+}
+//#endregion
 //#region src/host/soul-self.ts
 /** SELF 派生快照：骨架与事实共享，运行身份只在模型出口加入。 */
 const SOUL_SELF_SOURCE = "data/SELF.src.md";
@@ -26911,45 +27354,78 @@ function readSoulSelfSnapshot(moduleDir) {
 		revision: revisionOf$4(content)
 	};
 }
-function refreshSoulSelf(moduleDir, index, options) {
-	const budget = validateSelfBudget(options.budgetBytes);
-	options.signal?.throwIfAborted();
+function selfInputs(moduleDir) {
 	const source = readModuleFile(moduleDir, SOUL_SELF_SOURCE).content;
+	const ledger = readSoulLedgerProjection(moduleDir);
+	return {
+		source,
+		ledger,
+		version: revisionOf$4(source) + ":" + ledger.revision + ":" + ledger.pendingVersion + ":" + ledger.initialized
+	};
+}
+function deriveSoulSelf(moduleDir, index = { state: "unbuilt（未建）" }, budgetBytes = 12288) {
+	for (let attempt = 0; attempt < 3; attempt++) {
+		const input = selfInputs(moduleDir);
+		const candidate = renderSelfFacts(input, index, budgetBytes);
+		if (selfInputs(moduleDir).version === input.version) return candidate;
+	}
+	throw new Error("SELF 来源持续变化，无法形成一致候选");
+}
+function renderSelfFacts({ source, ledger }, index, budgetBytes) {
+	const budget = validateSelfBudget(budgetBytes);
 	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(),
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const lines = [
+		seal(source),
 		"",
-		"## 活体（自动装配）",
-		`- 装配时刻：${(/* @__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 超预算，需精简骨架或账本内容；旧快照保留");
+		"## 活体（当前权威事实）",
+		`- 当前时钟：${now}；时区：${Intl.DateTimeFormat().resolvedOptions().timeZone}`,
+		`- 账本：共 ${ledger.total} 条；未结 ${ledger.open} 条；历史待核对 ${ledger.pendingReview} 条${ledger.initialized ? "" : "；历史分界待初始化"}`,
+		`- 主导：${ledger.lead ? seal(ledger.lead["概要"]).slice(0, 160) : "尚无 lead 记录"}`,
+		`- 索引：${index.state}${index.files === void 0 ? "" : `；文件 ${count("files")}；会话 ${count("sessions")}；事件 ${count("events")}`}`,
+		`- 索引最近成功观测：${index.observedAt ?? "尚未观测"}；未扫描外部变化时不保证当前一致。`
+	];
+	const remaining = (shown) => `- 未展示事项：${ledger.items.length - shown}；用 soul_ledger list 的需处理视图分页读取。`;
+	const reserve = 224;
+	if (Buffer.byteLength([...lines, remaining(0)].join("\n")) > budget - reserve) throw new Error("SELF 超预算，需精简骨架；旧快照保留");
+	let shown = 0;
+	for (const item of ledger.items.slice(0, 3)) {
+		const summary = seal(item.entry["概要"]);
+		const line = `- [${item.status}] ${item.id}：${summary.slice(0, 240)}${summary.length > 240 ? "…（摘要）" : ""}`;
+		if (Buffer.byteLength([
+			...lines,
+			line,
+			remaining(shown + 1)
+		].join("\n")) > budget - reserve) break;
+		lines.push(line);
+		shown += 1;
+	}
+	lines.push(remaining(shown));
+	return {
+		content: lines.join("\n") + "\n",
+		sourceRevision: revisionOf$4(source),
+		ledgerRevision: ledger.revision,
+		pendingVersion: ledger.pendingVersion,
+		observedAt: now
+	};
+}
+function refreshSoulSelf(moduleDir, index, options) {
+	options.signal?.throwIfAborted();
+	const candidate = deriveSoulSelf(moduleDir, index, options.budgetBytes);
+	const content = candidate.content.replace("## 活体（当前权威事实）", `## 诊断快照（非实时）\n- 快照时刻：${candidate.observedAt}`);
 	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 assertCurrent = () => {
+			const current = selfInputs(moduleDir);
+			if (revisionOf$4(current.source) !== candidate.sourceRevision || current.ledger.revision !== candidate.ledgerRevision || current.ledger.pendingVersion !== candidate.pendingVersion) throw new Error("SELF 来源版本冲突");
+		};
+		assertCurrent();
 		const data = ensureDataDirectory(moduleDir), stateDir = join(data, ".soul");
 		assertNoModuleLinks(stateDir);
 		mkdirSync(stateDir, { recursive: true });
@@ -26962,6 +27438,7 @@ function refreshSoulSelf(moduleDir, index, options) {
 			});
 			options.signal?.throwIfAborted();
 			if (readSoulSelfSnapshot(moduleDir).revision !== options.expectedRevision) throw new Error("SELF 快照版本冲突");
+			assertCurrent();
 			renameSync(temp, target);
 		} finally {
 			rmSync(temp, { force: true });
@@ -26973,13 +27450,494 @@ function refreshSoulSelf(moduleDir, index, options) {
 		};
 	});
 }
-function renderSoulSelf(moduleDir, agent, signal, budgetBytes = 12288) {
+function renderSoulSelf(moduleDir, agent, signal, budgetBytes = 12288, index, runtimeLines = []) {
 	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`;
+	for (const path of [
+		SOUL_SELF_SOURCE,
+		"data/02-soul.jsonl",
+		"data/02-墨.jsonl"
+	]) assertNoModuleLinks(join(moduleDir, path));
+	let prefix;
+	try {
+		prefix = deriveSoulSelf(moduleDir, index, budgetBytes).content;
+	} catch (error) {
+		const code = error.code;
+		if (code === "EACCES" || code === "EPERM" || /链接|越界|超预算|不是普通文件/.test(String(error.message))) throw error;
+		const reason = /持续变化/.test(String(error.message)) ? "来源持续变化，无法形成一致候选" : "账本或骨架数据不可读取";
+		const snapshot = readSoulSelfSnapshot(moduleDir);
+		const stamp = /^- (?:快照时刻|装配时刻)：([^\n]+)/m.exec(snapshot.content)?.[1];
+		const sourceTime = stamp && Number.isFinite(Date.parse(stamp)) ? stamp : "unknown";
+		prefix = snapshot.revision === null ? `[SELF unavailable：${reason}；无安全诊断快照；未结数量未知]` : `[SELF degraded：来源时间：${sourceTime}；原因：${reason}；以下仅为历史诊断，当前未结未知]\n${seal(snapshot.content).replaceAll("当前权威事实", "历史诊断事实").replaceAll("当前时钟", "快照时钟")}`;
+	}
+	let text = seal(`${prefix}\n## 当前运行身份\n- 当前时钟：${(/* @__PURE__ */ new Date()).toISOString()}\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);
+	for (const line of runtimeLines) {
+		const available = budgetBytes - Buffer.byteLength(text) - 1;
+		const sealed = seal(line);
+		if (Buffer.byteLength(sealed) <= available) {
+			text += sealed + "\n";
+			continue;
+		}
+		const suffix = "…（状态摘要）";
+		let summary = "";
+		for (const char of sealed) {
+			if (Buffer.byteLength(summary + char + suffix) > available) break;
+			summary += char;
+		}
+		if (summary) text += summary + "…（状态摘要）\n";
+		break;
+	}
+	return text;
+}
+//#endregion
+//#region src/host/soul-diagnostics.ts
+/** 只读就绪证据；文件齐全、候选渲染与实际投递分别报告。 */
+function readSoulDiagnostics(moduleDir, observations = {}) {
+	const observedAt = (/* @__PURE__ */ new Date()).toISOString(), checks = [];
+	const read = (name, action) => {
+		try {
+			checks.push({
+				name,
+				observedAt,
+				...action()
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : "";
+			const reason = /链接|越界|非法资源路径/.test(message) ? "来源路径不安全" : /JSON|UTF-8|格式|无效/.test(message) ? "来源格式无效" : /超过|超限/.test(message) ? "来源超过预算" : "来源不可读取";
+			checks.push({
+				name,
+				state: "failed",
+				observedAt,
+				reason,
+				nextAction: "核对模块声明与来源文件后重新检查"
+			});
+		}
+	};
+	read("manifest", () => {
+		const checked = runModuleManifest(moduleDir, "check"), next = runModuleManifest(moduleDir, "next");
+		if (checked.ok && next.ok) return { state: "ready" };
+		const failed = checked.entries.find((entry) => !entry.ok);
+		return {
+			state: "incomplete",
+			reason: failed?.error ? `文件检查：${failed.error}` : "装配文件尚未齐备",
+			nextAction: "通过正式初始化入口预览缺失项"
+		};
+	});
+	read("skeleton", () => readModuleFile(moduleDir, "data/SELF.src.md").content.trim() ? { state: "ready" } : {
+		state: "missing",
+		nextAction: "初始化或补全SELF骨架"
+	});
+	read("ledger", () => {
+		const ledger = readSoulLedgerProjection(moduleDir);
+		if (!ledger.initialized) return {
+			state: "pending-initialization",
+			reason: "历史分界尚未初始化",
+			nextAction: "显式初始化或通过正式账本写入口建立历史分界"
+		};
+		return ledger.pendingReview ? {
+			state: "pending-review",
+			reason: `有${ledger.pendingReview}项历史记录待核对`,
+			nextAction: "使用soul_ledger逐项核对收口"
+		} : { state: "ready" };
+	});
+	for (const [name, time] of [["self-rendered", observations.selfRenderedAt], ["self-delivered", observations.selfDeliveredAt]]) checks.push(time ? {
+		name,
+		state: "observed",
+		observedAt: time
+	} : {
+		name,
+		state: "not-observed",
+		nextAction: name === "self-delivered" ? "等待实际模型投递确认" : "等待下一次真实装配"
+	});
+	for (const name of [
+		"index",
+		"maintenance",
+		"context",
+		"recovery"
+	]) {
+		const observation = observations[name];
+		if (!observation) checks.push({
+			name,
+			state: "not-observed",
+			nextAction: "核对能力启用并等待运行观测"
+		});
+		else if (name !== "index" && observation.state === "ready" && observation.last == null && !observation.observedAt) checks.push({
+			name,
+			state: "not-observed",
+			reason: "仅已装配，尚无执行证据"
+		});
+		else checks.push({
+			name,
+			state: observation.state,
+			...observation.observedAt ? { observedAt: observation.observedAt } : {},
+			...["ready", "success"].includes(observation.state) ? {} : { nextAction: name === "index" ? "显式刷新授权索引或检查刷新失败" : "核对能力状态与最近执行证据" }
+		});
+	}
+	return {
+		state: checks.every((check) => [
+			"ready",
+			"observed",
+			"success"
+		].includes(check.state)) ? "ready" : "attention",
+		observedAt,
+		checks
+	};
+}
+//#endregion
+//#region src/host/soul-upgrade.ts
+/** 定向升级只生成候选，持久化仍由正式导入预览与重建事务拥有。 */
+const RULE_IDS = ["soul-ledger-open", "soul-check"];
+const VARIABLE_IDS = ["ledger_open", "ledger_seq"];
+const BASELINE = `rules:
+  - id: soul-check
+    name: 检查失败处置
+    enabled: true
+    layer: system-section
+    if: { manifest: { ok: false } }
+    then:
+      - id: inject
+        kind: inject-text
+        config:
+          id: soul-check
+          layer: system-section
+          strategy: static
+          order: 247
+          text: |-
+            清单检查当前有未通过项（由引擎按装配事实求值，不需要手写变量）：
+            先 module_manifest（moduleId: soul）action=check 看全部明细，
+            再说清是哪一条、证据是什么、下一步改哪个文件或哪条规则；
+            修完要重新 check，不要用「已修复」代替重新检查，也不要把失败项藏进总结。
+  - id: soul-ledger-open
+    name: 未结账本提醒
+    enabled: true
+    layer: pre-step
+    if: { variable: { key: ledger_open, op: gt, value: '0' } }
+    then:
+      - id: inject
+        kind: inject-text
+        config:
+          id: soul-ledger-open
+          layer: pre-step
+          strategy: static
+          position: before-all
+          order: 126
+          role: user
+          text: |-
+            账本还有未结事项：回复里逐条收口，或说清为什么先放着。
+            先用 soul_ledger（moduleId: soul，action: list）核对原始未结记录；
+            需要追加时用 soul_ledger（moduleId: soul，action: append，type: fact/shelved/gain/loss/persona/container 之一，概要: 一句话，ref: 出处），
+            作者和时间由宿主提供，promise 只允许最后 lead 署名的主导会话；lead 需用户指定并经审批。
+            只往后加，不改旧行；收口后把 ledger_open 减到 0。
+`;
+async function readSoulUpgradePreview(moduleDir) {
+	const directory = assertModuleDirectory(userModulesDir(), basename(moduleDir));
+	if (directory !== moduleDir && directory.replaceAll("\\", "/") !== moduleDir.replaceAll("\\", "/")) throw new Error("Soul升级目标不在当前用户模块根");
+	const file = join(directory, "module.yml");
+	assertNoModuleLinks(file);
+	if (!statSync(file).isFile() || statSync(file).size > 1048576) throw new Error("Soul升级模块定义无效或超限");
+	const source = readFileSync(file, "utf8");
+	const value = parseDocument(source);
+	if (value.errors.length) throw new Error("Soul升级YAML无效");
+	const rules = value.get("rules");
+	if (!isSeq(rules) || !RULE_IDS.every((id) => rules.items.some((rule) => isMap(rule) && rule.get("id") === id))) return { status: "not-applicable" };
+	const seed = readFileSync(join(packageModulesDir(), "soul/module.yml"), "utf8");
+	const preview = previewSoulUpgrade(source, BASELINE, seed);
+	const result = {
+		...preview,
+		expectedRevision: revisionOf$4(source),
+		files: [],
+		apply: "仅预览；将完整files交给module_import模型工具正式预览，保留targetId并设overwrite:true；核对expectedRevision后携工具返回的两份凭据提交。该工具保留私有data、memory及既有技能资产并重建；不要用普通覆盖导入替代，不自动更新运行副本。"
+	};
+	if (!preview.candidate) return result;
+	const exported = await exportModulePackage(userModulesDir(), {
+		id: basename(moduleDir),
+		mode: "zip"
+	});
+	const files = await expandModuleSource([{
+		path: "soul.zip",
+		content: exported.content,
+		encoding: "base64"
+	}]);
+	if ((await exportModulePackage(userModulesDir(), {
+		id: basename(moduleDir),
+		mode: "zip",
+		preview: true
+	})).revision !== exported.revision) throw new Error("Soul升级资产已变化，请重新预览");
+	if (revisionOf$4(readFileSync(file, "utf8")) !== result.expectedRevision) throw new Error("Soul升级定义已变化，请重新预览");
+	const path = "assets/retrieval-synonyms.json";
+	const content = readFileSync(join(packageModulesDir(), "soul", path), "utf8");
+	const previous = files.find((file) => file.path === path);
+	if (previous && decodeAssetFile(previous).toString("utf8") !== content) return {
+		...result,
+		status: "conflict",
+		conflicts: [...result.conflicts, `${path}: 用户已修改近义表`],
+		candidate: null
+	};
+	result.files = files.map((file) => file.path === "module.yml" ? {
+		path: file.path,
+		content: preview.candidate
+	} : file);
+	if (!previous) {
+		result.files.push({
+			path,
+			content
+		});
+		result.changes.push({
+			id: path,
+			before: null,
+			after: "新增近义表资产"
+		});
+	}
+	return result;
+}
+function knownShape(value, shape) {
+	if (Array.isArray(shape)) return Array.isArray(value) ? value.map((item, i) => knownShape(item, shape[i])) : value;
+	if (shape && typeof shape === "object" && value && typeof value === "object") return Object.fromEntries(Object.keys(shape).map((key) => [key, knownShape(value[key], shape[key])]));
+	return value;
+}
+function mergeValue(current, old, fresh) {
+	if (Array.isArray(fresh)) return fresh.map((item, index) => mergeValue(Array.isArray(current) ? current[index] : void 0, Array.isArray(old) ? old[index] : void 0, item));
+	if (fresh && typeof fresh === "object") {
+		const result = current && typeof current === "object" && !Array.isArray(current) ? structuredClone(current) : {};
+		for (const key of Object.keys(old && typeof old === "object" ? old : {})) if (!(key in fresh) && !["enabled", "order"].includes(key)) delete result[key];
+		for (const [key, value] of Object.entries(fresh)) {
+			if (["enabled", "order"].includes(key) && key in result) continue;
+			result[key] = mergeValue(result[key], old && typeof old === "object" ? old[key] : void 0, value);
+		}
+		return result;
+	}
+	return fresh;
+}
+function patchNode(document, current, wanted) {
+	if (isAlias(current)) throw new Error("Soul升级目标含共享引用，请先解除相关引用");
+	if (isMap(current) && wanted && typeof wanted === "object" && !Array.isArray(wanted)) {
+		for (const key of current.items.map((pair) => String(pair.key))) if (!(key in wanted)) current.delete(key);
+		for (const [key, value] of Object.entries(wanted)) current.set(key, patchNode(document, current.get(key, true), value));
+		return current;
+	}
+	if (isSeq(current) && Array.isArray(wanted)) {
+		current.items = wanted.map((value, index) => patchNode(document, current.items[index], value));
+		return current;
+	}
+	if (isScalar(current) && (wanted === null || typeof wanted !== "object")) {
+		current.value = wanted;
+		return current;
+	}
+	const next = document.createNode(wanted);
+	if (current && typeof current === "object") {
+		for (const key of [
+			"comment",
+			"commentBefore",
+			"spaceBefore"
+		]) if (key in current) next[key] = current[key];
+	}
+	return next;
+}
+function behavior(rule) {
+	const value = structuredClone(rule);
+	delete value.enabled;
+	delete value.order;
+	if (Array.isArray(value.then)) {
+		for (const action of value.then) if (action && typeof action === "object" && action.config && typeof action.config === "object") delete action.config.order;
+	}
+	return JSON.stringify(value);
+}
+function previewSoulUpgrade(source, baseline, newSeed) {
+	const [document, base, seed] = [
+		source,
+		baseline,
+		newSeed
+	].map((text) => {
+		if (Buffer.byteLength(text) > 1048576) throw new Error("Soul升级YAML超过1 MiB");
+		const doc = parseDocument(text);
+		if (doc.errors.length || !isMap(doc.contents)) throw new Error("Soul升级YAML无效");
+		return doc;
+	});
+	const expected = JSON.parse(JSON.stringify(document.toJS()));
+	const conflicts = [];
+	const changes = [];
+	const sourceRules = document.get("rules"), baseRules = base.get("rules"), seedRules = seed.get("rules");
+	if (!isSeq(sourceRules) || !isSeq(baseRules) || !isSeq(seedRules)) throw new Error("Soul升级YAML缺少rules数组");
+	for (const id of RULE_IDS) {
+		const current = sourceRules.items.filter((rule) => isMap(rule) && rule.get("id") === id);
+		const old = baseRules.items.find((rule) => isMap(rule) && rule.get("id") === id);
+		const fresh = seedRules.items.find((rule) => isMap(rule) && rule.get("id") === id);
+		if (current.length !== 1 || !isMap(current[0]) || !isMap(old) || !isMap(fresh)) {
+			conflicts.push(`${id}: 目标规则缺失或重复`);
+			continue;
+		}
+		const node = current[0], before = node.toJSON();
+		const oldValue = old.toJSON(), freshValue = fresh.toJSON();
+		if (behavior(knownShape(before, freshValue)) === behavior(freshValue)) continue;
+		if (behavior(knownShape(before, oldValue)) !== behavior(oldValue)) {
+			conflicts.push(`${id}: 用户已修改规则行为`);
+			continue;
+		}
+		const after = mergeValue(before, oldValue, freshValue);
+		expected.rules[sourceRules.items.indexOf(node)] = after;
+		patchNode(document, node, after);
+		changes.push({
+			id,
+			before,
+			after
+		});
+	}
+	const external = document.toJS();
+	external.rules = external.rules.filter((rule) => !RULE_IDS.includes(String(rule.id)));
+	for (const id of VARIABLE_IDS) if (external.variables) delete external.variables[id];
+	const consumers = JSON.stringify(external);
+	for (const id of VARIABLE_IDS) {
+		if (consumers.includes(id)) {
+			conflicts.push(`${id}: 目标规则以外仍有引用`);
+			continue;
+		}
+		const variables = document.get("variables");
+		if (isMap(variables) && variables.has(id)) {
+			changes.push({
+				id,
+				before: expected.variables?.[id],
+				after: null
+			});
+			variables.delete(id);
+			delete expected.variables[id];
+		}
+	}
+	for (const [capability, keys] of [
+		["retrieval", ["synonymsFile"]],
+		["soul-maintenance", ["pressureThresholds"]],
+		["generation-recovery", [
+			"lineRepeatChars",
+			"crossCallRepeatChars",
+			"maxCycleChars"
+		]]
+	]) for (const key of keys) {
+		const path = [
+			"moduleConfigs",
+			capability,
+			key
+		];
+		const fresh = seed.getIn(path);
+		if (fresh === void 0) continue;
+		const freshValue = isSeq(fresh) || isMap(fresh) || isScalar(fresh) ? fresh.toJSON() : fresh;
+		const current = document.getIn(path);
+		const currentValue = isSeq(current) || isMap(current) || isScalar(current) ? current.toJSON() : current;
+		if (currentValue !== void 0) {
+			if (!isDeepStrictEqual(currentValue, freshValue)) conflicts.push(`${capability}.${key}: 用户已配置不同值`);
+			continue;
+		}
+		expected.moduleConfigs ??= {};
+		expected.moduleConfigs[capability] ??= {};
+		expected.moduleConfigs[capability][key] = structuredClone(freshValue);
+		document.setIn(path, document.createNode(freshValue));
+		changes.push({
+			id: `${capability}.${key}`,
+			before: null,
+			after: freshValue
+		});
+	}
+	return {
+		status: conflicts.length ? "conflict" : "ready",
+		conflicts,
+		changes,
+		candidate: conflicts.length ? null : serializeWithoutSharedAlias(document, expected, "Soul升级共享引用会连带改变用户定义，请先解除相关引用")
+	};
+}
+//#endregion
+//#region src/runtime/soul-pressure.ts
+function readSoulPressure(ctx, agent, thresholds) {
+	if (thresholds.length !== 3 || thresholds.some((value, i) => !Number.isFinite(value) || value <= 0 || value >= 1 || i > 0 && value <= thresholds[i - 1])) throw new Error("SOUL水位阈值必须为三个递增的0–1比例");
+	const observedAt = (/* @__PURE__ */ new Date()).toISOString();
+	try {
+		const header = agent.session.requestHeader(), route = agent.session.requestContext();
+		if (!header || !route || header.config.provider !== route.provider || header.config.model !== route.model) return {
+			state: "unknown",
+			observedAt,
+			reason: "当前请求缺少匹配的模型窗口事实"
+		};
+		const capacity = route.contextWindow;
+		if (!Number.isSafeInteger(capacity) || capacity <= 0) return {
+			state: "unknown",
+			observedAt,
+			reason: "当前模型窗口未知"
+		};
+		const meter = ctx.get("tokenMeter");
+		if (!meter || typeof meter.measure !== "function") return {
+			state: "unknown",
+			observedAt,
+			reason: "tokenMeter不可用"
+		};
+		const tokens = meter.measure(agent.session).totalTokens;
+		if (!Number.isSafeInteger(tokens) || tokens < 0) return {
+			state: "unknown",
+			observedAt,
+			reason: "压力测量无效"
+		};
+		const ratio = tokens / capacity;
+		const level = ratio >= thresholds[2] ? "urgent" : ratio >= thresholds[1] ? "persist" : ratio >= thresholds[0] ? "organize" : "normal";
+		return {
+			state: "known",
+			observedAt,
+			tokens,
+			capacity,
+			ratio,
+			level,
+			source: "tokenMeter.measure + session.requestContext",
+			guidance: level === "urgent" ? "优先落盘未结与关键依据，再整理上下文" : level === "persist" ? "先落盘关键事实与承诺" : level === "organize" ? "可开始整理上下文与未结事项" : "当前低于提示阈值"
+		};
+	} catch {
+		return {
+			state: "unknown",
+			observedAt,
+			reason: "当前会话压力不可测量"
+		};
+	}
+}
+//#endregion
+//#region src/runtime/soul-reminder.ts
+/** 未结提醒的确认态来自真实会话事件；候选求值不产生状态。 */
+function createSoulReminder(readProjection) {
+	return { read(moduleId, value) {
+		const agent = value, session = agent?.session;
+		if (!session?.id || typeof session.snapshotEvents !== "function") return void 0;
+		try {
+			const projection = readProjection(moduleId, agent), count = projection.open + projection.pendingReview;
+			if (!Number.isSafeInteger(count) || count < 0 || !projection.pendingVersion) return void 0;
+			let epoch = -1;
+			let confirmed;
+			const events = session.snapshotEvents();
+			for (let index = 0; index < events.length; index++) {
+				const event = events[index];
+				if (isSuccessfulCompactionEnd(event)) epoch = event.seq ?? index;
+				const source = eventMessage(event)?.source;
+				let mark = source?.moduleId === moduleId && source?.sessionId === session.id && String(source.kind).startsWith("plugin:") ? source.soulReminder : void 0;
+				if (source?.kind === "runtime-context" && source.form === "snapshot" && Array.isArray(source.sections)) for (const section of source.sections) {
+					if (typeof section?.text !== "string") continue;
+					for (const match of section.text.matchAll(/<!-- soul-reminder:([A-Za-z0-9+/=]+) -->/g)) {
+						let candidate;
+						try {
+							candidate = JSON.parse(Buffer.from(match[1], "base64").toString("utf8"));
+						} catch {
+							continue;
+						}
+						if (candidate.moduleId === moduleId && candidate.sessionId === session.id) mark = candidate;
+					}
+				}
+				if (typeof mark === "object" && mark !== null && "pendingVersion" in mark && "epoch" in mark && typeof mark.pendingVersion === "string" && typeof mark.epoch === "number" && Number.isSafeInteger(mark.epoch)) confirmed = {
+					pendingVersion: mark.pendingVersion,
+					epoch: mark.epoch
+				};
+			}
+			return {
+				count,
+				pendingVersion: projection.pendingVersion,
+				epoch,
+				due: count > 0 && (session.header?.delegationDepth ?? 0) === 0 && (confirmed?.pendingVersion !== projection.pendingVersion || confirmed.epoch !== epoch)
+			};
+		} catch {
+			return;
+		}
+	} };
 }
 //#endregion
 //#region engine/retrieval-reference.mjs
@@ -27014,10 +27972,122 @@ function makeSessionReference(moduleId, sessionId, events, seqs, range = {}) {
 	};
 }
 //#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/generation-recovery.mjs
+const observations = /* @__PURE__ */ new WeakMap();
+const recoveryObservationOf = (agent) => observations.get(agent);
+const recoveryLimit = passthrough((value, plugin, field) => {
+	if (value === void 0) return 0;
+	if (!Number.isSafeInteger(value) || value < 0 || value > 1e3) throw new TypeError(`${plugin}: ${field} must be an integer from 0 to 1000`);
+	return value;
+});
+defineConfig({
+	enabled: bool({ default: false }),
+	audience: enumOf([
+		"all",
+		"main",
+		"subagent"
+	], { default: "all" }),
+	textRepeatChars: int$2({
+		min: 3,
+		default: 4096
+	}),
+	reasoningRepeatChars: int$2({
+		min: 3,
+		default: 8192
+	}),
+	silentReasoningChars: int$2({
+		min: 0,
+		default: 0
+	}),
+	lineRepeatChars: int$2({
+		min: 0,
+		default: 0
+	}),
+	crossCallRepeatChars: int$2({
+		min: 0,
+		default: 0
+	}),
+	recoverEmpty: bool({ default: false }),
+	mainRecoveryLimit: recoveryLimit,
+	subagentRecoveryLimit: recoveryLimit,
+	maintenanceCompression: bool({ default: false }),
+	allowFullFallback: bool({ default: false }),
+	maxCycleChars: passthrough((value, plugin, field) => {
+		if (value === void 0) return 256;
+		if (!Number.isSafeInteger(value) || value < 1 || value > 1024) throw new TypeError(`${plugin}: ${field} must be an integer from 1 to 1024`);
+		return value;
+	})
+});
+//#endregion
 //#region src/host/module-retrieval.ts
 /** 检索只读权威来源；引用携定位和版本，不携访问权限。 */
 const digest$1 = (value) => createHash("sha256").update(value).digest("hex");
 const MAX_CHUNK = MAX_REFERENCE_CHARS;
+const normalize = (text) => text.normalize("NFKC").toLowerCase().replace(/(?<![0-9,])[0-9]{1,3}(?:,[0-9]{3})+(?![0-9,])/g, (value) => value.replaceAll(",", ""));
+function includesQuery(text, query) {
+	let start = text.indexOf(query);
+	while (start >= 0) {
+		if (!/^[0-9]+$/.test(query) || !/[0-9]/.test(text[start - 1] ?? "") && !/[0-9]/.test(text[start + query.length] ?? "")) return true;
+		start = text.indexOf(query, start + 1);
+	}
+	return false;
+}
+function matchKind(text, query) {
+	if (includesQuery(text.toLowerCase(), query.toLowerCase())) return "exact";
+	if (includesQuery(normalize(text), normalize(query))) return "normalized";
+}
+function synonymTerms(scope, query) {
+	if (!scope.synonymsFile) return { terms: [] };
+	resolveModuleFilePath(scope.dir, scope.synonymsFile, ["assets", "data"]);
+	const content = readModuleFile(scope.dir, scope.synonymsFile).content;
+	if (Buffer.byteLength(content) > 65536) throw new Error("检索近义表超过64 KiB");
+	let groups;
+	try {
+		groups = JSON.parse(content);
+	} catch {
+		throw new Error("检索近义表必须为JSON词组数组");
+	}
+	if (!Array.isArray(groups) || groups.length > 128 || groups.some((group) => !Array.isArray(group) || group.length < 2 || group.length > 16 || group.some((term) => typeof term !== "string" || !term.trim() || term.length > 128))) throw new Error("检索近义表词组无效或超限");
+	const needle = normalize(query), terms = /* @__PURE__ */ new Set();
+	for (const group of groups) if (group.some((term) => normalize(term) === needle)) {
+		for (const term of group) if (normalize(term) !== needle) terms.add(term);
+	}
+	if (terms.size > 32) throw new Error("检索近义扩展超过32项");
+	return {
+		terms: [...terms],
+		content
+	};
+}
+function timeOf(value) {
+	const time = typeof value === "number" ? value : typeof value === "string" && /^\d{4}-\d\d-\d\dT.*(?:Z|[+-]\d\d:\d\d)$/.test(value) ? Date.parse(value) : NaN;
+	return Number.isSafeInteger(time) && time >= 0 && time <= 864e13 ? time : void 0;
+}
 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 });
@@ -27051,7 +28121,7 @@ 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("检索会话未授权");
+		if (current.moduleId !== scope.moduleId || current.dir !== scope.dir || current.session?.id !== id && !current.sessions?.includes(id)) throw new Error("检索会话未授权");
 	};
 	async function authorizedSession(scope, id) {
 		assertSessionAuthorized(scope, id);
@@ -27068,7 +28138,7 @@ function createModuleRetrieval(scopeOf, loadSession) {
 		return session;
 	}
 	async function indexSession(scope, id) {
-		const events = [...(await authorizedSession(scope, id)).snapshotEvents()];
+		const session = await authorizedSession(scope, id), events = [...session.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);
@@ -27088,7 +28158,8 @@ function createModuleRetrieval(scopeOf, loadSession) {
 		});
 		return {
 			events,
-			rows
+			rows,
+			session
 		};
 	}
 	const sessionIds = (scope) => /* @__PURE__ */ new Set([...scope.session ? [scope.session.id] : [], ...scope.sessions ?? []]);
@@ -27097,22 +28168,170 @@ function createModuleRetrieval(scopeOf, loadSession) {
 		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 };
+		const selected = [];
+		let bytes = 0;
+		for (const hit of hits) {
+			bytes += Buffer.byteLength(JSON.stringify(hit));
+			if (bytes > 65536) break;
+			selected.push(hit);
+		}
+		return { hits: selected };
+	};
+	const timeline = async (input, limit) => {
+		const scope = scopeOf(), hits = [], versions = [], revalidate = [];
+		const since = input.since === void 0 ? void 0 : timeOf(input.since), until = input.until === void 0 ? void 0 : timeOf(input.until);
+		if (input.since !== void 0 && since === void 0 || input.until !== void 0 && until === void 0 || since !== void 0 && until !== void 0 && since > until) throw new Error("时间线需要明确有效的since/until时间");
+		let bytes = 0;
+		const add = (reference, content, value) => {
+			bytes += Buffer.byteLength(content);
+			if (bytes > 67108864) throw new Error("时间线来源超过64 MiB");
+			const time = timeOf(value);
+			if ((since !== void 0 || until !== void 0) && (time === void 0 || since !== void 0 && time < since || until !== void 0 && time > until)) return;
+			if (input.query !== void 0 && !matchKind(content, input.query)) return;
+			hits.push({
+				reference,
+				content,
+				time: time === void 0 ? null : new Date(time).toISOString(),
+				timeState: time === void 0 ? "unknown" : "known"
+			});
+		};
+		for (const path of filePaths(scope)) {
+			if (!["02-soul.jsonl", "02-墨.jsonl"].includes(path.split("/").at(-1))) continue;
+			const content = fileContent(scope, path), revision = digest$1(content);
+			versions.push([
+				"file",
+				path,
+				revision
+			]);
+			revalidate.push(() => {
+				if (digest$1(fileContent(scopeOf(), path)) !== revision) throw new Error("时间线来源已变化，请重新查询");
+			});
+			let offset = 0;
+			for (const line of content.split("\n")) {
+				if (line.trim()) {
+					let row;
+					try {
+						row = JSON.parse(line);
+					} catch {
+						throw new Error("时间线账本含无效记录");
+					}
+					if (!row || typeof row !== "object" || Array.isArray(row)) throw new Error("时间线账本含无效记录");
+					for (let part = 0; part < line.length; part += MAX_CHUNK) add({
+						kind: "file",
+						moduleId: scope.moduleId,
+						path,
+						revision,
+						start: offset + part,
+						end: offset + Math.min(line.length, part + MAX_CHUNK)
+					}, line.slice(part, part + MAX_CHUNK), row.t);
+				}
+				offset += line.length + 1;
+			}
+		}
+		for (const id of sessionIds(scope)) {
+			const { events, rows, session } = await indexSession(scope, id);
+			const revision = digest$1(JSON.stringify(events));
+			versions.push([
+				"session",
+				id,
+				revision
+			]);
+			revalidate.push(() => {
+				assertSessionAuthorized(scope, id);
+				if (digest$1(JSON.stringify(session.snapshotEvents())) !== revision) throw new Error("时间线来源已变化，请重新查询");
+			});
+			const times = new Map(events.map((event) => [event.seq, event.time]));
+			for (const row of rows) for (let start = 0; start < row.content.length; start += MAX_CHUNK) {
+				const end = Math.min(row.content.length, start + MAX_CHUNK);
+				add(makeSessionReference(scope.moduleId, id, events, [row.seq], {
+					start,
+					end
+				}), row.content.slice(start, end), times.get(row.seq));
+			}
+		}
+		resultOf(scope, hits);
+		const current = scopeOf();
+		if (JSON.stringify([
+			current.moduleId,
+			current.dir,
+			current.paths,
+			[...sessionIds(current)]
+		]) !== JSON.stringify([
+			scope.moduleId,
+			scope.dir,
+			scope.paths,
+			[...sessionIds(scope)]
+		])) throw new Error("时间线来源声明已变化");
+		for (const check of revalidate) check();
+		const sourceKey = (hit) => hit.reference.kind === "file" ? "0:" + hit.reference.path + ":" + String(hit.reference.start).padStart(12, "0") : "1:" + hit.reference.sessionId + ":" + String(hit.reference.seqs[0]).padStart(16, "0") + ":" + hit.reference.start;
+		hits.sort((a, b) => (a.time === b.time ? 0 : a.time === null ? 1 : b.time === null ? -1 : a.time.localeCompare(b.time)) || sourceKey(a).localeCompare(sourceKey(b)));
+		const version = digest$1(JSON.stringify([
+			scope.moduleId,
+			scope.dir,
+			scope.paths,
+			[...sessionIds(scope)],
+			versions,
+			input.query ?? null,
+			since ?? null,
+			until ?? null,
+			limit
+		]));
+		let offset = 0;
+		if (input.cursor !== void 0) {
+			let cursor;
+			try {
+				cursor = JSON.parse(Buffer.from(input.cursor, "base64url").toString("utf8"));
+			} catch {
+				throw new Error("时间线游标无效");
+			}
+			if (!cursor || Object.keys(cursor).sort().join(",") !== "offset,version" || cursor.version !== version || !Number.isSafeInteger(cursor.offset) || cursor.offset < 0 || cursor.offset >= hits.length) throw new Error("时间线游标已失效，请重新查询");
+			offset = cursor.offset;
+		}
+		const selected = [];
+		let outputBytes = 0;
+		for (const hit of hits.slice(offset, offset + limit)) {
+			outputBytes += Buffer.byteLength(JSON.stringify(hit));
+			if (outputBytes > 65536) break;
+			selected.push(hit);
+		}
+		const next = offset + selected.length;
+		return {
+			hits: selected,
+			...next < hits.length ? { nextCursor: Buffer.from(JSON.stringify({
+				version,
+				offset: next
+			})).toString("base64url") } : {}
+		};
 	};
 	return {
 		async search(input) {
-			if (typeof input.query !== "string" || input.query.trim().length === 0 || input.query.length > 1024) throw new Error("检索 query 必须为1–1024字符");
+			if (input.mode !== void 0 && input.mode !== "search" && input.mode !== "timeline") throw new Error("检索模式无效");
+			if ((input.query !== void 0 || input.mode !== "timeline") && (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 = [];
+			if (input.cursor !== void 0 && (typeof input.cursor !== "string" || input.cursor.length > 2048)) throw new Error("时间线游标无效");
+			if (input.mode === "timeline") return timeline(input, limit);
+			if (input.since !== void 0 || input.until !== void 0 || input.cursor !== void 0) throw new Error("时间过滤和游标只用于时间线");
+			const scope = scopeOf(), query = input.query, candidates = [];
+			const synonyms = synonymTerms(scope, query);
+			let candidateBytes = 0;
+			const add = (hit) => {
+				const match = matchKind(hit.content, query);
+				if (!match && !scope.synonymsFile) return;
+				candidateBytes += Buffer.byteLength(hit.content);
+				if (candidateBytes > 67108864) throw new Error("检索候选超过64 MiB");
+				candidates.push({
+					...hit,
+					...match ? { match } : {}
+				});
+			};
 			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({
+						add({
 							reference: {
 								kind: "file",
 								moduleId: scope.moduleId,
@@ -27123,29 +28342,51 @@ function createModuleRetrieval(scopeOf, loadSession) {
 							},
 							content: text
 						});
-						if (hits.length === limit) return resultOf(scope, hits);
+						if (!scope.synonymsFile && candidates.length === limit) return resultOf(scope, candidates);
 					}
 					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)
+				for (const row of rows) for (let start = 0; start < row.content.length; start += MAX_CHUNK) {
+					const end = Math.min(row.content.length, start + MAX_CHUNK), text = row.content.slice(start, end);
+					add({
+						reference: makeSessionReference(scope.moduleId, id, events, [row.seq], {
+							start,
+							end
+						}),
+						content: text
 					});
-					if (hits.length === limit) return resultOf(scope, hits);
+					if (!scope.synonymsFile && candidates.length === limit) return resultOf(scope, candidates);
 				}
 			}
-			return resultOf(scope, hits);
+			const hits = [];
+			for (const candidate of candidates) {
+				const match = matchKind(candidate.content, query);
+				if (match) hits.push({
+					...candidate,
+					match
+				});
+			}
+			hits.sort((a, b) => Number(a.match === "normalized") - Number(b.match === "normalized"));
+			if (hits.length < 3 && synonyms.terms.length) {
+				for (const candidate of candidates) if (!matchKind(candidate.content, query) && synonyms.terms.some((term) => matchKind(candidate.content, term))) hits.push({
+					...candidate,
+					match: "synonym"
+				});
+			}
+			const current = scopeOf();
+			if (current.synonymsFile !== scope.synonymsFile || scope.synonymsFile && readModuleFile(current.dir, scope.synonymsFile).content !== synonyms.content) throw new Error("检索近义表已变化，请重新搜索");
+			const selected = [];
+			let bytes = 0;
+			for (const hit of hits.slice(0, limit)) {
+				const size = Buffer.byteLength(JSON.stringify(hit));
+				if (bytes + size > 65536) break;
+				bytes += size;
+				selected.push(hit);
+			}
+			return resultOf(scope, selected);
 		},
 		async open(reference) {
 			const scope = scopeOf();
@@ -27215,10 +28456,14 @@ function registerModuleRetrievalTools(ctx, retrievalOf) {
 			description: "搜索 moduleId 声明模块已授权的文件、账本或历史会话。结果中的 reference 可交 module_open 回取相同原文。",
 			parameters: {
 				moduleId: MODULE_ID_PARAM,
-				query: {
+				query: { type: "string" },
+				mode: {
 					type: "string",
-					required: true
+					enum: ["search", "timeline"]
 				},
+				since: { type: "string" },
+				until: { type: "string" },
+				cursor: { type: "string" },
 				limit: { type: "number" }
 			},
 			output: {
@@ -27235,11 +28480,19 @@ function registerModuleRetrievalTools(ctx, retrievalOf) {
 				if (Object.keys(args).some((key) => ![
 					"moduleId",
 					"query",
+					"mode",
+					"since",
+					"until",
+					"cursor",
 					"limit"
 				].includes(key))) throw new Error("检索请求含未知字段");
 				exec.signal?.throwIfAborted();
 				const value = await retrievalOf(exec, args.moduleId).search({
 					query: args.query,
+					mode: args.mode,
+					since: args.since,
+					until: args.until,
+					cursor: args.cursor,
 					limit: args.limit
 				});
 				exec.signal?.throwIfAborted();
@@ -27285,6 +28538,15 @@ function registerModuleRetrievalTools(ctx, retrievalOf) {
 }
 function createModuleRetrievalProvider(host, loadSession) {
 	const agents = /* @__PURE__ */ new WeakMap();
+	const moduleStates = /* @__PURE__ */ new Map();
+	const declarationOf = (state, moduleId) => [...state.modules.get(moduleId)?.values() ?? []].at(-1);
+	const invalidate = (state, moduleId) => {
+		const previous = state.observations.get(moduleId);
+		state.observations.set(moduleId, {
+			...previous,
+			state: previous ? "stale" : "unbuilt"
+		});
+	};
 	const retrievalFor = (state, moduleId, agent) => {
 		let retrieval = state.indexes.get(moduleId);
 		if (retrieval === void 0) {
@@ -27296,6 +28558,7 @@ function createModuleRetrievalProvider(host, loadSession) {
 					dir: current.dir,
 					paths: current.config.paths,
 					sessions: current.config.sessions,
+					synonymsFile: current.config.synonymsFile,
 					session: agent.session
 				};
 			}, loadSession);
@@ -27304,38 +28567,69 @@ function createModuleRetrievalProvider(host, loadSession) {
 		return retrieval;
 	};
 	return {
+		status(agent, moduleId) {
+			const state = agents.get(agent);
+			if (!state?.modules.has(moduleId)) return { state: "unauthorized" };
+			return { ...state.observations.get(moduleId) };
+		},
+		invalidate(agent, moduleId) {
+			const state = agents.get(agent);
+			if (state?.modules.has(moduleId)) invalidate(state, moduleId);
+		},
+		invalidateModule(moduleId) {
+			for (const state of moduleStates.get(moduleId) ?? []) invalidate(state, moduleId);
+		},
 		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;
+			const declaration = declarationOf(state, moduleId);
+			const observation = {
+				...state.observations.get(moduleId),
+				state: "refreshing"
+			};
+			state.observations.set(moduleId, observation);
+			try {
+				const result = await retrievalFor(state, moduleId, agent).refresh();
+				signal?.throwIfAborted();
+				if (agents.get(agent) !== state || declarationOf(state, moduleId) !== declaration) throw new Error("检索来源声明已变化或未授权");
+				if (state.observations.get(moduleId) !== observation) throw new Error("检索来源状态已变化，请重新刷新");
+				state.observations.set(moduleId, {
+					...result,
+					observedAt: (/* @__PURE__ */ new Date()).toISOString()
+				});
+				return result;
+			} catch (error) {
+				if (agents.get(agent) === state && state.observations.get(moduleId) === observation) state.observations.set(moduleId, {
+					...observation,
+					state: "failed"
+				});
+				throw error;
+			}
 		},
 		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("检索来源白名单无效或超限");
+			if (config.synonymsFile !== void 0 && (typeof config.synonymsFile !== "string" || !config.synonymsFile || config.synonymsFile.length > 1024)) 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
+					observations: /* @__PURE__ */ new Map(),
+					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
+						}, target.id, agent);
+					})
 				};
 				agents.set(agent, state);
 			}
@@ -27343,19 +28637,31 @@ function createModuleRetrievalProvider(host, loadSession) {
 			if (declarations === void 0) {
 				declarations = /* @__PURE__ */ new Map();
 				state.modules.set(sourceModuleId, declarations);
+				let members = moduleStates.get(sourceModuleId);
+				if (!members) {
+					members = /* @__PURE__ */ new Set();
+					moduleStates.set(sourceModuleId, members);
+				}
+				members.add(state);
 			}
 			const token = Symbol(sourceModuleId);
 			declarations.set(token, {
 				config,
 				dir: sourceModuleDir
 			});
+			invalidate(state, sourceModuleId);
 			const owner = state;
 			return () => {
+				const wasCurrent = [...declarations.keys()].at(-1) === token;
 				if (!declarations.delete(token)) return;
 				if (declarations.size === 0) {
 					owner.modules.delete(sourceModuleId);
 					owner.indexes.delete(sourceModuleId);
-				}
+					owner.observations.delete(sourceModuleId);
+					const members = moduleStates.get(sourceModuleId);
+					members?.delete(owner);
+					if (!members?.size) moduleStates.delete(sourceModuleId);
+				} else if (wasCurrent) invalidate(owner, sourceModuleId);
 				if (owner.modules.size === 0) {
 					owner.dispose();
 					agents.delete(agent);
@@ -27366,6 +28672,19 @@ function createModuleRetrievalProvider(host, loadSession) {
 }
 //#endregion
 //#region src/runtime/soul-maintenance.ts
+async function waitForIdle(agent, signal) {
+	signal.throwIfAborted();
+	let aborted;
+	try {
+		await Promise.race([agent.whenIdle(), new Promise((_resolve, reject) => {
+			aborted = () => reject(signal.reason);
+			signal.addEventListener("abort", aborted, { once: true });
+			if (signal.aborted) aborted();
+		})]);
+	} finally {
+		signal.removeEventListener("abort", aborted);
+	}
+}
 function createSoulMaintenanceProvider(options) {
 	const states = /* @__PURE__ */ new Map();
 	const status = (id) => {
@@ -27391,18 +28710,32 @@ function createSoulMaintenanceProvider(options) {
 		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
+				state.state = "waiting";
+				await waitForIdle(owner.agent, signal);
+				if (!valid()) return;
+				let entered = false;
+				try {
+					await owner.agent.runMaintenance(async (activitySignal) => {
+						entered = true;
+						state.state = "running";
+						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
+						});
 					});
-				});
+				} catch (error) {
+					if (!entered && valid()) {
+						state.state = "waiting";
+						return;
+					}
+					throw error;
+				}
 				if (!valid()) return;
 				state.state = "ready";
 				if (owner.config.wake) owner.agent.followup(pluginMessage("soul-maintenance", "书房索引与 SELF 已维护。请核对当前未结事项；无需重复写入已有事实。", "书房维护心跳"));
@@ -27417,10 +28750,13 @@ function createSoulMaintenanceProvider(options) {
 				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();
+					if (current !== owner && controller.signal.aborted) tick(id);
+					else {
+						state.timer = setTimeout(() => {
+							tick(id);
+						}, current.config.intervalMs);
+						state.timer.unref();
+					}
 				}
 			}
 		});
@@ -27473,6 +28809,31 @@ function createSoulMaintenanceProvider(options) {
 //#region src/runtime/soul-runtime.ts
 /** Soul宿主接线：历史只读句柄、检索授权与SELF/维护共享owner。 */
 function installSoulRuntime(ctx, host, moduleIds) {
+	let active = true;
+	const rendered = /* @__PURE__ */ new Map();
+	const digest = (text) => createHash("sha256").update(text).digest("hex");
+	const delivered = /* @__PURE__ */ new Map();
+	const source = (id, agent, signal) => {
+		signal?.throwIfAborted();
+		if (!active || !agent?.session?.id || !moduleIds(agent.id).includes(id)) throw new Error("SELF来源模块未参与本Agent装配");
+		return assertModuleSnapshotSource(host.root, id);
+	};
+	const keyOf = (id, agent) => JSON.stringify([id, agent.session.id]);
+	const activityOf = (agent) => {
+		const events = agent.session.snapshotEvents();
+		for (let i = events.length - 1; i >= 0; i--) {
+			const event = events[i];
+			if ([
+				"user/message",
+				"assistant/message",
+				"tool/call",
+				"tool/result",
+				"step/start",
+				"turn/end"
+			].includes(event.type) && Number.isFinite(event.time)) return new Date(event.time).toISOString();
+		}
+		return null;
+	};
 	const budgets = /* @__PURE__ */ new Map();
 	const readSelfBudget = (dir) => {
 		const stat = statSync(join(dir, "module.yml"), { throwIfNoEntry: false });
@@ -27509,18 +28870,134 @@ function installSoulRuntime(ctx, host, moduleIds) {
 		}
 	});
 	const maintenance = createSoulMaintenanceProvider({ refreshRetrieval: (agent, id, signal) => retrieval.refresh(agent, id, signal) });
+	const reminder = createSoulReminder((id, agent) => readSoulLedgerProjection(source(id, agent)));
+	const pressure = (dir, agent) => {
+		try {
+			const thresholds = readModuleFacts(dir).effectiveConfigs?.["soul-maintenance"]?.pressureThresholds;
+			return Array.isArray(thresholds) ? readSoulPressure(ctx, agent, thresholds) : { state: "disabled" };
+		} catch {
+			return {
+				state: "unknown",
+				reason: "水位配置或会话观测不可用"
+			};
+		}
+	};
 	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));
-	} });
+	const status = (id, agent) => {
+		const dir = source(id, agent), ledger = readSoulLedgerProjection(dir), state = readSoulState(dir, agent.session.id);
+		return {
+			clock: (/* @__PURE__ */ new Date()).toISOString(),
+			timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+			sessionId: agent.session.id,
+			revision: state.revision,
+			mark: state.mark ? { ...state.mark } : null,
+			activityAt: activityOf(agent),
+			ledger: {
+				total: ledger.total,
+				open: ledger.open,
+				pendingReview: ledger.pendingReview,
+				initialized: ledger.initialized,
+				pendingVersion: ledger.pendingVersion
+			},
+			index: { ...retrieval.status(agent, id) },
+			pressure: pressure(dir, agent),
+			renderedAt: rendered.get(keyOf(id, agent))?.at ?? null,
+			deliveredAt: delivered.get(keyOf(id, agent)) ?? null
+		};
+	};
+	ctx.provide(SOUL_SELF_SERVICE, {
+		status,
+		reminder,
+		committed: (id, agent) => {
+			source(id, agent);
+			retrieval.invalidateModule(id);
+			maintenance.tick(id);
+			return { state: maintenance.status(id).state === "disabled" ? "stale-maintenance-disabled" : "refresh-pending" };
+		},
+		render: (id, agent, signal) => {
+			const dir = source(id, agent, signal), budget = readSelfBudget(dir);
+			return Promise.resolve().then(() => {
+				if (source(id, agent, signal) !== dir) throw new Error("SELF来源发生变化");
+				const state = readSoulState(dir, agent.session.id);
+				const water = pressure(dir, agent);
+				const text = renderSoulSelf(dir, agent, signal, budget, retrieval.status(agent, id), [
+					`- 显式状态：${state.mark?.text ?? "尚未标记"}；标记时刻：${state.mark?.recordedAt ?? "无"}`,
+					`- 实际活动时刻：${activityOf(agent) ?? "未观测"}`,
+					`- SELF实际投递观测：${delivered.get(keyOf(id, agent)) ?? "尚未观测"}`,
+					...water.state === "disabled" ? [] : [water.state === "known" ? `- 上下文水位：${(water.ratio * 100).toFixed(1)}%（${water.tokens}/${water.capacity}；${water.source}）；${water.guidance}。此为提示，不自动压缩。` : `- 上下文水位：未知；${water.reason}`]
+				]);
+				source(id, agent, signal);
+				if (rendered.size > 1024) rendered.delete(rendered.keys().next().value);
+				const key = keyOf(id, agent), candidates = [...rendered.get(key)?.candidates ?? [], digest(text)].slice(-16);
+				rendered.set(key, {
+					at: (/* @__PURE__ */ new Date()).toISOString(),
+					candidates,
+					sessionId: agent.session.id
+				});
+				return text;
+			});
+		}
+	});
+	ctx.effect(() => ctx.on("session/event", (session, event) => {
+		const observed = event.data.message?.source;
+		if (observed?.kind !== "runtime-context" || observed.form !== "snapshot") return;
+		for (const [key, candidate] of rendered) if (candidate.sessionId === session.id && observed.sections?.some((section) => typeof section.text === "string" && candidate.candidates.includes(digest(section.text)))) {
+			if (delivered.size > 1024) delivered.delete(delivered.keys().next().value);
+			delivered.set(key, new Date(event.time).toISOString());
+		}
+	}));
 	ctx.effect(() => () => {
+		active = false;
 		maintenance.dispose();
 		budgets.clear();
+		rendered.clear();
+		delivered.clear();
 	});
+	const observe = (exec, id) => {
+		if (!exec.agent) throw new Error("Soul状态缺少实际Agent");
+		return status(id, exec.agent);
+	};
+	return {
+		status: observe,
+		check: async (exec, id, includeUpgrade) => {
+			if (!exec.agent) throw new Error("Soul状态缺少实际Agent");
+			const agent = exec.agent, dir = source(id, agent), key = keyOf(id, agent);
+			const diagnostics = readSoulDiagnostics(dir, {
+				index: retrieval.status(agent, id),
+				selfRenderedAt: rendered.get(key)?.at,
+				selfDeliveredAt: delivered.get(key),
+				maintenance: maintenance.status(id),
+				context: contextRuntimeOf(agent)?.status(),
+				recovery: recoveryObservationOf(agent)
+			});
+			const sessionId = agent.session.id;
+			const upgrade = includeUpgrade ? await readSoulUpgradePreview(dir) : { status: "not-applicable" };
+			if (source(id, agent, exec.signal) !== dir || agent.session.id !== sessionId) throw new Error("Soul诊断来源或会话已变化");
+			return {
+				...diagnostics,
+				checks: diagnostics.checks.map((check) => ({ ...check })),
+				upgrade: upgrade.status === "not-applicable" ? {
+					status: includeUpgrade ? upgrade.status : "not-requested",
+					expectedRevision: null,
+					conflicts: [],
+					candidate: null,
+					files: [],
+					apply: null
+				} : {
+					status: upgrade.status,
+					expectedRevision: upgrade.expectedRevision,
+					conflicts: upgrade.conflicts,
+					candidate: upgrade.candidate,
+					files: upgrade.files.map((file) => ({ ...file })),
+					apply: upgrade.apply
+				}
+			};
+		}
+	};
+}
+function soulReminderOf(ctx) {
+	return ctx.get(SOUL_SELF_SERVICE)?.reminder;
 }
 //#endregion
 //#region engine/promotion-pool.mjs
@@ -28979,32 +30456,6 @@ function createGenerationRecoveryState(root = join(storageRoot(), "generation-re
 	};
 }
 //#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",
@@ -29095,7 +30546,8 @@ function mountSources(ctx, sources, options = {}) {
 				standingMountFor: options.standingMountFor,
 				promotionPool: pool,
 				variableStore: options.variableStore,
-				manifestCheck: options.manifestCheck
+				manifestCheck: options.manifestCheck,
+				soulReminder: options.soulReminder
 			});
 		} catch (error) {
 			throw sourceError(error, source.moduleId);
@@ -29778,7 +31230,8 @@ function createAgentAssembly(ctx, options) {
 					onOutcome: ruleDiagnostics.record,
 					variableStore,
 					standingMountFor: await loadStandingMountFor(),
-					manifestCheck
+					manifestCheck,
+					soulReminder: soulReminderOf(ctx)
 				});
 			} catch (error) {
 				await root.dispose();
@@ -30488,7 +31941,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) ?? []);
+	const soulRuntime = installSoulRuntime(ctx, moduleToolHost, (id) => assembly?.moduleIds(id) ?? []);
 	ctx.provide(toolServiceName("module-import-tools"), { mount: (scopeCtx) => registerModuleImportTools(scopeCtx, {
 		...moduleToolHost,
 		rebuild: async (id) => {
@@ -30498,7 +31951,19 @@ 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(toolServiceName("soul-ledger"), { mount: (scopeCtx) => {
+		const ledger = registerSoulLedgerTools(scopeCtx, moduleToolHost);
+		try {
+			const state = registerSoulStateTools(scopeCtx, moduleToolHost, soulRuntime);
+			return () => {
+				state();
+				ledger();
+			};
+		} catch (error) {
+			ledger();
+			throw error;
+		}
+	} });
 	ctx.provide(DISCOVERY_SERVICE, createDiscoveryRegistry());
 	ctx.provide(MANIFEST_CHECK_SERVICE, createManifestCheckReader(modulesDir()));
 	ctx.provide(toolServiceName("module-variable-tools"), { mount: (scopeCtx) => registerModuleVariableTools(scopeCtx, moduleToolHost) });