@lmzhen/dsh-evolution-review 0.3.65 → 0.3.67

package/README.md

@@ -25,7 +25,7 @@ Independent of request-prefix construction. This package does not alter the asse
 - Review subagents run as `spawn` children on the deployment default preset rather than inheriting the parent agent's composition (`fork`): a fork child is always promoted by the Anchored Standard bootstrap and its narrowed resident catalog would drop the plain `skill` tool from the review allow-list.
 - The review request text is redacted for credential-shaped patterns before it reaches the subagent, but redaction is pattern-based and best-effort, not a security boundary.
 - Read-before-write tracks only reads through the `skill` tool. `skill_manage` has no per-skill read action (`list`/`review` are whole-library, not targeted at one name), so a skill that was only listed via `skill_manage` is not marked as read — a background review may still reject a patch to it until it is actually loaded.
-- The completion-channel counters (`cumulativeToolCalls` / `completionInjected`) are in-memory only. A process restart resets them, which is accepted behavior: the completion review is a one-per-session post-task adaptation and a restart is treated as a fresh conversation boundary. The cadence state (`turnsSinceMemory` / `turnsSinceSkill`) is persisted via `ReviewState` and survives restart.
+- The completion-channel counters (`cumulativeToolCalls` / `completionInjected`) are in-memory only. A process restart resets them, which is accepted behavior: the completion review is a one-per-session post-task adaptation and a restart is treated as a fresh conversation boundary. The cadence state (`turnsSinceMemory` / `turnsSinceSkill`) is persisted via `ReviewState` and survives restart — bounded by `REVIEW_STATE_SESSION_CAP` (500, seam constant): the least-recently-active sessions are pruned on save, so a very old session restarting resumes from a fresh cadence baseline rather than an unbounded store.
 - `evolution/review-scheduled` and `evolution/review-error` are emitted for platform/user wiring only — this family has no in-repo production `ctx.on` consumer for them. They are declared externally owned (the platform side wires consumption), which matches the `EXEMPT_ORPHANS` set in `scripts/verify-event-pairing.mjs`.
 - When the `evolution-state` service is not mounted, the memory/skill cadence state is not persisted and every turn restarts from a clean `{ turnsSinceMemory: 0, turnsSinceSkill: 0 }` baseline — the review schedule is stateless and re-decided each turn rather than accumulating across the conversation. The loss is surfaced once per process as a logger warning at the first turn/end.
 - Read-before-write can see the review subagent's own `skill` reads only when the subagent backend exposes `localAgent` (the in-process driver does; out-of-process backends such as ACP and the CLI providers set `localAgent: undefined`). With a remote backend the subagent's reads are invisible, so a plan item patching a skill the subagent itself loaded is dropped as "unread" — the review then falls back to the parent session's reads only. Documented rather than worked around: recovering the child read set needs a `SubagentLike` contract change (v14 P2-6).

package/lib/index.js

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import z from "@deepseek-ai/schemastery";
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
-import { COMPLETION_SKILL_REVIEW_PROMPT, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, 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_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_USER_CHAR_LIMIT, PROMPT_BUNDLE, SkillLibrary, advanceReview, clampedNumber, evolutionIoAdapter, foldTurn, redactSecrets, resolveOrigins, resolveRootConfig, resolveSkillsRoot, reviewPrompt, verifyPromptBundle } from "@lmzhen/dsh-evolution-core";
+import { COMPLETION_SKILL_REVIEW_PROMPT, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, 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_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_USER_CHAR_LIMIT, PROMPT_BUNDLE, SkillLibrary, advanceReview, clampedNumber, contentHash, evolutionIoAdapter, foldTurn, redactSecrets, resolveOrigins, resolveRootConfig, resolveSkillsRoot, reviewPrompt, verifyPromptBundle } from "@lmzhen/dsh-evolution-core";
 import { validateEvolutionPlan } from "@lmzhen/dsh-evolution-plan-validator";
 //#region lib/types/index.js
 /**
@@ -93,8 +93,18 @@ function apply(ctx, rawConfig = {}) {
 	const cadenceResetWarned = /* @__PURE__ */ new Set();
 	let reviewInFlight = false;
 	const policy = () => ctx.get("evolutionPolicy")?.get();
+	const reviewStateLocks = /* @__PURE__ */ new Map();
+	async function withReviewStateLock(id, task) {
+		const next = (reviewStateLocks.get(id) ?? Promise.resolve()).catch(() => {}).then(task);
+		reviewStateLocks.set(id, next);
+		try {
+			return await next;
+		} finally {
+			if (reviewStateLocks.get(id) === next) reviewStateLocks.delete(id);
+		}
+	}
 	ctx.on("session/event", (session, event) => {
-		if (event.type === "turn/start") turnStarts.set(session.id, session.seq - 1);
+		if (event.type === "turn/start" && session.header.origin !== "subagent") turnStarts.set(session.id, session.seq - 1);
 		if (event.type !== "turn/end") return;
 		if (turnStarts.size >= COUNTER_SWEEP_THRESHOLD || cumulativeToolCalls.size >= COUNTER_SWEEP_THRESHOLD || completionInjected.size >= COUNTER_SWEEP_THRESHOLD || pendingCadenceReviews.size >= COUNTER_SWEEP_THRESHOLD || skipNextCadenceFire.size >= COUNTER_SWEEP_THRESHOLD || cadenceResetWarned.size >= COUNTER_SWEEP_THRESHOLD) {
 			const isAlive = (id) => ctx.agents.get(id) !== void 0;
@@ -132,24 +142,32 @@ function apply(ctx, rawConfig = {}) {
 			statelessReviewStateWarned = true;
 			ctx.logger.warn("dsh-evolution-review: evolution-state service not mounted — memory/skill review cadence is not persisted and resets every turn (see README Known Limitations).");
 		}
-		const state = await stateService?.loadReviewState(session.id) ?? {
+		const snapshot = policy();
+		const skipFire = skipNextCadenceFire.get(session.id) ?? false;
+		if (skipFire) skipNextCadenceFire.delete(session.id);
+		let state = {
 			turnsSinceMemory: 0,
 			turnsSinceSkill: 0,
 			lastTurn: -1
 		};
-		const snapshot = policy();
-		const skipFire = skipNextCadenceFire.get(session.id) ?? false;
-		if (skipFire) skipNextCadenceFire.delete(session.id);
-		const rawKind = advanceReview(state, event.data.turn, signal, {
-			memoryInterval: snapshot?.reviewMemoryInterval ?? config.memoryInterval,
-			skillInterval: snapshot?.reviewSkillInterval ?? config.skillInterval,
-			substantiveMinToolCalls: snapshot?.substantiveMinToolCalls ?? 3,
-			substantiveMinUserChars: snapshot?.substantiveMinUserChars ?? 200,
-			substantiveMinAgentChars: snapshot?.substantiveMinAgentChars ?? 500,
-			resetOnFire: false
+		const advanced = { kind: null };
+		await withReviewStateLock(session.id, async () => {
+			state = await stateService?.loadReviewState(session.id) ?? {
+				turnsSinceMemory: 0,
+				turnsSinceSkill: 0,
+				lastTurn: -1
+			};
+			advanced.kind = advanceReview(state, event.data.turn, signal, {
+				memoryInterval: snapshot?.reviewMemoryInterval ?? config.memoryInterval,
+				skillInterval: snapshot?.reviewSkillInterval ?? config.skillInterval,
+				substantiveMinToolCalls: snapshot?.substantiveMinToolCalls ?? 3,
+				substantiveMinUserChars: snapshot?.substantiveMinUserChars ?? 200,
+				substantiveMinAgentChars: snapshot?.substantiveMinAgentChars ?? 500,
+				resetOnFire: false
+			});
+			await stateService?.saveReviewState(session.id, state);
 		});
-		const kind = skipFire ? null : rawKind;
-		await stateService?.saveReviewState(session.id, state);
+		const kind = skipFire ? null : advanced.kind;
 		const cumulative = (cumulativeToolCalls.get(session.id) ?? 0) + signal.toolCalls;
 		cumulativeToolCalls.set(session.id, cumulative);
 		if (event.data.reason.kind === "completed") {
@@ -158,29 +176,60 @@ function apply(ctx, rawConfig = {}) {
 				pendingCadenceReviews.delete(session.id);
 				if ((policy()?.reviewMode ?? config.reviewMode) === "inject") try {
 					deliverMessage(agent, reviewPrompt(pendingKind), "auto-review");
+					try {
+						ctx.emit("evolution/review-scheduled", {
+							sessionId: session.id,
+							kind: pendingKind,
+							toolCalls: signal.toolCalls,
+							userChars: signal.userChars,
+							assistantChars: signal.assistantChars,
+							channel: "inject"
+						});
+					} catch (emitError) {
+						ctx.logger.warn(`dsh-evolution-review: review-scheduled emit failed: ${emitError instanceof Error ? emitError.message : String(emitError)}`);
+					}
 				} catch (injectError) {
 					ctx.logger.warn(`dsh-evolution-review: deferred review inject failed: ${injectError instanceof Error ? injectError.message : String(injectError)}`);
 				}
-				else if (await trySubagentReview(session, agent, pendingKind, signal)) try {
-					ctx.emit("evolution/review-scheduled", {
-						sessionId: session.id,
-						kind: pendingKind,
-						toolCalls: signal.toolCalls,
-						userChars: signal.userChars,
-						assistantChars: signal.assistantChars
-					});
-				} catch (emitError) {
-					ctx.logger.warn(`dsh-evolution-review: review-scheduled emit failed: ${emitError instanceof Error ? emitError.message : String(emitError)}`);
-				}
-				else try {
-					deliverMessage(agent, reviewPrompt(pendingKind), "auto-review");
-				} catch (injectError) {
-					ctx.logger.warn(`dsh-evolution-review: deferred review inject failed: ${injectError instanceof Error ? injectError.message : String(injectError)}`);
+				else {
+					const reviewOutcome = await trySubagentReview(session, agent, pendingKind, signal);
+					if (reviewOutcome === true) try {
+						ctx.emit("evolution/review-scheduled", {
+							sessionId: session.id,
+							kind: pendingKind,
+							toolCalls: signal.toolCalls,
+							userChars: signal.userChars,
+							assistantChars: signal.assistantChars,
+							channel: "subagent"
+						});
+					} catch (emitError) {
+						ctx.logger.warn(`dsh-evolution-review: review-scheduled emit failed: ${emitError instanceof Error ? emitError.message : String(emitError)}`);
+					}
+					else if (reviewOutcome !== "deferred") try {
+						deliverMessage(agent, reviewPrompt(pendingKind), "auto-review");
+						try {
+							ctx.emit("evolution/review-scheduled", {
+								sessionId: session.id,
+								kind: pendingKind,
+								toolCalls: signal.toolCalls,
+								userChars: signal.userChars,
+								assistantChars: signal.assistantChars,
+								channel: "inject"
+							});
+						} catch (emitError) {
+							ctx.logger.warn(`dsh-evolution-review: review-scheduled emit failed: ${emitError instanceof Error ? emitError.message : String(emitError)}`);
+						}
+					} catch (injectError) {
+						ctx.logger.warn(`dsh-evolution-review: deferred review inject failed: ${injectError instanceof Error ? injectError.message : String(injectError)}`);
+					}
 				}
-				state.turnsSinceMemory = 0;
-				state.turnsSinceSkill = 0;
 				try {
-					await stateService?.saveReviewState(session.id, state);
+					await withReviewStateLock(session.id, async () => {
+						const fresh = await stateService?.loadReviewState(session.id) ?? state;
+						fresh.turnsSinceMemory = 0;
+						fresh.turnsSinceSkill = 0;
+						await stateService?.saveReviewState(session.id, fresh);
+					});
 				} catch (resetError) {
 					if (!cadenceResetWarned.has(session.id)) {
 						cadenceResetWarned.add(session.id);
@@ -204,6 +253,22 @@ function apply(ctx, rawConfig = {}) {
 		if (completionInjected.has(session.id)) return;
 		if (!shouldCompletionReview(event.data.reason, cumulative, config.skillReviewCompletionMinToolCalls)) return;
 		completionInjected.add(session.id);
+		if (reviewInFlight) {
+			if (deferredFallbackReviews.length < DEFERRED_REVIEW_CAP) deferredFallbackReviews.push({
+				agent,
+				sessionId: session.id,
+				kind: "skill",
+				prompt: COMPLETION_SKILL_REVIEW_PROMPT,
+				label: "completion review",
+				channel: "completion",
+				counts: signal
+			});
+			else {
+				completionInjected.delete(session.id);
+				ctx.logger.warn(`dsh-evolution-review: deferred-review queue at cap (${DEFERRED_REVIEW_CAP}) — dropped one deferred completion review prompt; the completion gate re-arms for the next completed turn`);
+			}
+			return;
+		}
 		try {
 			deliverMessage(agent, COMPLETION_SKILL_REVIEW_PROMPT, "completion review");
 		} catch (injectError) {
@@ -217,7 +282,8 @@ function apply(ctx, rawConfig = {}) {
 				kind: "skill",
 				toolCalls: signal.toolCalls,
 				userChars: signal.userChars,
-				assistantChars: signal.assistantChars
+				assistantChars: signal.assistantChars,
+				channel: "completion"
 			});
 		} catch (emitError) {
 			ctx.logger.warn(`dsh-evolution-review: review-scheduled emit failed: ${emitError instanceof Error ? emitError.message : String(emitError)}`);
@@ -246,11 +312,40 @@ function apply(ctx, rawConfig = {}) {
 			skipNextCadenceFire.set(agent.session.id, true);
 		} else agent.inject(message);
 	};
+	const withTimeout = (promise, ms, label) => new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			reject(/* @__PURE__ */ new Error(`dsh-evolution-review: ${label} timed out after ${ms}ms`));
+		}, ms);
+		promise.then((value) => {
+			clearTimeout(timer);
+			resolve(value);
+		}, (error) => {
+			clearTimeout(timer);
+			reject(error instanceof Error ? error : new Error(String(error)));
+		});
+	});
+	const deferredFallbackReviews = [];
+	const DEFERRED_REVIEW_CAP = 16;
+	ctx.effect(() => () => {
+		deferredFallbackReviews.length = 0;
+	}, "dsh-evolution-review.deferred-drain");
 	async function trySubagentReview(session, agent, kind, signal) {
 		if ((policy()?.reviewMode ?? config.reviewMode) === "inject") return false;
 		const subagents = ctx.get("subagents");
 		if (!subagents) return false;
-		if (reviewInFlight) return false;
+		if (reviewInFlight) {
+			if (deferredFallbackReviews.length < DEFERRED_REVIEW_CAP) deferredFallbackReviews.push({
+				agent,
+				sessionId: session.id,
+				kind,
+				prompt: reviewPrompt(kind),
+				label: "auto-review",
+				channel: "inject",
+				counts: signal
+			});
+			else ctx.logger.warn(`dsh-evolution-review: deferred-review queue at cap (${DEFERRED_REVIEW_CAP}) — dropping one fallback review prompt`);
+			return "deferred";
+		}
 		reviewInFlight = true;
 		try {
 			const snapshot = policy();
@@ -296,7 +391,7 @@ function apply(ctx, rawConfig = {}) {
 				});
 				const acceptedSkillOps = validation.accepted.skillOps ?? [];
 				const skippedUnread = filterUnreadSkillOps(acceptedSkillOps, new Set([...collectReadSkillNames(session), ...childReads]));
-				const executed = await executePlan(validation.accepted, session);
+				const executed = await withTimeout(executePlan(validation.accepted, session), config.reviewTimeoutMs, "review plan execution");
 				const actions = executed.actions;
 				const evidenceQuotes = [...validation.accepted.memoryOps ?? [], ...acceptedSkillOps].reduce((total, op) => total + (Array.isArray(op.evidence) ? op.evidence.length : 0), 0);
 				if (actions.length > 0) {
@@ -347,15 +442,43 @@ function apply(ctx, rawConfig = {}) {
 			}
 		} catch (error) {
 			ctx.logger.warn(`dsh-evolution-review: subagent review failed: ${error instanceof Error ? error.message : String(error)}`);
+			if (error instanceof Error && error.message.includes("plan execution timed out")) ctx.logger.warn("dsh-evolution-review: plan execution abandoned on timeout — any late write it lands has NO plan-applied record and races the fallback inject; inspect the skill tree and usage sidecar");
 			return false;
 		} finally {
 			reviewInFlight = false;
+			const deferred = deferredFallbackReviews.splice(0);
+			for (const { agent: waitingAgent, sessionId: entrySession, kind: waitingKind, prompt, label, channel, counts: entryCounts } of deferred) {
+				try {
+					deliverMessage(waitingAgent, prompt, label);
+				} catch (injectError) {
+					if (channel === "completion") completionInjected.delete(entrySession);
+					ctx.logger.warn(`dsh-evolution-review: deferred review inject failed: ${injectError instanceof Error ? injectError.message : String(injectError)}`);
+					continue;
+				}
+				try {
+					ctx.emit("evolution/review-scheduled", {
+						sessionId: entrySession,
+						kind: waitingKind,
+						toolCalls: entryCounts.toolCalls,
+						userChars: entryCounts.userChars,
+						assistantChars: entryCounts.assistantChars,
+						channel
+					});
+				} catch (emitError) {
+					ctx.logger.warn(`dsh-evolution-review: review-scheduled emit failed: ${emitError instanceof Error ? emitError.message : String(emitError)}`);
+				}
+			}
 		}
 	}
 	async function executePlan(plan, session) {
 		const sessionId = session?.id;
 		const memory = ctx.get("memory");
 		const approval = ctx.get("evolutionApproval");
+		const hashLibrary = (() => {
+			const io = ctx.get("evolutionIo");
+			if (!io) return null;
+			return new SkillLibrary(resolveSkillsRoot({ root: rootConfig.root }), evolutionIoAdapter(() => io.provider()));
+		})();
 		const origins = resolveOrigins(void 0, true);
 		const actions = [];
 		const failedOps = [];
@@ -390,6 +513,10 @@ function apply(ctx, rawConfig = {}) {
 					...op,
 					evidence: op.evidence
 				};
+				if ((args.action === "update" || args.action === "edit") && hashLibrary && typeof args.name === "string" && args.name !== "") {
+					const stageCurrent = await hashLibrary.read(args.name).catch(() => null);
+					if (stageCurrent !== null) args.staged_from_sha256 = contentHash(stageCurrent);
+				}
 				const runnerArgs = {
 					operation: args,
 					origin: origins.library
@@ -516,6 +643,7 @@ function apply(ctx, rawConfig = {}) {
 		pendingCadenceWarned.clear();
 		skipNextCadenceFire.clear();
 		cadenceResetWarned.clear();
+		reviewStateLocks.clear();
 	}, "dsh-evolution-review.cleanup");
 }
 /** Completion-channel decision: task finished normally AND the session is proven long. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-review",
   "description": "Background review orchestration (community build)",
-  "version": "0.3.65",
+  "version": "0.3.67",
   "publishConfig": {
     "access": "public"
   },
@@ -31,9 +31,9 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-approval": "^0.3.65",
-    "@lmzhen/dsh-evolution-core": "^0.3.65",
-    "@lmzhen/dsh-evolution-plan-validator": "^0.3.65"
+    "@lmzhen/dsh-evolution-approval": "^0.3.67",
+    "@lmzhen/dsh-evolution-core": "^0.3.67",
+    "@lmzhen/dsh-evolution-plan-validator": "^0.3.67"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
@@ -42,8 +42,8 @@
     "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
     "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
     "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
-    "@lmzhen/dsh-evolution-state": "^0.3.65",
-    "@lmzhen/dsh-evolution-policy": "^0.3.65"
+    "@lmzhen/dsh-evolution-state": "^0.3.67",
+    "@lmzhen/dsh-evolution-policy": "^0.3.67"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-agent": "^0.1.1-rc.2",
@@ -54,9 +54,9 @@
     "@deepseek-ai/dsh-session-persistence": "^0.1.1-rc.2",
     "@deepseek-ai/dsh-session-persistence-jsonl": "^0.1.1-rc.2",
     "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
-    "@lmzhen/dsh-evolution-approval": "^0.3.65",
-    "@lmzhen/dsh-evolution-core": "^0.3.65",
-    "@lmzhen/dsh-evolution-plan-validator": "^0.3.65",
-    "@lmzhen/dsh-evolution-state": "^0.3.65"
+    "@lmzhen/dsh-evolution-approval": "^0.3.67",
+    "@lmzhen/dsh-evolution-core": "^0.3.67",
+    "@lmzhen/dsh-evolution-plan-validator": "^0.3.67",
+    "@lmzhen/dsh-evolution-state": "^0.3.67"
   }
 }