pi-blackhole 0.3.3 → 0.3.5

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,
@@ -59,9 +60,9 @@ import {
 	type Reflection,
 } from "./ledger/index.js";
 
-type ResolvedModel = Extract<ResolveResult, { ok: true }>;
+export type ResolvedModel = Extract<ResolveResult, { ok: true }>;
 
-type ConsolidationCtx = {
+export type ConsolidationCtx = {
 	cwd: string;
 	hasUI: boolean;
 	ui?: { notify: (message: string, type?: "warning" | "info" | "error") => void };
@@ -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[] {
@@ -182,15 +201,16 @@ function stageThinkingLevel(runtime: Runtime, stage: "observer" | "reflector" |
 	return stageModel?.thinking ?? runtime.config.model?.thinking ?? "low";
 }
 
-function makeModelResolver(runtime: Runtime, ctx: ConsolidationCtx): (stage: "observer" | "reflector" | "dropper") => Promise<ResolvedModel | undefined> {
+export function makeModelResolver(runtime: Runtime, ctx: ConsolidationCtx): (stage: "observer" | "reflector" | "dropper") => Promise<ResolvedModel | undefined> {
 	return async (stage) => {
+		const stageFallbacks = stageFallbackModels(runtime, stage);
 		const resolved = await runtime.resolveModel({
 			model: ctx.model,
 			modelRegistry: ctx.modelRegistry,
 			hasUI: ctx.hasUI,
 			ui: ctx.ui,
 			stageModel: stageModelConfig(runtime, stage),
-			stageFallbacks: stageFallbackModels(runtime, stage),
+			stageFallbacks,
 		});
 		if (resolved.ok) {
 			runtime.resolveFailureNotified = false;
@@ -198,7 +218,17 @@ function makeModelResolver(runtime: Runtime, ctx: ConsolidationCtx): (stage: "ob
 		}
 		debugLog(`${stage}.model_unavailable`, { reason: resolved.reason });
 		if (!runtime.resolveFailureNotified && ctx.hasUI && ctx.ui) {
-			ctx.ui.notify(`Observational memory: ${stage} skipped — ${resolved.reason}`, "warning");
+			if (runtime.failedInCycle.size > 0 && resolved.reason.includes("all candidates exhausted")) {
+				const fallbackMsg = stageFallbacks.length === 0
+					? "no fallbacks configured"
+					: "no available fallbacks";
+				ctx.ui.notify(
+					`Observational memory: ${stage} skipped — model unavailable (cooldown set to 0, ${fallbackMsg}, will retry next run)`,
+					"info",
+				);
+			} else {
+				ctx.ui.notify(`Observational memory: ${stage} skipped — ${resolved.reason}`, "warning");
+			}
 			runtime.resolveFailureNotified = true;
 		}
 		return undefined;
@@ -254,6 +284,8 @@ export async function runConsolidationPipeline(
 	const resolveModel = makeModelResolver(runtime, ctx);
 
 	runtime.consolidationPhase = "observer";
+	runtime.failedInCycle.clear();
+	runtime.resolveFailureNotified = false;
 	try {
 		const observerOutcome = await runObserverStage(pi, runtime, ctx, resolveModel);
 		if (observerOutcome === "abort") return;
@@ -263,6 +295,8 @@ export async function runConsolidationPipeline(
 	}
 
 	runtime.consolidationPhase = "reflector";
+	runtime.failedInCycle.clear();
+	runtime.resolveFailureNotified = false;
 	let reflectorResult: ReflectorStageResult;
 	try {
 		reflectorResult = await runReflectorStage(pi, runtime, ctx, resolveModel);
@@ -273,6 +307,8 @@ export async function runConsolidationPipeline(
 	}
 
 	runtime.consolidationPhase = "dropper";
+	runtime.failedInCycle.clear();
+	runtime.resolveFailureNotified = false;
 	try {
 		await runDropperStage(pi, runtime, ctx, resolveModel, reflectorResult.sameRunReflections, reflectorResult.effectiveReflectionCoverageId);
 	} catch (error) {
@@ -298,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;
@@ -307,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);
@@ -373,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");
@@ -457,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);
@@ -506,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);
 			}
@@ -518,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");
@@ -597,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);
@@ -644,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);
 			}
@@ -675,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

@@ -75,33 +75,51 @@ function writeCooldownMap(map: CooldownMap): void {
 /**
  * Check whether a model is currently cooled down.
  * Expired entries are cleaned up lazily.
+ *
+ * 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 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;
 }
 
 /**
  * Record a cooldown for a model after a retryable error.
  *
+ * When cooldownHours is explicitly 0, cooldown is disabled — no-op.
+ *
  * @param model   The model that failed.
  * @param reason  Human-readable error reason (e.g. "429 Too Many Requests").
  * @param stage   Which pipeline stage failed ("observer" | "reflector" | "dropper").
  */
 export function recordCooldown(model: OmModelConfig, reason: string, stage: string): void {
+	// cooldownHours === 0 means cooldown disabled
+	if (model.cooldownHours === 0) return;
+
 	const hours = model.cooldownHours ?? 1;
 	const until = new Date(Date.now() + hours * 3_600_000).toISOString();
 	const map = readCooldownMap();
@@ -127,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,72 +1,12 @@
 /**
  * Terminal utilities shared by blackhole overlay components.
  *
- * Key matcher — standalone replacement for pi-tui's `matchesKey`
- * to keep overlay components free of that dependency.
+ * Re-exports visibleWidth from pi-tui.
  *
- * visibleWidth — CJK-aware visible width for terminal columns,
- * extracted from pi-tui to avoid import resolution issues.
- *
- * 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).
  */
 
-// ---------------------------------------------------------------------------
-// Key matching
-// ---------------------------------------------------------------------------
-
-export function matchKey(data: string, key: string): boolean {
-	// Escape
-	if (key === "escape") return data === "\x1b";
-	// Enter
-	if (key === "enter") return data === "\r" || data === "\n";
-	// Tab
-	if (key === "tab") return data === "\t";
-	// Space
-	if (key === "space") return data === " ";
-	// Backspace
-	if (key === "backspace") return data === "\x7f" || data === "\b";
-	// Arrows
-	if (key === "up") return data === "\x1b[A" || data === "\x1bOA";
-	if (key === "down") return data === "\x1b[B" || data === "\x1bOB";
-	if (key === "left") return data === "\x1b[D" || data === "\x1bOD";
-	if (key === "right") return data === "\x1b[C" || data === "\x1bOC";
-	// Ctrl+letter (must be exactly 6 chars: "ctrl+" + one lowercase letter)
-	if (key.startsWith("ctrl+") && key.length === 6) {
-		const letter = key[5];
-		if (letter && letter >= "a" && letter <= "z") {
-			const code = letter.charCodeAt(0) - 96; // ctrl+a = 1, ctrl+z = 26
-			return data.length === 1 && data.charCodeAt(0) === code;
-		}
-	}
-	return false;
-}
-
-// ---------------------------------------------------------------------------
-// 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);
+	};
+}