pi-blackhole 0.3.4 → 0.3.7

package/src/om/consolidation.ts

@@ -15,7 +15,7 @@ import type { ModelThinkingLevel } from "@earendil-works/pi-ai";
 import type { ConfiguredModel } from "./config.js";
 import { debugLog, withDebugLogContext } from "./debug-log.js";
 import { type ResolveResult, type Runtime } from "./runtime.js";
-import { isRetryableError } from "./cooldown.js";
+import { isRetryableError } from "./retryable-error.js";
 import { effectiveContextWindow } from "./model-budget.js";
 import { serializeSourceAddressedBranchEntries } from "./serialize.js";
 
@@ -27,6 +27,7 @@ import {
 	savePendingReflection,
 	savePendingDropped,
 	isObservationChunkPending,
+	PendingOMState,
 } from "./pending.js";
 import {
 	OM_OBSERVATIONS_DROPPED,
@@ -98,6 +99,8 @@ function capSourceEntriesToTokens(entries: Entry[], maxTokens: number): Entry[]
 	for (let i = entries.length - 1; i >= 0; i--) {
 		const entry = entries[i];
 		let chars = 0;
+		// Tokenize all entry types, not just "message": custom_message and
+		// branch_summary entries also consume observer context window.
 		if (entry.type === "message" && entry.message) {
 			const msg = entry.message as any;
 			if (typeof msg.content === "string") chars = msg.content.length;
@@ -106,9 +109,25 @@ function capSourceEntriesToTokens(entries: Entry[], maxTokens: number): Entry[]
 					if (block.text) chars += block.text.length;
 				}
 			}
+		} else if (entry.type === "custom" && (entry.customType === OM_OBSERVATIONS_RECORDED || entry.customType === OM_REFLECTIONS_RECORDED || entry.customType === OM_OBSERVATIONS_DROPPED)) {
+			// Custom entries carry structured data — estimate from JSON serialization
+			chars = String(JSON.stringify(entry.data ?? {})).length;
+		} else if (entry.summary) {
+			chars = String(entry.summary).length;
 		}
 		const estTokens = Math.ceil(chars / 4);
 		if (totalTokens + estTokens > maxTokens && kept.length > 0) break;
+		// Remove the `kept.length > 0` guard? No — keep the guard but allow
+		// the first entry to be dropped only if it exceeds maxTokens alone.
+		// (The guard against empty kept list prevents dropping the first entry
+		// when later entries are small; but a single oversized entry should
+		// still be included to avoid losing the newest data entirely.)
+		if (totalTokens + estTokens > maxTokens && kept.length === 0) {
+			// First (newest) entry exceeds maxTokens alone — include it anyway
+			// to avoid data loss, but don't add more.
+			kept.unshift(entry);
+			break;
+		}
 		kept.unshift(entry);
 		totalTokens += estTokens;
 	}
@@ -140,7 +159,7 @@ function mergeReflections(existing: Reflection[], additional: Reflection[]): Ref
  * should still be served as "new" on subsequent runs.
  */
 function pendingObservationsCreatedAfter(
-	pending: any,
+	pending: PendingOMState,
 	entries: Entry[],
 	afterCoversUpToId: string | undefined,
 ): Observation[] {
@@ -315,8 +334,6 @@ async function runObserverStage(
 	// of processing everything including the compaction summary.
 	const effectiveStart = lastCoverageIdx >= 0 ? lastCoverageIdx : findLastCompactionIndex(entries);
 	let chunkEntries = sourceEntriesAfter(entries, effectiveStart);
-	const coversUpToId = chunkEntries.at(-1)?.id;
-	if (!coversUpToId) return "continue";
 
 	// Cap observer input to observerChunkMaxTokens (newest-to-oldest)
 	const maxChunkTokens = runtime.config.observerChunkMaxTokens;
@@ -324,6 +341,10 @@ async function runObserverStage(
 		chunkEntries = capSourceEntriesToTokens(chunkEntries, maxChunkTokens);
 	}
 
+	// coversUpToId must point to the LAST entry AFTER capping, not before
+	const coversUpToId = chunkEntries.at(-1)?.id;
+	if (!coversUpToId) return "continue";
+
 	const { text: chunk, sourceEntryIds } = serializeSourceAddressedBranchEntries(chunkEntries);
 	if (!chunk.trim() || sourceEntryIds.length === 0) return "continue";
 	const chunkTokens = Math.ceil(chunk.length / 4);
@@ -390,8 +411,9 @@ async function runObserverStage(
 		const stageModelForThinking = runtime.findCandidateConfig(resolved.model, { model: ctx.model, modelRegistry: ctx.modelRegistry, hasUI: ctx.hasUI, ui: ctx.ui, stageModel: stageModelConfig(runtime, "observer"), stageFallbacks: stageFallbackModels(runtime, "observer") });
 
 		// Check if estimated input fits in model's context window
+		// Use actual chunk tokens (already computed) instead of the configured cap
 		const effectiveObsCtx = effectiveContextWindow(resolved.model as any, stageModelForThinking);
-		const observerEstimatedInput = runtime.config.observerChunkMaxTokens + AGENT_LOOP_RESERVE;
+		const observerEstimatedInput = chunkTokens + AGENT_LOOP_RESERVE;
 		if (observerEstimatedInput > effectiveObsCtx) {
 			debugLog("observer.context_window_exceeded", { estimatedInput: observerEstimatedInput, effectiveCtx: effectiveObsCtx, model: `${(resolved.model as any).provider}/${(resolved.model as any).id}` });
 			runtime.recordRetryableError(stageModelForThinking, new Error(`context window ${effectiveObsCtx} too small for estimated input ${observerEstimatedInput}`), "observer");
@@ -474,7 +496,7 @@ async function runReflectorStage(
 ): Promise<ReflectorStageResult> {
 	const sessionId = ctx.sessionManager.getSessionId();
 	const entries = ctx.sessionManager.getBranch() as Entry[];
-	let reflectionTokens: number;
+	let reflectionTokens = 0;
 	let observationCoverageId: string | undefined;
 	if (runtime.config.noAutoCompact) {
 		const pending = readPendingState(sessionId);
@@ -523,8 +545,7 @@ async function runReflectorStage(
 		// Adjust accumulated for pending coverage in noAutoCompact mode
 		let effectiveReflectionTokens = reflectionTokens;
 		if (runtime.config.noAutoCompact) {
-			const pending = readPendingState(sessionId);
-			if (pending.reflection?.coversUpToId) {
+			if (pending?.reflection?.coversUpToId) {
 				const idx = entryIndexForId(entries, pending.reflection.coversUpToId);
 				if (idx >= 0) effectiveReflectionTokens = rawTokensAfterIndex(entries, idx);
 			}
@@ -535,8 +556,9 @@ async function runReflectorStage(
 		const stageModelForThinking = runtime.findCandidateConfig(resolved.model, { model: ctx.model, modelRegistry: ctx.modelRegistry, hasUI: ctx.hasUI, ui: ctx.ui, stageModel: stageModelConfig(runtime, "reflector"), stageFallbacks: stageFallbackModels(runtime, "reflector") });
 
 		// Check if estimated input fits in model's context window
+		// Use actual computed input size (new items + summary budget) instead of cap
 		const effectiveRefCtx = effectiveContextWindow(resolved.model as any, stageModelForThinking);
-		const reflectorEstimatedInput = runtime.config.reflectorInputMaxTokens + AGENT_LOOP_RESERVE;
+		const reflectorEstimatedInput = reflectorInputTokens + AGENT_LOOP_RESERVE;
 		if (reflectorEstimatedInput > effectiveRefCtx) {
 			debugLog("reflector.context_window_exceeded", { estimatedInput: reflectorEstimatedInput, effectiveCtx: effectiveRefCtx, model: `${(resolved.model as any).provider}/${(resolved.model as any).id}` });
 			runtime.recordRetryableError(stageModelForThinking, new Error(`context window ${effectiveRefCtx} too small for estimated input ${reflectorEstimatedInput}`), "reflector");
@@ -614,7 +636,7 @@ async function runDropperStage(
 ): Promise<StageOutcome> {
 	const sessionId = ctx.sessionManager.getSessionId();
 	const entries = ctx.sessionManager.getBranch() as Entry[];
-	let dropTokens: number;
+	let dropTokens = 0;
 	let observationCoverageId: string | undefined;
 	if (runtime.config.noAutoCompact) {
 		const pending = readPendingState(sessionId);
@@ -661,8 +683,7 @@ async function runDropperStage(
 		// Adjust accumulated for pending coverage in noAutoCompact mode
 		let effectiveDropTokens = dropTokens;
 		if (runtime.config.noAutoCompact) {
-			const pending = readPendingState(sessionId);
-			if (pending.dropped?.coversUpToId) {
+			if (pending?.dropped?.coversUpToId) {
 				const idx = entryIndexForId(entries, pending.dropped.coversUpToId);
 				if (idx >= 0) effectiveDropTokens = rawTokensAfterIndex(entries, idx);
 			}
@@ -692,8 +713,9 @@ async function runDropperStage(
 			const stageModelForThinking = runtime.findCandidateConfig(resolved.model, { model: ctx.model, modelRegistry: ctx.modelRegistry, hasUI: ctx.hasUI, ui: ctx.ui, stageModel: stageModelConfig(runtime, "dropper"), stageFallbacks: stageFallbackModels(runtime, "dropper") });
 
 			// Check if estimated input fits in model's context window
+			// Use actual computed input size (new observations + summary budget) instead of cap
 			const effectiveDropCtx = effectiveContextWindow(resolved.model as any, stageModelForThinking);
-			const dropperEstimatedInput = runtime.config.dropperInputMaxTokens + AGENT_LOOP_RESERVE;
+			const dropperEstimatedInput = dropperInputTokens + AGENT_LOOP_RESERVE;
 			if (dropperEstimatedInput > effectiveDropCtx) {
 				debugLog("dropper.context_window_exceeded", { estimatedInput: dropperEstimatedInput, effectiveCtx: effectiveDropCtx, model: `${(resolved.model as any).provider}/${(resolved.model as any).id}` });
 				runtime.recordRetryableError(stageModelForThinking, new Error(`context window ${effectiveDropCtx} too small for estimated input ${dropperEstimatedInput}`), "dropper");

package/src/om/cooldown.ts

@@ -79,24 +79,32 @@ function writeCooldownMap(map: CooldownMap): void {
  * When cooldownHours is explicitly 0, cooldown is disabled — always returns false.
  */
 export function isCooldownActive(model: OmModelConfig, now: Date = new Date()): boolean {
+	return getCooldownEntry(model, now) !== undefined;
+}
+
+/**
+ * Returns the active cooldown entry for a model, or undefined if not cooled down.
+ * Expired entries are cleaned up lazily.
+ */
+export function getCooldownEntry(model: OmModelConfig, now: Date = new Date()): CooldownEntry | undefined {
 	// cooldownHours === 0 means cooldown disabled
-	if (model.cooldownHours === 0) return false;
+	if (model.cooldownHours === 0) return undefined;
 
 	const map = readCooldownMap();
 	const key = modelKey(model);
 	const entry = map[key];
-	if (!entry) return false;
+	if (!entry) return undefined;
 
 	const until = new Date(entry.until);
-	if (isNaN(until.getTime())) return false;
+	if (isNaN(until.getTime())) return undefined;
 
 	if (now >= until) {
 		// Expired — clean up
 		delete map[key];
 		writeCooldownMap(map);
-		return false;
+		return undefined;
 	}
-	return true;
+	return entry;
 }
 
 /**
@@ -137,11 +145,6 @@ export function expireCooldowns(): void {
 	if (changed) writeCooldownMap(map);
 }
 
-/** Regex matching retryable API error messages. */
-const RETRYABLE_ERROR_RE = /(?:\b|^)(?:overloaded|provider|rate\s*limit|too\s+many\s+requests|429|500|502|503|504|timeout|timed?\s*out|network\s*error|connection\s*error|service\s*unavailable|server\s*error|internal\s*error|fetch\s*failed|upstream|websocket\s*closed|retry)(?:\b|$)/i;
+import { isRetryableError } from "./retryable-error.js";
 
-/** Check whether an error string or Error indicates a retryable error. */
-export function isRetryableError(error: unknown): boolean {
-	const message = error instanceof Error ? error.message : String(error || "");
-	return RETRYABLE_ERROR_RE.test(message);
-}
+export { isRetryableError };

package/src/om/debug-log.ts

@@ -1,11 +1,15 @@
 /**
  * Debug logging — writes JSONL to ~/.pi/agent/pi-blackhole/debug.ndjson.
  *
+ * Uses a memory buffer flushed asynchronously on a timer to avoid blocking
+ * the event loop with synchronous disk I/O on every event.
+ *
  * Upstream: https://github.com/elpapi42/pi-observational-memory (src/debug-log.ts)
- * Modified: path changed from observational-memory/ to pi-blackhole/.
+ * Modified: path changed from observational-memory/ to pi-blackhole/; async buffered.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
 import { existsSync, mkdirSync, renameSync, statSync, unlinkSync, appendFileSync } from "node:fs";
+import { appendFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
@@ -25,25 +29,89 @@ export function withDebugLogContext<T>(context: DebugLogContext, fn: () => T): T
 	return storage.run({ ...parent, ...context }, fn);
 }
 
+// ── Async buffer ────────────────────────────────────────────────────────────
+
+const BUFFER_FLUSH_MS = 1_000;
+const FLUSH_IDLE_MS = 10_000;
+let buffer: string[] = [];
+let flushTimer: ReturnType<typeof setInterval> | null = null;
+let flushing = false;
+let lastWriteMs = 0;
+
+function ensureFlushTimer(): void {
+	if (flushTimer) return;
+	flushTimer = setInterval(() => {
+		// Stop the timer if buffer has been empty for a while
+		if (buffer.length === 0 && lastWriteMs > 0 && Date.now() - lastWriteMs > FLUSH_IDLE_MS) {
+			clearInterval(flushTimer!);
+			flushTimer = null;
+			return;
+		}
+		flushBuffer().catch(() => {});
+	}, BUFFER_FLUSH_MS);
+	// Don't prevent process exit
+	if (flushTimer && typeof flushTimer === "object" && "unref" in flushTimer) {
+		flushTimer.unref();
+	}
+}
+
+async function flushBuffer(): Promise<void> {
+	if (flushing) return;
+	if (buffer.length === 0) return;
+	flushing = true;
+	// Drain the buffer atomically so flushDebugLog doesn't split entries
+	const batch = buffer;
+	buffer = [];
+	try {
+		const path = join(getAgentDir(), DEBUG_LOG_RELATIVE_PATH);
+		mkdirSync(dirname(path), { recursive: true });
+		rotateIfNeeded(path);
+		await appendFile(path, batch.join(""), "utf-8");
+	} catch (error) {
+		console.error("blackhole: debug log write failed", error);
+	} finally {
+		flushing = false;
+	}
+}
+
+// Flush remaining buffer on exit — synchronous to work with process.exit() too
+process.on("exit", () => {
+	flushDebugLog();
+});
+
 export function debugLog(event: string, data: Record<string, unknown> = {}, forceEnabled?: boolean): void {
 	const context = storage.getStore();
 	const enabled = forceEnabled ?? context?.enabled ?? false;
 	if (enabled !== true) return;
 
+	const payload = {
+		ts: new Date().toISOString(),
+		event,
+		cwd: context?.cwd,
+		runId: context?.runId,
+		data,
+	};
+	buffer.push(JSON.stringify(payload) + "\n");
+	lastWriteMs = Date.now();
+	ensureFlushTimer();
+}
+
+/**
+ * Synchronously flush the buffer to disk. Used by tests to verify written content.
+ * Skips if an async flush is in progress to avoid splitting the buffer.
+ * In production, the background timer handles flushing automatically.
+ */
+export function flushDebugLog(): void {
+	if (flushing || buffer.length === 0) return;
+	const batch = buffer;
+	buffer = [];
 	try {
 		const path = join(getAgentDir(), DEBUG_LOG_RELATIVE_PATH);
 		mkdirSync(dirname(path), { recursive: true });
 		rotateIfNeeded(path);
-		const payload = {
-			ts: new Date().toISOString(),
-			event,
-			cwd: context?.cwd,
-			runId: context?.runId,
-			data,
-		};
-		appendFileSync(path, `${JSON.stringify(payload)}\n`, "utf-8");
-	} catch {
-		// Debug logging must never affect memory behavior.
+		appendFileSync(path, batch.join(""), "utf-8");
+	} catch (error) {
+		console.error("blackhole: debug log flush failed", error);
 	}
 }
 

package/src/om/key-matcher.ts

@@ -1,38 +1,12 @@
 /**
  * Terminal utilities shared by blackhole overlay components.
  *
- * visibleWidth — CJK-aware visible width for terminal columns,
- * extracted from pi-tui to avoid import resolution issues.
+ * Re-exports visibleWidth from pi-tui.
  *
- * Ported from voice-type extension's key-matcher.ts.
+ * Previously had a local CJK-width implementation extracted from pi-tui
+ * to avoid import resolution issues in the overlay TUI context.
+ * If this re-export causes runtime resolution failures, restore the
+ * local copy (see git history for the original implementation).
  */
 
-// ---------------------------------------------------------------------------
-// Visible width (CJK-aware)
-// ---------------------------------------------------------------------------
-
-function stripAnsi(s: string): string {
-	return s.replace(/\x1b\[[0-9;]*m/g, "");
-}
-
-/**
- * Calculate the visible width of a string in terminal columns.
- * Strips ANSI codes and counts CJK characters as width 2.
- */
-export function visibleWidth(s: string): number {
-	const stripped = stripAnsi(s);
-	let w = 0;
-	for (const ch of stripped) {
-		const code = ch.codePointAt(0)!;
-		if (code >= 0x1100 && (code <= 0x115f || code === 0x2329 || code === 0x232a ||
-			(code >= 0x2e80 && code <= 0xa4cf) || (code >= 0xac00 && code <= 0xd7a3) ||
-			(code >= 0xf900 && code <= 0xfaff) || (code >= 0xfe30 && code <= 0xfe6f) ||
-			(code >= 0xff01 && code <= 0xff60) || (code >= 0xffe0 && code <= 0xffe6) ||
-			(code >= 0x1b000 && code <= 0x1b0ff) || (code >= 0x20000 && code <= 0x2fa1f))) {
-			w += 2;
-		} else {
-			w += 1;
-		}
-	}
-	return w;
-}
+export { visibleWidth } from "@earendil-works/pi-tui";

package/src/om/ledger/fold.ts

@@ -15,6 +15,7 @@ import {
 	type Observation,
 	type Reflection,
 } from "./types.js";
+import { debugLog } from "../debug-log.js";
 
 export type FoldLedgerOptions = {
 	/** Fold entries from branch root through this entry id, inclusive. Omit to fold through branch tip. */
@@ -88,6 +89,13 @@ export function foldLedger(entries: Entry[], options: FoldLedgerOptions = {}): F
 			for (const observationId of entry.data.observationIds) {
 				droppedObservationIds.add(observationId);
 			}
+			continue;
+		}
+
+		// Log unknown custom entry types — they are silently skipped, but
+		// should be visible when debugging extension compatibility issues.
+		if (entry.type === "custom" && entry.customType) {
+			debugLog("fold.unknown_custom_type", { customType: entry.customType, entryId: entry.id });
 		}
 	}
 

package/src/om/ledger/render-summary.ts

@@ -6,20 +6,16 @@
  */
 import type { Observation, Reflection } from "./types.js";
 
-const RECALL_NOTE =
-	"Use `recall` to search for prior work, decisions, and context from before this summary. " +
-	"Do not redo work already completed.";
+const OM_INSTRUCTIONS_FULL = `Bracketed ids in reflections and observations connect to their source session entries. These are condensed memories from earlier in this session.
+When entries conflict, the most recent observation reflects the latest known state.
+Use \`recall\` with an id to retrieve original context, or \`#N:path\` drill-down to explore file content from referenced entries.
+When exact source context is needed for precision or traceability, use the \`recall\` tool with the relevant observation or reflection id. This is especially useful when a reflection materially affects a decision or is too compressed to continue confidently.`;
 
-const CONTEXT_USAGE_INSTRUCTIONS = `These are condensed memories from earlier in this session.
+const OM_INSTRUCTIONS_BASIC = `Use \`recall\` with an id to retrieve original context, or \`#N:path\` drill-down to explore file content from referenced entries.
+When entries conflict, the most recent entry reflects the latest known state.`;
 
-- Reflections: stable, long-lived facts about the user, project, decisions, and constraints. New reflection lines may include ids in brackets.
-- Observations: timestamped events from the conversation history, in chronological order. Observation lines include ids in brackets.
-
-Treat these as past records. When entries conflict, the most recent observation reflects the latest known state. Work that prior observations describe as completed should not be redone unless the user explicitly asks to revisit it.
-
-When exact source context is needed for precision or traceability, use the \`recall\` tool with the relevant observation or reflection id. This is especially useful when a reflection materially affects a decision or is too compressed to continue confidently. Do not use \`recall\` as broad search or inject raw source unless it is needed.`;
-
-export const OM_FOOTER = `----\n${RECALL_NOTE}\n\n${CONTEXT_USAGE_INSTRUCTIONS}\n----`;
+export const OM_FOOTER_FULL = `----\n${OM_INSTRUCTIONS_FULL}\n----`;
+export const OM_FOOTER_BASIC = `----\n${OM_INSTRUCTIONS_BASIC}\n----`;
 
 export function observationToSummaryLine(observation: Observation): string {
 	return `[${observation.id}] ${observation.timestamp} [${observation.relevance}] ${observation.content}`;
@@ -81,7 +77,7 @@ export function reflectionToSummaryLine(reflection: Reflection): string {
 }
 
 export function renderSummary(reflections: Reflection[], observations: Observation[]): string {
-	if (reflections.length === 0 && observations.length === 0) return "";
+	const hasContent = reflections.length > 0 || observations.length > 0;
 
 	const parts: string[] = [];
 	if (reflections.length > 0) {
@@ -90,6 +86,11 @@ export function renderSummary(reflections: Reflection[], observations: Observati
 	if (observations.length > 0) {
 		parts.push(`## Observations\n${observations.map(observationToSummaryLine).join("\n")}`);
 	}
-	parts.push(OM_FOOTER);
-	return parts.join("\n\n");
+
+	const footer = hasContent ? OM_FOOTER_FULL : OM_FOOTER_BASIC;
+	if (parts.length > 0) {
+		parts.push(footer);
+		return parts.join("\n\n");
+	}
+	return footer;
 }

package/src/om/ledger/types.ts

@@ -12,7 +12,7 @@ export const OM_FOLDED = "om.folded";
 export const RELEVANCE_VALUES = ["low", "medium", "high", "critical"] as const;
 export type Relevance = (typeof RELEVANCE_VALUES)[number];
 
-export const MEMORY_ID_PATTERN = /^[a-f0-9]{12}$/;
+export const MEMORY_ID_PATTERN = /^[a-f0-9]{12}$/i;
 
 export type Entry = {
 	type: string;

package/src/om/pending.ts

@@ -106,7 +106,7 @@ function readSessionState(sessionId: string): PendingOMState {
 
 	try {
 		const raw = JSON.parse(readFileSync(path, "utf-8"));
-		if (isPendingOMState(raw)) return raw;
+		if (isPendingOMState(raw)) return sanitizePendingState(raw);
 		return defaultState();
 	} catch {
 		return defaultState();
@@ -150,16 +150,49 @@ function writeSessionState(sessionId: string, state: PendingOMState): void {
 	}
 }
 
-/**
- * Validate that an unknown value is a valid PendingOMState.
- */
+/** Validate that unknown value is shape-compatible with PendingOMState. */
 function isPendingOMState(value: unknown): value is PendingOMState {
 	if (!value || typeof value !== "object") return false;
 	const v = value as Record<string, unknown>;
 	const hasObs = !!(v.observation && typeof v.observation === "object" && typeof (v.observation as any).coversUpToId === "string");
 	const hasRef = !!(v.reflection && typeof v.reflection === "object" && typeof (v.reflection as any).coversUpToId === "string");
 	const hasDrop = !!(v.dropped && typeof v.dropped === "object" && typeof (v.dropped as any).coversUpToId === "string");
-	return hasObs || hasRef || hasDrop;
+	// Also accept states with only batch arrays (no singular fields)
+	const hasBatches = Array.isArray(v.observationBatches) || Array.isArray(v.reflectionBatches) || Array.isArray(v.droppedBatches);
+	return hasObs || hasRef || hasDrop || hasBatches;
+}
+
+/**
+ * Sanitize pending state: filter out corrupted batch entries (missing required fields).
+ * Returns a clean copy; does not mutate the input.
+ */
+function sanitizePendingState(raw: PendingOMState): PendingOMState {
+	const sanitized: PendingOMState = {
+		...raw,
+		observation: raw.observation ?? undefined,
+		reflection: raw.reflection ?? undefined,
+		dropped: raw.dropped ?? undefined,
+	};
+	// Filter batch arrays to only include valid entries with the required shape
+	if (Array.isArray(raw.observationBatches)) {
+		sanitized.observationBatches = raw.observationBatches.filter(
+			(b): b is PendingObservation =>
+				!!b && typeof b === "object" && typeof (b as any).coversUpToId === "string" && (b as any).data !== undefined,
+		);
+	}
+	if (Array.isArray(raw.reflectionBatches)) {
+		sanitized.reflectionBatches = raw.reflectionBatches.filter(
+			(b): b is PendingReflection =>
+				!!b && typeof b === "object" && typeof (b as any).coversUpToId === "string" && (b as any).data !== undefined,
+		);
+	}
+	if (Array.isArray(raw.droppedBatches)) {
+		sanitized.droppedBatches = raw.droppedBatches.filter(
+			(b): b is PendingDropped =>
+				!!b && typeof b === "object" && typeof (b as any).coversUpToId === "string" && (b as any).data !== undefined,
+		);
+	}
+	return sanitized;
 }
 
 // ── API ─────────────────────────────────────────────────────────────────────

package/src/om/provider-stream.ts

@@ -0,0 +1,17 @@
+/**
+ * Bridge streamSimple to support custom providers via global Symbol.for().
+ *
+ * When a custom provider is registered (via index.ts at startup), its stream
+ * function is stored under a shared global symbol. This module provides the
+ * bridge logic so all OM agents (observer, reflector, dropper) use the same
+ * custom-provider resolution instead of each duplicating the 15-line function.
+ */
+export function createBridgeStreamFn(streamSimple: any) {
+	const PROVIDER_STREAMS_KEY = Symbol.for("pi-blackhole:provider-streams");
+	return (model: any, ctx: any, opts: any) => {
+		const providerStreams: Map<string, Function> | undefined = (globalThis as any)[PROVIDER_STREAMS_KEY];
+		if (!providerStreams) return streamSimple(model, ctx, opts);
+		const customFn = model?.api ? providerStreams.get(model.api) : undefined;
+		return customFn ? customFn(model, ctx, opts) : streamSimple(model, ctx, opts);
+	};
+}

package/src/om/retryable-error.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared retryable-error regex and detection function.
+ *
+ * Extracted from compaction-trigger.ts and cooldown.ts which had diverging
+ * copies of the same logic. This is the single source of truth.
+ *
+ * Now also re-exports Pi's context-overflow detection from @earendil-works/pi-ai,
+ * avoiding the need to duplicate 20+ provider-specific overflow patterns.
+ */
+
+/** Regex matching retryable API error messages. */
+export const RETRYABLE_ERROR_RE =
+  /overloaded|provider.?returned.?error|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|network.?error|connection.?error|connection.?refused|connection.?lost|websocket.?closed|websocket.?error|other side closed|fetch failed|upstream.?connect|reset before headers|socket hang up|ended without|http2 request did not get a response|timed? out|timeout|terminated|retry delay/i;
+
+/** Check whether an error string or Error indicates a retryable error. */
+export function isRetryableError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error || "");
+  return RETRYABLE_ERROR_RE.test(message);
+}
+
+/**
+ * Re-export Pi's context-overflow detection so blackhole callers use one
+ * authoritative source instead of maintaining their own provider-specific patterns.
+ * @see @earendil-works/pi-ai/dist/utils/overflow.d.ts
+ */
+export { isContextOverflow } from "@earendil-works/pi-ai";

package/src/om/reverse-recall.ts

@@ -82,7 +82,7 @@ export function findReflectionsForEntryIds(
 
 export function formatRelatedObservations(
 	observations: RelatedObservation[],
-	_reflections: RelatedReflection[],
+	reflections: RelatedReflection[],
 ): string {
 	const parts: string[] = [];
 
@@ -97,6 +97,14 @@ export function formatRelatedObservations(
 		}
 	}
 
+	if (reflections.length > 0) {
+		if (parts.length > 0) parts.push("");
+		parts.push("Related reflections:");
+		for (const ref of reflections) {
+			parts.push(`  [${ref.memoryId}] ${ref.content}`);
+		}
+	}
+
 	return parts.join("\n");
 }