@lmzhen/dsh-evolution-review 0.15.1 → 0.16.0

package/README.md

@@ -22,6 +22,8 @@ own, and the delivery mode lives on the `evolution-policy` row, not here.
 - `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.
+- **Hosts without `agent.inbox` fall back to delivery-time settlement.** With no queue to observe there is no `claimed`/`discarded` to wait for, so the delivery itself closes the window (`delivery-no-inbox`) and each completed boundary may deliver again: that is the pre-0.3.41 behavior, and under `interval=1` it can chain review turns. Every current host exposes `Agent.inbox`, so this is the degradation path for stub or older agents (the plugin's own tests rely on it).
+- **The subagent channel settles on completion, not on a queue event.** A subagent review never enters the parent's queue, so when the run finishes the window restarts (`subagent-flush`) — including any notice an earlier inject-mode fallback left queued, which then runs once more (a mixed-mode session pays at most one extra review; the queue copy is not cancelled).
 - **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)).
 - **Evidence that cites only bookkeeping frames is REPORTED, never refused (phase 1).** `EVIDENCE_CLASS` (`evolution-plan-validator`) counts the ops whose entire `evidence` list points at turn/step boundary frames — a seq the range rule accepts but that carries no content — and this plugin logs one `dsh-evolution-review:` warning per plan; the count rides `evolution/plan-applied` as `evidenceClassReports` and appears in no model-visible text. Nothing is dropped: `EVIDENCE_RANGE` remains the only evidence gate, and a session log whose frames carry no `seq` leaves the report silent (`undefined` is not an empty index) instead of reporting every op.
 - **`.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). 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.
@@ -44,9 +46,9 @@ own, and the delivery mode lives on the `evolution-policy` row, not here.
 - **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.
 - **`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 (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: the RESULT watchdog's budget runs from the abort deadline (the full `reviewTimeoutMs` PLUS the 5 s settle margin, the sum capped at the platform timer ceiling), while the `run.dispose` arm point counts that margin alone, from the moment the result settled (PLAN S1.1 / P2-1 / P2-2, 0.3.83); 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). **Cost of a re-armed wake (review D2, 2026-09-16):** coalescing one wake-channel delivery adds ONE model-visible parent turn: the stub is queued behind the refreshed prompt as a second next-turn and the platform claims exactly one next-turn per driver round, so `turns: 2` suppresses the cadence fire of both rounds but cannot remove the round itself.
-- **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).
+- **`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 turn that runs our notice is excluded from the counting window (an injected review prompt alone must not re-trigger a review under `interval=1`): the platform reports which turn claimed the notice (`agent/inbox/claimed` carries the turn), that turn's `turn/end` settles the window and that turn is not counted, and any unrelated turn ending in the meantime is unaffected (V7-02, S2-9, FLOW1-5).
+- **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: the RESULT watchdog's budget runs from the abort deadline (the full `reviewTimeoutMs` PLUS the 5 s settle margin, the sum capped at the platform timer ceiling), while the `run.dispose` arm point counts that margin alone, from the moment the result settled (PLAN S1.1 / P2-1 / P2-2, 0.3.83); 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).
+- **One review at a time: the counting window follows the delivered notice, not the delivery.** The `turnsSinceMemory`/`turnsSinceSkill` counters stay monotonic across threshold fires (`resetOnFire: false`) and restart when the notice SETTLES: the queue dropped it unrun (removed, cleared, replaced — `agent/inbox/discarded`) or the turn that claimed it (`agent/inbox/claimed` names the turn) ended. While a notice is outstanding — still queued, or claimed and running — `deliverMessage` refuses to queue another review prompt (it answers `false`, so the caller keeps its one-shot latch and retries at a later boundary); that is what keeps a long task from stacking prompt after prompt. Result notices are not gated. The record is in-memory while the queue is durable, so the judgement reads both: a queue still holding one of our notices with no record (a restart) keeps the window shut, and a record whose notice has left the queue settles as `queue-lost`, while a missed `turn/end` for the claiming turn settles at the next turn that does end (turn numbers increase per session) — a lost event must not wedge the gate. Every settle logs its attribution (`discarded` / `turn-end` / `delivery-no-inbox` / `subagent-flush` / `queue-lost`). 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,6 +4,62 @@ import { createUserMessage } from "@deepseek-ai/dsh-llm";
 import { SessionId } from "@deepseek-ai/dsh-session";
 import { COMPLETION_SKILL_REVIEW_PROMPT, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MEMORY_REVIEW_MODEL, DEFAULT_REVIEW_CONTEXT_MESSAGES, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_MESSAGE_CHARS, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_REVIEW_TIMEOUT_MS, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_MODEL, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_USER_CHAR_LIMIT, MAX_TIMER_DELAY_MS, PROMPT_BUNDLE, advanceReview, assertSkillsRootAliasRetired, clampedNumber, clearReviewChannel, collectReadSkillNames, contentHash, evidenceKindIndex, evolutionIoAdapter, filterUnreadSkillOps, filterUnreadSkillOps as filterUnreadSkillOps$1, foldTurn, installParamSection, markReviewChannel, newSkillLibrary, paramNamespace, policyStageLimits, readDispatchSignal, readNumberParam, redactSecrets, resolveOrigins, resolveRootConfig, reviewPrompt, sessionAudited, sweepReviewChannelSessions, verifyPromptBundle } from "@lmzhen/dsh-evolution-core";
 import { validateEvolutionPlan } from "@lmzhen/dsh-evolution-plan-validator";
+/**
+* Whether a message is a notice this plugin delivered, judged only by durable source fields.
+*
+* The source — not the record — is what survives a restart, so a rebuild reads the same facts it
+* would have read live.
+* @param message - the message the platform reported.
+* @returns true only for this plugin's own notices.
+*/
+function isReviewNotice(message) {
+	const source = message.source;
+	return source?.kind === "plugin" && source.plugin === "dsh-evolution-review" && source.form === "notice";
+}
+/**
+* Fold one inbox event into the session's outstanding notice.
+*
+* `inserted` and `claimed` ADOPT the message (last wins): a message of ours that the queue holds or
+* a turn is running is outstanding by definition, whether or not a record survived a restart.
+* `discarded` settles whatever we were tracking — or nothing, when the delivery's `inserted` was
+* never seen — and ignores only the stale case: a record naming a DIFFERENT message means the
+* current notice is still queued, so that window must not be reset.
+* @param current - the session's record before this event.
+* @param event - the inbox notification and its message.
+* @returns the record afterwards, and whether the tracked notice settled.
+*/
+function noticeAfter(current, event) {
+	if (!isReviewNotice(event.message)) return {
+		notice: current,
+		settled: false
+	};
+	switch (event.kind) {
+		case "inserted": return {
+			notice: {
+				messageId: event.message.id,
+				turn: null
+			},
+			settled: false
+		};
+		case "claimed": return {
+			notice: {
+				messageId: event.message.id,
+				turn: event.turn ?? null
+			},
+			settled: false
+		};
+		case "discarded":
+			if (current !== void 0 && current.messageId !== event.message.id) return {
+				notice: current,
+				settled: false
+			};
+			return {
+				notice: void 0,
+				settled: true
+			};
+	}
+}
+//#endregion
 //#region lib/types/session-state.js
 /**
 * A registry of one plugin instance's session-keyed collections.
@@ -12,6 +68,9 @@ import { validateEvolutionPlan } from "@lmzhen/dsh-evolution-plan-validator";
 * 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 —
+* the first and last of those four have since been replaced by the outstanding-
+* notice window (0.15.2: one record per session, and the claim names the turn), so
+* only pendingCadenceReviews, pendingCadenceWarned and cadenceResetWarned remain —
 * 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
@@ -108,23 +167,9 @@ const REVIEW_OUTPUT_SCHEMA = {
 	}
 };
 /**
-* Is this pending row our own notice of the SAME kind? `summary` is the kind
-* discriminator, so distinct notices (cadence review vs completion review vs
-* self-improvement) still queue side by side: a repeat of one kind replaces its
-* pending copy instead of adding a second.
-*/
-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.
+* v43 audit (P1-4 / FLOW1): the cadence summary MUST name the review kind — it
+* is what tells the three cadence deliveries apart (their prompts differ by
+* kind: memory / skill / combined), both in the queue and in the session log.
 */
 const cadenceSummary = (kind) => `auto-review:${kind}`;
 function clampReviewConfig(rawConfig, ctx) {
@@ -176,12 +221,12 @@ function apply(ctx, rawConfig = {}) {
 	const turnStarts = sessionState.add("turnStarts", /* @__PURE__ */ new Map());
 	let statelessReviewStateWarned = false;
 	let channelMarkSuppressedWarned = false;
+	let reviewNoticeOutstandingWarned = 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 pendingReviewNotices = sessionState.add("pendingReviewNotices", /* @__PURE__ */ new Map());
 	const cadenceResetWarned = sessionState.add("cadenceResetWarned", /* @__PURE__ */ new Set());
 	let reviewInFlight = false;
 	const policy = () => ctx.get("evolutionPolicy")?.get();
@@ -240,29 +285,83 @@ 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);
-			lastTurnStart.set(session.id, event.data.turn);
-		}
+		if (event.type === "turn/start" && session.header.origin !== "subagent") turnStarts.set(session.id, session.seq - 1);
 		if (event.type === "user/message") {
 			if ((event.data?.source)?.kind === "user") clearReviewChannel(session.id);
 			return;
 		}
 		if (event.type !== "turn/end") return;
-		if (turnStarts.size >= COUNTER_SWEEP_THRESHOLD || pendingCadenceWarned.size >= COUNTER_SWEEP_THRESHOLD || cumulativeToolCalls.size >= COUNTER_SWEEP_THRESHOLD || completionInjected.size >= COUNTER_SWEEP_THRESHOLD || pendingCadenceReviews.size >= COUNTER_SWEEP_THRESHOLD || skipNextCadenceFire.size >= COUNTER_SWEEP_THRESHOLD || cadenceResetWarned.size >= COUNTER_SWEEP_THRESHOLD || lastTurnStart.size >= COUNTER_SWEEP_THRESHOLD) {
+		if (turnStarts.size >= COUNTER_SWEEP_THRESHOLD || pendingCadenceWarned.size >= COUNTER_SWEEP_THRESHOLD || cumulativeToolCalls.size >= COUNTER_SWEEP_THRESHOLD || completionInjected.size >= COUNTER_SWEEP_THRESHOLD || pendingCadenceReviews.size >= COUNTER_SWEEP_THRESHOLD || cadenceResetWarned.size >= COUNTER_SWEEP_THRESHOLD || pendingReviewNotices.size >= COUNTER_SWEEP_THRESHOLD) {
 			const isAlive = (id) => ctx.agents.get(id) !== void 0;
 			sweepDeadSessionEntries(turnStarts, isAlive);
-			sweepDeadSessionEntries(lastTurnStart, isAlive);
 			sweepDeadSessionEntries(cumulativeToolCalls, isAlive);
 			sweepDeadSessionEntries(completionInjected, isAlive);
 			sweepDeadSessionEntries(pendingCadenceReviews, isAlive);
 			sweepDeadSessionEntries(pendingCadenceWarned, isAlive);
-			sweepDeadSessionEntries(skipNextCadenceFire, isAlive);
 			sweepDeadSessionEntries(cadenceResetWarned, isAlive);
+			sweepDeadSessionEntries(pendingReviewNotices, isAlive);
 			sweepReviewChannelSessions((id) => ctx.agents.get(SessionId(id)) !== void 0);
 		}
 		onTurnEnd(session, event);
 	});
+	/**
+	* Settle the session's outstanding notice: drop the record and restart the counting window.
+	*
+	* The window restarts when the notice LEAVES — either the queue dropped it unrun (`discarded`) or
+	* the turn that claimed it ended. The reset runs under the state lock and re-loads the persisted
+	* record before zeroing (V24-04): the in-memory snapshot may be turns old by then, and writing it
+	* back would roll a later turn's counters away.
+	* @param sessionId - the session whose notice settled.
+	* @param why - which exit settled it; carried into the warning only, the effect is the same.
+	*/
+	const settleNotice = async (sessionId, why) => {
+		pendingReviewNotices.delete(sessionId);
+		ctx.logger.warn(`dsh-evolution-review: the outstanding review notice settled (${why}) — the review window restarts`);
+		const stateService = ctx.get("evolutionState");
+		try {
+			await withReviewStateLock(sessionId, async () => {
+				const fresh = await stateService?.loadReviewState(sessionId);
+				if (fresh === void 0 || fresh === null) return;
+				fresh.turnsSinceMemory = 0;
+				fresh.turnsSinceSkill = 0;
+				await stateService?.saveReviewState(sessionId, fresh);
+			});
+		} catch (resetError) {
+			if (!cadenceResetWarned.has(sessionId)) {
+				cadenceResetWarned.add(sessionId);
+				ctx.logger.warn(`dsh-evolution-review: the counting window could not be restarted after a settled review (${why}: ${resetError instanceof Error ? resetError.message : String(resetError)}) — the next boundary may deliver a repeat`);
+			}
+		}
+	};
+	/**
+	* Fold one inbox notification into the session's outstanding-notice record.
+	*
+	* The platform emits these on the agent scope (plain `ctx.on` receives every agent's, which is
+	* how the platform's own plugins consume them); the state machine lives in `review-notice.ts`,
+	* so this only routes the payload and keeps the sweep honest.
+	* @param kind - which notification arrived.
+	* @param payload - the agent, the message and (for a claim) the owning turn.
+	*/
+	const foldNoticeEvent = (kind, payload) => {
+		const sessionId = payload.agent.session.id;
+		const outcome = noticeAfter(pendingReviewNotices.get(sessionId), {
+			kind,
+			message: payload.message,
+			turn: payload.turn
+		});
+		if (outcome.notice === void 0) pendingReviewNotices.delete(sessionId);
+		else pendingReviewNotices.set(sessionId, outcome.notice);
+		if (outcome.settled) settleNotice(sessionId, "discarded");
+	};
+	ctx.on("agent/inbox/inserted", (payload) => {
+		foldNoticeEvent("inserted", payload);
+	});
+	ctx.on("agent/inbox/claimed", (payload) => {
+		foldNoticeEvent("claimed", payload);
+	});
+	ctx.on("agent/inbox/discarded", (payload) => {
+		foldNoticeEvent("discarded", payload);
+	});
 	async function onTurnEnd(session, event) {
 		try {
 			await runOnTurnEnd(session, event);
@@ -288,20 +387,16 @@ 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 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
-		});
+		const outstanding = pendingReviewNotices.get(session.id);
+		const settlesHere = outstanding !== void 0 && outstanding.turn !== null && event.data.turn >= outstanding.turn;
 		let state = {
 			turnsSinceMemory: 0,
 			turnsSinceSkill: 0,
 			lastTurn: -1
 		};
 		const advanced = { kind: null };
-		await withReviewStateLock(session.id, async () => {
+		if (settlesHere) await settleNotice(session.id, "turn-end");
+		else await withReviewStateLock(session.id, async () => {
 			state = await stateService?.loadReviewState(session.id) ?? {
 				turnsSinceMemory: 0,
 				turnsSinceSkill: 0,
@@ -317,7 +412,7 @@ function apply(ctx, rawConfig = {}) {
 			});
 			await stateService?.saveReviewState(session.id, state);
 		});
-		const kind = skipFire ? null : advanced.kind;
+		const kind = advanced.kind;
 		const cumulative = (cumulativeToolCalls.get(session.id) ?? 0) + signal.toolCalls;
 		cumulativeToolCalls.set(session.id, cumulative);
 		if (event.data.reason.kind === "completed") {
@@ -343,19 +438,21 @@ function apply(ctx, rawConfig = {}) {
 					}
 				} 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 === "dropped") {
+					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)}`);
+						}
+						await settleNotice(session.id, "subagent-flush");
+					} else if (reviewOutcome === "dropped") {
 						pendingCadenceReviews.set(session.id, pendingKind);
 						return;
 					} else if (reviewOutcome !== "deferred") {
@@ -377,19 +474,6 @@ function apply(ctx, rawConfig = {}) {
 						}
 					}
 				}
-				try {
-					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);
-						ctx.logger.warn(`dsh-evolution-review: cadence counter reset could not be persisted after a delivered review (${resetError instanceof Error ? resetError.message : String(resetError)}) — a stateful reload may re-deliver this review`);
-					}
-				}
 				return;
 			}
 		}
@@ -401,7 +485,7 @@ function apply(ctx, rawConfig = {}) {
 			}
 			return;
 		}
-		if (skipFire) return;
+		if (settlesHere) return;
 		const trigger = params().skillReviewTrigger;
 		if (trigger !== "completion" && trigger !== "both") return;
 		if (completionInjected.has(session.id)) return;
@@ -465,6 +549,42 @@ function apply(ctx, rawConfig = {}) {
 	* the mark (a host without `inbox` behaves exactly as before).
 	*/
 	const humanQueuedAhead = (inbox) => [...inbox?.nextTurn ?? [], ...inbox?.nextStep ?? []].some((row) => row.source?.kind === "user");
+	/** The one pending row that is a notice of ours, if the host's queue holds one. */
+	const queuedNotice = (inbox) => [...inbox?.nextTurn ?? [], ...inbox?.nextStep ?? []].find((row) => isReviewNotice(row));
+	/**
+	* D 组（兜底）：is one of our notices still outstanding? The record is in-memory, the queue is
+	* durable, so the queue is read here as well — it is the only account that survives a restart or
+	* a mount that missed the live events.
+	*
+	* Two directions have to hold. A queue holding one of our notices with no record means the review
+	* is still waiting (rebuild the record; the `claimed`/`discarded`/`turn/end` pairing then works
+	* as usual). A record saying "still queued" while the queue no longer holds that message means the
+	* notice left without us seeing the event — settle it, or the gate would stay shut for good.
+	* @param sessionId - the session whose window is judged.
+	* @param inbox - the agent's pending-message view; without one the record is all there is.
+	* @returns true while this session must not be asked for another review.
+	*/
+	const noticeIsOutstanding = (sessionId, inbox) => {
+		const record = pendingReviewNotices.get(sessionId);
+		const queued = queuedNotice(inbox);
+		if (record === void 0) {
+			if (queued === void 0) return false;
+			pendingReviewNotices.set(sessionId, {
+				messageId: queued.id,
+				turn: null
+			});
+			return true;
+		}
+		if (record.turn !== null) return true;
+		if (queued !== void 0 && queued.id === record.messageId) return true;
+		settleNotice(sessionId, "queue-lost");
+		if (queued === void 0) return false;
+		pendingReviewNotices.set(sessionId, {
+			messageId: queued.id,
+			turn: null
+		});
+		return true;
+	};
 	/** 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. */
@@ -479,6 +599,15 @@ function apply(ctx, rawConfig = {}) {
 		markReviewChannel(agent.session.id);
 	};
 	const deliverMessage = (agent, text, summary, reviewPrompt = false) => {
+		const wake = agent;
+		const inbox = agent.inbox;
+		if (reviewPrompt && noticeIsOutstanding(agent.session.id, inbox)) {
+			if (!reviewNoticeOutstandingWarned) {
+				reviewNoticeOutstandingWarned = true;
+				ctx.logger.warn("dsh-evolution-review: this session already has an outstanding review notice (still queued, or claimed by a turn that has not ended) — no second prompt is queued; the review runs when that one settles");
+			}
+			return false;
+		}
 		const message = createUserMessage({
 			content: [{
 				type: "text",
@@ -491,42 +620,11 @@ function apply(ctx, rawConfig = {}) {
 				summary
 			}
 		});
-		const wake = agent;
-		const inbox = agent.inbox;
-		if (inbox !== void 0 && typeof inbox.replace === "function") try {
-			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`);
-		}
 		try {
-			if (params().reviewWakeInject && typeof wake.followup === "function") {
-				wake.followup(message);
-				skipNextCadenceFire.set(agent.session.id, { afterTurn: lastTurnStart.get(agent.session.id) ?? -1 });
-			} else agent.inject(message);
+			if (params().reviewWakeInject && typeof wake.followup === "function") wake.followup(message);
+			else agent.inject(message);
 			if (reviewPrompt) markReviewChannelForDelivery(agent, inbox);
+			if (reviewPrompt && inbox === void 0) settleNotice(agent.session.id, "delivery-no-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`);

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

@@ -0,0 +1,74 @@
+/**
+ * The one outstanding review notice of one session, as a pure state machine (A 组).
+ *
+ * Why this exists: the plugin used to model "have I already asked?" with its own latch and to
+ * reset the cadence counter at DELIVERY — three shadows of one fact the platform already owns
+ * (the agent's pending-message queue). This module keeps ONE record instead: whether a notice of
+ * ours is still outstanding, and which turn took it. The queue's own lifecycle events feed it, so
+ * the plugin never invents a second account of the same fact.
+ *
+ * The events are the agent-scoped inbox notifications: `inserted` (a message entered the queue —
+ * which is also what a steer does when it re-inserts the same message into `next-step`),
+ * `claimed` (a turn took it, payload carries that turn) and `discarded` (the queue dropped it
+ * unrun: removed, cleared, or replaced).
+ *
+ * Invariants: the record is per session and there is AT MOST ONE (one outstanding review at a
+ * time); only the notice we were tracking can settle — an event about some other of our messages
+ * leaves the record untouched; nothing here touches counters, io or the locale, which keeps the
+ * whole rule testable without a host.
+ * @module @lmzhen/dsh-evolution-review/review-notice
+ */
+/** The plugin id every notice of this plugin carries in its durable message source. */
+export declare const REVIEW_NOTICE_PLUGIN = "dsh-evolution-review";
+/** The subset of a platform message this module reads. */
+export interface NoticeMessage {
+    readonly id: string;
+    readonly source?: {
+        readonly kind?: string;
+        readonly plugin?: string;
+        readonly form?: string;
+    } | undefined;
+}
+/** One delivered notice that has not settled yet. */
+export interface ReviewNotice {
+    /** The platform identity of the delivered message. */
+    readonly messageId: string;
+    /** The turn that claimed it, or null while it is still waiting in the queue. */
+    readonly turn: number | null;
+}
+/** The three inbox notifications that move a notice from delivery to settlement. */
+export type NoticeEventKind = 'inserted' | 'claimed' | 'discarded';
+/** What one inbox event did to the outstanding notice. */
+export interface NoticeOutcome {
+    /** The record that stands afterwards, or undefined when nothing is outstanding. */
+    readonly notice: ReviewNotice | undefined;
+    /** Whether this event settled the notice we were tracking (the counter resets here). */
+    readonly settled: boolean;
+}
+/**
+ * Whether a message is a notice this plugin delivered, judged only by durable source fields.
+ *
+ * The source — not the record — is what survives a restart, so a rebuild reads the same facts it
+ * would have read live.
+ * @param message - the message the platform reported.
+ * @returns true only for this plugin's own notices.
+ */
+export declare function isReviewNotice(message: NoticeMessage): boolean;
+/**
+ * Fold one inbox event into the session's outstanding notice.
+ *
+ * `inserted` and `claimed` ADOPT the message (last wins): a message of ours that the queue holds or
+ * a turn is running is outstanding by definition, whether or not a record survived a restart.
+ * `discarded` settles whatever we were tracking — or nothing, when the delivery's `inserted` was
+ * never seen — and ignores only the stale case: a record naming a DIFFERENT message means the
+ * current notice is still queued, so that window must not be reset.
+ * @param current - the session's record before this event.
+ * @param event - the inbox notification and its message.
+ * @returns the record afterwards, and whether the tracked notice settled.
+ */
+export declare function noticeAfter(current: ReviewNotice | undefined, event: {
+    readonly kind: NoticeEventKind;
+    readonly message: NoticeMessage;
+    readonly turn?: number | undefined;
+}): NoticeOutcome;
+//# sourceMappingURL=review-notice.d.ts.map

package/lib/types/session-state.d.ts

@@ -5,6 +5,9 @@
  * 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 —
+ * the first and last of those four have since been replaced by the outstanding-
+ * notice window (0.15.2: one record per session, and the claim names the turn), so
+ * only pendingCadenceReviews, pendingCadenceWarned and cadenceResetWarned remain —
  * 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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-review",
   "description": "Background review orchestration (community build)",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "publishConfig": {
     "access": "public"
   },
@@ -27,9 +27,9 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-approval": "^0.15.1",
-    "@lmzhen/dsh-evolution-core": "^0.15.1",
-    "@lmzhen/dsh-evolution-plan-validator": "^0.15.1"
+    "@lmzhen/dsh-evolution-approval": "^0.16.0",
+    "@lmzhen/dsh-evolution-core": "^0.16.0",
+    "@lmzhen/dsh-evolution-plan-validator": "^0.16.0"
   },
   "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.15.1",
-    "@lmzhen/dsh-evolution-policy": "^0.15.1"
+    "@lmzhen/dsh-evolution-state": "^0.16.0",
+    "@lmzhen/dsh-evolution-policy": "^0.16.0"
   },
   "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.15.1",
-    "@lmzhen/dsh-evolution-core": "^0.15.1",
-    "@lmzhen/dsh-evolution-curator": "^0.15.1",
-    "@lmzhen/dsh-evolution-plan-validator": "^0.15.1",
-    "@lmzhen/dsh-evolution-state": "^0.15.1"
+    "@lmzhen/dsh-evolution-approval": "^0.16.0",
+    "@lmzhen/dsh-evolution-core": "^0.16.0",
+    "@lmzhen/dsh-evolution-curator": "^0.16.0",
+    "@lmzhen/dsh-evolution-plan-validator": "^0.16.0",
+    "@lmzhen/dsh-evolution-state": "^0.16.0"
   }
 }