pi-blackhole 0.3.4 → 0.3.5

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");
 }
 

package/src/om/runtime.ts

@@ -10,7 +10,7 @@
  * - markConsolidationError sets 30s retry gate for failed runs.
  */
 import { type Config, type ConfiguredModel, DEFAULTS, loadConfig } from "./config.js";
-import { isCooldownActive, recordCooldown, expireCooldowns, modelKey } from "./cooldown.js";
+import { isCooldownActive, getCooldownEntry, recordCooldown, expireCooldowns, modelKey } from "./cooldown.js";
 
 export type ResolveResult =
 	| { ok: true; model: any; apiKey: string; headers?: Record<string, string>; cooldownApplied?: boolean }
@@ -94,13 +94,17 @@ export class Runtime {
 	 * Tries the candidate list in order:
 	 * 1. Primary stage model → 2. Stage fallbacks → 3. Base config.model → 4. Session model.
 	 *
+	 * Session model fallback can be disabled via config.sessionFallback: false.
+	 * When disabled, returns { ok: false } instead of using the session model,
+	 * allowing the stage to be skipped entirely when all configured OM models fail.
+	 *
 	 * Skips models that are currently in a cooldown window.
 	 * On retryable error (after the agent runs), the model that failed is cooled down
 	 * and the next candidate is tried.  The caller must call `recordRetryableError`
 	 * after the API attempt to mark the failed model.
 	 *
 	 * Returns `ok: true` with the resolved model, or `ok: false` with a reason
-	 * if all candidates (including session model) are exhausted or unavailable.
+	 * if all candidates (including session model, if enabled) are exhausted or unavailable.
 	 */
 	async resolveModel(ctx: ResolveCtx): Promise<ResolveResult> {
 		const candidates = this.buildCandidateList(ctx.stageModel, ctx.stageFallbacks);
@@ -123,8 +127,10 @@ export class Runtime {
 
 			if (isCooldownActive(candidate)) {
 				if (ctx.hasUI && ctx.ui) {
+					const entry = getCooldownEntry(candidate);
+					const reason = entry ? `: ${entry.reason}` : "";
 					ctx.ui.notify(
-						`Observational memory: ${stageName} skipping ${key} (cooldown active)`,
+						`Observational memory: ${stageName} skipping ${key} (cooldown${reason})`,
 						"info",
 					);
 				}
@@ -162,25 +168,40 @@ export class Runtime {
 			};
 		}
 
-		// Fall back to session model
-		const sessionModel = ctx.model;
-		if (!sessionModel) {
-			return { ok: false, reason: `no model available for ${stageName} (all candidates exhausted, no session model)` };
+		// Fall back to session model (if enabled)
+		if (this.config.sessionFallback !== false) {
+			const sessionModel = ctx.model;
+			if (!sessionModel) {
+				return { ok: false, reason: `no model available for ${stageName} (all candidates exhausted, no session model)` };
+			}
+
+			const auth = await ctx.modelRegistry.getApiKeyAndHeaders(sessionModel);
+			if (!auth.ok || !auth.apiKey) {
+				const provider = (sessionModel as { provider?: string }).provider ?? "unknown";
+				return { ok: false, reason: `no API key for session model provider "${provider}"` };
+			}
+
+			return {
+				ok: true,
+				model: sessionModel,
+				apiKey: auth.apiKey as string,
+				headers: auth.headers as Record<string, string> | undefined,
+				cooldownApplied: false,
+			};
 		}
 
-		const auth = await ctx.modelRegistry.getApiKeyAndHeaders(sessionModel);
-		if (!auth.ok || !auth.apiKey) {
-			const provider = (sessionModel as { provider?: string }).provider ?? "unknown";
-			return { ok: false, reason: `no API key for session model provider "${provider}"` };
+		// All configured candidates exhausted and session fallback disabled —
+		// skip the stage entirely.  Info-level to match cooldown-disabled pattern.
+		// Set resolveFailureNotified so the consolidation layer doesn't duplicate.
+		if (ctx.hasUI && ctx.ui) {
+			ctx.ui.notify(
+				`Observational memory: ${stageName} skipped — all candidates failed (sessionFallback disabled, won't use main model)`,
+				"info",
+			);
 		}
+		this.resolveFailureNotified = true;
 
-		return {
-			ok: true,
-			model: sessionModel,
-			apiKey: auth.apiKey as string,
-			headers: auth.headers as Record<string, string> | undefined,
-			cooldownApplied: false,
-		};
+		return { ok: false, reason: `no model available for ${stageName} (all candidates exhausted, sessionFallback disabled)` };
 	}
 
 	/**

package/src/sections.ts

@@ -4,7 +4,6 @@
  * Upstream: https://github.com/sting8k/pi-vcc (src/sections.ts)
  * Unmodified.
  */
-import type { TranscriptEntry } from "./core/brief";
 
 export interface SectionData {
   sessionGoal: string[];
@@ -13,6 +12,4 @@ export interface SectionData {
   commits: string[];
   userPreferences: string[];
   briefTranscript: string;
-  /** Structured transcript entries (verbose object format) */
-  transcriptEntries: TranscriptEntry[];
 }

package/src/tools/recall.ts

@@ -138,7 +138,11 @@ async function vccRecall(params: { query?: string; expand?: number[]; page?: num
 
 	// Merge expanded entries into full result set BEFORE pagination
 	// so pagination counts and positioning stay consistent
+	let appendedExpandCount = 0;
 	if (expandedFullEntries) {
+		// Track expand-only entries that don't match the query so the header can distinguish them
+		const existingIndices = new Set(allResults.map((r) => r.index));
+		appendedExpandCount = expandedFullEntries.filter((fe) => !existingIndices.has(fe.index)).length;
 		allResults = mergeExpandedIntoSearchResults(allResults, expandedFullEntries);
 	}
 
@@ -148,9 +152,10 @@ async function vccRecall(params: { query?: string; expand?: number[]; page?: num
 		const pageResults: SearchHit[] = allResults.slice(start, start + PAGE_SIZE);
 		const totalPages = Math.ceil(allResults.length / PAGE_SIZE);
 		const scopeSuffix = scope === "all" ? " (scope: all)" : "";
+		const matchCount = allResults.length - appendedExpandCount;
 		const header = totalPages > 1
-			? `Page ${page}/${totalPages} (${allResults.length} total matches${scopeSuffix})`
-			: `${allResults.length} matches${scopeSuffix}`;
+			? `Page ${page}/${totalPages} (${matchCount} matches${appendedExpandCount > 0 ? ` + ${appendedExpandCount} expanded` : ""}${scopeSuffix})`
+			: `${matchCount} matches${appendedExpandCount > 0 ? ` (+ ${appendedExpandCount} expanded)` : ""}${scopeSuffix}`;
 		const footer = page < totalPages
 			? `\n--- Use page:${page + 1}${scope === "all" ? " with scope:'all'" : ""} for more results ---`
 			: "";