pi-blackhole 0.3.2 → 0.3.3

package/src/core/unified-config.ts

@@ -15,7 +15,18 @@ import type { ModelThinkingLevel } from "@earendil-works/pi-ai";
 const CONFIG_DIR = "pi-blackhole";
 const CONFIG_FILE = "pi-blackhole-config.json";
 
-function configPath(): string {
+/** Test-only: override for config directory. Set via __setTestConfigDir(). */
+let __testConfigDir: string | undefined;
+
+/** Test-only: set to override config directory. Use in beforeEach/afterEach. */
+export function __setTestConfigDir(dir: string | undefined): void {
+	__testConfigDir = dir;
+}
+
+export function configPath(): string {
+	if (__testConfigDir) {
+		return join(__testConfigDir, CONFIG_DIR, CONFIG_FILE);
+	}
 	return join(getAgentDir(), CONFIG_DIR, CONFIG_FILE);
 }
 
@@ -28,14 +39,35 @@ export interface OmModelConfig {
 	/** Cooldown duration in hours after a retryable error (429/5xx/timeout).
 	 *  Defaults to 1 hour when omitted. */
 	cooldownHours?: number;
+	/** Context window override for this model. Inherits from Pi's model registry when unset. */
+	contextWindow?: number;
 }
 
 export interface UnifiedConfig {
-	/** When true, pi-vcc handles all compactions (not just /pi-vcc). */
-	overrideDefaultCompaction: boolean;
+	/** @deprecated Use compactionEngine instead. */
+	overrideDefaultCompaction?: boolean;
 	/** Write debug snapshots to /tmp/pi-blackhole-debug.json. */
 	debug: boolean;
 
+	// ── New config surface — compaction, engine, tail behavior ──
+
+	/** Unified compaction control: "auto" | "manual" | "off".
+	 *  "auto"   — auto-trigger on compactAfterTokens threshold
+	 *  "manual"  — only via /blackhole command
+	 *  "off"    — never compact (disables auto + blocks /blackhole) */
+	compaction: "auto" | "manual" | "off";
+
+	/** Which engine handles compaction.
+	 *  "blackhole"  — blackhole's compile() + OM injection
+	 *  "pi-default" — Pi's built-in summarization */
+	compactionEngine: "blackhole" | "pi-default";
+
+	/** How much recent transcript to keep visible after compaction.
+	 *  "pi-default" — use Pi's firstKeptEntryId (respects Pi's keepRecentTokens)
+	 *  "minimal"    — keep only last user message (current agressive pi-vcc behavior)
+	 *  ONLY applies when compactionEngine: "blackhole" */
+	tailBehavior: "pi-default" | "minimal";
+
 	/** Token threshold for observer runs. */
 	observeAfterTokens: number;
 	/** Token threshold for reflector and dropper. */
@@ -68,6 +100,7 @@ export interface UnifiedConfig {
 	/** Shared turn cap for background memory agents. */
 	agentMaxTurns: number;
 
+
 	/** Base model override for all memory workers. */
 	model?: OmModelConfig;
 	/** Model override for observer (most frequent worker). */
@@ -84,12 +117,10 @@ export interface UnifiedConfig {
 	/** Fallback models for dropper, tried in order after primary model fails. */
 	dropperFallbackModels?: OmModelConfig[];
 
-	/** When true, observations/reflections are saved to pending.json
-	 *  instead of appended to the conversation. Auto-compaction is
-	 *  disabled.  User triggers /blackhole to flush and compact. */
-	noAutoCompact: boolean;
-	/** Disables background workers and auto-compaction entirely. */
-	passive: boolean;
+	/** @deprecated Use compaction instead. */
+	noAutoCompact?: boolean;
+	/** @deprecated Use compaction + memory instead. */
+	passive?: boolean;
 	/** Enables observational memory (workers + content injection). Set to false for pi-vcc only. */
 	memory: boolean;
 	/** Writes debug JSONL to agent directory. */
@@ -99,9 +130,13 @@ export interface UnifiedConfig {
 // ── Defaults ─────────────────────────────────────────────────────────────────
 
 export const DEFAULTS: UnifiedConfig = {
-	overrideDefaultCompaction: false,
 	debug: false,
 
+	// New config surface
+	compaction: "auto",
+	compactionEngine: "blackhole",
+	tailBehavior: "minimal",
+
 	observeAfterTokens: 15_000,
 	reflectAfterTokens: 25_000,
 	compactAfterTokens: 81_000,
@@ -113,8 +148,6 @@ export const DEFAULTS: UnifiedConfig = {
 	observerPreambleMaxTokens: 0,
 	agentMaxTurns: 16,
 
-	noAutoCompact: false,
-	passive: false,
 	memory: true,
 	debugLog: false,
 };
@@ -123,6 +156,21 @@ export const DEFAULTS: UnifiedConfig = {
 
 const THINKING_LEVELS: readonly string[] = ["off", "minimal", "low", "medium", "high", "xhigh"];
 
+// String enums for new config surface
+const COMPACTION_VALUES = ["auto", "manual", "off"] as const;
+const COMPACTION_ENGINE_VALUES = ["blackhole", "pi-default"] as const;
+const TAIL_BEHAVIOR_VALUES = ["pi-default", "minimal"] as const;
+
+function isCompaction(v: unknown): v is "auto" | "manual" | "off" {
+	return typeof v === "string" && (COMPACTION_VALUES as readonly string[]).includes(v);
+}
+function isCompactionEngine(v: unknown): v is "blackhole" | "pi-default" {
+	return typeof v === "string" && (COMPACTION_ENGINE_VALUES as readonly string[]).includes(v);
+}
+function isTailBehavior(v: unknown): v is "pi-default" | "minimal" {
+	return typeof v === "string" && (TAIL_BEHAVIOR_VALUES as readonly string[]).includes(v);
+}
+
 function isRecord(v: unknown): v is Record<string, unknown> {
 	return typeof v === "object" && v !== null;
 }
@@ -148,6 +196,8 @@ function parseModel(v: unknown): OmModelConfig | undefined {
 	if (isThinkingLevel(v.thinking)) model.thinking = v.thinking;
 	const cooldown = positiveInt(v.cooldownHours);
 	if (cooldown !== undefined) model.cooldownHours = cooldown;
+	const ctxWindow = positiveInt(v.contextWindow);
+	if (ctxWindow !== undefined) model.contextWindow = ctxWindow;
 	return model;
 }
 
@@ -160,6 +210,11 @@ function parseModelArray(v: unknown): OmModelConfig[] | undefined {
 function parseConfig(raw: Record<string, unknown>): Partial<UnifiedConfig> {
 	const c: Partial<UnifiedConfig> = {};
 
+	// String enums — compaction surface
+	if (isCompaction(raw.compaction)) c.compaction = raw.compaction;
+	if (isCompactionEngine(raw.compactionEngine)) c.compactionEngine = raw.compactionEngine;
+	if (isTailBehavior(raw.tailBehavior)) c.tailBehavior = raw.tailBehavior;
+
 	// Booleans — pi-vcc
 	if (typeof raw.overrideDefaultCompaction === "boolean") c.overrideDefaultCompaction = raw.overrideDefaultCompaction;
 	if (typeof raw.debug === "boolean") c.debug = raw.debug;
@@ -198,6 +253,45 @@ function parseConfig(raw: Record<string, unknown>): Partial<UnifiedConfig> {
 	return c;
 }
 
+// ── Migration ────────────────────────────────────────────────────────────────
+
+/**
+ * Migrate legacy config knobs to new unified surface.
+ * Runs once at load time; old keys are removed from the parsed object.
+ * Does NOT mutate the on-disk config file.
+ */
+function migrateOldKnobs(parsed: Record<string, unknown>): void {
+	// Only run if new keys are absent AND old keys are present
+	if (parsed.compaction !== undefined || parsed.compactionEngine !== undefined) {
+		return; // new keys already set — no migration
+	}
+
+	// passive → compaction: "off" + memory: false
+	if (parsed.passive === true) {
+		parsed.compaction = "off";
+		parsed.memory = false;
+	}
+	// noAutoCompact → compaction: "manual"
+	else if (parsed.noAutoCompact === true) {
+		parsed.compaction = "manual";
+	}
+	// overrideDefaultCompaction → compactionEngine + tailBehavior
+	if (parsed.overrideDefaultCompaction === true) {
+		parsed.compactionEngine = "blackhole";
+		// Preserve aggressive cut for existing users
+		if (parsed.tailBehavior === undefined) {
+			parsed.tailBehavior = "minimal";
+		}
+	} else if (parsed.overrideDefaultCompaction === false) {
+		parsed.compactionEngine = "pi-default";
+	}
+
+	// Remove old keys so migration runs only once
+	delete parsed.passive;
+	delete parsed.noAutoCompact;
+	delete parsed.overrideDefaultCompaction;
+}
+
 // ── Load and save ────────────────────────────────────────────────────────────
 
 function readJson(path: string): Record<string, unknown> | null {
@@ -241,12 +335,34 @@ export function loadUnifiedConfig(cwd: string): UnifiedConfig {
 
 	const parsed = parseConfig(raw);
 
-	// Env override
+	// ── Migration: old → new knobs ──
+	migrateOldKnobs(parsed);
+
+	// Env override — legacy passive env vars
 	const envPassive = process.env.PI_BLACKHOLE_PASSIVE ?? process.env.PI_VCC_OM_PASSIVE ?? process.env.PI_OBSERVATIONAL_MEMORY_PASSIVE;
 	if (envPassive !== undefined) {
 		const v = envPassive.trim().toLowerCase();
-		if (["1", "true", "yes", "on"].includes(v)) parsed.passive = true;
-		else if (["0", "false", "no", "off"].includes(v)) parsed.passive = false;
+		if (["1", "true", "yes", "on"].includes(v)) {
+			parsed.compaction = "off";
+			parsed.memory = false;
+		} else if (["0", "false", "no", "off"].includes(v)) {
+			// Falsy env override: undo passive migration when config relied on legacy key
+			if (raw?.passive === true) {
+				delete parsed.compaction;
+				delete parsed.memory;
+			}
+		}
+	}
+
+	// Env override — new compaction surface
+	const envCompaction = process.env.PI_BLACKHOLE_COMPACTION;
+	if (envCompaction !== undefined && isCompaction(envCompaction.trim().toLowerCase())) {
+		parsed.compaction = envCompaction.trim().toLowerCase() as "auto" | "manual" | "off";
+	}
+
+	const envCompactionEngine = process.env.PI_BLACKHOLE_COMPACTION_ENGINE;
+	if (envCompactionEngine !== undefined && isCompactionEngine(envCompactionEngine.trim().toLowerCase())) {
+		parsed.compactionEngine = envCompactionEngine.trim().toLowerCase() as "blackhole" | "pi-default";
 	}
 
 	// Merge defaults then override
@@ -254,23 +370,26 @@ export function loadUnifiedConfig(cwd: string): UnifiedConfig {
 
 	// ── Validate all numeric fields ──
 	// Prevents NaN/undefined from leaking into runtime math.
-	const NUMERIC_KEYS: ReadonlyArray<keyof UnifiedConfig> = [
+	// Required numeric keys — must be >= 1 (or >= 0 for observerPreambleMaxTokens)
+	const REQUIRED_NUMERIC_KEYS: ReadonlyArray<keyof UnifiedConfig> = [
 		"observeAfterTokens", "reflectAfterTokens", "compactAfterTokens",
 		"observationsPoolMaxTokens", "observationsPoolTargetTokens",
 		"reflectorInputMaxTokens", "dropperInputMaxTokens",
 		"observerChunkMaxTokens", "observerPreambleMaxTokens",
 		"agentMaxTurns",
 	];
-	for (const k of NUMERIC_KEYS) {
+	for (const k of REQUIRED_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;
+		// so 0 is valid for those fields. 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 ||
@@ -320,3 +439,43 @@ export function scaffoldConfig(): void {
 		console.error("blackhole: config scaffold failed", e);
 	}
 }
+
+// ── Toggle helpers ───────────────────────────────────────────────────────────
+
+/** Cycle compaction: auto → manual → off → auto */
+export function toggleCompaction(current: "auto" | "manual" | "off"): "auto" | "manual" | "off" {
+	const cycle: Array<"auto" | "manual" | "off"> = ["auto", "manual", "off"];
+	const idx = cycle.indexOf(current);
+	return cycle[(idx + 1) % cycle.length];
+}
+
+/** Toggle compactionEngine: blackhole ↔ pi-default */
+export function toggleCompactionEngine(current: "blackhole" | "pi-default"): "blackhole" | "pi-default" {
+	return current === "blackhole" ? "pi-default" : "blackhole";
+}
+
+/** Toggle tailBehavior: pi-default ↔ minimal */
+export function toggleTailBehavior(current: "pi-default" | "minimal"): "pi-default" | "minimal" {
+	return current === "pi-default" ? "minimal" : "pi-default";
+}
+
+// ── Migration detection ───────────────────────────────────────────────────────
+
+/**
+ * Check if the on-disk config file still uses legacy keys (needs migration).
+ * Returns true when the file exists, has no new keys, but has old keys.
+ * Used to prompt users to save their config with the new keys.
+ */
+export function configFileNeedsMigration(): boolean {
+	try {
+		const path = configPath();
+		if (!existsSync(path)) return false;
+		const raw = JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown>;
+		if (raw.compaction !== undefined || raw.compactionEngine !== undefined || raw.tailBehavior !== undefined) {
+			return false; // already has new keys
+		}
+		return raw.passive !== undefined || raw.noAutoCompact !== undefined || raw.overrideDefaultCompaction !== undefined;
+	} catch {
+		return false;
+	}
+}

package/src/hooks/before-compact.ts

@@ -15,9 +15,34 @@ 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";
+import { configFileNeedsMigration } from "../core/unified-config.js";
 
 export const PI_VCC_COMPACT_INSTRUCTION = "__pi_vcc__";
 
+// ── Migration reminder ────────────────────────────────────────────────────────
+
+/** Per-session notification count for migration reminder (max 2). */
+const migrationNotifyCount = new Map<string, number>();
+
+/**
+ * Show migration reminder notification if user's on-disk config still has legacy keys.
+ * At most 2 notifications per session. Call after compaction completes.
+ */
+export function notifyMigrationReminder(
+	sessionId: string,
+	notify: (msg: string, level: string) => void,
+): void {
+	const count = migrationNotifyCount.get(sessionId) ?? 0;
+	if (count >= 2) return;
+	if (!configFileNeedsMigration()) return;
+	migrationNotifyCount.set(sessionId, count + 1);
+	notify(
+		"blackhole: Use `/blackhole configure` to save your updated configuration.",
+		"info",
+	);
+}
+
+
 const formatTokens = (n: number): string => {
   if (n >= 1000) return `${(n / 1000).toFixed(1)}k`;
   return String(n);
@@ -58,7 +83,13 @@ export type OwnCutResult =
   | { ok: true; messages: any[]; firstKeptEntryId: string; compactAll: boolean }
   | { ok: false; reason: OwnCutCancelReason };
 
-export function buildOwnCut(branchEntries: any[]): OwnCutResult {
+export function buildOwnCut(
+  branchEntries: any[],
+  /** Pi's firstKeptEntryId from preparation (undefined = don't use Pi's cut). */
+  piFirstKeptEntryId?: string,
+  /** "pi-default" = use Pi's cut, "minimal" = keep only last user message (current). */
+  tailBehavior?: "pi-default" | "minimal",
+): OwnCutResult {
   // Find the last compaction entry and its firstKeptEntryId
   let lastCompactionIdx = -1;
   let lastKeptId: string | undefined;
@@ -99,6 +130,74 @@ export function buildOwnCut(branchEntries: any[]): OwnCutResult {
     }
   }
 
+  // ── Pi's cut path: use Pi's firstKeptEntryId instead of last-user cut ──
+  if (tailBehavior === "pi-default" && piFirstKeptEntryId) {
+    const cutInBranch = branchEntries.findIndex((e: any) => e.id === piFirstKeptEntryId);
+    if (cutInBranch >= 0) {
+      const liveCutIdx = liveMessages.findIndex((lm) => lm.entry.id === piFirstKeptEntryId);
+      if (liveCutIdx > 0) {
+        return {
+          ok: true,
+          messages: liveMessages.slice(0, liveCutIdx).map((e) => e.message),
+          firstKeptEntryId: piFirstKeptEntryId,
+          compactAll: false,
+        };
+      }
+      if (liveCutIdx === 0) {
+        // Pi's cut is at first live message.
+        // Pi wants to keep everything, so only compact-all is acceptable (summarizes
+        // everything for a fresh page).  If minimal path would aggressively cut
+        // (multiple user messages), cancel to respect Pi's guidance.
+        let lastUserIdx = liveMessages.length - 1;
+        while (lastUserIdx > 0 && liveMessages[lastUserIdx].message.role !== "user") {
+          lastUserIdx--;
+        }
+        if (lastUserIdx > 0) {
+          // Multiple user messages — minimal would aggressively cut, violating Pi
+          return { ok: false, reason: "too_few_live_messages" };
+        }
+        // Single user message — fall through to minimal path (will compact-all)
+      }
+      // liveCutIdx === -1: piFirstKeptEntryId not found in liveMessages
+      // (e.g., refers to a non-message entry like type:"custom" OM metadata or
+      // type:"compaction"). Resolve to the next message entry after pi's cut point.
+      if (liveCutIdx < 0) {
+        const nextMsgEntry = branchEntries.find(
+          (e: any, i: number) => i > cutInBranch && e.type === "message" && e.message,
+        );
+        if (nextMsgEntry) {
+          const resolvedId: string = nextMsgEntry.id;
+          const resolvedLiveIdx = liveMessages.findIndex(
+            (lm) => lm.entry.id === resolvedId,
+          );
+          if (resolvedLiveIdx > 0) {
+            return {
+              ok: true,
+              messages: liveMessages.slice(0, resolvedLiveIdx).map((e) => e.message),
+              firstKeptEntryId: resolvedId,
+              compactAll: false,
+            };
+          }
+          if (resolvedLiveIdx === 0) {
+            let lastUserIdx = liveMessages.length - 1;
+            while (lastUserIdx > 0 && liveMessages[lastUserIdx].message.role !== "user") {
+              lastUserIdx--;
+            }
+            if (lastUserIdx > 0) {
+              return { ok: false, reason: "too_few_live_messages" };
+            }
+            // Single user message — fall through to minimal (will compact-all)
+          }
+          // resolvedLiveIdx === -1: resolved message not in liveMessages
+          // (shouldn't happen since liveMessages starts from prior firstKeptEntryId
+          // which should be before or at pi's cut), but fall through if it does.
+        }
+        // No message found after pi's cut point in branch — fall through
+      }
+    }
+    // piFirstKeptEntryId not found in branch → fall through to minimal / orphan recovery
+  }
+
   if (liveMessages.length === 0) return { ok: false, reason: "no_live_messages" };
   if (liveMessages.length <= 2) return { ok: false, reason: "too_few_live_messages" };
 
@@ -135,7 +234,7 @@ export function buildOwnCut(branchEntries: any[]): OwnCutResult {
 
 const REASON_MESSAGES: Record<OwnCutCancelReason, string> = {
   no_live_messages: "blackhole: Nothing to compact (no live messages)",
-  too_few_live_messages: "blackhole: Too few messages to compact",
+  too_few_live_messages: "blackhole: Too few live messages — Pi's default logic preserves visible context. Set tailBehavior to \"minimal\" in config to force compaction with fewer messages.",
 };
 
 export const registerBeforeCompactHook = (pi: ExtensionAPI, omRuntime: Runtime) => {
@@ -156,18 +255,56 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI, omRuntime: Runtime)
     // 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) {
-      trace("before_compact.return_early", { reason: "overrideDefaultCompaction=false and not /blackhole" });
+
+    // NEW: Unified compaction guards
+    // compaction "off": blackhole skips auto-triggered, but /blackhole still uses blackhole pipeline
+    if (omRuntime.config.compaction === "off" && !isPiVcc) {
+      trace("before_compact.return_early", { reason: "compaction_off" });
       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 };
+    // compactionEngine "pi-default" means let Pi handle auto-triggered compactions
+    if (omRuntime.config.compactionEngine === "pi-default" && !isPiVcc) {
+      trace("before_compact.return_early", { reason: "compactionEngine_pi_default" });
+      return;
     }
 
-    const ownCut = buildOwnCut(branchEntries as any[]);
+    // compaction "manual": /compact falls through to Pi, /blackhole still works
+    if (omRuntime.config.compaction === "manual" && !isPiVcc) {
+      trace("before_compact.return_early", { reason: "compaction_manual" });
+      return;
+    }
+
+    // LEGACY: old config key guards — only apply when new keys are absent (unmigrated config)
+    if (omRuntime.config.compaction === undefined && omRuntime.config.compactionEngine === undefined) {
+      if (!isPiVcc && !omRuntime.config.overrideDefaultCompaction) {
+        trace("before_compact.return_early", { reason: "overrideDefaultCompaction=false and not /blackhole" });
+        return;
+      }
+
+      if (omRuntime.config.noAutoCompact && !isPiVcc) {
+        trace("before_compact.cancel", { reason: "noAutoCompact and not /blackhole" });
+        return { cancel: true };
+      }
+    }
+
+    // Determine effective tail behavior for buildOwnCut
+    const effectiveTailBehavior = isPiVcc
+      ? (omRuntime.config.tailBehavior ?? "minimal")   // /blackhole: minimal by default
+      : (omRuntime.config.tailBehavior ?? "minimal");
+
+    trace("before_compact.tail_behavior", {
+      effectiveTailBehavior,
+      configTailBehavior: omRuntime.config.tailBehavior,
+      isPiVcc,
+      piFirstKeptEntryId: preparation.firstKeptEntryId,
+    });
+
+    const ownCut = buildOwnCut(
+      branchEntries as any[],
+      preparation.firstKeptEntryId,
+      effectiveTailBehavior,
+    );
     if (!ownCut.ok) {
       const lastComp = [...branchEntries].reverse().find((e: any) => e.type === "compaction");
       const lastCompIdx = lastComp ? (branchEntries as any[]).indexOf(lastComp) : -1;
@@ -344,12 +481,14 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI, omRuntime: Runtime)
     if (omRuntime.compactWasPiVcc) return; // /blackhole handles its own toast via onComplete
     const stats = omRuntime.compactionStats;
     if (!stats) return;
+    const sessionId = ctx.sessionManager.getSessionId();
     setTimeout(() => {
       try {
         ctx?.ui?.notify?.(
           `blackhole: ${stats.summarized} source entries processed; tail kept ${stats.kept} (~${formatTokens(stats.keptTokensEst)} tok).`,
           "info",
         );
+        notifyMigrationReminder(sessionId, (msg, level) => ctx?.ui?.notify?.(msg, level as any));
       } catch {}
     }, 500);
   });

package/src/om/compaction-trigger.ts

@@ -29,24 +29,38 @@ export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): v
 			compactAfterTokens: runtime.config.compactAfterTokens,
 		});
 
-		if (runtime.config.passive === true) {
-			dbg("compaction_trigger.skip", { reason: "passive" });
+		// NEW: Unified compaction guards
+		if (runtime.config.compaction === "off") {
+			dbg("compaction_trigger.skip", { reason: "compaction_off" });
 			return;
 		}
-		if (runtime.config.memory === false) {
-			dbg("compaction_trigger.skip", { reason: "memory" });
+		if (runtime.config.compaction === "manual") {
+			dbg("compaction_trigger.skip", { reason: "compaction_manual" });
 			return;
 		}
-		if (runtime.config.noAutoCompact === true) {
-			dbg("compaction_trigger.skip", { reason: "noAutoCompact" });
+		if (runtime.config.compactionEngine === "pi-default") {
+			dbg("compaction_trigger.skip", { reason: "compactionEngine_pi_default" });
 			return;
 		}
-		// Don't force Pi to compact unless the user explicitly opted into blackhole's pipeline.
-		// When overrideDefaultCompaction is false (default), blackhole stays out of the way
-		// and lets Pi handle its own compaction naturally.
-		if (runtime.config.overrideDefaultCompaction === false) {
-			dbg("compaction_trigger.skip", { reason: "overrideDefaultCompaction_false" });
-			return;
+		// NOTE: memory no longer gates compaction — memory:false + compaction:auto = compact without OM
+
+		// LEGACY: old config key guards — only apply when new keys are absent (unmigrated config)
+		if (runtime.config.compaction === undefined && runtime.config.compactionEngine === undefined) {
+			if (runtime.config.passive === true) {
+				dbg("compaction_trigger.skip", { reason: "passive" });
+				return;
+			}
+			if (runtime.config.noAutoCompact === true) {
+				dbg("compaction_trigger.skip", { reason: "noAutoCompact" });
+				return;
+			}
+			// Don't force Pi to compact unless the user explicitly opted into blackhole's pipeline.
+			// When overrideDefaultCompaction is false (default), blackhole stays out of the way
+			// and lets Pi handle its own compaction naturally.
+			if (runtime.config.overrideDefaultCompaction === false) {
+				dbg("compaction_trigger.skip", { reason: "overrideDefaultCompaction_false" });
+				return;
+			}
 		}
 		if (runtime.compactInFlight) {
 			dbg("compaction_trigger.skip", { reason: "compactInFlight" });