clearai-dsh 0.1.6 → 0.2.0

package/presets/clearai/plugins/clearai-kernel.js

@@ -401,7 +401,22 @@ export const HUMAN_GATE_MARK = '[clearai·人门]'
  * 两侧白名单一旦各自维护,摘动词时只改一侧 ⇒ 内核仍认、宿主不认 ⇒ **等价性用例立刻红** ✓。
  * 这正是那条用例存在的意义:两份实现漂移不许静默。
  */
-export const HUMAN_GATE_ACTIONS = ['adopt_branch', 'abandon_fork', 'promote_skill', 'retract_fact', 'keep_fact', 'confirm_provisional']
+/**
+ * **逐字镜像 `ui/lib/fold.js` 的同名清单**(预设面不能 import 宿主半,于是只能两份;
+ * 两份相等由 `test/authority-boundary.test.mjs` 钉死——它红的时候,是清单漂了,不是测试坏了)。
+ */
+export const HUMAN_GATE_ACTIONS = [
+	'adopt_branch',
+	'abandon_fork',
+	'promote_skill',
+	'retract_fact',
+	'keep_fact',
+	'confirm_provisional',
+	'register_term',
+	'register_predicate',
+	'revise_term',
+	'deprecate_entry',
+]
 export function parseHumanGateMessage(message) {
 	if (message === null || typeof message !== 'object') return null
 	// 署名必须是人:插件与模型来源的同名标记不算人门动作(与宿主半同一条纪律)。
@@ -478,6 +493,8 @@ export const MECHANISM_TOOLS = {
 	brain: ['SaveSkill', 'WriteMemory'],
 	/** 账本两件:它长在 git 上(A 层用工作区自己的仓库,B 层用数据区的旁路账本,与世界线共用一本)。 */
 	ledger: ['FileHistory', 'RestoreFile'],
+	/** 领域语言:七个动词 = 词汇的全部写入口(注册/修订/废止) + 一个读入口(按概念取已知)。 */
+	ontology: ['RegisterTerm', 'RegisterPredicate', 'ReviseTerm', 'RevisePredicate', 'DeprecateTerm', 'DeprecatePredicate', 'QueryKnowledge'],
 }
 const TOOL_CATALOG = new Set(Object.values(MECHANISM_TOOLS).flat())
 
@@ -1123,7 +1140,7 @@ export function apply(ctx, config = {}) {
 			`- 要裁决的分歧:${fork.question}`,
 			`- **你这一个方案**:${branch.label} —— ${branch.approach}`,
 			`- **判定标准(你必须做到,并且可被客观核对)**:${branch.done_criteria}`,
-			`- **裁决指标(所有世界线共用同一把尺子,不许各自另定口径)**:${fork.decide_by?.metric ?? '(未登记)'}(${fork.decide_by?.direction === 'min' ? '越小越好' : '越大越好'})`,
+			`- **裁决指标(所有世界线共用同一把尺子,不许各自另定口径;口径里引用的那个文件就是测量仪,你的读数必须出自它)**:${fork.decide_by?.metric ?? '(未登记)'}(${fork.decide_by?.direction === 'min' ? '越小越好' : '越大越好'})`,
 			/**
 			 * **声明的物证路径必须告诉干活的人**。
 			 *
@@ -1152,7 +1169,7 @@ export function apply(ctx, config = {}) {
 		})
 		if (dispatched.ok !== true) return { ok: false, note: `执行者派不出去(${dispatched.reason})`, mutations }
 		const childId = String(dispatched.run.id)
-		const entry = { fork: fork.id, branch: branch.id, label: branch.label, workspace: branch.workspace, child: childId, settled: null, reported: false, run: dispatched.run }
+		const entry = { sessionId, fork: fork.id, branch: branch.id, label: branch.label, workspace: branch.workspace, child: childId, settled: null, reported: false, run: dispatched.run }
 		executorRuns.set(childId, entry)
 		mutations.push({ t: 'worldline/executing', fork: fork.id, branch: branch.id, child: childId, capability: dispatched.capability, degraded_reason: dispatched.degraded ?? null })
 		/**
@@ -1524,7 +1541,7 @@ export function apply(ctx, config = {}) {
 
 
 	/**
-	 * **失联的评估者**。
+	 * **已结束的评估者**。
 	 *
 	 * `pendingAudits` 是**进程内**的:重启之后它空了,而投影里那条 `audit/dispatched` 还在
 	 * (`verdict === null`)。后果有两条,后一条更狠:
@@ -1533,13 +1550,16 @@ export function apply(ctx, config = {}) {
 	 *      一条永远不会回来的裁决,把整个目标按死在挂起上。
 	 *
 	 * 判据不看内存,看**宿主的目录**:`subagents.listChildren(sessionId)` 给每个子会话一个
-	 * `activity: 'running' | 'inactive'`(还在跑 / 只剩日志),而且它不需要把子代理加载起来。
-	 * 投影里在裁决 + 子会话不在跑 ⇒ 落一条 `audit/settled{verdict:'unknown', note:'lost'}`:
-	 * 与别的结局用同一个转变,只是缘由写具体(「失联」)。下一次交付会重新派评估者。
+	 * `activity: 'running' | 'inactive'`(还在跑 / 只剩日志)——**宿主是"还在不在跑"的唯一权威**。
+	 * 目录说已结束 ⇒ 这次运行**结束了**。结束不等于失联:结论可能就躺在它自己的会话日志里,
+	 * 所以**先取回**(与侦察的 `sweepScouts` 同一条路),取不回才如实落 unknown。
+	 *
+	 * 结算只报事实、不给建议(「重新交付会派一个新的评估者」那类话删了):
+	 * 要不要重试是计划层的决定,不是账本该说的话。
 	 *
 	 * 拿不到目录(服务不在 / 查询失败)时**什么都不做**:不猜、不误伤正在跑的裁决。
 	 */
-	async function sweepLostAudits(sessionId, state) {
+	async function sweepEndedAudits(sessionId, state) {
 		const pending = (state?.audits ?? []).filter((audit) => audit.verdict === null && typeof audit.child === 'string' && audit.child !== '')
 		if (pending.length === 0) return { mutations: [], lost: 0, lines: [] }
 		// 这个进程里正攥着的那几次派遣:它们是活的,不问目录。
@@ -1560,18 +1580,41 @@ export function apply(ctx, config = {}) {
 		const lines = []
 		for (const audit of unresolved) {
 			if (running.has(String(audit.child))) continue
-			mutations.push({
-				t: 'audit/settled',
-				id: audit.id,
-				step: audit.step,
-				verdict: 'unknown',
-				basis: '评估者失联:派它的那次进程已经不在了,子会话也不在跑——这次裁决不会有结果。重新交付这一步会派一个新的评估者。',
-				shortfalls: ['auditor_lost'],
-				card_path: null,
-			})
-			lines.push(`${audit.step}:裁决失联(记为 unknown,可重新交付)`)
+			/**
+			 * 宿主说已结束 ⇒ **先把它的结论取回来**(读它自己的会话日志,与侦察同一条路)。
+			 * 跳过它就把「结束」误报成「死亡」,还会诱导重新交付 ⇒ 同一次评估被重做。
+			 */
+			const recovered = recoverVerdictFromChildSession(audit.child)
+			if (recovered !== null && recovered.ok === true) {
+				const card = { schema_version: 'clearai.audit.v1', kind: audit.kind ?? 'evidence_audit', step_id: audit.step, auditor_run_id: String(audit.child), verdict: recovered.verdict.verdict, shortfalls: recovered.verdict.shortfalls, card: recovered.verdict.basis, created_at: Date.now() }
+				const cardPath = writeAuditCard(sessionId, audit.step, card)
+				mutations.push({ t: 'audit/settled', id: audit.id, step: audit.step, verdict: recovered.verdict.verdict, basis: recovered.verdict.basis, shortfalls: recovered.verdict.shortfalls, card_path: cardPath })
+				lines.push(`${audit.step}:裁决从子会话日志取回(${recovered.verdict.verdict})`)
+				continue
+			}
+			if (recovered !== null && recovered.ok !== true) {
+				mutations.push({ t: 'audit/settled', id: audit.id, step: audit.step, verdict: 'unknown', basis: `评估者已结束,但未正常完成(${recovered.stopReason})。`, shortfalls: ['audit_incomplete'], card_path: null })
+				lines.push(`${audit.step}:评估者已结束、未正常完成(记为 unknown)`)
+				continue
+			}
+			mutations.push({ t: 'audit/settled', id: audit.id, step: audit.step, verdict: 'unknown', basis: '评估者已结束(宿主目录报告),但其结论未能从子会话日志取回。', shortfalls: ['auditor_ended_uncollected'], card_path: null })
+			lines.push(`${audit.step}:评估者已结束、结论未取回(记为 unknown)`)
 		}
-		return { mutations, lost: mutations.length, lines }
+		return { mutations, settled: mutations.length, lines }
+	}
+
+	/**
+	 * 从子会话日志里取回**评估者**的裁决——与侦察的 `recoverFromChildSession` 同一条路。
+	 *
+	 * 返回三档:`{ok:true, verdict}` 取回了;`{ok:false, stopReason}` 它结束了但未正常完成;
+	 * `null` 连它的日志都读不到。三档都只是**读数**,判断留给调用方如实分档。
+	 */
+	function recoverVerdictFromChildSession(childId) {
+		const settled = recoverFromChildSession(childId)
+		if (settled === null) return null
+		if (settled.ok !== true) return { ok: false, stopReason: settled.stopReason }
+		const verdict = normalizeVerdict(parseLooseJson([{ type: 'text', text: settled.conclusion }]))
+		return { ok: true, verdict }
 	}
 
 	function sweepWorldlineExecutors(state, sessionId) {
@@ -1711,7 +1754,7 @@ export function apply(ctx, config = {}) {
 		 * 事实该在副作用之前/同批落账:所以派遣立即返回,结论由 `sweepScouts()` 在
 		 * 「下一个回合边界 / 用到世界线与侦察的那几件工具」上收(与执行者完全同一套)。
 		 */
-		const entry = { scoutId, stepId: step.id, planId: plan?.id ?? null, trigger, digest, child: childId, settled: null, reported: false, run: dispatched.run }
+		const entry = { sessionId, scoutId, stepId: step.id, planId: plan?.id ?? null, trigger, digest, child: childId, settled: null, reported: false, run: dispatched.run }
 		scoutRuns.set(childId, entry)
 		/**
 		 * 只有一次性派遣才有 `result` promise。可续跑那一档没有 ⇒ 结算改由
@@ -1753,7 +1796,7 @@ export function apply(ctx, config = {}) {
 				return { verdict: 'unknown', basis: `独立评估者无法派遣(${dispatched.reason})`, shortfalls: ['audit_dispatch_failed'], cardPath: null, mutations }
 			}
 			mutations.push({ t: 'audit/dispatched', id: auditKey, step: step.id, plan: plan?.id ?? 'goal', kind, evaluator_session: String(dispatched.run.id), capability: dispatched.capability })
-			entry = { run: dispatched.run, capability: dispatched.capability, auditKey, settled: undefined }
+			entry = { sessionId, run: dispatched.run, capability: dispatched.capability, auditKey, step: step.id, plan: plan?.id ?? 'goal', kind, settled: undefined }
 			pendingAudits.set(key, entry)
 			entry.settled = dispatched.run.result.then(
 				(value) => ({ ok: true, value }),
@@ -1774,12 +1817,24 @@ export function apply(ctx, config = {}) {
 		// 已落定:这次派遣的生命周期到此为止。下一次交付是**新的一次评估**(新证据),必须重新派遣。
 		pendingAudits.delete(key)
 		if (outcome.ok !== true) {
-			return { verdict: 'unknown', basis: `评估者失败:${String(outcome.error?.message ?? outcome.error)}`, shortfalls: ['audit_failed'], cardPath: null, mutations }
+			return settleUnknown(`评估者失败:${String(outcome.error?.message ?? outcome.error)}`, ['audit_failed'])
+		}
+		/**
+		 * **裁决一旦结束,就要落一条结算事实**——不管结局是什么。
+		 *
+		 * 三条路原来直接 `return unknown`(评估者失败 / 没正常结束 / 评估卡落盘失败),
+		 * 账上只剩 `audit/dispatched`:看上去像"它还在跑",而它**已经结束了**。
+		 * 结局不好也是结局,如实落下来——不然那条派发事实会在账上挂到天荒地老,
+		 * 而"评估者没有悬空"这条不变量也只能红着,连解释都拿不出证据。
+		 */
+		const settleUnknown = (basis, shortfalls) => {
+			mutations.push({ t: 'audit/settled', id: entry.auditKey, step: step.id, verdict: 'unknown', basis, shortfalls, card_path: null })
+			return { verdict: 'unknown', basis, shortfalls, cardPath: null, mutations }
 		}
 		const settled = outcome.value
 		const stopReason = String(settled?.stopReason ?? 'completed')
 		if (stopReason !== 'completed' && settled?.structured === undefined) {
-			return { verdict: 'unknown', basis: `评估者未正常结束(${stopReason})`, shortfalls: ['audit_incomplete'], cardPath: null, mutations }
+			return settleUnknown(`评估者未正常结束(${stopReason})`, ['audit_incomplete'])
 		}
 		const verdict = settled?.structured !== undefined ? normalizeVerdict(settled.structured) : normalizeVerdict(parseLooseJson(settled?.output))
 		try {
@@ -1790,7 +1845,7 @@ export function apply(ctx, config = {}) {
 		const card = { schema_version: 'clearai.audit.v1', kind, step_id: step.id, auditor_run_id: String(entry.run.id), verdict: verdict.verdict, shortfalls: verdict.shortfalls, card: verdict.basis, created_at: Date.now() }
 		const cardPath = writeAuditCard(sessionId, step.id, card)
 		if (cardPath === null) {
-			return { verdict: 'unknown', basis: '评估卡落盘失败:裁决降级', shortfalls: ['card_persist_failed'], cardPath: null, mutations }
+			return settleUnknown('评估卡落盘失败:裁决降级', ['card_persist_failed'])
 		}
 		mutations.push({ t: 'audit/settled', id: entry.auditKey, step: step.id, verdict: verdict.verdict, basis: verdict.basis, shortfalls: verdict.shortfalls, card_path: cardPath })
 		return { ...verdict, cardPath, mutations }
@@ -2519,7 +2574,7 @@ export function apply(ctx, config = {}) {
 		const facts = Array.isArray(state?.facts) ? state.facts : []
 		if (facts.length === 0) return null
 		const lines = [
-			'# 事实库(已升格、可作为「已知」引用)',
+			'# 本体内容(已确立条目,可作为「已知」引用;未结构化的旧条目照旧在架)',
 			'',
 			'> 每条都带**边界**(推翻条件)与**支持等级**:引用它之前先看边界还在不在。',
 			'> 这一份由系统维护(做的人不能写 `clear/knowledge/facts`);新的在前。',
@@ -2567,6 +2622,59 @@ export function apply(ctx, config = {}) {
 		}
 	}
 
+	/**
+	 * **领域词汇货架**:把折出来的词汇落成 `clear/ontology/domain.md`。
+	 *
+	 * 与过程本体货架同一条纪律(读面 + 幂等),但**触发时机不同**:过程本体随发布版本,
+	 * 一个会话铺一次就够;词汇每一步都可能变,所以每个本体动词落账之后都要重铺一遍——
+	 * 内容没变就不重写(文件时间戳是给人的读数,不是噪声)。
+	 *
+	 * 带 `mutations` 时按**这一步之后**的样子渲染:工具返回前货架就已更新,读的人不必等下一回合。
+	 */
+	function ensureDomainShelf(hostService, sessionId, mutations = []) {
+		if (hostService?.domain?.renderShelf === undefined) return ''
+		try {
+			const body = hostService.domain.renderShelf(sessionId, Array.isArray(mutations) ? mutations : [])
+			const file = join(sessionCwd(sessionId), 'clear', 'ontology', 'domain.md')
+			if (existsSync(file) && readFileSync(file, 'utf8') === body) return ''
+			writeTextFile(file, body)
+			return `\n词汇货架已更新:${join('clear', 'ontology', 'domain.md')}(概念 / 谓词 / 图 / 引用)。**它是读面,不是权威**——要改词汇就调注册 / 修订 / 废止动词。`
+		} catch (error) {
+			ctx.logger?.warn?.(`clearai domain shelf: 写入失败 ${String(error?.message ?? error).slice(0, 160)}`)
+			return ''
+		}
+	}
+
+	/**
+	 * 领域判据的宿主入口。**拿不到就明确拒,不抛**:预设与宿主半同包同版本,
+	 * 但一个缺了这道门的宿主(旧包、裁剪过的部署、测试桩)不该让工具在 `undefined` 上崩——
+	 * 崩掉会让模型以为是自己的参数错了,而真实原因是这一层没接上。
+	 */
+	function domainJudge(hostService) {
+		return hostService?.domain ?? null
+	}
+
+	/** 在折出来的词汇里找一个条目(概念或谓词)。判据与折法同源:读的就是 `state.lexicon`。 */
+	function findLexiconEntry(state, id) {
+		const lexicon = state?.lexicon ?? {}
+		const wanted = String(id ?? '').trim()
+		if (wanted === '') return null
+		const term = (Array.isArray(lexicon.terms) ? lexicon.terms : []).find((item) => item.id === wanted)
+		if (term !== undefined) return { kind: 'term', entry: term }
+		const predicate = (Array.isArray(lexicon.predicates) ? lexicon.predicates : []).find((item) => item.id === wanted)
+		if (predicate !== undefined) return { kind: 'predicate', entry: predicate }
+		return null
+	}
+
+	/** 查询条件的一行人话:让「查不到」也说得清查的是什么。 */
+	function describeFilter(filter) {
+		const parts = []
+		if (filter.term !== '') parts.push(`概念「${filter.term}」`)
+		if (filter.predicate !== '') parts.push(`谓词「${filter.predicate}」`)
+		if (filter.subject !== '') parts.push(`主体「${filter.subject}」`)
+		return `查询:${parts.join(' · ')}`
+	}
+
 	/**
 	 * **本体货架**:把已装的那份本体落成 `clear/ontology/<id>.md`。
 	 *
@@ -2647,10 +2755,34 @@ export function apply(ctx, config = {}) {
 				promote_at_level: { type: 'string', enum: LEVELS, description: '升格门槛(默认 L3)' },
 				hypotheses: {
 					type: 'array',
-					description: '候选假设:每条一句话主张 + 一句推翻条件',
+					description:
+						'候选假设:每条一句话主张 + 一句推翻条件;可带**类型化断言**(可选,提供即严校:谓词与概念必须已登记、宾语形态要合值域、同一事实里不许自相矛盾)。不写断言照旧成立——断言是加法,不是门槛。',
 					items: {
 						type: 'object',
-						properties: { claim: { type: 'string' }, refute_when: { type: 'string' } },
+						properties: {
+							claim: { type: 'string' },
+							refute_when: { type: 'string' },
+							assertions: {
+								type: 'array',
+								description: '断言:主词–谓词–宾语(引用领域词汇里的 id)',
+								items: {
+									type: 'object',
+									properties: {
+										predicate: { type: 'string' },
+										subject: { type: 'object', properties: { id: { type: 'string' }, type: { type: 'string' } }, required: ['id'], additionalProperties: false },
+										object: {
+											type: 'object',
+											properties: { kind: { type: 'string', enum: ['statement', 'quantity', 'formula', 'code', 'reference', 'instance'] }, value: {}, unit: { type: 'string' }, type: { type: 'string' } },
+											required: ['kind'],
+											additionalProperties: false,
+										},
+										qualifiers: { type: 'object' },
+									},
+									required: ['predicate', 'subject', 'object'],
+									additionalProperties: false,
+								},
+							},
+						},
 						required: ['claim', 'refute_when'],
 						additionalProperties: false,
 					},
@@ -2676,6 +2808,19 @@ export function apply(ctx, config = {}) {
 			for (const hypothesis of hypotheses) {
 				if (typeof hypothesis?.claim !== 'string' || hypothesis.claim.trim() === '') return fail('hypothesis_claim_required', '每条假设要有一句话主张。')
 				if (typeof hypothesis?.refute_when !== 'string' || hypothesis.refute_when.trim() === '') return fail('hypothesis_refute_required', '每条假设必须写清「什么结果会推翻它」——没有推翻条件的假设无法被检验。')
+				/**
+				 * **宽松+校验**:不写断言放行(断言是加法),写了就在**落账之前**严校——
+				 * 引用不存在的谓词 / 概念、宾语形态不合值域、同一事实自相矛盾,一律当场拒。
+				 * 判据来自宿主半(`hostService.domain`),与折法和读面同源。
+				 */
+				if (hypothesis.assertions !== undefined && hypothesis.assertions !== null) {
+					const judge = domainJudge(hostService)
+					if (judge === null) return fail('domain_unavailable', '这一层的宿主没有提供领域判据(domain facade):无法校验断言。请检查宿主半与预设是否同版本。')
+					const problems = judge.validateAssertions(sessionId, hypothesis.assertions)
+					if (problems.length > 0) {
+						return fail('assertions_rejected', `这条假设的断言不能成立(先注册词汇,或改断言):\n${problems.map((item) => `- ${item}`).join('\n')}`)
+					}
+				}
 			}
 			// 假设数量下限:首次立目标就得带够候选——0 条一样拦(候选对比是检验的前提,
 			// 只有一个猜想时「验证」容易退化成找证据支持自己)。修订不受此限。
@@ -2701,6 +2846,8 @@ export function apply(ctx, config = {}) {
 					id: `h-${Math.random().toString(36).slice(2, 8)}`,
 					claim: hypothesis.claim.trim(),
 					refute_when: hypothesis.refute_when.trim(),
+					/** 断言随假设落账;没写就是 null(加法,不是门槛)。 */
+					assertions: Array.isArray(hypothesis.assertions) ? hypothesis.assertions : null,
 					version: index + 1,
 				})),
 			})
@@ -2871,10 +3018,17 @@ export function apply(ctx, config = {}) {
 					t: 'fact/promoted',
 					id: factId,
 					goal: goal.id,
+					/**
+					 * **身份与内容一起定型**:`hypothesis` 是产出它的那条假设(按 id 关联,
+					 * 措辞改了也认得出),`assertions` 是这条事实的类型化内容(没写就是 null)。
+					 * 断言只在**升格这一刻**落地——旧事实不会被回溯改写。
+					 */
+					hypothesis: hypothesis.id,
 					text: hypothesis.claim,
 					scope: hypothesis.refute_when ?? null,
 					level: hypothesis.supportedLevel ?? null,
 					evidence: state.evidence.filter((item) => item.verdict === 'support').map((item) => item.id),
+					assertions: Array.isArray(hypothesis.assertions) ? hypothesis.assertions : null,
 					path,
 				})
 				promoted.push(hypothesis.claim)
@@ -2969,6 +3123,301 @@ export function apply(ctx, config = {}) {
 		additionalProperties: false,
 	}
 
+
+	// ── 领域语言(本体动词)─────────────────────────────────────────────────
+	/**
+	 * 七个动词 = 领域词汇的**全部写入口**(注册 / 修订 / 废止,概念与谓词各一套)+ 一个读入口。
+	 *
+	 * 它们只做一件事:把「这个领域有哪些概念、哪些谓词、关系取什么值形态」写进账本事件,
+	 * 由折法折成 `state.lexicon`;再由同一份折法长出本体图、冲突读数与货架。
+	 *
+	 * 四条贯穿所有动词的纪律:
+	 *   · **判据只有一份**——校验经 `hostService.domain.*`(与折法、读面同源),预设侧不复制规则;
+	 *   · **依据必填**——约定可以自愿,不能无来由;
+	 *   · **没有删除**——修订留版本,废止留缘由且是黏性终态;
+	 *   · **语义变化必须换 id**——改展示信息走修订,改含义/主词域/值域走「废止 + 新注册」。
+	 */
+	defineTool({
+		name: 'RegisterTerm',
+		description:
+			'登记一个领域概念(本体图上的节点)。id 用小写 slug;`gloss` 一句话说清它指什么;`basis` 必填——哪份材料、哪条事实或人说的哪句话让这个词成立。`parent` 可选(is_a,只能连概念)。登记是**约定**不是主张:它不需要证据等级,但从此可以出现在断言里。要改展示信息用 ReviseTerm,要作废用 DeprecateTerm(记录不会删)。',
+		parameters: {
+			type: 'object',
+			properties: {
+				id: { type: 'string', description: '小写字母开头的 slug(字母/数字/下划线,≤40)' },
+				label: { type: 'string', description: '给人看的名字' },
+				gloss: { type: 'string', description: '一句话释义' },
+				aliases: { type: 'array', items: { type: 'string' }, description: '别名(可选)' },
+				parent: { type: 'string', description: '父概念 id(可选,is_a)' },
+				basis: { type: 'string', description: '依据:哪份材料 / 哪条事实 / 谁说的' },
+			},
+			required: ['id', 'label', 'gloss', 'basis'],
+			additionalProperties: false,
+		},
+		output: CARD_OUTPUT,
+		async execute(args, exec) {
+			const call = open(exec)
+			if (call.ok !== true) return call.response
+			const { hostService, sessionId, mutations } = call
+			const done = finish(hostService, sessionId, mutations)
+			const judge = domainJudge(hostService)
+			if (judge === null) return fail('domain_unavailable', '这一层的宿主没有提供领域判据(domain facade):无法校验词汇。请检查宿主半与预设是否同版本。')
+			const problems = judge.validateTerm(sessionId, args)
+			if (problems.length > 0) return fail('term_rejected', `这个词不能登记:\n${problems.map((item) => `- ${item}`).join('\n')}`)
+			mutations.push({
+				t: 'ontology/term_added',
+				id: String(args.id).trim(),
+				label: String(args.label).trim(),
+				gloss: String(args.gloss).trim(),
+				aliases: Array.isArray(args.aliases) ? args.aliases.map((alias) => String(alias)) : [],
+				parent: args.parent === undefined ? null : String(args.parent).trim(),
+				basis: String(args.basis).trim(),
+			})
+			const note = ensureDomainShelf(hostService, sessionId, mutations)
+			return done({
+				ok: true,
+				code: 'term_registered',
+				message: `概念 ${String(args.id).trim()} 已登记。它现在是本体图上的一个节点:新断言可以引用它。${note}`,
+			})
+		},
+	})
+
+	defineTool({
+		name: 'RegisterPredicate',
+		description:
+			'登记一个领域谓词(本体图上的边)。值域二选一:`range={form:"quantity"|"statement"|"formula"|"code"|"reference",unit?}` 说宾语是一个**字面值**,或 `range={term:"<概念 id>"}` 说宾语是**另一个概念的实例**。`domain` 可选(主词域,声明了它,断言的主体就必须写明类型)。`functional=true` 表示单值:同一主体出现两个不同取值时,投影会给出一对**冲突**(只暴露,不裁决)。',
+		parameters: {
+			type: 'object',
+			properties: {
+				id: { type: 'string', description: '小写字母开头的 slug' },
+				label: { type: 'string', description: '给人看的名字' },
+				gloss: { type: 'string', description: '一句话释义(可选)' },
+				domain: { type: 'string', description: '主词域:概念 id(可选)' },
+				range: {
+					type: 'object',
+					description: '值域:{form,unit?} 或 {term}',
+					properties: {
+						form: { type: 'string', enum: ['statement', 'quantity', 'formula', 'code', 'reference'] },
+						unit: { type: 'string' },
+						term: { type: 'string' },
+					},
+					additionalProperties: false,
+				},
+				functional: { type: 'boolean', description: '是否单值(默认否)' },
+				basis: { type: 'string', description: '依据(必填)' },
+			},
+			required: ['id', 'label', 'range', 'basis'],
+			additionalProperties: false,
+		},
+		output: CARD_OUTPUT,
+		async execute(args, exec) {
+			const call = open(exec)
+			if (call.ok !== true) return call.response
+			const { hostService, sessionId, mutations } = call
+			const done = finish(hostService, sessionId, mutations)
+			const judge = domainJudge(hostService)
+			if (judge === null) return fail('domain_unavailable', '这一层的宿主没有提供领域判据(domain facade):无法校验词汇。请检查宿主半与预设是否同版本。')
+			const problems = judge.validatePredicate(sessionId, args)
+			if (problems.length > 0) return fail('predicate_rejected', `这个谓词不能登记:\n${problems.map((item) => `- ${item}`).join('\n')}`)
+			mutations.push({
+				t: 'ontology/predicate_added',
+				id: String(args.id).trim(),
+				label: String(args.label).trim(),
+				gloss: args.gloss === undefined ? '' : String(args.gloss).trim(),
+				domain: args.domain === undefined ? null : String(args.domain).trim(),
+				range: args.range,
+				functional: args.functional === true,
+				basis: String(args.basis).trim(),
+			})
+			const note = ensureDomainShelf(hostService, sessionId, mutations)
+			return done({
+				ok: true,
+				code: 'predicate_registered',
+				message: `谓词 ${String(args.id).trim()} 已登记(${args.range?.term ? `宾语是概念 ${args.range.term} 的实例` : `宾语取 ${args.range?.form} 形态`}${args.functional === true ? ' · 单值' : ''})。下一步:在 SetGoal 的假设里带上断言,引用它。${note}`,
+			})
+		},
+	})
+
+	defineTool({
+		name: 'ReviseTerm',
+		description:
+			'修订一个概念的**展示信息**(名字 / 释义 / 别名):版本 +1,旧值留在账上,id 不变。**语义变化不许走这条路**——含义、父概念变了就废止旧条目、注册新条目;稳定 id 的含义在历史上悄悄改变,等于拿今天的释义重写所有旧事实。',
+		parameters: {
+			type: 'object',
+			properties: {
+				id: { type: 'string' },
+				label: { type: 'string', description: '新名字(可选)' },
+				gloss: { type: 'string', description: '新释义(可选)' },
+				aliases: { type: 'array', items: { type: 'string' } },
+				reason: { type: 'string', description: '为什么改(必填)' },
+			},
+			required: ['id', 'reason'],
+			additionalProperties: false,
+		},
+		output: CARD_OUTPUT,
+		async execute(args, exec) {
+			const call = open(exec)
+			if (call.ok !== true) return call.response
+			const { hostService, sessionId, state, mutations } = call
+			const done = finish(hostService, sessionId, mutations)
+			const entry = findLexiconEntry(state, args.id)
+			if (entry === null || entry.kind !== 'term') return fail('unknown_term', `词汇里没有这个概念:${String(args.id)}`)
+			if (entry.entry.status === 'deprecated') return fail('term_deprecated', `概念 ${String(args.id)} 已废止,不能修订(要恢复语义就注册新条目)。`)
+			if (typeof args.reason !== 'string' || args.reason.trim() === '') return fail('reason_required', '修订要写一句原因:改了什么、为什么改。')
+			if (args.label === undefined && args.gloss === undefined && args.aliases === undefined) return fail('nothing_to_revise', '没有要改的字段:label / gloss / aliases 至少给一个。')
+			mutations.push({ t: 'ontology/term_revised', id: String(args.id), label: args.label === undefined ? undefined : String(args.label).trim(), gloss: args.gloss === undefined ? undefined : String(args.gloss).trim(), aliases: Array.isArray(args.aliases) ? args.aliases.map((alias) => String(alias)) : undefined, reason: String(args.reason).trim() })
+			const note = ensureDomainShelf(hostService, sessionId, mutations)
+			return done({ ok: true, code: 'term_revised', message: `概念 ${String(args.id)} 已修订(旧值留在账上)。${note}` })
+		},
+	})
+
+	defineTool({
+		name: 'RevisePredicate',
+		description: '修订一个谓词的**展示信息**(名字 / 释义)。值域、主词域与单值性是语义——那三样变了要废止旧谓词、注册新的。',
+		parameters: {
+			type: 'object',
+			properties: { id: { type: 'string' }, label: { type: 'string' }, gloss: { type: 'string' }, reason: { type: 'string' } },
+			required: ['id', 'reason'],
+			additionalProperties: false,
+		},
+		output: CARD_OUTPUT,
+		async execute(args, exec) {
+			const call = open(exec)
+			if (call.ok !== true) return call.response
+			const { hostService, sessionId, state, mutations } = call
+			const done = finish(hostService, sessionId, mutations)
+			const entry = findLexiconEntry(state, args.id)
+			if (entry === null || entry.kind !== 'predicate') return fail('unknown_predicate', `词汇里没有这个谓词:${String(args.id)}`)
+			if (entry.entry.status === 'deprecated') return fail('predicate_deprecated', `谓词 ${String(args.id)} 已废止,不能修订。`)
+			if (typeof args.reason !== 'string' || args.reason.trim() === '') return fail('reason_required', '修订要写一句原因。')
+			mutations.push({ t: 'ontology/predicate_revised', id: String(args.id), label: args.label === undefined ? undefined : String(args.label).trim(), gloss: args.gloss === undefined ? undefined : String(args.gloss).trim(), reason: String(args.reason).trim() })
+			const note = ensureDomainShelf(hostService, sessionId, mutations)
+			return done({ ok: true, code: 'predicate_revised', message: `谓词 ${String(args.id)} 已修订(版本 +1,旧值留着)。${note}` })
+		},
+	})
+
+	/**
+	 * **废止是黏性终态**:没有复活这条路。存量事实照旧可读(历史留着),
+	 * 引用它的**新**断言会被拒,并在货架上标明「所用术语已废止」。
+	 */
+	defineTool({
+		name: 'DeprecateTerm',
+		description:
+			'废止一个概念(或谓词):缘由必填。**没有删除**——条目、旧版本与引用过它的事实全部留着;新断言不许再引用它,存量事实在货架上标明「所用术语已废止」。要恢复语义就注册一个新条目(那是覆盖,不是复活)。',
+		parameters: {
+			type: 'object',
+			properties: { id: { type: 'string', description: '概念或谓词的 id' }, reason: { type: 'string', description: '为什么废止(必填)' } },
+			required: ['id', 'reason'],
+			additionalProperties: false,
+		},
+		output: CARD_OUTPUT,
+		async execute(args, exec) {
+			const call = open(exec)
+			if (call.ok !== true) return call.response
+			const { hostService, sessionId, state, mutations } = call
+			const done = finish(hostService, sessionId, mutations)
+			const entry = findLexiconEntry(state, args.id)
+			if (entry === null) return fail('unknown_entry', `词汇里没有这个条目:${String(args.id)}`)
+			if (entry.entry.status === 'deprecated') return fail('already_deprecated', `${String(args.id)} 已经是废止状态(这一步不会重复记账)。`)
+			if (typeof args.reason !== 'string' || args.reason.trim() === '') return fail('reason_required', '废止要写缘由:为什么这个词不再用。')
+			mutations.push({ t: entry.kind === 'term' ? 'ontology/term_deprecated' : 'ontology/predicate_deprecated', id: String(args.id), reason: String(args.reason).trim() })
+			const note = ensureDomainShelf(hostService, sessionId, mutations)
+			return done({
+				ok: true,
+				code: 'entry_deprecated',
+				message: `${entry.kind === 'term' ? '概念' : '谓词'} ${String(args.id)} 已废止(记录保留,新断言不许再引用;引用过它的事实照旧可读)。${note}`,
+			})
+		},
+	})
+
+	defineTool({
+		name: 'DeprecatePredicate',
+		description: '废止一个谓词:缘由必填,记录保留,新断言不许再引用它(与 DeprecateTerm 同一条纪律,单列出来是为了让参数与语义各自说清)。',
+		parameters: {
+			type: 'object',
+			properties: { id: { type: 'string' }, reason: { type: 'string' } },
+			required: ['id', 'reason'],
+			additionalProperties: false,
+		},
+		output: CARD_OUTPUT,
+		async execute(args, exec) {
+			const call = open(exec)
+			if (call.ok !== true) return call.response
+			const { hostService, sessionId, state, mutations } = call
+			const done = finish(hostService, sessionId, mutations)
+			const entry = findLexiconEntry(state, args.id)
+			if (entry === null || entry.kind !== 'predicate') return fail('unknown_predicate', `词汇里没有这个谓词:${String(args.id)}`)
+			if (entry.entry.status === 'deprecated') return fail('already_deprecated', `${String(args.id)} 已经是废止状态。`)
+			if (typeof args.reason !== 'string' || args.reason.trim() === '') return fail('reason_required', '废止要写缘由。')
+			mutations.push({ t: 'ontology/predicate_deprecated', id: String(args.id), reason: String(args.reason).trim() })
+			const note = ensureDomainShelf(hostService, sessionId, mutations)
+			return done({ ok: true, code: 'entry_deprecated', message: `谓词 ${String(args.id)} 已废止(记录保留,新断言不许再引用)。${note}` })
+		},
+	})
+
+	/**
+	 * **螺旋上半圈的入口**:按概念 / 谓词 / 主体取「已知」。
+	 * 读数全部来自投影(事实与流转中的假设),不新建任何存储;它也不改任何东西。
+	 */
+	defineTool({
+		name: 'QueryKnowledge',
+		description:
+			'按概念 / 谓词 / 主体查「已知」:返回带类型化断言的**已升格事实**与**还在流转的命题**。要复用前面的结论就用它,而不是把事实库重读一遍。只读:它不改任何东西。',
+		parameters: {
+			type: 'object',
+			properties: {
+				term: { type: 'string', description: '概念 id:匹配断言的主体类型 / 宾语概念 / 词条本身' },
+				predicate: { type: 'string', description: '谓词 id' },
+				subject: { type: 'string', description: '主体名称(实例)' },
+			},
+			additionalProperties: false,
+		},
+		output: CARD_OUTPUT,
+		async execute(args, exec) {
+			const call = open(exec)
+			if (call.ok !== true) return call.response
+			const { hostService, sessionId, state, mutations } = call
+			const done = finish(hostService, sessionId, mutations)
+			const derived = hostService.derive(sessionId)
+			const filter = { term: args.term === undefined ? '' : String(args.term).trim(), predicate: args.predicate === undefined ? '' : String(args.predicate).trim(), subject: args.subject === undefined ? '' : String(args.subject).trim() }
+			if (filter.term === '' && filter.predicate === '' && filter.subject === '') return fail('query_empty', '至少给一个条件:term / predicate / subject。')
+			const match = (assertion) => {
+				const subject = assertion?.subject ?? {}
+				const object = assertion?.object ?? {}
+				if (filter.predicate !== '' && String(assertion?.predicate ?? '') !== filter.predicate) return false
+				if (filter.subject !== '' && String(subject.id ?? '') !== filter.subject) return false
+				if (filter.term !== '') {
+					const hits = [String(subject.type ?? ''), String(subject.id ?? ''), String(object.kind) === 'instance' ? String(object.type ?? '') : '', String(object.kind) === 'instance' ? String(object.value ?? '') : '', String(assertion?.predicate ?? '')]
+					if (!hits.includes(filter.term)) return false
+				}
+				return true
+			}
+			const facts = derived.factRows.filter((fact) => (Array.isArray(fact.assertions) ? fact.assertions : []).some(match))
+			const inFlight = derived.hypotheses.filter((hypothesis) => (Array.isArray(hypothesis.assertions) ? hypothesis.assertions : []).some(match))
+			if (facts.length === 0 && inFlight.length === 0) {
+				return done({ ok: true, code: 'knowledge_empty', message: `这个词汇条件下还没有任何东西:${describeFilter(filter)}。要么先登记/验证,要么换个条件——**不要**把「查不到」写成「不存在」。` })
+			}
+			const lines = []
+			if (facts.length > 0) {
+				lines.push(`已知(已升格,可作为已知引用):${facts.length} 条`)
+				for (const fact of facts.slice(0, 12)) {
+					lines.push(`- ${fact.id} · ${clip(String(fact.text ?? ''), 120)}(支持到 ${fact.level ?? '—'}${fact.review?.decision === 'retracted' ? ' · **已撤回**' : fact.refuted === true ? ' · 有推翻证据等人决定' : ''})`)
+					lines.push(`  边界:${clip(String(fact.scope ?? '(未写)'), 120)}`)
+					for (const assertion of fact.assertions ?? []) if (match(assertion)) lines.push(`  断言:${hostService.domain.format(sessionId, assertion)}`)
+				}
+				if (facts.length > 12) lines.push(`  (还有 ${facts.length - 12} 条,见 clear/knowledge/facts/INDEX.md)`)
+			}
+			if (inFlight.length > 0) {
+				lines.push(`还在流转的命题(未升格):${inFlight.length} 条`)
+				for (const hypothesis of inFlight.slice(0, 8)) {
+					lines.push(`- ${hypothesis.id} [${hypothesis.status}] ${clip(String(hypothesis.claim ?? ''), 100)}${hypothesis.supportedLevel === null ? '' : `(支持到 ${hypothesis.supportedLevel})`}`)
+					for (const assertion of hypothesis.assertions ?? []) if (match(assertion)) lines.push(`  断言:${hostService.domain.format(sessionId, assertion)}`)
+				}
+			}
+			return done({ ok: true, code: 'knowledge_found', message: `${describeFilter(filter)}\n${lines.join('\n')}` })
+		},
+	})
+
 	defineTool({
 		name: 'CreatePlan',
 		description:
@@ -3661,18 +4110,23 @@ export function apply(ctx, config = {}) {
 	 *
 	 * 失败如实告警并返回空串:账本没记上就说没记上,不假装记过。
 	 */
-	function snapshotWorkspace(sessionId, cwd, state, mutations, turn) {
+	function snapshotWorkspace(sessionId, cwd, state, mutations, turn, phase = 'mid') {
 		const calls = Number(state?.writeCalls ?? 0)
 		if (calls <= 0 || lastWorkspaceSnapshot.get(sessionId) === calls) return ''
 		lastWorkspaceSnapshot.set(sessionId, calls)
-		const committed = commitLedger(cwd, `clearai: 探索期快照 — 第 ${turn} 回合中尚未交付的写入`)
+		/**
+		 * 措辞分流:pre-step 是**回合中途**的恢复点,turn-stopping 是**回合结束时**那一笔
+		 * ——后者才是"跑动在这里停下,工作区长这样",也是唯一在一次性形态里会落地的那笔。
+		 */
+		const when = phase === 'end' ? `第 ${turn} 回合结束时尚未交付的写入` : `第 ${turn} 回合中尚未交付的写入`
+		const committed = commitLedger(cwd, `clearai: 探索期快照 — ${when}`)
 		if (committed.ok !== true) {
 			ctx.logger?.warn?.(`clearai: 工作区快照失败 ${String(committed.reason ?? '').slice(0, 160)}`)
 			return ''
 		}
 		if (committed.skipped === true) return ''
 		// 落一条**台账事实**:系统对工作区做过什么,日志里要说得出来(与交付那笔同一条纪律)。
-		mutations.push({ t: 'git/snapshot', commit: committed.commit, reason: '探索期快照(尚未交付的写入)', turn })
+		mutations.push({ t: 'git/snapshot', commit: committed.commit, reason: phase === 'end' ? '探索期快照(回合结束时尚未交付的写入)' : '探索期快照(尚未交付的写入)', turn })
 		const short = committed.commit === null ? '' : `(${String(committed.commit).slice(0, 7)})`
 		return `\n(工作区已记入账本${short}:探索期的产出从此可查、可恢复——不需要你为它声明什么。)`
 	}
@@ -3977,7 +4431,7 @@ export function apply(ctx, config = {}) {
 		}
 	}
 
-	function validateForkOptions(options, decideBy) {
+	function validateForkOptions(options, decideBy, cwd) {
 		if (!Array.isArray(options) || options.length < 2 || options.length > 4) return 'fork_needs_2to4_options:世界线要 2–4 条(分叉是「选一」,不是清单)'
 		if (decideBy === null || decideBy === undefined || typeof decideBy !== 'object') return 'decide_by_required:分叉必须登记一把尺子 {metric, direction}——没有判定契约就不能收敛'
 		if (typeof decideBy.metric !== 'string' || decideBy.metric.trim() === '') return 'decide_by_metric_required:尺子要有指标名(如 yield_pct)'
@@ -3994,7 +4448,26 @@ export function apply(ctx, config = {}) {
 		 */
 		const scale = decideBy.metric.split(/[=＝]/).slice(1).join('=').trim()
 		if (!/[=＝]/.test(decideBy.metric) || scale.length < 4) {
-			return 'decide_by_scale_required:尺子要写成「量 = 口径」(口径 = 这个数怎么算出来、单位是什么),例:字节数 = 生成文件的字节数。只有指标名不是尺子:口径不能留给每条世界线各自去定,否则两条线各写一套公式,比出来的大小不作数'
+			return 'decide_by_scale_required:尺子要写成「量 = 口径」——口径必须是**工作区里真有的一个文件**(脚本或规格),例:读数 = lab/measure.py 的输出。只有指标名不是尺子:口径留给每条世界线各自去定,两条线各写一套公式,比出来的大小不作数'
+		}
+		/**
+		 * **口径必须是可指认的引用,不是散文**。
+		 *
+		 * 「评分 = 按本路线情况评分」同样能通过格式检查,却什么也没保证。一条引用
+		 * (工作区里的路径)则不同:路径相等是机器可核的,文件内容在账本里有版本——
+		 * 「同一把尺子」从一句声明变成一个可指认的对象。至于两条世界线**有没有真的
+		 * 用它**去量,那是评估者重跑的事,字符串检查到这里就到头了,不冒充能验。
+		 */
+		const pathTokens = scale.match(/[^\s,;(){}"']+\/+[^\s,;(){}"']*/g) ?? []
+		const resolvable = pathTokens.filter((token) => {
+			try {
+				return existsSync(isAbsolute(token) ? token : resolvePath(cwd, token))
+			} catch {
+				return false
+			}
+		})
+		if (pathTokens.length === 0 || resolvable.length === 0) {
+			return `decide_by_scale_not_reference:口径里必须引用**工作区里真有的一个文件**(现在写的是「${scale.slice(0, 60)}」)。先在工作区写好测量脚本或口径说明,再用它登记尺子——散文口径两条世界线各读各的,比出来的大小不作数`
 		}
 		if (decideBy.direction !== 'max' && decideBy.direction !== 'min') return 'decide_by_direction_required:尺子要说明方向:max(越大越好)或 min(越小越好)'
 		/** 量那一半:判据里要点名它。 */
@@ -4252,7 +4725,7 @@ export function apply(ctx, config = {}) {
 	defineTool({
 		name: 'ForkPlan',
 		description:
-			'分叉:把一个步骤分成 2–4 条互斥的世界线,每条自己做一份工作副本、自己交付。**必须先登记一把尺子**(decide_by{metric,direction}),而 metric 要写成**「量 = 口径」**(口径 = 这个数怎么算出来、单位是什么),并且这句话要**逐字**出现在每条世界线的判据里——把同一台测量仪装到每条世界线上。口径不能留给各条世界线自己定:两条线上各写一套公式,比出来的大小不作数。收敛由算术决定,不由谁说得响。分叉是「选一」,不是并行加速。',
+			'分叉:把一个步骤分成 2–4 条互斥的世界线,每条自己做一份工作副本、自己交付。**必须先登记一把尺子**(decide_by{metric,direction}),而 metric 要写成**「量 = 口径」**,口径必须是**工作区里真有的一个文件**(测量脚本或口径说明),例:读数 = lab/measure.py 的输出;先写好那个文件再开分叉。量那一半要**逐字**出现在每条世界线的判据里。散文口径两条世界线各读各的,比出来的大小不作数。收敛由算术决定,不由谁说得响。分叉是「选一」,不是并行加速。',
 		parameters: {
 			type: 'object',
 			properties: {
@@ -4297,7 +4770,7 @@ export function apply(ctx, config = {}) {
 			if (step === null) return fail('no_open_step', '这份计划没有未落定的步了。')
 			if (typeof args.question !== 'string' || args.question.trim() === '') return fail('question_required', '分叉要说清要裁决的分歧是什么。')
 			if (forkOfStep(hostService.derive(sessionId).forks, step.id) !== null) return fail('fork_depth_exceeded', `步骤 ${step.id} 已经长过一个分叉了:一步只分叉一次。`)
-			const problem = validateForkOptions(args.options, args.decide_by)
+			const problem = validateForkOptions(args.options, args.decide_by, cwd)
 			if (problem !== null) return fail(problem.split(':')[0], problem)
 			const forkId = uniqueId('k')
 			const options = args.options.map((option) => ({
@@ -5645,7 +6118,12 @@ export function apply(ctx, config = {}) {
 
 	function protectedRoots(sessionId) {
 		const cwd = sessionCwd(sessionId)
-		return [join(cwd, 'clear', 'evidence'), join(cwd, 'clear', 'knowledge', 'facts'), join(cwd, 'clear', 'goals')]
+		/**
+		 * 系统所有的四格:`evidence` / `facts` / `goals`,加上 `ontology`(词汇货架)。
+		 * 为什么词汇也在此列:货架是**渲染**,词条的权威在账本事件里——
+		 * 谁直接改那份 markdown,谁就制造了一份谁也不认的词汇表(面板读的是折法)。
+		 */
+		return [join(cwd, 'clear', 'evidence'), join(cwd, 'clear', 'knowledge', 'facts'), join(cwd, 'clear', 'goals'), join(cwd, 'clear', 'ontology')]
 	}
 
 	function touchesProtected(sessionId, value) {
@@ -5782,7 +6260,7 @@ export function apply(ctx, config = {}) {
 				// 「评估卡与事实只能由系统写」:做的人写不进证据面(执行者同样适用)
 				const suspect = touchesProtected(sessionId, args.file_path) ?? touchesProtected(sessionId, args.path) ?? (exec.name === 'bash' ? touchesProtected(sessionId, args.command) : null)
 				if (suspect !== null) {
-					return { kind: 'deny', reason: `clear/evidence、clear/knowledge/facts、clear/goals 由系统所有,做的人不能写:${suspect}。事实与评估卡只能由系统落盘。` }
+					return { kind: 'deny', reason: `clear/evidence、clear/knowledge/facts、clear/goals、clear/ontology 由系统所有,做的人不能写:${suspect}。事实、评估卡与词汇货架只能由系统落盘(词汇要改就调注册/修订/废止动词)。` }
 				}
 				// L4 人放行:ClearAI 的设计目标未实现,这里用宿主的审批瀑布实现。
 				// 门挂在**等级**上:主线看步骤等级,世界线看分支等级——两条路同一道门。
@@ -5853,6 +6331,62 @@ export function apply(ctx, config = {}) {
 	}
 
 	// 会话一被创建/接入就把工作区铺好(见 ensureWorkspace:要抢在原生目录快照之前)。
+	/**
+	 * **子 run 落定由宿主告诉我们**(`subagent/end`),不再只靠"轮询子会话日志"。
+	 *
+	 * 载荷 `{runId, provider, id, local, stopReason, lastAssistantMessage?}` 由持有 `run.result`
+	 * 的那个 service 在**同一个 promise 落定的那一刻**发出(成功与失败都发)——与我们本来
+	 * 就信任的那次 `run.result` 是同一个触发点,所以权威性相同,而好处是:handle 已经不在
+	 * (重启、换档、早退)时结算也不会丢,失败一路也不用再靠日志里的停止原因去猜。
+	 *
+	 * 认出 id 才吃:只认我们自己派出去的那几个(别人的子 run 不是我们的事实)。
+	 */
+	ctx.on('subagent/end', (info) => {
+		try {
+			const childId = String(info?.id ?? '')
+			if (childId === '') return
+			const settled = settleSubRun({ output: Array.isArray(info.lastAssistantMessage) ? info.lastAssistantMessage : [], stopReason: String(info.stopReason ?? 'completed') })
+			for (const table of [executorRuns, scoutRuns]) {
+				const entry = table.get(childId)
+				// 已经落定的不覆盖:先到的那一条为准(事件与 promise 是同一个触发点)。
+				if (entry !== undefined && (entry.settled === null || entry.settled === undefined)) entry.settled = settled
+			}
+		} catch (error) {
+			ctx.logger?.warn?.(`clearai: 子 run 结算事件处理失败 ${String(error?.message ?? error).slice(0, 160)}`)
+		}
+	})
+
+
+	/**
+	 * **回合收尾**:宿主在回合将停、且队列里没有下一步时**串行 await** 这一拍。
+	 *
+	 * 这里只做一件真正属于我们的事:把这一回合的写入记进账本(**回合边界**的那一笔,
+	 * 一次性形态里唯一会落地的那笔)。**不判在飞、不写裁决、不叫醒任何人**:
+	 * 「还在不在跑」的权威是宿主的子任务目录,「结果收没收回」是收集通道的事——
+	 * 收尾那一拍各有一句要说的话,但都不该由这里替它们说。
+	 */
+	function snapshotAtTurnEnd(payload) {
+		try {
+			const hostService = host()
+			if (hostService === undefined) return
+			const sessionId = String(payload?.agent?.id ?? '')
+			if (sessionId === '') return
+			const turn = typeof payload?.turn === 'number' ? payload.turn : null
+			// mutations 进空数组:这一拍没有工具结果可以携带变更,账本提交本身就是记录。
+			snapshotWorkspace(sessionId, sessionCwd(sessionId), hostService.state(sessionId), [], turn, 'end')
+		} catch (error) {
+			ctx.logger?.warn?.(`clearai: 回合收尾失败 ${String(error?.message ?? error).slice(0, 160)}`)
+		}
+	}
+
+	ctx.on('agent/turn-stopping', snapshotAtTurnEnd)
+
+	/**
+	 * **回合以错误结束也要记一笔工作区**:那一拍的写入不能因为出错就丢。
+	 * 宿主在出错那一档**不派** `agent/turn-stopping`(它 throw 出去了),所以这里也挂一份。
+	 */
+	ctx.on('agent/error', snapshotAtTurnEnd)
+
 	ctx.on('agent/created', (payload) => {
 		const agent = payload?.agent
 		const id = agent?.id ?? agent?.session?.id
@@ -5899,6 +6433,14 @@ export function apply(ctx, config = {}) {
 			ontologyShelved.add(sessionId)
 			if (shelf !== null) ontologyNote = `\n- 本体已就位(${CONTRIB.ontology.objects.length} 个对象 · ${CONTRIB.ontology.levels.length} 级):${join('clear', 'ontology', `${CONTRIB.ontology.id}.md`)}——交付前对照它(哪些状态合法、每一级谁来判)。`
 		}
+		/**
+		 * **领域词汇货架**每一拍都重铺一次(幂等:内容没变就不重写)。
+		 *
+		 * 为什么不像过程本体那样只铺一次:那一份随**发布版本**,这一份随**会话**——
+		 * 一个项目今天没用词汇、明天开始用,货架必须自己长出来,而不是等人记得去建。
+		 * 它也不进卡:货架的位置在提示词里说一次就够,每拍重复就是往上下文里灌水。
+		 */
+		ensureDomainShelf(host(), sessionId)
 		let brainNote = ''
 		/** 事实货架那句话说一次就够(事实很少变)。 */
 		let factsNote = ''
@@ -5986,14 +6528,14 @@ export function apply(ctx, config = {}) {
 		 */
 		let auditsResolved = false
 		try {
-			const audits = await sweepLostAudits(sessionId, hostService.state(sessionId))
+			const audits = await sweepEndedAudits(sessionId, hostService.state(sessionId))
 			if (audits.mutations.length > 0) {
 				factMutations.push(...audits.mutations)
 				auditsResolved = true
-				brainNote = `${brainNote}\n(有 ${audits.lost} 条独立裁决**失联**(子会话已不在跑):已如实记为 unknown——不必再等它,重新交付这一步就会派一个新的评估者。)`
+				brainNote = `${brainNote}\n(有 ${audits.settled} 条此前在等的独立裁决已收口:结论从子会话日志取回,或如实记为 unknown。)`
 			}
 		} catch (error) {
-			ctx.logger?.warn?.(`clearai: 失联裁决盘点失败 ${String(error?.message ?? error).slice(0, 160)}`)
+			ctx.logger?.warn?.(`clearai: 已结束裁决盘点失败 ${String(error?.message ?? error).slice(0, 160)}`)
 		}
 		/**
 		 * **失联的侦察**:同一拍、同一套判据(原生子代理目录 + 本进程攥着的派遣)。
@@ -6005,7 +6547,7 @@ export function apply(ctx, config = {}) {
 			const scouts = await sweepLostScouts(sessionId, hostService.state(sessionId), settledInBatch)
 			if (scouts.mutations.length > 0) {
 				factMutations.push(...scouts.mutations)
-				brainNote = `${brainNote}\n(有 ${scouts.lost} 条侦察**失联**(子会话已不在跑):已如实记下「结论收不回来」——不必再等它,需要那份材料就重新派一次。)`
+				brainNote = `${brainNote}\n(有 ${scouts.lost} 条侦察已结束但结论未能取回:已如实记下。)`
 			}
 		} catch (error) {
 			ctx.logger?.warn?.(`clearai: 失联侦察盘点失败 ${String(error?.message ?? error).slice(0, 160)}`)