@lmzhen/dsh-evolution-review 0.3.81 → 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
 
@@ -31,19 +31,20 @@ Independent of request-prefix construction. This package does not alter the asse
 - 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).
 - **The default `reviewMode: 'inject'` produces no plan ledger.** The review runs in the parent session and emits no `evolution/plan-applied` event, so `evolution-activity`'s `activity.json` and the `evolution-replay` leaderboard never grow in this mode — the only production emit point sits inside the subagent path. Set `reviewMode: 'subagent'` on the `evolution-policy` row when the plan audit trail is required; the plugin states this once at load instead of leaving an empty ledger to be read as "no reviews happened" (v37 S2.2, plan decision (c)).
-- **`.pinned` protection in the `'inject'` channel rides a family-internal session mark.** The review prompt marks the parent session, `tool-skill-manage` reads that mark and resolves both origin surfaces (approval + library) to `background_review`, and the next REAL user message (`source.kind === 'user'`) clears it — plugin notices, including the review prompt itself, do not. Two bounds follow from the platform's inject contract (no driver wake; a prompt is dropped on cancel/dispose and may be missed with an already-claimed batch): with `reviewWakeInject: false`, or on a host without `followup`, (a) a pending prompt may never execute while the session stays idle, and (b) when the user's next message wakes the session, the mark is cleared before that pending prompt reaches the model — its writes are then attributed `foreground` and the pinned guard does not cover them. The mark is in-memory, so a restart drops the window (v37 S2.2, plan decision (b)).
+- **`.pinned` protection in the `'inject'` channel rides a family-internal session mark.** The review prompt marks the parent session, `tool-skill-manage` reads that mark and resolves both origin surfaces (approval + library) to `background_review`, and the next REAL user message (`source.kind === 'user'`) clears it — plugin notices, including the review prompt itself, do not. Two bounds follow from the platform's inject contract (no driver wake; a prompt is dropped on cancel/dispose and may be missed with an already-claimed batch): with `reviewWakeInject: false`, or on a host without `followup`, (a) a pending prompt may never execute while the session stays idle, and (b) when the user's next message wakes the session, the mark is cleared before that pending prompt reaches the model — its writes are then attributed `foreground` and the pinned guard does not cover them. The mark is in-memory, so a restart drops the window (v37 S2.2, plan decision (b)). A prompt delivered while a HUMAN message is already queued is not marked at all: the platform claims that human turn first, so a session-level window would attribute the user's own writes to `background_review` (S2-8, FLOW1-3) — the plugin reads the pre-claim queue (`agent.inbox`) because the platform exposes no claim identity, and warns once per mount when it withholds the mark.
 
 ## Configuration
 
 `reviewProvider` selects the LLM provider for review subagents. When omitted, the subagent inherits the deployment default route instead of a hardcoded provider name. Model selection stays on the policy (`memoryReviewModel` / `skillReviewModel`).
 
-`reviewTimeoutMs` bounds each review subagent run (an `AbortSignal.timeout`; `0` aborts immediately). The former `executionTimeoutMs` declaration was removed in v14 (nothing read it, so it was configuration that did nothing); use `reviewTimeoutMs`.
+`reviewTimeoutMs` bounds each review subagent run (an `AbortSignal.timeout`; `0` aborts immediately) and the write leg that executes the plan. The deadline does not stop an abandoned write leg: an op that lands after it is reported to the model as its own notice (S2-10, FLOW1-6), while the `evolution/plan-applied` record stays the deadline snapshot, so late writes still have no plan-applied entry. The former `executionTimeoutMs` declaration was removed in v14 (nothing read it, so it was configuration that did nothing); use `reviewTimeoutMs`.
 
 ### Review delivery contract (0.3.38-0.3.42)
 
 - **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`); 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).
 
 **Runtime invariant:** No companion is published. The platform auto-assembles nothing and the family mounts no `<pkg>/invariant` cordis row, so a companion here would never execute (v37 S2.1 / I-3).

package/lib/index.js

@@ -4,11 +4,67 @@ 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, contentHash, evolutionIoAdapter, foldToolDispatches, foldTurn, markReviewChannel, newSkillLibrary, readDispatchSignal, redactSecrets, resolveOrigins, resolveRootConfig, reviewPrompt, sessionAudited, skillReadNameOf, sweepReviewChannelSessions, verifyPromptBundle } from "@lmzhen/dsh-evolution-core";
 import { validateEvolutionPlan } from "@lmzhen/dsh-evolution-plan-validator";
+//#region lib/types/session-state.js
+/**
+* A registry of one plugin instance's session-keyed collections.
+*
+* P1-9 (S2-2): the review plugin kept eight per-session maps and cleared them
+* from a hand-written list inside its dispose hook. The list drifted — the
+* 0.3.38-0.3.42 additions (pendingCadenceReviews, pendingCadenceWarned,
+* skipNextCadenceFire, cadenceResetWarned) were missing from it until V7-16 —
+* because nothing tied a declaration to its cleanup. Registering at the
+* declaration site removes the list: a collection clears because it was
+* registered, and tests/session-state-ownership.spec.ts fails when a new
+* `new Map<SessionId, …>` skips the registry.
+*
+* Deliberately package-local: evolution-review is the only current consumer
+* (commands holds no per-session state, and state-json's warn dedupe sets are
+* process-lifetime by design). Promote it to evolution-core when a second
+* package needs the same registration discipline.
+*/
+var SessionScopedState = class {
+	registered = [];
+	/**
+	* Register a collection and return it, so declaration and registration stay
+	* one statement.
+	*
+	* @param key - the declaring variable name; also the diagnostic name.
+	* @param collection - any collection exposing clear().
+	* @returns the same collection.
+	*/
+	add(key, collection) {
+		if (this.registered.some((entry) => entry.key === key)) throw new Error(`dsh-evolution-review: session state "${key}" is registered twice`);
+		this.registered.push({
+			key,
+			collection
+		});
+		return collection;
+	}
+	/** Registered keys in registration order (diagnostics and the ownership spec). */
+	keys() {
+		return this.registered.map((entry) => entry.key);
+	}
+	/** Clear every registered collection. Idempotent; safe on a partially used mount. */
+	dispose() {
+		for (const entry of this.registered) entry.collection.clear();
+	}
+};
+//#endregion
 //#region lib/types/index.js
 /**
 * Background review orchestration: signal gate → one-shot subagent → trusted plan execution.
 * @module @lmzhen/dsh-evolution-review
 */
+/** 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";
 const name = "evolution-review";
 const inject = ["agents"];
 const Config = z.object({
@@ -61,6 +117,16 @@ function isSameKindPending(message, summary) {
 	const source = message.source;
 	return source?.kind === "plugin" && source.plugin === "dsh-evolution-review" && source.form === "notice" && source.summary === summary;
 }
+/**
+* v43 audit (P1-4 / FLOW1): the cadence summary MUST name the review kind.
+* The three cadence deliveries used to share the bare `auto-review` summary
+* while their prompts differ by kind (memory / skill / combined), so
+* `isSameKindPending` matched ACROSS kinds: a pending memory prompt was replaced
+* in place by a skill prompt — one kind silently lost, while the caller still
+* consumed the cadence latch and the deferred drain still emitted
+* `evolution/review-scheduled` as if both had been delivered.
+*/
+const cadenceSummary = (kind) => `auto-review:${kind}`;
 function clampReviewConfig(rawConfig, ctx) {
 	const clamped = [];
 	const field = (name, value, fallback, min, max) => {
@@ -94,14 +160,17 @@ function apply(ctx, rawConfig = {}) {
 	const config = clampReviewConfig(rawConfig, ctx);
 	assertSkillsRootAliasRetired(rawConfig);
 	const rootConfig = resolveRootConfig(rawConfig);
-	const turnStarts = /* @__PURE__ */ new Map();
+	const sessionState = new SessionScopedState();
+	const turnStarts = sessionState.add("turnStarts", /* @__PURE__ */ new Map());
 	let statelessReviewStateWarned = false;
-	const cumulativeToolCalls = /* @__PURE__ */ new Map();
-	const completionInjected = /* @__PURE__ */ new Set();
-	const pendingCadenceReviews = /* @__PURE__ */ new Map();
-	const pendingCadenceWarned = /* @__PURE__ */ new Set();
-	const skipNextCadenceFire = /* @__PURE__ */ new Map();
-	const cadenceResetWarned = /* @__PURE__ */ new Set();
+	let channelMarkSuppressedWarned = false;
+	const cumulativeToolCalls = sessionState.add("cumulativeToolCalls", /* @__PURE__ */ new Map());
+	const completionInjected = sessionState.add("completionInjected", /* @__PURE__ */ new Set());
+	const pendingCadenceReviews = sessionState.add("pendingCadenceReviews", /* @__PURE__ */ new Map());
+	const pendingCadenceWarned = sessionState.add("pendingCadenceWarned", /* @__PURE__ */ new Set());
+	const skipNextCadenceFire = sessionState.add("skipNextCadenceFire", /* @__PURE__ */ new Map());
+	const lastTurnStart = sessionState.add("lastTurnStart", /* @__PURE__ */ new Map());
+	const cadenceResetWarned = sessionState.add("cadenceResetWarned", /* @__PURE__ */ new Set());
 	let reviewInFlight = false;
 	const policy = () => ctx.get("evolutionPolicy")?.get();
 	const schemaDefaults = Config["~standard"].validate({}).value;
@@ -122,8 +191,8 @@ function apply(ctx, rawConfig = {}) {
 			warnShadowed();
 		});
 	}
-	if ((policy()?.reviewMode ?? config.reviewMode) === "inject") ctx.logger.warn("dsh-evolution-review: reviewMode \"inject\" (default) runs the review in the parent session and emits NO evolution/plan-applied ledger entry — evolution-activity and evolution-replay stay empty in this mode (see packages/docs/known-limitations.md). Set reviewMode: \"subagent\" on the evolution-policy row to keep the audited plan path.");
-	const reviewStateLocks = /* @__PURE__ */ new Map();
+	if ((policy()?.reviewMode ?? config.reviewMode) === "inject") ctx.logger.warn("dsh-evolution-review: reviewMode \"inject\" (default) runs the review in the parent session and emits NO evolution/plan-applied ledger entry — evolution-activity and evolution-replay stay empty in this mode (see the evolution-review README, \"Known Limitations and Deferred Work\"). Set reviewMode: \"subagent\" on the evolution-policy row to keep the audited plan path.");
+	const reviewStateLocks = sessionState.add("reviewStateLocks", /* @__PURE__ */ new Map());
 	async function withReviewStateLock(id, task) {
 		const next = (reviewStateLocks.get(id) ?? Promise.resolve()).catch(() => {}).then(task);
 		reviewStateLocks.set(id, next);
@@ -135,15 +204,19 @@ 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);
+		if (event.type === "turn/start" && session.header.origin !== "subagent") {
+			turnStarts.set(session.id, session.seq - 1);
+			lastTurnStart.set(session.id, event.data.turn);
+		}
 		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 || 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);
@@ -179,8 +252,13 @@ function apply(ctx, rawConfig = {}) {
 			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 snapshot = policy();
-		const skipFire = skipNextCadenceFire.get(session.id) ?? false;
-		if (skipFire) skipNextCadenceFire.delete(session.id);
+		const suppression = skipNextCadenceFire.get(session.id);
+		const skipFire = suppression !== void 0 && event.data.turn > suppression.afterTurn;
+		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,
@@ -211,7 +289,7 @@ function apply(ctx, rawConfig = {}) {
 			if (pendingKind !== void 0) {
 				pendingCadenceReviews.delete(session.id);
 				if ((policy()?.reviewMode ?? config.reviewMode) === "inject") {
-					if (!deliverMessage(agent, reviewPrompt(pendingKind), "auto-review", true)) {
+					if (!deliverMessage(agent, reviewPrompt(pendingKind), cadenceSummary(pendingKind), true)) {
 						pendingCadenceReviews.set(session.id, pendingKind);
 						return;
 					}
@@ -245,7 +323,7 @@ function apply(ctx, rawConfig = {}) {
 						pendingCadenceReviews.set(session.id, pendingKind);
 						return;
 					} else if (reviewOutcome !== "deferred") {
-						if (!deliverMessage(agent, reviewPrompt(pendingKind), "auto-review", true)) {
+						if (!deliverMessage(agent, reviewPrompt(pendingKind), cadenceSummary(pendingKind), true)) {
 							pendingCadenceReviews.set(session.id, pendingKind);
 							return;
 						}
@@ -339,6 +417,31 @@ function apply(ctx, rawConfig = {}) {
 	* prototype method), the caller's catch demoted that to a console warning,
 	* and the cadence reset ran anyway — the segment's review was consumed with
 	* nothing queued (silent no-delivery window: 2026-09-07 → 0.3.73). */
+	/**
+	* S2-8 (FLOW1-3): is a HUMAN message already queued ahead of ours? The
+	* review-channel mark is a session-level WINDOW, not a claim on one message:
+	* if a real user message is pending when the review prompt is delivered, the
+	* platform claims that human turn first and the mark would be in effect for
+	* the user's own writes — attributing them `background_review` (the pinned /
+	* hermes-managed protection would cover human edits). The platform exposes no
+	* claim identity to the plugin, so the pre-claim queue is the identity that is
+	* readable; this is the plan's documented fallback, and it only ever WITHHOLDS
+	* the mark (a host without `inbox` behaves exactly as before).
+	*/
+	const humanQueuedAhead = (inbox) => [...inbox?.nextTurn ?? [], ...inbox?.nextStep ?? []].some((row) => row.source?.kind === "user");
+	/** Mark the delivered review prompt's session — unless human input is queued
+	* ahead of it (see humanQueuedAhead). Says so once per mount: an unmarked
+	* window silently downgrades that review's writes to foreground attribution. */
+	const markReviewChannelForDelivery = (agent, inbox) => {
+		if (humanQueuedAhead(inbox)) {
+			if (!channelMarkSuppressedWarned) {
+				channelMarkSuppressedWarned = true;
+				ctx.logger.warn("dsh-evolution-review: the review prompt was delivered BEHIND queued human input — the review-channel mark stays unset for this window, so this review’s writes are attributed foreground and the .pinned/.hermes-managed protection does not cover them");
+			}
+			return;
+		}
+		markReviewChannel(agent.session.id);
+	};
 	const deliverMessage = (agent, text, summary, reviewPrompt = false) => {
 		const message = createUserMessage({
 			content: [{
@@ -352,29 +455,73 @@ 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) markReviewChannel(agent.session.id);
+				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);
-				skipNextCadenceFire.set(agent.session.id, true);
+				skipNextCadenceFire.set(agent.session.id, { afterTurn: lastTurnStart.get(agent.session.id) ?? -1 });
 			} else agent.inject(message);
-			if (reviewPrompt) markReviewChannel(agent.session.id);
+			if (reviewPrompt) markReviewChannelForDelivery(agent, inbox);
 			return true;
 		} catch (error) {
 			ctx.logger.warn(`dsh-evolution-review: review delivery failed (${error instanceof Error ? error.message : String(error)}) — nothing was queued; the review is NOT consumed and retries at the next completed boundary`);
 			return false;
 		}
 	};
+	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} ${overdue(budgetMs)} — abandoning the handle`);
+			error.name = REVIEW_SETTLE_TIMEOUT;
+			reject(error);
+		}, budgetMs);
+		promise.then((value) => {
+			clearTimeout(timer);
+			resolve(value);
+		}, (error) => {
+			clearTimeout(timer);
+			reject(error instanceof Error ? error : new Error(String(error)));
+		});
+	});
 	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`));
@@ -417,16 +564,19 @@ function apply(ctx, rawConfig = {}) {
 		const subagents = ctx.get("subagents");
 		if (!subagents) return false;
 		if (reviewInFlight) {
-			if (deferredFallbackReviews.length < DEFERRED_REVIEW_CAP) {
-				deferredFallbackReviews.push({
+			const existing = deferredFallbackReviews.findIndex((entry) => entry.sessionId === session.id && entry.kind === kind);
+			if (existing >= 0 || deferredFallbackReviews.length < DEFERRED_REVIEW_CAP) {
+				const entry = {
 					agent,
 					sessionId: session.id,
 					kind,
 					prompt: reviewPrompt(kind),
-					label: "auto-review",
+					label: cadenceSummary(kind),
 					channel: "inject",
 					counts: signal
-				});
+				};
+				if (existing >= 0) deferredFallbackReviews[existing] = entry;
+				else deferredFallbackReviews.push(entry);
 				return "deferred";
 			}
 			ctx.logger.warn(`dsh-evolution-review: deferred-review queue at cap (${DEFERRED_REVIEW_CAP}) — dropping one fallback review prompt`);
@@ -463,7 +613,7 @@ function apply(ctx, rawConfig = {}) {
 				outputSchema: REVIEW_OUTPUT_SCHEMA
 			});
 			try {
-				const result = await run.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 });
@@ -509,10 +659,21 @@ function apply(ctx, rawConfig = {}) {
 					}
 				};
 				const landed = [];
+				let deadlineMissed = false;
+				const lateLandings = [];
+				const noteLanded = (action) => {
+					landed.push(action);
+					if (!deadlineMissed) return;
+					lateLandings.push(action);
+					const before = landed.length - lateLandings.length;
+					const earlier = before > 0 ? ` (${before} other op(s) had landed before the deadline)` : "";
+					deliverMessage(agent, `\u{1F4BE} Self-improvement review: ${action} ${lateLandings.length === 1 ? "landed AFTER the review timed out" : `landed after the timeout (${lateLandings.length} late so far)`}${earlier} \u2014 reconcile before re-requesting the same change.`, "self-improvement review late landing");
+				};
 				let executed;
 				try {
-					executed = await withTimeout(executePlan(validation.accepted, session, (action) => landed.push(action), preRunHashes), config.reviewTimeoutMs, "review plan execution");
+					executed = await withTimeout(executePlan(validation.accepted, session, noteLanded, preRunHashes), config.reviewTimeoutMs, "review plan execution");
 				} catch (error) {
+					deadlineMissed = true;
 					emitApplied({
 						actions: landed,
 						executionError: `execution timed out after ${config.reviewTimeoutMs}ms`
@@ -543,14 +704,19 @@ function apply(ctx, rawConfig = {}) {
 				return true;
 			} finally {
 				try {
-					await run.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)}`);
 				}
 			}
 		} 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");
+			if (error instanceof Error && error.name === REVIEW_SETTLE_TIMEOUT) try {
+				ctx.emit("evolution/review-error", { sessionId: session.id });
+			} catch (emitError) {
+				ctx.logger.warn(`dsh-evolution-review: review-error emit failed: ${emitError instanceof Error ? emitError.message : String(emitError)}`);
+			}
+			if (error instanceof Error && error.message.includes("plan execution timed out")) ctx.logger.warn("dsh-evolution-review: plan execution abandoned on timeout — late writes ARE reported to the model as they land (S2-10) but still have NO plan-applied record and race the fallback inject; inspect the skill tree and usage sidecar");
 			return false;
 		} finally {
 			reviewInFlight = false;
@@ -558,6 +724,7 @@ function apply(ctx, rawConfig = {}) {
 			for (const { agent: waitingAgent, sessionId: entrySession, kind: waitingKind, prompt, label, channel, counts: entryCounts } of deferred) {
 				if (!deliverMessage(waitingAgent, prompt, label, true)) {
 					if (channel === "completion") completionInjected.delete(entrySession);
+					else pendingCadenceReviews.set(entrySession, waitingKind);
 					continue;
 				}
 				try {
@@ -757,12 +924,12 @@ function apply(ctx, rawConfig = {}) {
 			if (op.action === "edit" || op.action === "update") {
 				const updated = await library.update(name, op.content ?? "", origin, anchorOf(op));
 				if (updated.stale === true) return staleRefusal(updated, name, op.file_path);
-				if (updated.ok) await ctx.get("skillUsage")?.record?.(name, "patch").catch(() => {});
+				if (updated.ok && updated.noop !== true) await ctx.get("skillUsage")?.record?.(name, "patch").catch(() => {});
 				return updated;
 			}
 			if (op.action === "patch") {
 				const patched = await library.patch(name, op.old_string ?? "", op.new_string ?? "", op.file_path ?? "", op.replace_all === true, origin);
-				if (patched.ok) await ctx.get("skillUsage")?.record?.(name, "patch").catch(() => {});
+				if (patched.ok && patched.noop !== true) await ctx.get("skillUsage")?.record?.(name, "patch").catch(() => {});
 				return patched;
 			}
 			if (op.action === "delete") {
@@ -784,7 +951,7 @@ function apply(ctx, rawConfig = {}) {
 				}
 				const removedSupport = await library.removeSupportFile(name, op.file_path ?? "", origin, anchor);
 				if (removedSupport.stale === true) return staleRefusal(removedSupport, name, op.file_path);
-				if (removedSupport.ok) await ctx.get("skillUsage")?.record?.(name, "patch").catch(() => {});
+				if (removedSupport.ok && removedSupport.noop !== true) await ctx.get("skillUsage")?.record?.(name, "patch").catch(() => {});
 				return removedSupport;
 			}
 			if (op.action === "restructure") {
@@ -801,14 +968,7 @@ function apply(ctx, rawConfig = {}) {
 		}
 	}
 	ctx.effect(() => () => {
-		turnStarts.clear();
-		cumulativeToolCalls.clear();
-		completionInjected.clear();
-		pendingCadenceReviews.clear();
-		pendingCadenceWarned.clear();
-		skipNextCadenceFire.clear();
-		cadenceResetWarned.clear();
-		reviewStateLocks.clear();
+		sessionState.dispose();
 	}, "dsh-evolution-review.cleanup");
 }
 /** Completion-channel decision: task finished normally AND the session is proven long. */
@@ -972,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 = [];
@@ -1009,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/lib/types/session-state.d.ts

@@ -0,0 +1,36 @@
+/**
+ * A registry of one plugin instance's session-keyed collections.
+ *
+ * P1-9 (S2-2): the review plugin kept eight per-session maps and cleared them
+ * from a hand-written list inside its dispose hook. The list drifted — the
+ * 0.3.38-0.3.42 additions (pendingCadenceReviews, pendingCadenceWarned,
+ * skipNextCadenceFire, cadenceResetWarned) were missing from it until V7-16 —
+ * because nothing tied a declaration to its cleanup. Registering at the
+ * declaration site removes the list: a collection clears because it was
+ * registered, and tests/session-state-ownership.spec.ts fails when a new
+ * `new Map<SessionId, …>` skips the registry.
+ *
+ * Deliberately package-local: evolution-review is the only current consumer
+ * (commands holds no per-session state, and state-json's warn dedupe sets are
+ * process-lifetime by design). Promote it to evolution-core when a second
+ * package needs the same registration discipline.
+ */
+export declare class SessionScopedState {
+    private readonly registered;
+    /**
+     * Register a collection and return it, so declaration and registration stay
+     * one statement.
+     *
+     * @param key - the declaring variable name; also the diagnostic name.
+     * @param collection - any collection exposing clear().
+     * @returns the same collection.
+     */
+    add<T extends {
+        clear(): void;
+    }>(key: string, collection: T): T;
+    /** Registered keys in registration order (diagnostics and the ownership spec). */
+    keys(): string[];
+    /** Clear every registered collection. Idempotent; safe on a partially used mount. */
+    dispose(): void;
+}
+//# sourceMappingURL=session-state.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-review",
   "description": "Background review orchestration (community build)",
-  "version": "0.3.81",
+  "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.81",
-    "@lmzhen/dsh-evolution-core": "^0.3.81",
-    "@lmzhen/dsh-evolution-plan-validator": "^0.3.81"
+    "@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.81",
-    "@lmzhen/dsh-evolution-policy": "^0.3.81"
+    "@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.81",
-    "@lmzhen/dsh-evolution-core": "^0.3.81",
-    "@lmzhen/dsh-evolution-curator": "^0.3.81",
-    "@lmzhen/dsh-evolution-plan-validator": "^0.3.81",
-    "@lmzhen/dsh-evolution-state": "^0.3.81"
+    "@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"
   }
 }