@lmzhen/dsh-evolution-review 0.3.66 → 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

@@ -93,6 +93,16 @@ 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" && session.header.origin !== "subagent") turnStarts.set(session.id, session.seq - 1);
 		if (event.type !== "turn/end") return;
@@ -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,6 +176,18 @@ 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)}`);
 				}
@@ -169,21 +199,37 @@ function apply(ctx, rawConfig = {}) {
 							kind: pendingKind,
 							toolCalls: signal.toolCalls,
 							userChars: signal.userChars,
-							assistantChars: signal.assistantChars
+							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);
@@ -207,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) {
@@ -220,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)}`);
@@ -273,7 +336,12 @@ function apply(ctx, rawConfig = {}) {
 		if (reviewInFlight) {
 			if (deferredFallbackReviews.length < DEFERRED_REVIEW_CAP) deferredFallbackReviews.push({
 				agent,
-				kind
+				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";
@@ -379,10 +447,26 @@ function apply(ctx, rawConfig = {}) {
 		} finally {
 			reviewInFlight = false;
 			const deferred = deferredFallbackReviews.splice(0);
-			for (const { agent: waitingAgent, kind: waitingKind } of deferred) try {
-				deliverMessage(waitingAgent, reviewPrompt(waitingKind), "auto-review");
-			} catch (injectError) {
-				ctx.logger.warn(`dsh-evolution-review: deferred review inject failed: ${injectError instanceof Error ? injectError.message : String(injectError)}`);
+			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)}`);
+				}
 			}
 		}
 	}
@@ -559,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.66",
+  "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.66",
-    "@lmzhen/dsh-evolution-core": "^0.3.66",
-    "@lmzhen/dsh-evolution-plan-validator": "^0.3.66"
+    "@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.66",
-    "@lmzhen/dsh-evolution-policy": "^0.3.66"
+    "@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.66",
-    "@lmzhen/dsh-evolution-core": "^0.3.66",
-    "@lmzhen/dsh-evolution-plan-validator": "^0.3.66",
-    "@lmzhen/dsh-evolution-state": "^0.3.66"
+    "@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"
   }
 }