@iowarp/clio-coder 0.5.0 → 0.5.2

package/src/domains/memory/prompt-cache.ts

@@ -0,0 +1,95 @@
+import { createHash } from "node:crypto";
+import { canonicalMemoryRepositoryIdentity } from "./operations.js";
+import { buildMemoryPromptSection, type MemoryPromptOptions } from "./prompt-section.js";
+import { MEMORY_RELEVANCE_VERSION } from "./relevance.js";
+import { readMemoryStoreSnapshot } from "./store.js";
+
+/** Host-owned attempt identity, distinct from the ledger ID allocated after preflight. */
+export interface MemoryPromptRequest {
+	readonly turnId: string | null;
+	readonly sessionAuthority: string;
+	readonly cwd: string;
+	readonly targetId: string;
+	readonly runtimeId: string;
+	readonly modelId: string;
+	readonly taskText: string;
+	readonly activePaths: readonly string[];
+	readonly activeSymbols?: readonly string[];
+}
+
+export interface MemoryPromptReaderOptions {
+	getDataDir: () => string;
+	/** Explicit experiment only; production leaves relevance off. */
+	experimentalRelevance?: boolean;
+	selection?: Pick<MemoryPromptOptions, "scopes" | "tokenBudget" | "maxItems">;
+	/** Source seam for deterministic read-count tests; production reads the real bounded store. */
+	readStore?: typeof readMemoryStoreSnapshot;
+}
+
+/**
+ * Single-entry immutable text cache. A new prepared operator attempt rereads the
+ * store; ordinary external edits become visible at the next attempt. Within an
+ * attempt/its admitted continuations, selection is frozen, except authority
+ * changes (session/branch, data root, canonical repo, actual target/runtime/model).
+ * Calls without a prepared turn (boot/reset prewarm) read each time. Later
+ * prewarm can reuse the preceding snapshot; a fresh attempt always rereads.
+ */
+export function createMemoryPromptReader(options: MemoryPromptReaderOptions): (request: MemoryPromptRequest) => string {
+	// Copy options now: mutable caller arrays must not silently change eligibility.
+	const selection = { ...options.selection, scopes: [...(options.selection?.scopes ?? ["global", "repo", "runtime"])] };
+	const experimentalRelevance = options.experimentalRelevance === true;
+	const readStore = options.readStore ?? readMemoryStoreSnapshot;
+	let frame: { key: string; section: string } | null = null;
+	let selected: { key: string; section: string } | null = null;
+	return (request) => {
+		const dataDir = options.getDataDir();
+		const activeRepository = canonicalMemoryRepositoryIdentity(request.cwd);
+		const authority = JSON.stringify([
+			dataDir,
+			request.sessionAuthority,
+			request.cwd,
+			activeRepository,
+			request.targetId,
+			request.runtimeId,
+			request.modelId,
+		]);
+		const frameKey = JSON.stringify([request.turnId, authority]);
+		if (request.turnId !== null && frame?.key === frameKey) return frame.section;
+		let section = "";
+		try {
+			const snapshot = readStore(dataDir);
+			const relevance = {
+				taskText: request.taskText,
+				activePaths: [...request.activePaths],
+				activeSymbols: [...(request.activeSymbols ?? [])],
+			};
+			const key = createHash("sha256")
+				.update(
+					JSON.stringify([
+						snapshot.revision,
+						authority,
+						selection,
+						relevance,
+						experimentalRelevance,
+						MEMORY_RELEVANCE_VERSION,
+					]),
+				)
+				.digest("hex");
+			if (selected?.key === key) section = selected.section;
+			else {
+				section = buildMemoryPromptSection(snapshot.records, {
+					...selection,
+					activeRepository,
+					activeRuntime: { kind: "runtime", key: request.runtimeId },
+					...(experimentalRelevance ? { relevance } : {}),
+				}).section;
+				selected = Object.freeze({ key, section });
+			}
+		} catch {
+			// A failed fresh read revokes old approved content, including its cache.
+			selected = null;
+		}
+		frame = request.turnId === null ? null : Object.freeze({ key: frameKey, section });
+		return section;
+	};
+}

package/src/domains/memory/prompt-section.ts

@@ -1,4 +1,6 @@
-import { estimateMemoryTokens, selectApprovedMemory } from "./operations.js";
+import { ceilChars } from "../session/context-accounting.js";
+import { eligibleMemoryRecords } from "./operations.js";
+import { type MemoryRelevanceInput, type RankedMemoryCandidate, rankMemoryByRelevance } from "./relevance.js";
 import type {
 	MemoryAgentIdentity,
 	MemoryRecord,
@@ -21,6 +23,8 @@ export const MEMORY_PROMPT_DEFAULT_MAX_ITEMS = 5;
 export const MEMORY_PROMPT_DEFAULT_SCOPES: ReadonlyArray<MemoryScope> = ["global", "repo"];
 
 export interface MemoryPromptOptions {
+	/** Explicit experiment only; omitted options preserve legacy priority. */
+	relevance?: MemoryRelevanceInput;
 	scopes?: ReadonlyArray<MemoryScope>;
 	tokenBudget?: number;
 	maxItems?: number;
@@ -42,18 +46,51 @@ export function selectMemoryForPrompt(
 	records: ReadonlyArray<MemoryRecord>,
 	options: MemoryPromptOptions = {},
 ): MemoryRecord[] {
+	return inspectMemoryPromptSelection(records, options).records;
+}
+
+export interface MemoryPromptDecision {
+	id: string;
+	reason: "selected" | "token-budget" | "item-limit";
+	relevance?: Omit<RankedMemoryCandidate, "record">;
+}
+
+/** Diagnostics cover eligible candidates only: excluded records are never scored. */
+export function inspectMemoryPromptSelection(
+	records: ReadonlyArray<MemoryRecord>,
+	options: MemoryPromptOptions = {},
+): { records: MemoryRecord[]; decisions: MemoryPromptDecision[] } {
 	const scopes = options.scopes ?? MEMORY_PROMPT_DEFAULT_SCOPES;
 	const tokenBudget = options.tokenBudget ?? MEMORY_PROMPT_DEFAULT_TOKEN_BUDGET;
 	const maxItems = options.maxItems ?? MEMORY_PROMPT_DEFAULT_MAX_ITEMS;
-	if (tokenBudget <= 0 || maxItems <= 0) return [];
-	const selected = selectApprovedMemory(records, {
+	if (!Number.isFinite(tokenBudget) || !Number.isFinite(maxItems) || tokenBudget <= 0 || maxItems < 1)
+		return { records: [], decisions: [] };
+	const eligibility = {
 		scopes,
-		tokenBudget,
 		activeRepository: options.activeRepository ?? null,
 		activeRuntime: options.activeRuntime ?? null,
 		activeAgent: options.activeAgent ?? null,
-	});
-	return selected.slice(0, maxItems);
+	};
+	const candidates =
+		options.relevance === undefined
+			? eligibleMemoryRecords(records, eligibility).map((record) => ({ record, relevance: undefined }))
+			: rankMemoryByRelevance(records, eligibility, options.relevance).map(({ record, ...relevance }) => ({
+					record,
+					relevance,
+				}));
+	const selected: MemoryRecord[] = [];
+	const decisions: MemoryPromptDecision[] = [];
+	for (const { record, relevance } of candidates) {
+		const reason =
+			selected.length >= Math.floor(maxItems)
+				? "item-limit"
+				: ceilChars(renderMemoryPromptSection([...selected, record]).length) > tokenBudget
+					? "token-budget"
+					: "selected";
+		decisions.push({ id: record.id, reason, ...(relevance === undefined ? {} : { relevance }) });
+		if (reason === "selected") selected.push(record);
+	}
+	return { records: selected, decisions };
 }
 
 /**
@@ -74,10 +111,16 @@ export function renderMemoryPromptSection(records: ReadonlyArray<MemoryRecord>):
 		const lesson = record.lesson.replace(/\s+/g, " ").trim();
 		const evidence = record.evidenceRefs.join(", ");
 		lines.push(`- [${record.id}] (${renderApplicability(record)}) ${lesson} Evidence: ${evidence}.`);
+		if (record.appliesWhen.length > 0) lines.push(`  Applies when: ${record.appliesWhen.map(compactText).join("; ")}.`);
+		if (record.avoidWhen.length > 0) lines.push(`  Avoid when: ${record.avoidWhen.map(compactText).join("; ")}.`);
 	}
 	return lines.join("\n");
 }
 
+function compactText(value: string): string {
+	return value.replace(/\s+/g, " ").trim();
+}
+
 function renderApplicability(record: MemoryRecord): string {
 	if (record.scope === "repo") {
 		if (record.repository !== undefined) {
@@ -101,6 +144,6 @@ export function buildMemoryPromptSection(
 ): { section: string; records: MemoryRecord[]; tokens: number } {
 	const selected = selectMemoryForPrompt(records, options);
 	const section = renderMemoryPromptSection(selected);
-	const tokens = selected.reduce((acc, record) => acc + estimateMemoryTokens(record), 0);
+	const tokens = ceilChars(section.length);
 	return { section, records: selected, tokens };
 }

package/src/domains/memory/relevance.ts

@@ -0,0 +1,93 @@
+import { eligibleMemoryRecords } from "./operations.js";
+import type { MemoryRecord, MemoryRetrievalOptions } from "./types.js";
+
+/** Versioned, deterministic heuristic; not a semantic applicability or truth check. */
+export const MEMORY_RELEVANCE_VERSION = "lexical-v1";
+export const MEMORY_RELEVANCE_WEIGHTS = { taskTerm: 1, path: 8, symbol: 4 } as const;
+
+export interface MemoryRelevanceInput {
+	readonly taskText: string;
+	readonly activePaths?: readonly string[];
+	readonly activeSymbols?: readonly string[];
+}
+
+export interface RankedMemoryCandidate {
+	readonly record: MemoryRecord;
+	readonly score: number;
+	readonly matches: {
+		readonly taskTerms: readonly string[];
+		readonly paths: readonly string[];
+		readonly symbols: readonly string[];
+	};
+	readonly fallback: boolean;
+}
+
+const STOP_WORDS = new Set(["and", "are", "for", "from", "into", "the", "this", "that", "with", "use", "when"]);
+
+function normalized(value: string): string {
+	return value.normalize("NFKC").toLowerCase();
+}
+
+function terms(value: string): string[] {
+	return [...new Set(normalized(value.replace(/([a-z])([A-Z])/g, "$1 $2")).match(/[\p{L}\p{N}]+/gu) ?? [])].filter(
+		(term) => term.length >= 2 && !STOP_WORDS.has(term),
+	);
+}
+
+function pathKey(value: string): string {
+	return normalized(value).replaceAll("\\", "/").replace(/^\.\//, "");
+}
+
+/**
+ * Gates are identical to legacy retrieval and run before scoring. Text features
+ * use NFKC/lowercase exact Unicode terms; paths/symbols match whole lexical
+ * features, never filesystem ancestry or fuzzy substrings. Task features are
+ * bounded to 64 terms, 32 explicit paths, and 32 symbols in supplied order.
+ * Evidence IDs and avoidWhen do not create positive relevance.
+ *
+ * One legacy-priority zero-overlap lesson gets an early opportunity after the
+ * first positive hit. This can displace a relevant item and cannot guarantee
+ * that general constraints fit a finite budget. All other ties retain legacy
+ * verification/creation-time then ID order. No input record is mutated.
+ */
+export function rankMemoryByRelevance(
+	records: ReadonlyArray<MemoryRecord>,
+	options: Omit<MemoryRetrievalOptions, "tokenBudget">,
+	input: MemoryRelevanceInput,
+): RankedMemoryCandidate[] {
+	const taskTerms = terms(input.taskText).slice(0, 64);
+	const paths = [...new Set((input.activePaths ?? []).map(pathKey).filter(Boolean))].slice(0, 32);
+	const symbols = [...new Set((input.activeSymbols ?? []).map(normalized).filter(Boolean))].slice(0, 32);
+	const candidates = eligibleMemoryRecords(records, options).map((record): RankedMemoryCandidate => {
+		const text = [record.key, record.lesson, ...record.appliesWhen].join("\n");
+		const textTerms = new Set(terms(text));
+		const textPaths = new Set(
+			(text.match(/[\p{L}\p{N}_./\\:-]+/gu) ?? []).map((path) => pathKey(path.replace(/[.:]+$/, ""))),
+		);
+		const textSymbols = new Set(normalized(text).match(/[\p{L}\p{N}_$]+/gu) ?? []);
+		const matches = {
+			taskTerms: taskTerms.filter((term) => textTerms.has(term)),
+			paths: paths.filter((path) => textPaths.has(path)),
+			symbols: symbols.filter((symbol) => textSymbols.has(symbol)),
+		};
+		return {
+			record,
+			matches,
+			fallback: false,
+			score:
+				matches.taskTerms.length * MEMORY_RELEVANCE_WEIGHTS.taskTerm +
+				matches.paths.length * MEMORY_RELEVANCE_WEIGHTS.path +
+				matches.symbols.length * MEMORY_RELEVANCE_WEIGHTS.symbol,
+		};
+	});
+	// Stable sorting preserves the already established legacy tie ordering.
+	candidates.sort((a, b) => b.score - a.score);
+	if ((candidates[0]?.score ?? 0) > 0) {
+		const fallbackIndex = candidates.findIndex((candidate) => candidate.score === 0);
+		if (fallbackIndex >= 0) {
+			const [fallback] = candidates.splice(fallbackIndex, 1);
+			if (fallback !== undefined) candidates.splice(1, 0, { ...fallback, fallback: true });
+		}
+	}
+	return candidates;
+}

package/src/domains/memory/restoration.ts

@@ -0,0 +1,78 @@
+import { ceilChars } from "../session/context-accounting.js";
+import type { TaskMemoryEntry, TaskMemorySnapshot } from "./task-bank.js";
+
+export interface MemoryRestorationInput {
+	readonly bank: {
+		readonly version: TaskMemorySnapshot["version"];
+		readonly status: Readonly<TaskMemoryEntry> | null;
+		readonly knowledge: readonly Readonly<TaskMemoryEntry>[];
+		readonly procedural: readonly Readonly<TaskMemoryEntry>[];
+	};
+	/** Already admitted current state. Only nonblank text suppresses historical status; it is never recopied. */
+	readonly currentState: { readonly kind: "handoff" | "summary"; readonly text: string } | null;
+	readonly maxTokens: number;
+}
+
+export interface MemoryRestorationRender {
+	readonly message: string;
+	readonly tokens: number;
+	readonly citedEntryIds: readonly string[];
+	readonly omittedEntryIds: readonly string[];
+}
+
+const PREFIX = "Memory: remembered execution context (unverified; current instructions take precedence).\n";
+
+/**
+ * Pure conservative renderer. lastTouchedAt is only a recency/usage heuristic,
+ * never verification. Equal whitespace-normalized content shares one rendered
+ * row with all source IDs; near duplicates remain distinct. Knowledge and
+ * procedure have equal access in recency order, with ID as the stable tie.
+ * Nothing is deleted, marked injected, promoted, or inferred to be current.
+ */
+export function renderMemoryRestoration(input: MemoryRestorationInput): MemoryRestorationRender {
+	const hasCurrentState = input.currentState !== null && input.currentState.text.trim().length > 0;
+	const source = [
+		...(!hasCurrentState && input.bank.status !== null ? [input.bank.status] : []),
+		...input.bank.knowledge,
+		...input.bank.procedural,
+	].sort((a, b) => {
+		const status = Number(b.kind === "status") - Number(a.kind === "status");
+		return status || b.lastTouchedAt.localeCompare(a.lastTouchedAt) || a.id.localeCompare(b.id);
+	});
+	const groups = new Map<string, { ids: string[]; kinds: Set<TaskMemoryEntry["kind"]>; content: string }>();
+	for (const entry of source) {
+		const content = entry.content.replace(/\s+/gu, " ").trim();
+		const group = groups.get(content);
+		if (group) {
+			if (!group.ids.includes(entry.id)) group.ids.push(entry.id);
+			group.kinds.add(entry.kind);
+		} else groups.set(content, { ids: [entry.id], kinds: new Set([entry.kind]), content: entry.content });
+	}
+	const lines: string[] = [];
+	const cited: string[] = [];
+	const omitted = hasCurrentState && input.bank.status !== null ? [input.bank.status.id] : [];
+	const validBudget = Number.isFinite(input.maxTokens) && input.maxTokens > 0;
+	for (const [content, group] of groups) {
+		const kinds = [...group.kinds]
+			.sort()
+			.map((kind) => (kind === "status" ? "historical status" : `remembered ${kind}`))
+			.join("/");
+		// Quote the chosen source losslessly, including its original whitespace.
+		// Normalization above is only the dedup key, never a rewrite of evidence.
+		const line = `- ${group.ids.map((id) => `[${id}]`).join(" ")} ${kinds}: ${JSON.stringify(group.content)}`;
+		const candidate = PREFIX + [...lines, line].join("\n");
+		if (!validBudget || content.length === 0 || ceilChars(candidate.length) > input.maxTokens) {
+			omitted.push(...group.ids);
+			continue;
+		}
+		lines.push(line);
+		cited.push(...group.ids);
+	}
+	const message = lines.length > 0 ? PREFIX + lines.join("\n") : "";
+	return Object.freeze({
+		message,
+		tokens: ceilChars(message.length),
+		citedEntryIds: Object.freeze(cited),
+		omittedEntryIds: Object.freeze(omitted),
+	});
+}

package/src/domains/memory/store.ts

@@ -1,4 +1,5 @@
-import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { closeSync, openSync, readFileSync, readSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { safeResourceWrite } from "../../core/safe-resource-write.js";
@@ -8,6 +9,43 @@ import { validateMemoryStore } from "./validate.js";
 export const MEMORY_STORE_MAX_RECORDS = 500;
 export const MEMORY_STALE_APPROVED_DAYS = 180;
 export const MEMORY_STALE_UNAPPROVED_DAYS = 30;
+/** Prompt compilation fails closed above this read ceiling; store writers are unchanged. */
+export const MEMORY_PROMPT_STORE_MAX_BYTES = 16 * 1024 * 1024;
+
+export interface MemoryStoreSnapshot {
+	revision: string;
+	records: MemoryRecord[];
+}
+
+/** Hash the exact bounded bytes read, so same-size external replacements invalidate selection. */
+export function readMemoryStoreSnapshot(dataDir: string): MemoryStoreSnapshot {
+	const path = memoryStorePath(dataDir);
+	let fd: number;
+	try {
+		fd = openSync(path, "r");
+	} catch (error) {
+		if (isErrorWithCode(error) && error.code === "ENOENT") return { revision: "missing", records: [] };
+		throw error;
+	}
+	const chunks: Buffer[] = [];
+	let total = 0;
+	try {
+		while (true) {
+			const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, MEMORY_PROMPT_STORE_MAX_BYTES + 1 - total));
+			const count = readSync(fd, chunk);
+			if (count === 0) break;
+			total += count;
+			if (total > MEMORY_PROMPT_STORE_MAX_BYTES) throw new Error("memory prompt store exceeds read ceiling");
+			chunks.push(chunk.subarray(0, count));
+		}
+	} finally {
+		closeSync(fd);
+	}
+	const raw = Buffer.concat(chunks);
+	const records = parseAndValidate(raw.toString("utf8"), path);
+	if (records.length > MEMORY_STORE_MAX_RECORDS) throw new Error("memory prompt store exceeds record limit");
+	return { revision: createHash("sha256").update(raw).digest("hex"), records };
+}
 
 export function memoryRoot(dataDir: string): string {
 	return join(dataDir, "memory");

package/src/domains/middleware/memory-intervention.ts

@@ -8,6 +8,13 @@ import {
 	sanitizeToolResultDigest,
 	type ToolResultDigest,
 } from "../../tools/result-disposition.js";
+import {
+	type MemoryCommitScope,
+	MemoryCommitState,
+	type MemoryRestorationOffer,
+	type SuccessfulMemoryContextCommit,
+} from "../memory/commit-state.js";
+import type { MemoryRestorationInput } from "../memory/restoration.js";
 import { TASK_MEMORY_DEFAULT_PROCEDURAL_CAP, type TaskMemoryBank, type TaskMemoryEntry } from "../memory/task-bank.js";
 import {
 	runTaskMemoryPolicy,
@@ -119,7 +126,7 @@ export interface MemoryInterventionDeps {
 	 * closed. The composition root buffers it into the next submitted turn, which
 	 * is where a synchronous turn_end reminder would have landed anyway.
 	 */
-	onDeferredReminder?: (message: string) => void;
+	onDeferredReminder?: (message: string, isCurrent?: () => boolean) => void;
 	/**
 	 * False when no further turn will be submitted in this process. A background
 	 * step is detached from the boundary that triggered it and a local route
@@ -145,6 +152,14 @@ export interface MemoryPromptedStepResult extends TaskMemoryPolicyResult {
 }
 
 export interface MemoryInterventionRegistration extends MiddlewareHookRegistration {
+	bindCommitScope(scope: MemoryCommitScope): void;
+	notifyContextCommitted(input: SuccessfulMemoryContextCommit): void;
+	prepareRestoration(
+		currentState: MemoryRestorationInput["currentState"],
+		maxTokens: number,
+	): MemoryRestorationOffer | null;
+	acknowledgeRestoration(offer: MemoryRestorationOffer): boolean;
+	isContentCurrent(): () => boolean;
 	/** Invalidate pending content and discard all transient session/branch state. */
 	reset(): void;
 	/** Invalidate immediately without waiting for the model; refuse further work. */
@@ -177,6 +192,20 @@ export interface MemoryInterventionRegistration extends MiddlewareHookRegistrati
  */
 export function createMemoryInterventionRegistration(deps: MemoryInterventionDeps): MemoryInterventionRegistration {
 	let generation = 0;
+	let commitState: MemoryCommitState | null = null;
+	let commitScope: MemoryCommitScope | null = null;
+	let commitBridgeEnabled = false;
+	const captureContentGuard = (): (() => boolean) => {
+		const capturedGeneration = generation;
+		const owner = commitState;
+		const scope = commitScope;
+		const stamp = owner?.capture();
+		return () =>
+			!disposed &&
+			generation === capturedGeneration &&
+			commitState === owner &&
+			(!owner || (!!stamp && !!scope && owner.isCurrent(stamp, scope)));
+	};
 	let generationController = new AbortController();
 	let observedSessionId: string | undefined;
 	let disposed = false;
@@ -207,6 +236,40 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 	let consecutiveLlmTimeouts = 0;
 
 	return {
+		bindCommitScope(scope) {
+			commitBridgeEnabled = true;
+			if (
+				commitScope?.sessionId === scope.sessionId &&
+				commitScope.branchAnchorTurnId === scope.branchAnchorTurnId &&
+				commitState
+			)
+				return;
+			if (commitState) reset();
+			commitScope = { ...scope };
+			commitState = new MemoryCommitState(scope, generation);
+			observedSessionId = scope.sessionId;
+		},
+		notifyContextCommitted(input) {
+			commitState?.notifyContextCommitted(input, generation);
+		},
+		prepareRestoration(currentState, maxTokens) {
+			if (!commitScope || !settings().enabled) return null;
+			return (
+				commitState?.prepareRestoration({
+					scope: commitScope,
+					generation,
+					bank: deps.bank.snapshot(),
+					currentState,
+					maxTokens: Math.min(maxTokens, settings().maxTokens),
+				}) ?? null
+			);
+		},
+		acknowledgeRestoration(offer) {
+			if (!commitScope || !commitState?.acknowledgeRestoration(offer, commitScope, generation)) return false;
+			deps.bank.recordInjection(offer.citedEntryIds);
+			return true;
+		},
+		isContentCurrent: captureContentGuard,
 		reset,
 		dispose(): void {
 			disposed = true;
@@ -257,7 +320,7 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 						// Recall grows the working set; it is an observability point, not
 						// context loss that should reactivate compacted task memory.
 						if (input.metadata?.stage === "working_set_recall") return NO_EFFECTS;
-						reactivateAfterCompaction = true;
+						if (!commitBridgeEnabled) reactivateAfterCompaction = true;
 						return NO_EFFECTS;
 					case "turn_start": {
 						if (input.text?.trim()) currentTask = shortText(input.text, 2_000);
@@ -346,6 +409,7 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 					false);
 			rulesInjectedSincePromptedStep = false;
 			const stepGeneration = generation;
+			const contentCurrent = captureContentGuard();
 			promptedStepInFlight = true;
 			outstandingStep = runPromptedStep({
 				deterministicTrigger: triggers.some((trigger) => trigger !== "interval"),
@@ -353,14 +417,14 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 				triggerReasons: triggers,
 			})
 				.then((result) => {
-					if (stepGeneration !== generation || disposed) return;
+					if (!contentCurrent()) return;
 					// A rules-only reminder can win the visible boundary while the optional
 					// background route resolves to null. Preserve the operator-visible
 					// injected outcome instead of overwriting it with that no-client silence.
 					if (rulesAlreadySpoke && result.decision === "silent") lastDecision = "injected";
 					if (result.reminder === null) return;
 					lastInjectedMessage = result.reminder;
-					deps.onDeferredReminder?.(result.reminder);
+					deps.onDeferredReminder?.(result.reminder, contentCurrent);
 				})
 				.catch(() => {
 					// runPromptedStep already resolves failures to silence; this only
@@ -393,6 +457,7 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 		// Retain completed bank entries, but revoke pending content and delivery
 		// authority. Late provider usage still belongs to its captured origin.
 		generation += 1;
+		commitState?.cancel(generation);
 		generationController.abort();
 		generationController = new AbortController();
 		promptedStepInFlight = false;
@@ -408,6 +473,9 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 	}
 
 	function reset(): void {
+		commitState?.dispose();
+		commitState = null;
+		commitScope = null;
 		generation += 1;
 		generationController.abort();
 		generationController = new AbortController();
@@ -466,7 +534,8 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 		});
 		const live = settings();
 		const stepGeneration = generation;
-		const isCurrent = () => !disposed && stepGeneration === generation;
+		const isCurrent = captureContentGuard();
+		const isUsageCurrent = () => !disposed && stepGeneration === generation;
 		const usageSink = deps.captureStepUsage?.();
 		if (disposed || !live.enabled) {
 			const result = silent("no_client");
@@ -504,7 +573,7 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 							isCurrent,
 							signal: generationController.signal,
 							onStepUsage: (usage) => {
-								if (usageSink) usageSink(usage, isCurrent());
+								if (usageSink) usageSink(usage, isUsageCurrent());
 								else deps.onStepUsage?.(usage);
 							},
 							task: input.task?.trim() || currentTask,
@@ -515,7 +584,13 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 							...(input.suppressIntervention === undefined ? {} : { suppressIntervention: input.suppressIntervention }),
 							previousReminder: lastInjectedMessage,
 							timeoutMs,
-							...(deps.onEnvelope === undefined ? {} : { onEnvelope: deps.onEnvelope }),
+							...(deps.onEnvelope === undefined
+								? {}
+								: {
+										onEnvelope: (envelope: TaskMemoryEnvelope) => {
+											if (isCurrent()) deps.onEnvelope?.(envelope);
+										},
+									}),
 						});
 					const remainingMs = () => Math.floor(live.timeoutMs - Number(process.hrtime.bigint() - started) / 1_000_000);
 					const initialTimeoutMs = remainingMs();
@@ -557,17 +632,18 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 			// runTaskMemoryPolicy resolves its own failures, so reaching here means
 			// resolving the client itself threw. That is still a broken route.
 			promptedResult = silent("client_error");
-			deps.onEnvelope?.({
-				systemPrompt: "",
-				userPrompt: "",
-				response: "",
-				decision: "silent",
-				reason: "client_error",
-				bankOperations: 0,
-				droppedOperations: 0,
-				reminder: null,
-				error: error instanceof Error ? error.message : "resolving the background model client failed",
-			});
+			if (isCurrent())
+				deps.onEnvelope?.({
+					systemPrompt: "",
+					userPrompt: "",
+					response: "",
+					decision: "silent",
+					reason: "client_error",
+					bankOperations: 0,
+					droppedOperations: 0,
+					reminder: null,
+					error: error instanceof Error ? error.message : "resolving the background model client failed",
+				});
 		}
 		if (!isCurrent()) return { ...promptedResult, reminder: null, effects: NO_EFFECTS };
 		if (promptedResult.reason === "endpoint_busy") telemetryDecision = "dropped";
@@ -705,6 +781,14 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 		};
 		trajectory.push(step);
 		if (trajectory.length > live.windowSteps) trajectory.splice(0, trajectory.length - live.windowSteps);
+		if (input.metadata?.resultKind === "ok") {
+			// Only an explicit receipt for this exact operation closes its failure
+			// episode. Keep the bank entry and trajectory as history; this does not
+			// verify the surrounding task or reinterpret tool exit classifications.
+			failures.delete(step.operationFingerprint);
+			annotatedThisTurn.delete(step.operationFingerprint);
+			if (lastInjectedOperationFingerprint === step.operationFingerprint) lastInjectedOperationFingerprint = null;
+		}
 		if (outcome !== "error") return NO_EFFECTS;
 		rememberFailure(step);
 		return annotateRepeatedFailure(step);
@@ -718,11 +802,15 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 	 */
 	function annotateRepeatedFailure(step: TrajectoryStep): ReadonlyArray<MiddlewareEffect> {
 		if (annotatedThisTurn.has(step.operationFingerprint)) return NO_EFFECTS;
+		const failure = failures.get(step.operationFingerprint);
+		if (failure === undefined) return NO_EFFECTS;
 		const occurrences = trajectory.filter(
-			(candidate) => candidate.outcome === "error" && candidate.operationFingerprint === step.operationFingerprint,
+			(candidate) =>
+				candidate.outcome === "error" &&
+				candidate.operationFingerprint === step.operationFingerprint &&
+				candidate.step >= failure.firstStep,
 		).length;
-		const failure = failures.get(step.operationFingerprint);
-		if (occurrences < 2 || failure === undefined) return NO_EFFECTS;
+		if (occurrences < 2) return NO_EFFECTS;
 		const message = boundedReminder(
 			`Memory: [${failure.entryId}] you already tried ${failure.callDescription} at step ${failure.firstStep} and it failed with ${failure.errorDigest}. Change the approach rather than repeating it.`,
 			settings().maxTokens,
@@ -780,11 +868,15 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 				) {
 					continue;
 				}
+				const failure = failures.get(step.operationFingerprint);
+				if (failure === undefined || step.step < failure.firstStep) continue;
 				const occurrences = trajectory.filter(
-					(candidate) => candidate.outcome === "error" && candidate.operationFingerprint === step.operationFingerprint,
+					(candidate) =>
+						candidate.outcome === "error" &&
+						candidate.operationFingerprint === step.operationFingerprint &&
+						candidate.step >= failure.firstStep,
 				).length;
-				const failure = failures.get(step.operationFingerprint);
-				if (occurrences < 2 || failure === undefined) continue;
+				if (occurrences < 2) continue;
 				const message = boundedReminder(
 					`Memory: [${failure.entryId}] you already tried ${failure.callDescription} at step ${failure.firstStep} and it failed with ${failure.errorDigest}.`,
 					settings().maxTokens,