@lmzhen/dsh-evolution-review 0.16.0 → 0.17.0-rc.1

package/lib/index.js

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import z from "@deepseek-ai/schemastery";
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
 import { SessionId } from "@deepseek-ai/dsh-session";
-import { COMPLETION_SKILL_REVIEW_PROMPT, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MEMORY_REVIEW_MODEL, DEFAULT_REVIEW_CONTEXT_MESSAGES, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_MESSAGE_CHARS, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_REVIEW_TIMEOUT_MS, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_MODEL, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_USER_CHAR_LIMIT, MAX_TIMER_DELAY_MS, PROMPT_BUNDLE, advanceReview, assertSkillsRootAliasRetired, clampedNumber, clearReviewChannel, collectReadSkillNames, contentHash, evidenceKindIndex, evolutionIoAdapter, filterUnreadSkillOps, filterUnreadSkillOps as filterUnreadSkillOps$1, foldTurn, installParamSection, markReviewChannel, newSkillLibrary, paramNamespace, policyStageLimits, readDispatchSignal, readNumberParam, redactSecrets, resolveOrigins, resolveRootConfig, reviewPrompt, sessionAudited, sweepReviewChannelSessions, verifyPromptBundle } from "@lmzhen/dsh-evolution-core";
+import { COMPLETION_SKILL_REVIEW_PROMPT, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MEMORY_REVIEW_MODEL, DEFAULT_REVIEW_CONTEXT_MESSAGES, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_MESSAGE_CHARS, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_REVIEW_TIMEOUT_MS, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_MODEL, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_USER_CHAR_LIMIT, MAX_TIMER_DELAY_MS, PROMPT_BUNDLE, advanceReview, assertSkillsRootAliasRetired, clampedNumber, clearReviewChannel, contentHash, evolutionIoAdapter, filterUnreadSkillOps, filterUnreadSkillOps as filterUnreadSkillOps$1, markReviewChannel, newSkillLibrary, paramRowId, policyStageLimits, readDispatchSignal, redactSecrets, resolveOrigins, resolveRootConfig, reviewPrompt, sessionAudited, sessionEvidenceIndex, sessionReadNames, sessionTurnSignals, sweepReviewChannelSessions, verifyPromptBundle } from "@lmzhen/dsh-evolution-core";
 import { validateEvolutionPlan } from "@lmzhen/dsh-evolution-plan-validator";
 /**
 * Whether a message is a notice this plugin delivered, judged only by durable source fields.
@@ -14,7 +14,8 @@ import { validateEvolutionPlan } from "@lmzhen/dsh-evolution-plan-validator";
 */
 function isReviewNotice(message) {
 	const source = message.source;
-	return source?.kind === "plugin" && source.plugin === "dsh-evolution-review" && source.form === "notice";
+	if (source?.form !== "notice") return false;
+	return source.kind === "evolution-review" || source.kind === "plugin:dsh-evolution-review";
 }
 /**
 * Fold one inbox event into the session's outstanding notice.
@@ -127,8 +128,10 @@ const REVIEW_SETTLE_TIMEOUT = "ReviewSettleTimeout";
 const name = "evolution-review";
 const inject = ["agents"];
 const Config = z.object({
-	reviewEnabled: z.boolean().default(true),
-	reviewMode: z.union([z.const("subagent"), z.const("inject")]).default("inject"),
+	reviewEnabled: z.boolean().default(true).volatile(),
+	reviewMode: z.union([z.const("subagent"), z.const("inject")]).default("inject").volatile(),
+	reviewMemoryInterval: z.number().min(1).volatile(),
+	reviewSkillInterval: z.number().min(1).volatile(),
 	memoryInterval: z.number().min(1).default(DEFAULT_REVIEW_MEMORY_INTERVAL),
 	skillInterval: z.number().min(1).default(DEFAULT_REVIEW_SKILL_INTERVAL),
 	reviewToolAllow: z.array(z.string()).default(["skill"]),
@@ -141,10 +144,10 @@ const Config = z.object({
 		z.const("cadence"),
 		z.const("completion"),
 		z.const("both")
-	]).default(DEFAULT_SKILL_REVIEW_TRIGGER),
-	reviewWakeInject: z.boolean().default(true),
+	]).default(DEFAULT_SKILL_REVIEW_TRIGGER).volatile(),
+	reviewWakeInject: z.boolean().default(true).volatile(),
 	sessionScoped: z.boolean().default(false),
-	skillReviewCompletionMinToolCalls: z.number().min(1).default(DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS),
+	skillReviewCompletionMinToolCalls: z.number().min(1).default(DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS).volatile(),
 	root: z.string().default(""),
 	skillsRoot: z.string().default("")
 });
@@ -172,53 +175,97 @@ const REVIEW_OUTPUT_SCHEMA = {
 * kind: memory / skill / combined), both in the queue and in the session log.
 */
 const cadenceSummary = (kind) => `auto-review:${kind}`;
+/**
+* G3.1 (0.3.23): clamp one numeric review knob so a 0/negative/NaN/±Infinity value
+* falls back to the package default instead of folding as a "disabled" special value
+* (a 0 interval would fire a review every turn; NaN folds as NaN into the
+* cadence/timeout). The schema `.min(1)` guards the loader path; this clamp also
+* covers NaN/±Infinity (which schemastery lets a bare number schema through) and
+* programmatic assembly. `reviewMaxDepth` clamps to at least 1 because 0 is the
+* historical 0.3.1 maximum-depth defect (a 0 rejects the spawn outright). The warning
+* fires once per key: a live field is read at every use, so an assembly-time list
+* would repeat on each read.
+* @param warned - the keys this caller already warned about.
+* @param warn - the warning sink.
+* @param name - the config key, for the warning.
+* @param value - the value as supplied, or its volatile reference.
+* @param fallback - the package default a corrected value falls back to.
+* @param min - the smallest value the engine can act on.
+* @param max - the largest value the carrier can hold, when bounded.
+* @returns the value the engine may use.
+*/
+function clampField(warned, warn, name, value, fallback, min, max) {
+	const current = typeof value === "object" ? value.get() : value;
+	const result = clampedNumber(current, fallback, max === void 0 ? { min } : {
+		min,
+		max
+	});
+	if (current !== void 0 && result !== current && !warned.has(name)) {
+		warned.add(name);
+		warn(`${name} provided an invalid value; falling back to the default`);
+	}
+	return result;
+}
+/**
+* The DEPLOYMENT layer of this row, clamped once at assembly: the restart-only
+* numerics (registry tier E2) whose consumers read them from this snapshot. The
+* seven E3 keys are NOT resolved here — they are live (G1 §8.3), and
+* {@link resolveReviewRowSettings} reads them at every use.
+* @param rawConfig - the row config as the platform resolved it.
+* @param ctx - the plugin context, for the clamp warning.
+* @returns the deployment layer with its numerics clamped.
+*/
 function clampReviewConfig(rawConfig, ctx) {
-	const clamped = [];
-	const field = (name, value, fallback, min, max) => {
-		const result = clampedNumber(value, fallback, max === void 0 ? { min } : {
-			min,
-			max
-		});
-		if (value !== void 0 && result !== value) clamped.push(name);
-		return result;
+	const warned = /* @__PURE__ */ new Set();
+	const warn = (message) => {
+		ctx.logger.warn("dsh-evolution-review: " + message);
 	};
-	const config = Object.assign({}, rawConfig, {
-		memoryInterval: field("memoryInterval", readNumberParam(rawConfig, "reviewMemoryInterval"), DEFAULT_REVIEW_MEMORY_INTERVAL, 1),
-		skillInterval: field("skillInterval", readNumberParam(rawConfig, "reviewSkillInterval"), DEFAULT_REVIEW_SKILL_INTERVAL, 1),
+	const field = (name, value, fallback, min, max) => clampField(warned, warn, name, value, fallback, min, max);
+	return Object.assign({}, rawConfig, {
 		reviewTimeoutMs: field("reviewTimeoutMs", rawConfig.reviewTimeoutMs, DEFAULT_REVIEW_TIMEOUT_MS, 1, MAX_TIMER_DELAY_MS),
 		reviewContextMessages: field("reviewContextMessages", rawConfig.reviewContextMessages, DEFAULT_REVIEW_CONTEXT_MESSAGES, 1),
 		reviewMessageChars: field("reviewMessageChars", rawConfig.reviewMessageChars, DEFAULT_REVIEW_MESSAGE_CHARS, 1),
-		reviewMaxDepth: field("reviewMaxDepth", rawConfig.reviewMaxDepth, 1, 1),
-		skillReviewCompletionMinToolCalls: field("skillReviewCompletionMinToolCalls", rawConfig.skillReviewCompletionMinToolCalls, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, 1)
+		reviewMaxDepth: field("reviewMaxDepth", rawConfig.reviewMaxDepth, 1, 1)
 	});
-	if (clamped.length > 0) ctx.logger.warn(`dsh-evolution-review: ${clamped.join(", ")} provided an invalid value; falling back to the default`);
-	return config;
 }
 function policySnapshotOf(source) {
 	return source?.get?.();
 }
-/** Schema the platform validates the user layer against; defaults mirror the
-* core constants so an empty document resolves to today's behaviour. */
-const REVIEW_SETTINGS_SCHEMA = z.object({
-	reviewSkillInterval: z.number().min(1).default(DEFAULT_REVIEW_SKILL_INTERVAL),
-	reviewMemoryInterval: z.number().min(1).default(DEFAULT_REVIEW_MEMORY_INTERVAL),
-	skillReviewTrigger: z.union([
-		z.const("cadence"),
-		z.const("completion"),
-		z.const("both")
-	]).default(DEFAULT_SKILL_REVIEW_TRIGGER),
-	skillReviewCompletionMinToolCalls: z.number().min(1).default(DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS),
-	reviewEnabled: z.boolean().default(true),
-	reviewMode: z.union([z.const("subagent"), z.const("inject")]).default("inject"),
-	reviewWakeInject: z.boolean().default(true)
-});
+/**
+* This row's review knobs as they stand RIGHT NOW (G1 §8.3) — the base layer of the
+* precedence chain. The seven E3 keys are live: the platform hands each one a
+* reference it updates in place, so a committed settings edit needs neither a restart
+* nor a watcher. The deprecated cadence aliases stay the fallback spelling of the two
+* interval keys, and every numeric field is clamped (G3.1).
+* @param rawConfig - the row config as the platform resolved it.
+* @param warn - sink for the once-per-key clamp warning.
+* @returns the row layer of the review knobs.
+*/
+function resolveReviewRowSettings(rawConfig, warn) {
+	const warned = /* @__PURE__ */ new Set();
+	return {
+		reviewSkillInterval: clampField(warned, warn, "reviewSkillInterval", rawConfig.reviewSkillInterval?.get() ?? rawConfig.skillInterval, DEFAULT_REVIEW_SKILL_INTERVAL, 1),
+		reviewMemoryInterval: clampField(warned, warn, "reviewMemoryInterval", rawConfig.reviewMemoryInterval?.get() ?? rawConfig.memoryInterval, DEFAULT_REVIEW_MEMORY_INTERVAL, 1),
+		skillReviewTrigger: rawConfig.skillReviewTrigger?.get() ?? DEFAULT_SKILL_REVIEW_TRIGGER,
+		skillReviewCompletionMinToolCalls: clampField(warned, warn, "skillReviewCompletionMinToolCalls", rawConfig.skillReviewCompletionMinToolCalls, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, 1),
+		reviewEnabled: rawConfig.reviewEnabled?.get() ?? true,
+		reviewMode: rawConfig.reviewMode?.get() ?? "inject",
+		reviewWakeInject: rawConfig.reviewWakeInject?.get() ?? true
+	};
+}
 function apply(ctx, rawConfig = {}) {
+	ctx.inject(["settings"], (injected) => {
+		const settings = injected.settings;
+		if (typeof settings?.configure !== "function") return;
+		const disposer = settings.configure({ auto: false });
+		if (typeof disposer === "function") ctx.effect(() => disposer, "dsh-evolution-review: settings presentation");
+	});
 	if (!verifyPromptBundle(PROMPT_BUNDLE)) throw new Error("dsh-evolution prompt bundle integrity check failed; refusing to schedule review work");
 	const config = clampReviewConfig(rawConfig, ctx);
 	assertSkillsRootAliasRetired(rawConfig);
 	const rootConfig = resolveRootConfig(rawConfig);
 	const sessionState = new SessionScopedState();
-	const turnStarts = sessionState.add("turnStarts", /* @__PURE__ */ new Map());
+	const dispatchDigest = sessionState.add("dispatchDigest", /* @__PURE__ */ new Map());
 	let statelessReviewStateWarned = false;
 	let channelMarkSuppressedWarned = false;
 	let reviewNoticeOutstandingWarned = false;
@@ -230,42 +277,71 @@ function apply(ctx, rawConfig = {}) {
 	const cadenceResetWarned = sessionState.add("cadenceResetWarned", /* @__PURE__ */ new Set());
 	let reviewInFlight = false;
 	const policy = () => ctx.get("evolutionPolicy")?.get();
-	const settingsBase = {
-		reviewSkillInterval: config.skillInterval,
-		reviewMemoryInterval: config.memoryInterval,
-		skillReviewTrigger: config.skillReviewTrigger ?? DEFAULT_SKILL_REVIEW_TRIGGER,
-		skillReviewCompletionMinToolCalls: config.skillReviewCompletionMinToolCalls,
-		reviewEnabled: config.reviewEnabled ?? true,
-		reviewMode: config.reviewMode ?? "inject",
-		reviewWakeInject: config.reviewWakeInject ?? true
-	};
-	const overrides = installParamSection(ctx, paramNamespace("evolution-review"), REVIEW_SETTINGS_SCHEMA, settingsBase, { warn: (message) => {
+	/**
+	* This row's knobs as they stand right now (G1 §8.3): the live fields are resolved
+	* per call, so a committed edit needs neither a restart nor a watcher.
+	* @returns the row layer of the review settings.
+	*/
+	const rowSettings = () => resolveReviewRowSettings(rawConfig, (message) => {
 		ctx.logger.warn("dsh-evolution-review: " + message);
-	} });
+	});
+	/**
+	* The keys the user set in this row's namespace (G1 §8.4-A). This is the ONLY
+	* remaining read of the settings user layer, and it reads KEY NAMES, never values:
+	* the platform resolves the user layer into the row's live fields, so the value
+	* comes from `rowSettings()`.
+	* @returns the keys present in this row's user layer.
+	*/
+	const userSetKeys = () => {
+		const entry = ctx.get("settings")?.describe?.({ redactSecrets: false }).find((item) => item.ns === paramRowId("evolution-review"));
+		return new Set(Object.keys(entry?.user ?? {}));
+	};
 	const params = () => {
+		const row = rowSettings();
+		const userSet = userSetKeys();
 		const snapshot = policy();
+		const pick = (key) => {
+			if (userSet.has(key)) return row[key];
+			return snapshot?.[key] ?? row[key];
+		};
+		const mode = () => {
+			if (userSet.has("reviewMode")) return row.reviewMode;
+			return snapshot?.reviewMode ?? row.reviewMode;
+		};
 		return {
-			reviewSkillInterval: overrides.get("reviewSkillInterval") ?? snapshot?.reviewSkillInterval ?? config.skillInterval,
-			reviewMemoryInterval: overrides.get("reviewMemoryInterval") ?? snapshot?.reviewMemoryInterval ?? config.memoryInterval,
-			skillReviewTrigger: overrides.get("skillReviewTrigger") ?? config.skillReviewTrigger ?? DEFAULT_SKILL_REVIEW_TRIGGER,
-			skillReviewCompletionMinToolCalls: overrides.get("skillReviewCompletionMinToolCalls") ?? config.skillReviewCompletionMinToolCalls,
-			reviewEnabled: overrides.get("reviewEnabled") ?? config.reviewEnabled ?? true,
-			reviewMode: overrides.get("reviewMode") ?? snapshot?.reviewMode ?? config.reviewMode ?? "inject",
-			reviewWakeInject: overrides.get("reviewWakeInject") ?? config.reviewWakeInject ?? true
+			reviewSkillInterval: pick("reviewSkillInterval"),
+			reviewMemoryInterval: pick("reviewMemoryInterval"),
+			skillReviewTrigger: row.skillReviewTrigger,
+			skillReviewCompletionMinToolCalls: row.skillReviewCompletionMinToolCalls,
+			reviewEnabled: row.reviewEnabled,
+			reviewMode: mode(),
+			reviewWakeInject: row.reviewWakeInject
 		};
 	};
 	const schemaDefaults = Config["~standard"].validate({}).value;
+	/** The value the schema fills in when nobody sets the key — for a volatile field the
+	* reference is always present, so this is what "the row set nothing" resolves to. */
+	const SHADOW_DEFAULTS = {
+		reviewMode: "inject",
+		reviewMemoryInterval: DEFAULT_REVIEW_MEMORY_INTERVAL,
+		reviewSkillInterval: DEFAULT_REVIEW_SKILL_INTERVAL
+	};
+	const rowSupplied = (id, alias) => {
+		const canonical = rawConfig[id]?.get();
+		if (canonical !== void 0 && canonical !== SHADOW_DEFAULTS[id]) return true;
+		return alias !== void 0 && rawConfig[alias] !== void 0 && rawConfig[alias] !== schemaDefaults[alias];
+	};
 	const shadowedRowFields = [
-		"reviewMode",
-		"memoryInterval",
-		"skillInterval"
-	].filter((field) => rawConfig[field] !== void 0 && rawConfig[field] !== schemaDefaults[field]);
+		["reviewMode", void 0],
+		["reviewMemoryInterval", "memoryInterval"],
+		["reviewSkillInterval", "skillInterval"]
+	].filter(([id, alias]) => !userSetKeys().has(id) && rowSupplied(id, alias)).map(([id]) => id);
 	if (shadowedRowFields.length > 0) {
 		let shadowWarned = false;
 		const warnShadowed = () => {
 			if (shadowWarned) return;
 			shadowWarned = true;
-			ctx.logger.warn(`dsh-evolution-review: this row sets ${shadowedRowFields.join(", ")}, but the mounted evolution-policy service overrides all three — these row values have no effect. Set them on the evolution-policy row instead.`);
+			ctx.logger.warn(`dsh-evolution-review: this row sets ${shadowedRowFields.join(", ")}, but the mounted evolution-policy service overrides ${shadowedRowFields.length === 1 ? "it" : "them"} — these row values have no effect. Set them on the evolution-policy row instead.`);
 		};
 		if (policy() !== void 0) warnShadowed();
 		else ctx.inject(["evolutionPolicy"], () => {
@@ -285,16 +361,16 @@ function apply(ctx, rawConfig = {}) {
 	}
 	ctx.on("session/event", (session, event) => {
 		if (!sessionAudited(ctx, session.id, config.sessionScoped)) return;
-		if (event.type === "turn/start" && session.header.origin !== "subagent") turnStarts.set(session.id, session.seq - 1);
+		appendDispatchFrame(dispatchDigest, session.id, event);
 		if (event.type === "user/message") {
 			if ((event.data?.source)?.kind === "user") clearReviewChannel(session.id);
 			return;
 		}
 		if (event.type !== "turn/end") return;
-		if (turnStarts.size >= COUNTER_SWEEP_THRESHOLD || pendingCadenceWarned.size >= COUNTER_SWEEP_THRESHOLD || cumulativeToolCalls.size >= COUNTER_SWEEP_THRESHOLD || completionInjected.size >= COUNTER_SWEEP_THRESHOLD || pendingCadenceReviews.size >= COUNTER_SWEEP_THRESHOLD || cadenceResetWarned.size >= COUNTER_SWEEP_THRESHOLD || pendingReviewNotices.size >= COUNTER_SWEEP_THRESHOLD) {
+		if (cumulativeToolCalls.size >= COUNTER_SWEEP_THRESHOLD || dispatchDigest.size >= COUNTER_SWEEP_THRESHOLD || pendingCadenceWarned.size >= COUNTER_SWEEP_THRESHOLD || cumulativeToolCalls.size >= COUNTER_SWEEP_THRESHOLD || completionInjected.size >= COUNTER_SWEEP_THRESHOLD || pendingCadenceReviews.size >= COUNTER_SWEEP_THRESHOLD || cadenceResetWarned.size >= COUNTER_SWEEP_THRESHOLD || pendingReviewNotices.size >= COUNTER_SWEEP_THRESHOLD) {
 			const isAlive = (id) => ctx.agents.get(id) !== void 0;
-			sweepDeadSessionEntries(turnStarts, isAlive);
 			sweepDeadSessionEntries(cumulativeToolCalls, isAlive);
+			sweepDeadSessionEntries(dispatchDigest, isAlive);
 			sweepDeadSessionEntries(completionInjected, isAlive);
 			sweepDeadSessionEntries(pendingCadenceReviews, isAlive);
 			sweepDeadSessionEntries(pendingCadenceWarned, isAlive);
@@ -379,8 +455,11 @@ function apply(ctx, rawConfig = {}) {
 		if (session.header.origin === "subagent") return;
 		const agent = ctx.agents.get(session.id);
 		if (!agent) return;
-		const signal = foldTurn(session, turnStarts.get(session.id) ?? Math.max(0, session.seq - 1));
-		turnStarts.delete(session.id);
+		const signal = sessionTurnSignals(ctx, session);
+		if (signal === void 0) {
+			ctx.logger.warn("dsh-evolution-review: the session cannot be projected (no evolutionSignals state) — this turn is not counted");
+			return;
+		}
 		const stateService = ctx.get("evolutionState");
 		if (!stateService && !statelessReviewStateWarned) {
 			statelessReviewStateWarned = true;
@@ -614,8 +693,7 @@ function apply(ctx, rawConfig = {}) {
 				text
 			}],
 			source: {
-				kind: "plugin",
-				plugin: "dsh-evolution-review",
+				kind: "evolution-review",
 				form: "notice",
 				summary
 			}
@@ -720,7 +798,7 @@ function apply(ctx, rawConfig = {}) {
 		try {
 			const snapshot = policy();
 			const model = kind === "memory" ? snapshot?.memoryReviewModel ?? DEFAULT_MEMORY_REVIEW_MODEL : snapshot?.skillReviewModel ?? DEFAULT_SKILL_REVIEW_MODEL;
-			const reviewText = redactSecrets(buildReviewRequest(session, kind, signal, config.reviewContextMessages, config.reviewMessageChars));
+			const reviewText = redactSecrets(buildReviewRequest(session, kind, signal, config.reviewContextMessages, config.reviewMessageChars, dispatchDigest.get(session.id) ?? []));
 			const agentOptions = { model };
 			if (config.reviewProvider) agentOptions.provider = config.reviewProvider;
 			const registry = ctx.get("tools");
@@ -732,7 +810,7 @@ function apply(ctx, rawConfig = {}) {
 			}
 			const preRunHashes = await treeSkillHashes();
 			const sessionSeqAtPlanTime = session.seq - 1;
-			const substantiveEvidenceSeqs = evidenceKindIndex(session.snapshotEvents());
+			const substantiveEvidenceSeqs = sessionEvidenceIndex(ctx, session);
 			const run = await subagents.start("spawn", {
 				label: "dsh-evolution-review",
 				prompt: [{
@@ -760,7 +838,7 @@ function apply(ctx, rawConfig = {}) {
 					ctx.logger.warn(`dsh-evolution-review: review subagent returned no structured plan${stopDetail !== void 0 ? ` (stopReason=${stopDetail}${diagDetail !== void 0 ? `; diagnostic=${diagDetail}` : ""})` : ""}`);
 					return false;
 				}
-				const childReads = run.localAgent ? collectReadSkillNames(run.localAgent.session.snapshotEvents()) : /* @__PURE__ */ new Set();
+				const childReads = run.localAgent ? sessionReadNames(ctx, run.localAgent.session) ?? /* @__PURE__ */ new Set() : /* @__PURE__ */ new Set();
 				const plan = result.structured;
 				const policyFingerprint = fingerprintPolicy(snapshot);
 				const validation = validateEvolutionPlan(plan, {
@@ -774,7 +852,7 @@ function apply(ctx, rawConfig = {}) {
 				});
 				if (validation.reports.length > 0) ctx.logger.warn(`dsh-evolution-review: ${validation.reports.length} op(s) cite only bookkeeping frames as evidence: ${validation.reports.map((report) => report.reason).join("; ")}`);
 				const acceptedSkillOps = validation.accepted.skillOps ?? [];
-				const skippedUnread = filterUnreadSkillOps$1(acceptedSkillOps, new Set([...collectReadSkillNames(session.snapshotEvents()), ...childReads]));
+				const skippedUnread = filterUnreadSkillOps$1(acceptedSkillOps, new Set([...sessionReadNames(ctx, session) ?? /* @__PURE__ */ new Set(), ...childReads]));
 				const evidenceQuotes = [...validation.accepted.memoryOps ?? [], ...acceptedSkillOps].reduce((total, op) => total + (Array.isArray(op.evidence) ? op.evidence.length : 0), 0);
 				const emitApplied = (report) => {
 					try {
@@ -1159,8 +1237,36 @@ function staleRefusal(result, name, filePath) {
 /** Map/set size that triggers a dead-session counter sweep (bounded, not a hard cap). */
 const COUNTER_SWEEP_THRESHOLD = 128;
 /**
+* Dispatch frames kept per session for the review digest.
+*
+* The digest renders at most 12 tool lines and pairs a result with the call that opened it, so 128
+* frames (≈64 dispatches) is far more than the renderer can spend — and unlike the whole-log scan it
+* replaced, the memory this holds is bounded per session rather than proportional to the log.
+*/
+const DISPATCH_DIGEST_FRAMES = 128;
+/**
+* Keep one dispatch-relevant frame in a session's bounded digest.
+*
+* A frame is kept when the family's dispatch vocabulary recognizes it as opening a dispatch
+* (`readDispatchSignal`) or as answering one (`resultCallIdOf`) — the two shapes the digest renders.
+* Everything else (message frames, boundaries, chunks) is not evidence and is not copied.
+* @param digest - the per-session digest map.
+* @param id - the owning session.
+* @param event - the committed session event.
+*/
+function appendDispatchFrame(digest, id, event) {
+	if (readDispatchSignal(event) === null && resultCallIdOf(event) === null) return;
+	const frames = digest.get(id) ?? [];
+	frames.push({
+		type: event.type,
+		...event.data === void 0 ? {} : { data: event.data }
+	});
+	if (frames.length > DISPATCH_DIGEST_FRAMES) frames.splice(0, frames.length - DISPATCH_DIGEST_FRAMES);
+	digest.set(id, frames);
+}
+/**
 * Remove every entry whose session is no longer live (rc.42 audit P1-10):
-* `turnStarts` / `cumulativeToolCalls` / `completionInjected` are keyed by
+* `cumulativeToolCalls` / `completionInjected` / `pendingCadenceReviews` are keyed by
 * SessionId with no platform session-end hook to prune against, so they grew
 * unbounded over a long-lived host. Works for maps and sets; returns the
 * number of removed entries.
@@ -1267,7 +1373,7 @@ function textOfPersistedBlock(block) {
 	const candidate = block;
 	return candidate.type === "text" && typeof candidate.text === "string" ? candidate.text : "";
 }
-function buildReviewRequest(session, kind, signal, maxMessages, maxMessageChars) {
+function buildReviewRequest(session, kind, signal, maxMessages, maxMessageChars, dispatchTail = []) {
 	const messages = [];
 	const surface = session.deriveMessages();
 	for (const message of surface.slice(-maxMessages)) if (message.role === "user" || message.role === "assistant") {
@@ -1275,10 +1381,9 @@ function buildReviewRequest(session, kind, signal, maxMessages, maxMessageChars)
 		if (text) messages.push(`${message.role.toUpperCase()}: ${text.slice(0, maxMessageChars)}`);
 	}
 	const toolLines = [];
-	const events = session.snapshotEvents();
+	const events = dispatchTail;
 	const callIdentity = /* @__PURE__ */ new Map();
-	const identityWindowStart = Math.max(0, events.length - 2e3);
-	for (let index = events.length - 1; index >= identityWindowStart; index -= 1) {
+	for (let index = events.length - 1; index >= 0; index -= 1) {
 		const event = events[index];
 		const opened = readDispatchSignal(event);
 		if (opened === null || callIdentity.has(opened.callId)) continue;
@@ -1321,4 +1426,4 @@ function buildReviewRequest(session, kind, signal, maxMessages, maxMessageChars)
 	].join("\n");
 }
 //#endregion
-export { Config, REVIEW_OUTPUT_SCHEMA, REVIEW_SETTINGS_SCHEMA, apply, buildReviewRequest, clampReviewConfig, filterUnreadSkillOps, inject, name, renderToolResultLine, shouldCompletionReview, sweepDeadSessionEntries };
+export { Config, REVIEW_OUTPUT_SCHEMA, apply, buildReviewRequest, clampReviewConfig, filterUnreadSkillOps, inject, name, renderToolResultLine, resolveReviewRowSettings, shouldCompletionReview, sweepDeadSessionEntries };

package/lib/types/index.d.ts

@@ -2,15 +2,23 @@
  * Background review orchestration: signal gate → one-shot subagent → trusted plan execution.
  * @module @lmzhen/dsh-evolution-review
  */
-import type { Context } from '@deepseek-ai/cordis';
+import type { Context, Volatile } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
+import type { ContextFormed } from '@deepseek-ai/dsh-llm';
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        'evolution-review': {
+            kind: 'evolution-review';
+        } & ContextFormed;
+    }
+}
 import type { Session } from '@deepseek-ai/dsh-session';
 import { type ReviewKind } from '@lmzhen/dsh-evolution-core';
 export { filterUnreadSkillOps } from '@lmzhen/dsh-evolution-core';
 export declare const name = "evolution-review";
 export declare const inject: string[];
 export interface Config {
-    reviewEnabled?: boolean;
+    reviewEnabled?: Volatile<boolean>;
     /** How the flush delivers the review: `'inject'` (default since 0.3.74) hands
      * the review prompt to the PARENT agent — waking it through the same
      * followup-first channel — so the review runs on the parent's model against
@@ -23,16 +31,21 @@ export interface Config {
      * at full price. Deployments that prefer the clean-context split switch the
      * POLICY row (`evolution-policy`): the mounted policy snapshot shadows this
      * row's value, which the plugin reports once at load (v37 P2-24). */
-    reviewMode?: 'subagent' | 'inject';
-    /** Shadowed by the policy snapshot in every shipped composition — configure
-     * `reviewMemoryInterval` on the `evolution-policy` row instead (v37 P2-24).
-     * Deprecated alias (G0/S0.3): still readable, refused by writes; removed 0.7.0. */
-    /** Review cadence in TOOL CALLS (signals.ts: a turn advances by its tool-call count, minimum 1,
-     * or by 1 when the turn itself carried the memory signal). */
+    reviewMode?: Volatile<'subagent' | 'inject'>;
+    /** Review cadence in TOOL CALLS — the CANONICAL registry id (G1, signals.ts:
+     * a turn advances by its tool-call count, minimum 1, or by 1 when the turn
+     * itself carried the memory signal). Shadowed by the policy snapshot in every
+     * shipped composition — configure `reviewMemoryInterval` on the
+     * `evolution-policy` row instead (v37 P2-24). */
+    reviewMemoryInterval?: Volatile<number | undefined>;
+    /** Skill-channel review cadence — the CANONICAL registry id (G1); shadowed by
+     * the policy snapshot like the memory cadence. */
+    reviewSkillInterval?: Volatile<number | undefined>;
+    /** Deprecated alias of `reviewMemoryInterval` (G0/S0.3): still readable,
+     * refused by writes; removed 0.7.0. */
     memoryInterval?: number;
-    /** Shadowed by the policy snapshot in every shipped composition — configure
-     * `reviewSkillInterval` on the `evolution-policy` row instead. Deprecated
-     * alias (G0/S0.3): still readable, refused by writes; removed 0.7.0. */
+    /** Deprecated alias of `reviewSkillInterval` (G0/S0.3): still readable,
+     * refused by writes; removed 0.7.0. */
     skillInterval?: number;
     /**
      * Tools the one-shot review subagent may use. Only actually-existing tools
@@ -56,14 +69,14 @@ export interface Config {
      * 'completion' does NOT mean "cadence off", and 'both' is effectively
      * "completion on top of the always-on cadence". The mutually-exclusive
      * channel reading in earlier docs was wrong. */
-    skillReviewTrigger?: 'cadence' | 'completion' | 'both';
+    skillReviewTrigger?: Volatile<'cadence' | 'completion' | 'both'>;
     /** Cumulative session tool calls before a session counts as proven-long for the completion channel. */
-    skillReviewCompletionMinToolCalls?: number;
+    skillReviewCompletionMinToolCalls?: Volatile<number>;
     /** 0.3.40: deliver the deferred review with a WAKING inject for a summary the
      * model starts immediately (agent.followup — same send() queue, wakeup bit
      * differs). Default true; false degrades to the non-waking inject (the
      * summary then waits for the next driver wake). */
-    reviewWakeInject?: boolean;
+    reviewWakeInject?: Volatile<boolean>;
     /** V10-11 (P2-7): skill tree root for the review's direct skill writes.
      * Empty (the default) resolves through `resolveSkillsRoot` to the shared
      * default root — the historical behavior. A custom root keeps review-created
@@ -83,7 +96,45 @@ export interface Config {
      */
     sessionScoped?: boolean;
 }
-export declare const Config: z<Config>;
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    reviewEnabled: z<boolean, boolean, "volatile-defined">;
+    reviewMode: z<"subagent" | "inject", "subagent" | "inject", "volatile-defined">;
+    reviewMemoryInterval: z<number, number, "volatile">;
+    reviewSkillInterval: z<number, number, "volatile">;
+    memoryInterval: z<number, number, "defined">;
+    skillInterval: z<number, number, "defined">;
+    reviewToolAllow: z<string[], string[], "defined">;
+    reviewTimeoutMs: z<number, number, "defined">;
+    reviewContextMessages: z<number, number, "defined">;
+    reviewMessageChars: z<number, number, "defined">;
+    reviewMaxDepth: z<number, number, "defined">;
+    reviewProvider: z<string, string, "plain">;
+    skillReviewTrigger: z<"cadence" | "completion" | "both", "cadence" | "completion" | "both", "volatile-defined">;
+    reviewWakeInject: z<boolean, boolean, "volatile-defined">;
+    sessionScoped: z<boolean, boolean, "defined">;
+    skillReviewCompletionMinToolCalls: z<number, number, "volatile-defined">;
+    root: z<string, string, "defined">;
+    skillsRoot: z<string, string, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    reviewEnabled: z<boolean, boolean, "volatile-defined">;
+    reviewMode: z<"subagent" | "inject", "subagent" | "inject", "volatile-defined">;
+    reviewMemoryInterval: z<number, number, "volatile">;
+    reviewSkillInterval: z<number, number, "volatile">;
+    memoryInterval: z<number, number, "defined">;
+    skillInterval: z<number, number, "defined">;
+    reviewToolAllow: z<string[], string[], "defined">;
+    reviewTimeoutMs: z<number, number, "defined">;
+    reviewContextMessages: z<number, number, "defined">;
+    reviewMessageChars: z<number, number, "defined">;
+    reviewMaxDepth: z<number, number, "defined">;
+    reviewProvider: z<string, string, "plain">;
+    skillReviewTrigger: z<"cadence" | "completion" | "both", "cadence" | "completion" | "both", "volatile-defined">;
+    reviewWakeInject: z<boolean, boolean, "volatile-defined">;
+    sessionScoped: z<boolean, boolean, "defined">;
+    skillReviewCompletionMinToolCalls: z<number, number, "volatile-defined">;
+    root: z<string, string, "defined">;
+    skillsRoot: z<string, string, "defined">;
+}>>, "plain">;
 /** V8-01 (0.3.45): the review subagent's structured-output contract. The
  * `subagents.start` outputSchema is RAW JSON Schema validated by
  * assertObjectJsonSchema (upstream dsh-tools json-schema.ts — SCHEMA_TYPES
@@ -108,29 +159,26 @@ export declare const REVIEW_OUTPUT_SCHEMA: {
         };
     };
 };
-/**
- * G3.1 (0.3.23): clamp the numeric review config at assembly so a 0/negative/
- * NaN/±Infinity value falls back to the package default instead of folding as a
- * "disabled" special value (a 0 interval would fire a review every turn; NaN
- * folds as NaN into the cadence/timeout). The schema `.min(1)` guards the
- * loader path; this clamp also covers NaN/±Infinity (which schemastery lets a
- * bare number schema through) and direct construction. `reviewMaxDepth` clamps
- * to at least 1 because 0 is the historical 0.3.1 maximum-depth defect (a 0
- * rejects the spawn outright). Warn once when a user-supplied value had to be
- * corrected.
- */
-/** F5 (P2-16, v11): the clamp sets exactly these seven numeric fields — the
+/** F5 (P2-16, v11): the clamp sets exactly these four numeric fields — the
  * old `as Required<Config>` lied about `reviewToolAllow` etc. being populated
- * (`[...undefined]` TypeErrors under a direct `apply(ctx, {})`). */
+ * (`[...undefined]` TypeErrors under a direct `apply(ctx, {})`).
+ * G1: the seven E3 keys left this list — they are live and resolved at USE time by
+ * {@link resolveReviewRowSettings}, which clamps its own numerics. */
 type ClampedReviewConfig = Config & {
-    memoryInterval: number;
-    skillInterval: number;
     reviewTimeoutMs: number;
     reviewContextMessages: number;
     reviewMessageChars: number;
     reviewMaxDepth: number;
-    skillReviewCompletionMinToolCalls: number;
 };
+/**
+ * The DEPLOYMENT layer of this row, clamped once at assembly: the restart-only
+ * numerics (registry tier E2) whose consumers read them from this snapshot. The
+ * seven E3 keys are NOT resolved here — they are live (G1 §8.3), and
+ * {@link resolveReviewRowSettings} reads them at every use.
+ * @param rawConfig - the row config as the platform resolved it.
+ * @param ctx - the plugin context, for the clamp warning.
+ * @returns the deployment layer with its numerics clamped.
+ */
 export declare function clampReviewConfig(rawConfig: Config, ctx: Context): ClampedReviewConfig;
 /** Review behaviour a user may change (G3/S3.1). Field names are the CANONICAL
  * parameter ids from the registry, so the settings document, the params output,
@@ -153,17 +201,30 @@ export interface ReviewSettings {
     /** Deliver the deferred review as a waking follow-up message. */
     reviewWakeInject: boolean;
 }
-/** Schema the platform validates the user layer against; defaults mirror the
- * core constants so an empty document resolves to today's behaviour. */
-export declare const REVIEW_SETTINGS_SCHEMA: z<ReviewSettings>;
+/**
+ * This row's review knobs as they stand RIGHT NOW (G1 §8.3) — the base layer of the
+ * precedence chain. The seven E3 keys are live: the platform hands each one a
+ * reference it updates in place, so a committed settings edit needs neither a restart
+ * nor a watcher. The deprecated cadence aliases stay the fallback spelling of the two
+ * interval keys, and every numeric field is clamped (G3.1).
+ * @param rawConfig - the row config as the platform resolved it.
+ * @param warn - sink for the once-per-key clamp warning.
+ * @returns the row layer of the review knobs.
+ */
+export declare function resolveReviewRowSettings(rawConfig: Config, warn: (message: string) => void): ReviewSettings;
 export declare function apply(ctx: Context, rawConfig?: Config): void;
 /** Completion-channel decision: task finished normally AND the session is proven long. */
 export declare function shouldCompletionReview(reason: {
     kind?: string;
 } | undefined, sessionToolCalls: number, minToolCalls: number): boolean;
+/** One dispatch frame the review digest can render (a native call/result or a PTC sub-dispatch). */
+interface ReviewDispatchFrame {
+    readonly type: string;
+    readonly data?: unknown;
+}
 /**
  * Remove every entry whose session is no longer live (rc.42 audit P1-10):
- * `turnStarts` / `cumulativeToolCalls` / `completionInjected` are keyed by
+ * `cumulativeToolCalls` / `completionInjected` / `pendingCadenceReviews` are keyed by
  * SessionId with no platform session-end hook to prune against, so they grew
  * unbounded over a long-lived host. Works for maps and sets; returns the
  * number of removed entries.
@@ -196,5 +257,5 @@ export declare function buildReviewRequest(session: Session, kind: ReviewKind, s
     toolCalls: number;
     userChars: number;
     assistantChars: number;
-}, maxMessages: number, maxMessageChars: number): string;
+}, maxMessages: number, maxMessageChars: number, dispatchTail?: readonly ReviewDispatchFrame[]): string;
 //# sourceMappingURL=index.d.ts.map

package/lib/types/review-notice.d.ts

@@ -18,14 +18,24 @@
  * whole rule testable without a host.
  * @module @lmzhen/dsh-evolution-review/review-notice
  */
-/** The plugin id every notice of this plugin carries in its durable message source. */
-export declare const REVIEW_NOTICE_PLUGIN = "dsh-evolution-review";
+/** The producer-owned source kind every notice of this plugin carries (0.2.x: each
+ * producer declares its own kind; there is no shared catch-all `plugin` kind). */
+export declare const REVIEW_NOTICE_KIND = "evolution-review";
+/**
+ * The kind a notice persisted before the 0.2.x line reads back as.
+ *
+ * The platform's session-format v3→v4 migration rewrites the released shared
+ * `{ kind: 'plugin', plugin }` source into `plugin:<plugin>` for a producer its own tables do
+ * not know (session-format-v3-to-v4/src/sources.ts:59-65, :74-90), so the notices an
+ * upgraded session already carries must still be recognized — otherwise the window they
+ * belonged to would be delivered a second time.
+ */
+export declare const REVIEW_NOTICE_LEGACY_KIND = "plugin:dsh-evolution-review";
 /** The subset of a platform message this module reads. */
 export interface NoticeMessage {
     readonly id: string;
     readonly source?: {
         readonly kind?: string;
-        readonly plugin?: string;
         readonly form?: string;
     } | undefined;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-review",
   "description": "Background review orchestration (community build)",
-  "version": "0.16.0",
+  "version": "0.17.0-rc.1",
   "publishConfig": {
     "access": "public"
   },
@@ -27,31 +27,31 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-approval": "^0.16.0",
-    "@lmzhen/dsh-evolution-core": "^0.16.0",
-    "@lmzhen/dsh-evolution-plan-validator": "^0.16.0"
+    "@lmzhen/dsh-evolution-approval": "^0.17.0-rc.1",
+    "@lmzhen/dsh-evolution-core": "^0.17.0-rc.1",
+    "@lmzhen/dsh-evolution-plan-validator": "^0.17.0-rc.1"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-tools": "^0.1.5-rc.2",
-    "@lmzhen/dsh-evolution-state": "^0.16.0",
-    "@lmzhen/dsh-evolution-policy": "^0.16.0"
+    "@deepseek-ai/dsh-agent": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-session": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.2.0-rc.1",
+    "@lmzhen/dsh-evolution-state": "^0.17.0-rc.1",
+    "@lmzhen/dsh-evolution-policy": "^0.17.0-rc.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-tools": "^0.1.5-rc.2",
-    "@lmzhen/dsh-evolution-approval": "^0.16.0",
-    "@lmzhen/dsh-evolution-core": "^0.16.0",
-    "@lmzhen/dsh-evolution-curator": "^0.16.0",
-    "@lmzhen/dsh-evolution-plan-validator": "^0.16.0",
-    "@lmzhen/dsh-evolution-state": "^0.16.0"
+    "@deepseek-ai/dsh-agent": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-agent-loop-testkit": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-session": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.2.0-rc.1",
+    "@lmzhen/dsh-evolution-approval": "^0.17.0-rc.1",
+    "@lmzhen/dsh-evolution-core": "^0.17.0-rc.1",
+    "@lmzhen/dsh-evolution-curator": "^0.17.0-rc.1",
+    "@lmzhen/dsh-evolution-plan-validator": "^0.17.0-rc.1",
+    "@lmzhen/dsh-evolution-state": "^0.17.0-rc.1"
   }
 }