@lmzhen/dsh-evolution-review 0.3.82 → 0.3.83

package/README.md

@@ -1,4 +1,4 @@
-# @deepseek-ai/dsh-evolution-review
+# @lmzhen/dsh-evolution-review
 
 Background review orchestration
 
@@ -8,7 +8,7 @@ Background review orchestration
 
 #### What the model sees
 
-`@deepseek-ai/dsh-evolution-review` registers no direct prompt or tool schema itself. Model-visible effects are owned by the packages that consume this service.
+`@lmzhen/dsh-evolution-review` registers no direct prompt or tool schema itself. Model-visible effects are owned by the packages that consume this service.
 
 #### Token effect
 
@@ -43,7 +43,7 @@ Independent of request-prefix construction. This package does not alter the asse
 
 - **Both channels execute at conversation end only** (a `turn/end` with `reason.kind === 'completed'`): a cadence threshold fire mid-task merely latches the kind — no subagent spawn, no inject. The flush runs BEFORE the latch block (the completing turn may itself be a threshold-firing turn). `reviewMode` selects how the flush delivers: **`'inject'` is the default since 0.3.74**, `'subagent'` is an explicit opt-in. Rationale: the parent session already holds a warm prefix cache, so an injected prompt costs the new tokens only, while a spawned child re-prefills its own system prompt plus a redacted, re-serialized conversation digest (`buildReviewRequest`) under a **different model** (`skillReviewModel`/`memoryReviewModel`) — no prefix is shared with the parent, so the whole child input is paid at full price. `'subagent'` remains the choice for deployments that want the parent context kept clean (a review's skill reads and plan do not join the parent thread) or a dedicated review model; the subagent-only knobs (`reviewProvider`, `reviewTimeoutMs`, `reviewMaxDepth`, `reviewToolAllow`, the review models) are inert in inject mode. The explicit `'inject'` mode's historical "immediate on threshold" contract was superseded in 0.3.39 — both modes are end-of-conversation.
 - **`skillReviewTrigger`** (default `'cadence'`): the cadence channel is **always on** (one end-of-conversation review from the cadence latch per task segment); the flag gates **only the completion channel** — `'cadence'` disables it, `'completion'` enables it (cadence still fires), `'both'` enables it on top of the always-on cadence. At one boundary a turn is served by exactly one review: the cadence flush runs first and returns, so `'both'` never double-sends a second task-complete prompt at the same boundary (V10-13).
-- **`reviewWakeInject`** (default `true`): deliveries use `agent.followup` (next-turn + wake — the model starts processing immediately) instead of the non-waking `agent.inject` (which waits for the next driver wake). The host falls back to `inject` when it has no followup or the option is `false`. **The wake primitive is always called ON the agent instance** — the platform's `Agent.followup`/`inject` are prototype methods that call `this.send(...)`, so extracting one into a local and calling the detached reference throws (0.3.73: that throw was caught and logged while the cadence reset still ran, silently consuming every segment's review from 2026-09-07). A refused delivery now returns `false` and the caller keeps its latch and counters, so the review retries at the next completed boundary instead of vanishing; rule N13b in `packages/scripts/verify-arch-guards.mjs` pins the call form mechanically (comments and string literals are masked, and the detector self-tests at startup). The woken turn's own cadence fire is suppressed once (an injected review prompt alone must not re-trigger a review under `interval=1`); the suppression is bound to the turn the delivery WOKE — a busy-period turn that started before the delivery keeps its own cadence and cannot consume it (S2-9, FLOW1-5: the platform's `turn/start` carries only `{ turn }`, so ordering is the binding identity); a restart clears the queue, so the loop cannot survive it.
+- **`reviewWakeInject`** (default `true`): deliveries use `agent.followup` (next-turn + wake — the model starts processing immediately) instead of the non-waking `agent.inject` (which waits for the next driver wake). The host falls back to `inject` when it has no followup or the option is `false`. **The wake primitive is always called ON the agent instance** — the platform's `Agent.followup`/`inject` are prototype methods that call `this.send(...)`, so extracting one into a local and calling the detached reference throws (0.3.73: that throw was caught and logged while the cadence reset still ran, silently consuming every segment's review from 2026-09-07). A refused delivery now returns `false` and the caller keeps its latch and counters, so the review retries at the next completed boundary instead of vanishing; rule N13b in `packages/scripts/verify-arch-guards.mjs` pins the call form mechanically (comments and string literals are masked, and the detector self-tests at startup). The woken turn's own cadence fire is suppressed (an injected review prompt alone must not re-trigger a review under `interval=1`): a delivery that appends suppresses ONE turn, and an inbox-replace re-armed wake suppresses the TWO turns it can produce — the refreshed-prompt turn, then the wake-stub turn queued behind it — because the platform claims one next-turn per driver round (PLAN-R2 P1-1, 2026-09-16); the suppression is bound to the turn(s) the delivery WOKE — a busy-period turn that started before the delivery keeps its own cadence and cannot consume it (S2-9, FLOW1-5: the platform's `turn/start` carries only `{ turn }`, so ordering is the binding identity); a restart clears the queue, so the loop cannot survive it.
 - **In-flight triggers coalesce, and the drain settles at delivery**: a trigger that arrives while a review is in flight is queued as ONE entry per (session, kind) — last trigger wins — so one window can never deliver two prompts for the same segment, and the next completed boundary starts a fresh run once the window closes (the settle wait is bounded; a handle the platform never settles after its abort is abandoned and reported as `evolution/review-error`). A drain delivery that fails restores that session's cadence latch (and, on the completion channel, its `completionInjected` flag), so the segment's review retries at the next completed boundary instead of vanishing with no trace (S2-7, FLOW1-2/1-4).
 - **Counting window = injection-to-injection**: the `turnsSinceMemory`/`turnsSinceSkill` counters are monotonic across threshold fires (`resetOnFire: false`) and are zeroed at the flush delivery — a continued conversation starts a fresh segment from the injection. A threshold fire on the completing turn is caught by the flush (`pendingKind = latch ?? kind`). All deliveries (review prompt AND result notices) share the same waking channel; a failed counter-reset persist warns once per session (a stateful reload may re-deliver).
 

package/lib/index.js

@@ -55,9 +55,13 @@ var SessionScopedState = class {
 * Background review orchestration: signal gate → one-shot subagent → trusted plan execution.
 * @module @lmzhen/dsh-evolution-review
 */
-/** S2-6 (FLOW1-1): how long a subagent handle may keep the in-flight window
-* open AFTER its own review timeout, before the review abandons it. Caps the
-* wait at the review timeout itself so a short (test) budget stays short. */
+/** S2-6 (FLOW1-1): the settle-grace margin a subagent handle gets beyond its
+* own deadline before the review abandons it. As the dispose watchdog's WHOLE
+* budget it is capped by the review timeout so a short (test) budget stays
+* short; the result watchdog adds it AFTER the full timeout (PLAN S1.1,
+* 2026-09-16) and caps the sum at the timer ceiling (PLAN-R2 P2-1). The
+* `run.dispose` arm point counts this margin ALONE — its clock starts after
+* the result settled, not at the review timeout (PLAN-R2 P2-2, 2026-09-16). */
 const REVIEW_SETTLE_MARGIN_MS = 5e3;
 /** Error name marking the S2-6 watchdog expiry (see the catch in trySubagentReview). */
 const REVIEW_SETTLE_TIMEOUT = "ReviewSettleTimeout";
@@ -209,9 +213,10 @@ function apply(ctx, rawConfig = {}) {
 			return;
 		}
 		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) {
+		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 || lastTurnStart.size >= COUNTER_SWEEP_THRESHOLD) {
 			const isAlive = (id) => ctx.agents.get(id) !== void 0;
 			sweepDeadSessionEntries(turnStarts, isAlive);
+			sweepDeadSessionEntries(lastTurnStart, isAlive);
 			sweepDeadSessionEntries(cumulativeToolCalls, isAlive);
 			sweepDeadSessionEntries(completionInjected, isAlive);
 			sweepDeadSessionEntries(pendingCadenceReviews, isAlive);
@@ -249,7 +254,11 @@ function apply(ctx, rawConfig = {}) {
 		const snapshot = policy();
 		const suppression = skipNextCadenceFire.get(session.id);
 		const skipFire = suppression !== void 0 && event.data.turn > suppression.afterTurn;
-		if (skipFire) skipNextCadenceFire.delete(session.id);
+		if (skipFire) if (suppression.turns === void 0 || suppression.turns <= 1) skipNextCadenceFire.delete(session.id);
+		else skipNextCadenceFire.set(session.id, {
+			afterTurn: suppression.afterTurn,
+			turns: suppression.turns - 1
+		});
 		let state = {
 			turnsSinceMemory: 0,
 			turnsSinceSkill: 0,
@@ -446,17 +455,36 @@ function apply(ctx, rawConfig = {}) {
 				summary
 			}
 		});
+		const wake = agent;
 		const inbox = agent.inbox;
 		if (inbox !== void 0 && typeof inbox.replace === "function") try {
-			const superseded = [...inbox.nextTurn ?? [], ...inbox.nextStep ?? []].find((row) => isSameKindPending(row, summary));
+			const supersededTurnRow = (inbox.nextTurn ?? []).find((row) => isSameKindPending(row, summary));
+			const superseded = supersededTurnRow ?? (inbox.nextStep ?? []).find((row) => isSameKindPending(row, summary));
 			if (superseded !== void 0 && inbox.replace(superseded.id, message)) {
 				if (reviewPrompt) markReviewChannelForDelivery(agent, inbox);
+				if (supersededTurnRow !== void 0 && typeof wake.followup === "function") {
+					wake.followup(createUserMessage({
+						content: [{
+							type: "text",
+							text: `[${summary}] the queued prompt ahead of this notice was refreshed in place; that copy is the current request. If this notice reaches a turn on its own, the review turn already ran — no action is needed.`
+						}],
+						source: {
+							kind: "plugin",
+							plugin: "dsh-evolution-review",
+							form: "notice",
+							summary: `${summary} (wake)`
+						}
+					}));
+					skipNextCadenceFire.set(agent.session.id, {
+						afterTurn: lastTurnStart.get(agent.session.id) ?? -1,
+						turns: 2
+					});
+				}
 				return true;
 			}
 		} catch (error) {
 			ctx.logger.warn(`dsh-evolution-review: inbox coalescing failed (${error instanceof Error ? error.message : String(error)}) — delivering a fresh message instead`);
 		}
-		const wake = agent;
 		try {
 			if (config.reviewWakeInject && typeof wake.followup === "function") {
 				wake.followup(message);
@@ -469,14 +497,23 @@ function apply(ctx, rawConfig = {}) {
 			return false;
 		}
 	};
-	const settleBudgetMs = () => Math.min(config.reviewTimeoutMs, REVIEW_SETTLE_MARGIN_MS);
-	const withSettleWatchdog = (promise, label) => new Promise((resolve, reject) => {
-		const ms = settleBudgetMs();
+	let settleBudgetCapWarned = false;
+	const resultSettleBudgetMs = () => {
+		const budget = config.reviewTimeoutMs + Math.min(REVIEW_SETTLE_MARGIN_MS, config.reviewTimeoutMs);
+		if (budget <= MAX_TIMER_DELAY_MS) return budget;
+		if (!settleBudgetCapWarned) {
+			settleBudgetCapWarned = true;
+			ctx.logger.warn(`dsh-evolution-review: reviewTimeoutMs ${config.reviewTimeoutMs}ms plus the settle margin exceeds the 32-bit timer delay ceiling (${MAX_TIMER_DELAY_MS}ms) — the settle watchdog arms at the ceiling`);
+		}
+		return MAX_TIMER_DELAY_MS;
+	};
+	const disposeSettleBudgetMs = () => Math.min(REVIEW_SETTLE_MARGIN_MS, config.reviewTimeoutMs);
+	const withSettleWatchdog = (promise, label, budgetMs, overdue) => new Promise((resolve, reject) => {
 		const timer = setTimeout(() => {
-			const error = /* @__PURE__ */ new Error(`dsh-evolution-review: ${label} did not settle within ${ms}ms of the review timeout — abandoning the handle`);
+			const error = /* @__PURE__ */ new Error(`dsh-evolution-review: ${label} ${overdue(budgetMs)} — abandoning the handle`);
 			error.name = REVIEW_SETTLE_TIMEOUT;
 			reject(error);
-		}, ms);
+		}, budgetMs);
 		promise.then((value) => {
 			clearTimeout(timer);
 			resolve(value);
@@ -576,7 +613,7 @@ function apply(ctx, rawConfig = {}) {
 				outputSchema: REVIEW_OUTPUT_SCHEMA
 			});
 			try {
-				const result = await withSettleWatchdog(run.result, "subagent review result");
+				const result = await withSettleWatchdog(run.result, "subagent review result", resultSettleBudgetMs(), (total) => `did not settle within ${Math.max(0, total - config.reviewTimeoutMs)}ms after the review timeout (watchdog total ${total}ms)`);
 				if (!result.structured) {
 					try {
 						ctx.emit("evolution/review-error", { sessionId: session.id });
@@ -667,7 +704,7 @@ function apply(ctx, rawConfig = {}) {
 				return true;
 			} finally {
 				try {
-					await withSettleWatchdog(run.dispose(), "subagent dispose");
+					await withSettleWatchdog(run.dispose(), "subagent dispose", disposeSettleBudgetMs(), (total) => `did not settle within ${total}ms`);
 				} catch (disposeError) {
 					ctx.logger.warn(`dsh-evolution-review: subagent dispose failed: ${disposeError instanceof Error ? disposeError.message : String(disposeError)}`);
 				}
@@ -1095,11 +1132,27 @@ function renderToolResultLine(data) {
 	const output = resultBlocks.map((block) => Array.isArray(block.content) ? block.content.map((inner) => inner.type === "text" && typeof inner.text === "string" ? inner.text : "").join(" ") : typeof block.text === "string" ? block.text : "").join(" ").trim();
 	return `[result]${shape?.error || resultBlocks.some((block) => block.isError === true) ? " [ERROR]" : ""} ${output.slice(0, 500)}`;
 }
+/**
+* PLAN S4.1 (2026-09-16, audit P2-12): text of one persisted content block,
+* or `''` for any other shape. Content blocks cross the durable session-log
+* boundary, so their runtime shape is `unknown` even where the static type
+* promises `{ type, text }` — a persisted `content: [null]` (the A2-7 shape)
+* used to TypeError in buildReviewRequest and the caller's catch dropped the
+* whole subagent review leg. This mirrors evolution-core signals.ts's private
+* `textOfBlock` (same guard, same rationale); it is not imported because core
+* keeps that helper module-private, and this file's other block renderer
+* (renderToolResultLine) guards its own inner-block shapes inline.
+*/
+function textOfPersistedBlock(block) {
+	if (block === null || typeof block !== "object") return "";
+	const candidate = block;
+	return candidate.type === "text" && typeof candidate.text === "string" ? candidate.text : "";
+}
 function buildReviewRequest(session, kind, signal, maxMessages, maxMessageChars) {
 	const messages = [];
 	const surface = session.deriveMessages();
 	for (const message of surface.slice(-maxMessages)) if (message.role === "user" || message.role === "assistant") {
-		const text = message.content.map((block) => block.type === "text" ? block.text : "").join(" ").trim();
+		const text = message.content.map(textOfPersistedBlock).join(" ").trim();
 		if (text) messages.push(`${message.role.toUpperCase()}: ${text.slice(0, maxMessageChars)}`);
 	}
 	const toolLines = [];
@@ -1132,4 +1185,4 @@ function buildReviewRequest(session, kind, signal, maxMessages, maxMessageChars)
 	].join("\n");
 }
 //#endregion
-export { Config, REVIEW_OUTPUT_SCHEMA, apply, clampReviewConfig, filterUnreadSkillOps, inject, name, renderToolResultLine, shouldCompletionReview, sweepDeadSessionEntries };
+export { Config, REVIEW_OUTPUT_SCHEMA, apply, buildReviewRequest, clampReviewConfig, filterUnreadSkillOps, inject, name, renderToolResultLine, shouldCompletionReview, sweepDeadSessionEntries };

package/lib/types/index.d.ts

@@ -4,6 +4,8 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
+import type { Session } from '@deepseek-ai/dsh-session';
+import { type ReviewKind } from '@lmzhen/dsh-evolution-core';
 export declare const name = "evolution-review";
 export declare const inject: string[];
 export interface Config {
@@ -162,5 +164,10 @@ export declare function filterUnreadSkillOps(ops: Array<{
  * buildReviewRequest and is unchanged).
  */
 export declare function renderToolResultLine(data: unknown): string;
+export declare function buildReviewRequest(session: Session, kind: ReviewKind, signal: {
+    toolCalls: number;
+    userChars: number;
+    assistantChars: number;
+}, maxMessages: number, maxMessageChars: number): string;
 export {};
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-review",
   "description": "Background review orchestration (community build)",
-  "version": "0.3.82",
+  "version": "0.3.83",
   "publishConfig": {
     "access": "public"
   },
@@ -27,9 +27,9 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-approval": "^0.3.82",
-    "@lmzhen/dsh-evolution-core": "^0.3.82",
-    "@lmzhen/dsh-evolution-plan-validator": "^0.3.82"
+    "@lmzhen/dsh-evolution-approval": "^0.3.83",
+    "@lmzhen/dsh-evolution-core": "^0.3.83",
+    "@lmzhen/dsh-evolution-plan-validator": "^0.3.83"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
@@ -37,8 +37,8 @@
     "@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.3.82",
-    "@lmzhen/dsh-evolution-policy": "^0.3.82"
+    "@lmzhen/dsh-evolution-state": "^0.3.83",
+    "@lmzhen/dsh-evolution-policy": "^0.3.83"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-agent": "^0.1.5-rc.2",
@@ -48,10 +48,10 @@
     "@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.3.82",
-    "@lmzhen/dsh-evolution-core": "^0.3.82",
-    "@lmzhen/dsh-evolution-curator": "^0.3.82",
-    "@lmzhen/dsh-evolution-plan-validator": "^0.3.82",
-    "@lmzhen/dsh-evolution-state": "^0.3.82"
+    "@lmzhen/dsh-evolution-approval": "^0.3.83",
+    "@lmzhen/dsh-evolution-core": "^0.3.83",
+    "@lmzhen/dsh-evolution-curator": "^0.3.83",
+    "@lmzhen/dsh-evolution-plan-validator": "^0.3.83",
+    "@lmzhen/dsh-evolution-state": "^0.3.83"
   }
 }