pi-blackhole 0.2.3 → 0.3.1

package/src/core/search-entries.ts

@@ -6,13 +6,39 @@
  */
 import type { Message } from "@earendil-works/pi-ai";
 import type { RenderedEntry } from "./render-entries";
-import { textOf } from "./content";
+import { textOf, toolCallArgsText, isContentBearing } from "./content";
+import type { RecallMode } from "./recall-scope";
+
+export interface FileMatch {
+  /** Name of the tool (write, edit, hex_edit) */
+  toolName: string;
+  /** File path from the tool call arguments */
+  path: string;
+  /** Number of lines in the content that matched the query */
+  lineCount: number;
+  /** First matching line snippet (only populated for top matches) */
+  snippet?: string;
+}
+
+/** A file touched in one entry — used by mode:touched aggregation. */
+export interface FileTouch {
+  index: number;
+  toolName: string;
+}
+
+/** Aggregated view of a file touched across multiple entries. */
+export interface TouchedFile {
+  path: string;
+  entries: FileTouch[];
+}
 
 export interface SearchHit extends RenderedEntry {
   /** Context snippet around the first matched term (only when query provided) */
   snippet?: string;
   /** Number of query terms matched (for ranking) */
   matchCount?: number;
+  /** Per-file match indicators from content-bearing tool calls */
+  fileMatches?: FileMatch[];
 }
 
 const escapeRegex = (s: string): string =>
@@ -153,18 +179,131 @@ const lineSnippet = (text: string, regex: RegExp, contextLines = 2): string | un
   return parts.join("\n");
 };
 
-/** Build full searchable text for a message. */
-const fullText = (msg: Message): string => {
+/** Build full searchable text for a message, optionally filtered by mode. */
+const fullText = (msg: Message, mode?: RecallMode): string => {
   if ((msg as any).role === "bashExecution") {
+    if (mode === "file") return ""; // bash is not file content
     return `${(msg as any).command ?? ""} ${(msg as any).output ?? ""}`;
   }
-  return textOf(msg.content);
+  if (mode === "file") {
+    return toolCallArgsText(msg.content);
+  }
+  if (mode === "transcript") {
+    return textOf(msg.content);
+  }
+  // hybrid (default): both
+  const text = textOf(msg.content);
+  const toolArgs = toolCallArgsText(msg.content);
+  return toolArgs ? `${text}\n${toolArgs}` : text;
 };
 
+/**
+ * Extract searchable text from tool call arguments (content, edits, oldText, newText).
+ */
+function extractToolCallText(args: Record<string, unknown>): string {
+  let text = "";
+  if (typeof args.content === "string") text += args.content + "\n";
+  if (Array.isArray(args.edits)) {
+    for (const edit of args.edits) {
+      if (edit && typeof edit === "object") {
+        if (typeof edit.oldText === "string") text += edit.oldText + "\n";
+        if (typeof edit.newText === "string") text += edit.newText + "\n";
+      }
+    }
+  }
+  if (typeof args.oldText === "string" && !Array.isArray(args.edits)) text += args.oldText + "\n";
+  if (typeof args.newText === "string" && !Array.isArray(args.edits)) text += args.newText + "\n";
+  return text;
+}
+
+/**
+ * Compute file indicators from a message (no query — counts total lines per file).
+ */
+export function getFileIndicators(msg: Message): FileMatch[] {
+  if (!msg?.content || typeof msg.content === "string") return [];
+  const fileMatches: FileMatch[] = [];
+  for (const part of msg.content) {
+    if (!part || typeof part !== "object" || part.type !== "toolCall") continue;
+    const args = part.arguments as Record<string, unknown>;
+    if (!isContentBearing(args)) continue;
+
+    const path = ["path", "filePath", "file_path", "file"]
+      .map((k) => args[k])
+      .find((v): v is string => typeof v === "string")!;
+
+    const totalText = extractToolCallText(args);
+    const nonEmpty = totalText.split("\n").filter((l) => l.trim().length > 0);
+    fileMatches.push({
+      toolName: part.name || "",
+      path,
+      lineCount: nonEmpty.length,
+    });
+  }
+  return fileMatches;
+}
+
+function computeFileMatches(msg: Message | undefined, query: string): FileMatch[] {
+  if (!msg?.content || typeof msg.content === "string") return [];
+  const rawQuery = query.trim();
+  const hasQuery = rawQuery.length > 0;
+  if (!hasQuery) return getFileIndicators(msg as Message);
+  const regex = looksLikeRegex(rawQuery) ? safeRegex(rawQuery) : snippetRegex(rawQuery.split(/\s+/));
+  const fileMatches: FileMatch[] = [];
+
+  for (const part of msg.content) {
+    if (!part || typeof part !== "object" || part.type !== "toolCall") continue;
+    const args = part.arguments as Record<string, unknown>;
+    if (!isContentBearing(args)) continue;
+
+    // Path is guaranteed by isContentBearing check
+    const path = ["path", "filePath", "file_path", "file"]
+      .map((k) => args[k])
+      .find((v): v is string => typeof v === "string")!;
+
+    const searchText = extractToolCallText(args);
+    if (!searchText) continue;
+
+    const lines = searchText.split("\n");
+    const matchingLines = lines.filter((line) => regex.test(line));
+    if (matchingLines.length > 0) {
+      fileMatches.push({
+        toolName: part.name || "",
+        path,
+        lineCount: matchingLines.length,
+        snippet: matchingLines[0],
+      });
+    }
+  }
+
+  return fileMatches;
+}
+
+/** Aggregate file operations across all entries for mode:touched. */
+export function getTouchedFiles(
+  messages: Message[],
+  rendered: RenderedEntry[],
+): TouchedFile[] {
+  const map = new Map<string, TouchedFile>();
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+    const indicators = getFileIndicators(msg);
+    for (const fm of indicators) {
+      const index = rendered[i]?.index ?? i;
+      if (!map.has(fm.path)) {
+        map.set(fm.path, { path: fm.path, entries: [] });
+      }
+      map.get(fm.path)!.entries.push({ index, toolName: fm.toolName });
+    }
+  }
+  return Array.from(map.values());
+}
+
 export const searchEntries = (
   entries: RenderedEntry[],
   messages: Message[],
   query?: string,
+  _page?: number,
+  mode?: RecallMode,
 ): SearchHit[] => {
   if (!query?.trim()) return entries;
 
@@ -178,12 +317,14 @@ export const searchEntries = (
     for (let i = 0; i < entries.length; i++) {
       const e = entries[i];
       const msg = messages[i];
-      const text = msg ? fullText(msg) : e.summary;
+      const text = msg ? fullText(msg, mode) : e.summary;
       const filePart = e.files?.join(" ") ?? "";
       const hay = `${e.role} ${text} ${filePart}`;
       if (regex.test(hay)) {
         const snip = lineSnippet(text, regex);
-        hits.push({ ...e, snippet: snip, matchCount: 1 });
+        const fileMatches = mode === "transcript" ? [] : computeFileMatches(msg, rawQuery);
+        const extra = fileMatches.length > 0 ? { fileMatches } : {};
+        hits.push({ ...e, snippet: snip, matchCount: 1, ...extra });
       }
     }
     return hits;
@@ -194,12 +335,14 @@ export const searchEntries = (
   const terms = filterStopwords(rawTerms);
   const snipRe = snippetRegex(terms);
 
-  // Build all docs for BM25 context
+  // Build all docs for BM25 context (cache fullText to avoid recomputing)
   const docs: string[] = [];
+  const fullTextCache: string[] = [];
   for (let i = 0; i < entries.length; i++) {
     const e = entries[i];
     const msg = messages[i];
-    const text = msg ? fullText(msg) : e.summary;
+    const text = msg ? fullText(msg, mode) : e.summary;
+    fullTextCache.push(text);
     const filePart = e.files?.join(" ") ?? "";
     docs.push(`${e.role} ${text} ${filePart}`);
   }
@@ -213,10 +356,12 @@ export const searchEntries = (
     const mc = countMatches(hay, terms);
     if (mc === 0) continue;
     const score = bm25Score(hay, terms, ctx);
-    const text = messages[i] ? fullText(messages[i]) : e.summary;
+    const text = fullTextCache[i];
     const snip = lineSnippet(text, snipRe);
+    const fileMatches = mode === "transcript" ? [] : computeFileMatches(messages[i], rawQuery);
+    const extra = fileMatches.length > 0 ? { fileMatches } : {};
     scored.push({
-      hit: { ...e, snippet: snip, matchCount: mc },
+      hit: { ...e, snippet: snip, matchCount: mc, ...extra },
       score,
     });
   }

package/src/core/unified-config.ts

@@ -252,8 +252,30 @@ export function loadUnifiedConfig(cwd: string): UnifiedConfig {
 	// Merge defaults then override
 	const merged = { ...DEFAULTS, ...parsed };
 
-	// Derive observationsPoolTargetTokens if unset or invalid (must be < max)
-	if (merged.observationsPoolTargetTokens >= merged.observationsPoolMaxTokens) {
+	// ── Validate all numeric fields ──
+	// Prevents NaN/undefined from leaking into runtime math.
+	const NUMERIC_KEYS: ReadonlyArray<keyof UnifiedConfig> = [
+		"observeAfterTokens", "reflectAfterTokens", "compactAfterTokens",
+		"observationsPoolMaxTokens", "observationsPoolTargetTokens",
+		"reflectorInputMaxTokens", "dropperInputMaxTokens",
+		"observerChunkMaxTokens", "observerPreambleMaxTokens",
+		"agentMaxTurns",
+	];
+	for (const k of NUMERIC_KEYS) {
+		const v = (merged as Record<string, unknown>)[k];
+		// observerPreambleMaxTokens=0 means "auto-compute from observerChunkMaxTokens (30%)"
+		// so 0 is valid for that field. All other numeric fields must be strictly positive.
+		const minVal = k === "observerPreambleMaxTokens" ? 0 : 1;
+		if (typeof v !== "number" || !Number.isFinite(v) || v < minVal) {
+			(merged as Record<string, unknown>)[k] = DEFAULTS[k];
+		}
+	}
+
+	// Derive observationsPoolTargetTokens if still unset or invalid (must be < max)
+	if (
+		merged.observationsPoolTargetTokens === undefined ||
+		merged.observationsPoolTargetTokens >= merged.observationsPoolMaxTokens
+	) {
 		merged.observationsPoolTargetTokens = Math.floor(merged.observationsPoolMaxTokens / 2);
 	}
 
@@ -279,7 +301,11 @@ export function saveUnifiedConfig(settings: Partial<UnifiedConfig>): boolean {
 
 /**
  * Ensure ~/.pi/agent/pi-blackhole/pi-blackhole-config.json exists with defaults.
- * If the file exists but is missing keys, fill them in.
+ *
+ * Only creates the file if it doesn't exist. Missing keys are filled at read
+ * time by loadUnifiedConfig() via { ...DEFAULTS, ...parsed } merge, so there
+ * is no need to keep the on-disk file "complete". This avoids a crash on
+ * read-only filesystems where the config is managed externally (e.g., Nix).
  */
 export function scaffoldConfig(): void {
 	try {
@@ -289,21 +315,7 @@ export function scaffoldConfig(): void {
 
 		if (!existsSync(path)) {
 			writeFileSync(path, `${JSON.stringify(DEFAULTS, null, 2)}\n`);
-			return;
-		}
-
-		const parsed = readJson(path);
-		if (!parsed || typeof parsed !== "object") return;
-
-		let changed = false;
-		const next: Record<string, unknown> = { ...parsed };
-		for (const [key, value] of Object.entries(DEFAULTS)) {
-			if (!(key in next)) {
-				next[key] = value;
-				changed = true;
-			}
 		}
-		if (changed) writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`);
 	} catch (e) {
 		console.error("blackhole: config scaffold failed", e);
 	}

package/src/hooks/before-compact.ts

@@ -14,6 +14,7 @@ import { compile } from "../core/summarize";
 import type { PiVccCompactionDetails } from "../details";
 import { buildCompactionProjection, renderSummary } from "../om/ledger/index.js";
 import type { Runtime } from "../om/runtime.js";
+import { debugLog } from "../om/debug-log.js";
 
 export const PI_VCC_COMPACT_INSTRUCTION = "__pi_vcc__";
 
@@ -141,14 +142,28 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI, omRuntime: Runtime)
   pi.on("session_before_compact", (event, ctx) => {
     const { preparation, branchEntries, customInstructions } = event;
     omRuntime.ensureConfig(ctx.cwd ?? process.cwd());
+    const trace = (ev: string, d?: Record<string, unknown>) => debugLog(ev, d, omRuntime.config.debugLog === true);
+
+    trace("before_compact.enter", {
+      customInstructions,
+      isPiVcc: customInstructions === PI_VCC_COMPACT_INSTRUCTION,
+      overrideDefaultCompaction: omRuntime.config.overrideDefaultCompaction,
+      noAutoCompact: omRuntime.config.noAutoCompact,
+      branchLength: branchEntries.length,
+      hasPreviousSummary: !!preparation.previousSummary,
+    });
 
     // Always handle explicit /blackhole marker.
     // Otherwise, only handle when user opted in via settings.
     const isPiVcc = customInstructions === PI_VCC_COMPACT_INSTRUCTION;
-    if (!isPiVcc && !omRuntime.config.overrideDefaultCompaction) return;
+    if (!isPiVcc && !omRuntime.config.overrideDefaultCompaction) {
+      trace("before_compact.return_early", { reason: "overrideDefaultCompaction=false and not /blackhole" });
+      return;
+    }
 
     // When noAutoCompact is active, only /blackhole can trigger compaction
     if (omRuntime.config.noAutoCompact && !isPiVcc) {
+      trace("before_compact.cancel", { reason: "noAutoCompact and not /blackhole" });
       return { cancel: true };
     }
 
@@ -212,12 +227,20 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI, omRuntime: Runtime)
         })),
       });
 
+      trace("before_compact.cancel", { reason: ownCut.reason, isPiVcc });
       try {
         ctx?.ui?.notify?.(REASON_MESSAGES[ownCut.reason], "warning");
       } catch {}
       return { cancel: true };
     }
 
+    trace("before_compact.proceeding", {
+      messageCount: ownCut.messages.length,
+      firstKeptEntryId: ownCut.firstKeptEntryId,
+      compactAll: ownCut.compactAll,
+      isPiVcc,
+    });
+
     const agentMessages = ownCut.messages;
     const firstKeptEntryId = ownCut.firstKeptEntryId;
     const messages = convertToLlm(agentMessages);
@@ -278,6 +301,8 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI, omRuntime: Runtime)
       sections: [...summary.matchAll(/^\[(.+?)\]/gm)].map((m) => m[1]),
     });
 
+    trace("before_compact.summary_generated", { summaryLength: summary.length, messageCount: agentMessages.length });
+
     const details: PiVccCompactionDetails = {
       compactor: "blackhole",
       version: 1,
@@ -291,6 +316,7 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI, omRuntime: Runtime)
     // ── Inject observational-memory content ───────────────────────────
     let omContent = "";
     let omDetails: Record<string, unknown> | undefined;
+    trace("before_compact.om_injection", { memoryEnabled: omRuntime.config.memory !== false });
     if (omRuntime.config.memory !== false) {
       const projection = buildCompactionProjection(
       branchEntries as any[],

package/src/om/agents/dropper/agent.ts

@@ -7,7 +7,8 @@
  */
 import { agentLoop, type AgentContext, type AgentLoopConfig, type AgentTool } from "@earendil-works/pi-agent-core";
 import type { Message, Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
-import { Type } from "@earendil-works/pi-ai";
+import { streamSimple } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
 import type { Static } from "typebox";
 import { debugLog } from "../../debug-log.js";
 import { AGENT_LOOP_MAX_TOKENS, boundedMaxTokens } from "../../model-budget.js";
@@ -33,6 +34,10 @@ interface RunDropperArgs {
 	budgetTokens: number;
 	signal?: AbortSignal;
 	agentLoop?: typeof agentLoop;
+	/** Optional custom stream function bypassing agentLoop's default streamSimple.
+	 *  Used by the Symbol.for bridge to access native pi-ai provider registrations
+	 *  from jiti-loaded consolidation agents. */
+	streamFn?: (model: any, context: any, options: any) => any;
 	maxTurns?: number;
 	thinkingLevel?: ModelThinkingLevel;
 }
@@ -281,7 +286,16 @@ export async function runDropper(args: RunDropperArgs): Promise<string[] | undef
 	};
 
 	const loop = args.agentLoop ?? agentLoop;
-	const stream = loop(prompts, context, config, signal);
+	// ── Bridge stream function ──
+	const PROVIDER_STREAMS_KEY = Symbol.for("pi-blackhole:provider-streams");
+	const bridgeStreamFn = (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);
+	};
+	const streamFn = args.streamFn ?? bridgeStreamFn;
+	const stream = loop(prompts, context, config, signal, streamFn);
 	let agentError: string | undefined;
 	for await (const event of stream) {
 		// Tool execution collects candidate ids.

package/src/om/agents/observer/agent.ts

@@ -8,7 +8,8 @@
  */
 import { agentLoop, type AgentContext, type AgentLoopConfig, type AgentTool } from "@earendil-works/pi-agent-core";
 import type { Message, Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
-import { Type } from "@earendil-works/pi-ai";
+import { streamSimple } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
 import type { Static } from "typebox";
 import { hashId } from "../../ids.js";
 import { AGENT_LOOP_MAX_TOKENS, boundedMaxTokens } from "../../model-budget.js";
@@ -27,6 +28,10 @@ interface RunObserverArgs {
 	allowedSourceEntryIds: string[];
 	signal?: AbortSignal;
 	agentLoop?: typeof agentLoop;
+	/** Optional custom stream function bypassing agentLoop's default streamSimple.
+	 *  Used by the Symbol.for bridge to access native pi-ai provider registrations
+	 *  from jiti-loaded consolidation agents. */
+	streamFn?: (model: any, context: any, options: any) => any;
 	maxTurns?: number;
 	thinkingLevel?: ModelThinkingLevel;
 }
@@ -217,7 +222,22 @@ ${conversation}`;
 	};
 
 	const loop = args.agentLoop ?? agentLoop;
-	const stream = loop(prompts, context, config, signal);
+	// ── Bridge stream function ──
+	// Consolidation agents run via jiti (moduleCache: false) which creates a separate
+	// pi-ai instance whose apiProviderRegistry lacks custom providers registered by
+	// other extensions (e.g., claude-bridge). The bridge looks up streamSimple functions
+	// from a Symbol.for() global that index.ts populates during provider registration.
+	// If no custom provider is found, it falls back to the jiti-loaded streamSimple
+	// which handles all built-in providers correctly.
+	const PROVIDER_STREAMS_KEY = Symbol.for("pi-blackhole:provider-streams");
+	const bridgeStreamFn = (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);
+	};
+	const streamFn = args.streamFn ?? bridgeStreamFn;
+	const stream = loop(prompts, context, config, signal, streamFn);
 	let agentError: string | undefined;
 	for await (const event of stream) {
 		// Drain events; the tool's execute already collects records.

package/src/om/agents/reflector/agent.ts

@@ -7,7 +7,8 @@
  */
 import { agentLoop, type AgentContext, type AgentLoopConfig, type AgentTool } from "@earendil-works/pi-agent-core";
 import type { Message, Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
-import { Type } from "@earendil-works/pi-ai";
+import { streamSimple } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
 import type { Static } from "typebox";
 import { hashId } from "../../ids.js";
 import { AGENT_LOOP_MAX_TOKENS, boundedMaxTokens } from "../../model-budget.js";
@@ -15,6 +16,7 @@ import { truncateRecordContent } from "../../serialize.js";
 import { REFLECTOR_SYSTEM } from "./prompts.js";
 import { estimateStringTokens } from "../../tokens.js";
 import { observationToSummaryLine, reflectionToSummaryLine, type Observation, type Reflection } from "../../ledger/index.js";
+import type { ReflectionCoverageTier } from "../dropper/coverage.js";
 
 interface RunReflectorArgs {
 	model: Model<any>;
@@ -28,6 +30,10 @@ interface RunReflectorArgs {
 	existingObservationsSummary?: string;
 	signal?: AbortSignal;
 	agentLoop?: typeof agentLoop;
+	/** Optional custom stream function bypassing agentLoop's default streamSimple.
+	 *  Used by the Symbol.for bridge to access native pi-ai provider registrations
+	 *  from jiti-loaded consolidation agents. */
+	streamFn?: (model: any, context: any, options: any) => any;
 	maxTurns?: number;
 	thinkingLevel?: ModelThinkingLevel;
 }
@@ -143,7 +149,16 @@ export async function runReflector(args: RunReflectorArgs): Promise<Reflection[]
 	};
 
 	const loop = args.agentLoop ?? agentLoop;
-	const stream = loop(prompts, context, config, signal);
+	// ── Bridge stream function ──
+	const PROVIDER_STREAMS_KEY = Symbol.for("pi-blackhole:provider-streams");
+	const bridgeStreamFn = (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);
+	};
+	const streamFn = args.streamFn ?? bridgeStreamFn;
+	const stream = loop(prompts, context, config, signal, streamFn);
 	let agentError: string | undefined;
 	for await (const event of stream) {
 		// Tool execution collects records.
@@ -159,3 +174,37 @@ export async function runReflector(args: RunReflectorArgs): Promise<Reflection[]
 	if (agentError && accumulated.size === 0) throw new Error(`Reflector API error: ${agentError}`);
 	return accumulated.size > 0 ? Array.from(accumulated.values()) : undefined;
 }
+
+export function observationToReflectorLine(
+	observation: Observation,
+	coverage: ReflectionCoverageTier,
+): string {
+	return `[${observation.id}] ${observation.timestamp} [${observation.relevance}] [coverage: ${coverage}] ${observation.content}`;
+}
+
+export function summarizeSupportIdCounts(reflections: readonly Reflection[]): {
+	reflectionCount: number;
+	totalSupportIds: number;
+	minSupportIds: number;
+	maxSupportIds: number;
+	averageSupportIds: number;
+	histogram: Record<string, number>;
+} {
+	if (reflections.length === 0) {
+		return { reflectionCount: 0, totalSupportIds: 0, minSupportIds: 0, maxSupportIds: 0, averageSupportIds: 0, histogram: {} };
+	}
+	const supportIdCounts = reflections.map((r) => r.supportingObservationIds.length);
+	const total = supportIdCounts.reduce((sum, c) => sum + c, 0);
+	const histogram: Record<string, number> = {};
+	for (const count of supportIdCounts) {
+		histogram[String(count)] = (histogram[String(count)] || 0) + 1;
+	}
+	return {
+		reflectionCount: reflections.length,
+		totalSupportIds: total,
+		minSupportIds: Math.min(...supportIdCounts),
+		maxSupportIds: Math.max(...supportIdCounts),
+		averageSupportIds: total / reflections.length,
+		histogram,
+	};
+}

package/src/om/compaction-trigger.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { rawTokensSinceLastCompaction, type Entry } from "./ledger/index.js";
 import type { Runtime } from "./runtime.js";
+import { debugLog } from "./debug-log.js";
 
 /**
  * Regex matching Pi's internal retryable error detection.
@@ -13,10 +14,36 @@ const RETRYABLE_ERROR_RE =
 export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): void {
 	pi.on("agent_end", (event: any, ctx: any) => {
 		runtime.ensureConfig(ctx.cwd);
-		if (runtime.config.passive === true) return;
-		if (runtime.config.memory === false) return;
-		if (runtime.config.noAutoCompact === true) return;
-		if (runtime.compactInFlight) return;
+
+		// Pass the config flag explicitly — this handler runs outside ALS context
+		// (agent_end events don't flow through consolidation's withDebugLogContext),
+		// and the setTimeout callback would lose ALS context anyway.
+		const dbg = (ev: string, d?: Record<string, unknown>) => debugLog(ev, d, runtime.config.debugLog === true);
+
+		dbg("compaction_trigger.agent_end", {
+			passive: runtime.config.passive,
+			memory: runtime.config.memory,
+			noAutoCompact: runtime.config.noAutoCompact,
+			compactInFlight: runtime.compactInFlight,
+			compactAfterTokens: runtime.config.compactAfterTokens,
+		});
+
+		if (runtime.config.passive === true) {
+			dbg("compaction_trigger.skip", { reason: "passive" });
+			return;
+		}
+		if (runtime.config.memory === false) {
+			dbg("compaction_trigger.skip", { reason: "memory" });
+			return;
+		}
+		if (runtime.config.noAutoCompact === true) {
+			dbg("compaction_trigger.skip", { reason: "noAutoCompact" });
+			return;
+		}
+		if (runtime.compactInFlight) {
+			dbg("compaction_trigger.skip", { reason: "compactInFlight" });
+			return;
+		}
 
 		// Don't trigger compaction if Pi will auto-retry — the agent hasn't truly finished.
 		// Pi emits agent_end before its own retry check, so we must detect this ourselves.
@@ -34,8 +61,14 @@ export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): v
 		}
 
 		const entries = ctx.sessionManager.getBranch() as Entry[];
+		dbg("compaction_trigger.branch_check", { branchLength: entries.length, hasLastEntry: entries.length > 0, lastEntryType: entries.length > 0 ? entries[entries.length - 1].type : "none" });
+
 		const tokens = rawTokensSinceLastCompaction(entries);
-		if (tokens < runtime.config.compactAfterTokens) return;
+		dbg("compaction_trigger.tokens", { tokens, compactAfterTokens: runtime.config.compactAfterTokens, branchLength: entries.length });
+		if (tokens < runtime.config.compactAfterTokens) {
+			dbg("compaction_trigger.skip", { reason: "below_threshold", tokens, threshold: runtime.config.compactAfterTokens });
+			return;
+		}
 
 		// Capture ctx properties synchronously — the deferred callback below
 		// may outlive the extension ctx (stale after session replacement/reload).
@@ -43,18 +76,25 @@ export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): v
 		const ui = ctx.ui;
 		const sessionId = ctx.sessionManager.getSessionId();
 
+		dbg("compaction_trigger.threshold_reached", { tokens, sessionId, hasUI });
+
 		if (hasUI) ui?.notify(
 			`Observational memory: compaction threshold reached (~${tokens.toLocaleString()} tokens); triggering compaction`,
 			"info",
 		);
 
 		runtime.compactInFlight = true;
-		queueMicrotask(() => {
+		dbg("compaction_trigger.scheduled", { compactInFlight: runtime.compactInFlight });
+
+		setTimeout(() => {
+			dbg("compaction_trigger.microtask.enter", {});
 			try {
 				// Validate session identity — bail if the session was replaced/reloaded.
 				const currentSessionId = ctx.sessionManager.getSessionId();
+				dbg("compaction_trigger.microtask.session_check", { currentSessionId, expectedSessionId: sessionId, match: currentSessionId === sessionId });
 				if (currentSessionId !== sessionId) {
 					runtime.compactInFlight = false;
+					dbg("compaction_trigger.microtask.bail", { reason: "session_changed" });
 					if (hasUI) ui?.notify(
 						"Observational memory: compaction cancelled — session changed before compaction",
 						"info",
@@ -62,8 +102,11 @@ export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): v
 					return;
 				}
 
-				if (!ctx.isIdle()) {
+				const isIdle = ctx.isIdle();
+				dbg("compaction_trigger.microtask.idle_check", { isIdle });
+				if (!isIdle) {
 					runtime.compactInFlight = false;
+					dbg("compaction_trigger.microtask.bail", { reason: "not_idle" });
 					if (hasUI) ui?.notify(
 						"Observational memory: compaction deferred — agent became busy before compaction",
 						"info",
@@ -72,21 +115,27 @@ export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): v
 				}
 				const currentEntries = ctx.sessionManager.getBranch() as Entry[];
 				const currentTokens = rawTokensSinceLastCompaction(currentEntries);
+				dbg("compaction_trigger.microtask.recheck_tokens", { currentTokens, threshold: runtime.config.compactAfterTokens, ok: currentTokens >= runtime.config.compactAfterTokens });
 				if (currentTokens < runtime.config.compactAfterTokens) {
 					runtime.compactInFlight = false;
+					dbg("compaction_trigger.microtask.bail", { reason: "pressure_relieved", currentTokens, threshold: runtime.config.compactAfterTokens });
 					if (hasUI) ui?.notify(
 						"Observational memory: compaction skipped — another compaction already ran before deferred compaction",
 						"info",
 					);
 					return;
 				}
+
+				dbg("compaction_trigger.microtask.calling_compact", {});
 				ctx.compact({
-					onComplete: () => {
+					onComplete: (result: any) => {
 						runtime.compactInFlight = false;
+						dbg("compaction_trigger.onComplete", { result: !!result });
 						if (hasUI) ui?.notify("Observational memory: compaction complete", "info");
 					},
 					onError: (error: { message: string }) => {
 						runtime.compactInFlight = false;
+						dbg("compaction_trigger.onError", { message: error?.message ?? String(error) });
 						if (error.message === "Compaction cancelled") {
 							// We already notified the user with the real reason before returning { cancel: true }.
 							return;
@@ -97,8 +146,9 @@ export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): v
 			} catch (error) {
 				runtime.compactInFlight = false;
 				const msg = error instanceof Error ? error.message : String(error);
+				dbg("compaction_trigger.microtask.error", { message: msg });
 				if (hasUI) ui?.notify(`Observational memory: compact threw: ${msg}`, "error");
 			}
-		});
+		}, 0);
 	});
 }