pi-blackhole 0.3.2 → 0.3.4

package/src/om/configure-overlay.ts

@@ -0,0 +1,383 @@
+/**
+ * Configure Overlay — editable settings overlay for pi-blackhole-config.json.
+ *
+ * Used by `/blackhole configure` to edit compaction, memory, and debug settings.
+ * Opens as a floating overlay via ctx.ui.custom({ overlay: true }).
+ * Navigation: ↑↓  Edit: Enter  Save: Ctrl+S  Cancel: Esc
+ */
+
+import { visibleWidth } from "./key-matcher.js";
+import { matchesKey, decodeKittyPrintable } from "@earendil-works/pi-tui";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Field types
+// ---------------------------------------------------------------------------
+
+interface FieldDef {
+	key: string;
+	label: string;
+	type: "number" | "boolean" | "enum";
+	section: string;
+	enumValues?: string[];
+	helpText?: string;
+}
+
+interface FieldState {
+	def: FieldDef;
+	value: string;
+	editing: boolean;
+	cursor: number;
+}
+
+// ---------------------------------------------------------------------------
+// Field definitions
+// ---------------------------------------------------------------------------
+
+const FIELDS: FieldDef[] = [
+	// ── Compaction ──
+	{ key: "compaction", label: "Compaction mode", type: "enum", section: "Compaction", enumValues: ["auto", "manual", "off"],
+		helpText: "auto=trigger on threshold, manual=only /blackhole, off=auto:Pi handles, /blackhole:blackhole pipeline" },
+	{ key: "compactionEngine", label: "Compaction engine", type: "enum", section: "Compaction", enumValues: ["blackhole", "pi-default"],
+		helpText: "blackhole=structured summary+OM, pi-default=built-in Pi summarization" },
+	{ key: "tailBehavior", label: "Visible tail", type: "enum", section: "Compaction", enumValues: ["minimal", "pi-default"],
+		helpText: "minimal=keep last user message only (default), pi-default=keep Pi's preserved visible context" },
+	{ key: "compactAfterTokens", label: "Auto-compact threshold", type: "number", section: "Compaction",
+		helpText: "Token count that triggers auto-compaction when reached" },
+
+	// ── Observational Memory ──
+	{ key: "memory", label: "Observational memory", type: "boolean", section: "Observational Memory",
+		helpText: "Enable OM workers (observer, reflector, dropper) and content injection" },
+	{ key: "observeAfterTokens", label: "Observer threshold", type: "number", section: "Observational Memory",
+		helpText: "Tokens accumulated since last observer run before triggering next observe" },
+	{ key: "reflectAfterTokens", label: "Reflect + dropper threshold", type: "number", section: "Observational Memory",
+		helpText: "Tokens accumulated since last reflect before triggering reflector and dropper" },
+	{ key: "observationsPoolMaxTokens", label: "Observation pool max", type: "number", section: "Observational Memory",
+		helpText: "Max tokens in observation pool before dropper prunes (fold pressure)" },
+	{ key: "observationsPoolTargetTokens", label: "Observation pool target", type: "number", section: "Observational Memory",
+		helpText: "Target tokens after dropper prunes (defaults to half of pool max)" },
+	{ key: "reflectorInputMaxTokens", label: "Reflector input max", type: "number", section: "Observational Memory",
+		helpText: "Max prompt tokens for reflector model input (rolling window cap)" },
+	{ key: "dropperInputMaxTokens", label: "Dropper input max", type: "number", section: "Observational Memory",
+		helpText: "Max prompt tokens for dropper model input (rolling window cap)" },
+	{ key: "observerChunkMaxTokens", label: "Observer chunk max", type: "number", section: "Observational Memory",
+		helpText: "Max source entry tokens sent to observer per chunk" },
+	{ key: "observerPreambleMaxTokens", label: "Observer preamble max", type: "number", section: "Observational Memory",
+		helpText: "Preamble budget in manual compaction mode (0=auto-compute 30% of chunk)" },
+	{ key: "agentMaxTurns", label: "Max turns per agent", type: "number", section: "Observational Memory",
+		helpText: "Shared turn cap for background memory agents" },
+
+	// ── Debug ──
+	{ key: "debug", label: "Debug snapshots", type: "boolean", section: "Debug",
+		helpText: "Write detailed debug snapshots to /tmp/pi-blackhole-debug.json" },
+	{ key: "debugLog", label: "Debug JSONL logging", type: "boolean", section: "Debug",
+		helpText: "Write structured JSONL debug logs to agent directory" },
+];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function formatValue(def: FieldDef, rawValue: unknown): string {
+	if (rawValue === undefined || rawValue === null) return "";
+	switch (def.type) {
+		case "boolean":
+			return rawValue ? "on" : "off";
+		default:
+			return String(rawValue);
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Theme helper — wraps a minimal theme shape
+// ---------------------------------------------------------------------------
+
+type ThemeShim = {
+	fg: (style: string, text: string) => string;
+};
+
+const EMPTY_THEME: ThemeShim = {
+	fg: (_s: string, t: string) => t,
+};
+
+// ---------------------------------------------------------------------------
+// Overlay Component factory
+// ---------------------------------------------------------------------------
+
+export interface OverlayResult {
+	saved: boolean;
+	path: string;
+}
+
+/**
+ * Create a ConfigureOverlay instance to pass to ctx.ui.custom().
+ *
+ * Usage:
+ * ```ts
+ * const result = await ctx.ui.custom<OverlayResult | undefined>(
+ *   (tui, theme, _kb, done) => createConfigureOverlay(configPath, theme, tui, done),
+ *   { overlay: true },
+ * );
+ * ```
+ */
+export function createConfigureOverlay(
+	configPath: string,
+	theme: unknown,
+	tui: { requestRender: () => void },
+	done: (result: OverlayResult | undefined) => void,
+): { render(width: number): string[]; handleInput(data: string): void; invalidate(): void; dispose(): void } {
+	const th: ThemeShim = (theme && typeof (theme as Record<string, unknown>).fg === "function")
+		? theme as ThemeShim
+		: EMPTY_THEME;
+
+	// Parse config file
+	let raw: Record<string, unknown>;
+	try {
+		raw = JSON.parse(readFileSync(configPath, "utf8")) as Record<string, unknown>;
+	} catch {
+		raw = {};
+	}
+
+	const fields: FieldState[] = FIELDS.map((def) => ({
+		def,
+		value: formatValue(def, raw[def.key]),
+		editing: false,
+		cursor: 0,
+	}));
+
+	let selectedIndex = 0;
+	let cachedLines: string[] | undefined;
+
+	function invalidate(): void {
+		cachedLines = undefined;
+		try { tui.requestRender(); } catch { /* no-op */ }
+	}
+
+	function save(): boolean {
+		try {
+			const updated = { ...raw };
+			for (const f of fields) {
+				const val = f.value;
+				if (val === "" && !(f.def.key in raw)) continue;
+				switch (f.def.type) {
+					case "boolean":
+						updated[f.def.key] = val === "on";
+						break;
+					case "number": {
+						const num = Number(val);
+						updated[f.def.key] = (val && !isNaN(num)) ? num : raw[f.def.key];
+						break;
+					}
+					case "enum":
+						updated[f.def.key] = val;
+						break;
+					default:
+						updated[f.def.key] = val;
+						break;
+				}
+			}
+			mkdirSync(dirname(configPath), { recursive: true });
+			writeFileSync(configPath, JSON.stringify(updated, null, 2) + "\n");
+			raw = updated;
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	function handleInput(data: string): void {
+		const cur = fields[selectedIndex];
+		if (!cur) return;
+
+		// While editing a number field
+		if (cur.editing) {
+			if (matchesKey(data, "escape")) {
+				cur.value = formatValue(cur.def, raw[cur.def.key]);
+				cur.editing = false;
+				invalidate();
+				return;
+			}
+			if (matchesKey(data, "enter") || matchesKey(data, "tab")) {
+				cur.editing = false;
+				invalidate();
+				return;
+			}
+			if (matchesKey(data, "backspace")) {
+				if (cur.cursor > 0) {
+					cur.value = cur.value.slice(0, cur.cursor - 1) + cur.value.slice(cur.cursor);
+					cur.cursor--;
+					invalidate();
+				}
+				return;
+			}
+			if (matchesKey(data, "left")) {
+				cur.cursor = Math.max(0, cur.cursor - 1);
+				invalidate();
+				return;
+			}
+			if (matchesKey(data, "right")) {
+				cur.cursor = Math.min(cur.value.length, cur.cursor + 1);
+				invalidate();
+				return;
+			}
+			const digit = decodeKittyPrintable(data) ?? data;
+			if (digit.length === 1 && digit >= "0" && digit <= "9") {
+				cur.value = cur.value.slice(0, cur.cursor) + digit + cur.value.slice(cur.cursor);
+				cur.cursor++;
+				invalidate();
+			}
+			return;
+		}
+
+		// Not editing — global navigation
+
+		// Ctrl+S → save and close
+		if (matchesKey(data, "ctrl+s")) {
+			const saved = save();
+			done({ saved, path: configPath });
+			return;
+		}
+
+		// Esc → close without saving
+		if (matchesKey(data, "escape")) {
+			done(undefined);
+			return;
+		}
+
+		// Enter/space → edit/toggle
+		if (matchesKey(data, "enter") || matchesKey(data, "space")) {
+			switch (cur.def.type) {
+				case "boolean":
+					cur.value = cur.value === "on" ? "off" : "on";
+					invalidate();
+					break;
+				case "enum": {
+					const vals = cur.def.enumValues;
+					if (!vals || vals.length === 0) return;
+					const idx = vals.indexOf(cur.value);
+					cur.value = vals[(idx + 1) % vals.length];
+					invalidate();
+					break;
+				}
+				case "number":
+					cur.editing = true;
+					cur.cursor = cur.value.length;
+					invalidate();
+					break;
+			}
+			return;
+		}
+
+		// ↑↓ navigation
+		if (matchesKey(data, "up")) {
+			selectedIndex = Math.max(0, selectedIndex - 1);
+			invalidate();
+			return;
+		}
+		if (matchesKey(data, "down")) {
+			selectedIndex = Math.min(fields.length - 1, selectedIndex + 1);
+			invalidate();
+			return;
+		}
+	}
+
+	/** Compute minimum width to fit all content, plus borders. */
+	function contentWidth(): number {
+		const longestHelp = FIELDS.reduce((max, f) => {
+			if (!f.helpText) return max;
+			return Math.max(max, visibleWidth(f.helpText));
+		}, 0);
+		// Help line: │  ${help} ${│  → 4 chars overhead + at least 1 space
+		const helpOverhead = 4;
+		const longestLabel = FIELDS.reduce((max, f) => {
+			return Math.max(max, visibleWidth(f.label) + 3); // prefix + space + label
+		}, 0);
+		// Section header: ── N ──  → up to ~30, but help text dominates
+		// Hint line: ~54 visible
+		return Math.max(54 + 4, longestHelp + helpOverhead, longestLabel + 20);
+	}
+
+	function render(width: number): string[] {
+		if (cachedLines) return cachedLines;
+
+		const minW = contentWidth();
+		const w = Math.max(2, Math.min(width - 2, Math.max(minW, 50)));
+		const innerW = w - 4;
+		const fg = (style: string, text: string) => th.fg(style, text);
+
+		const lines: string[] = [];
+
+		// Top border + header
+		lines.push(fg("border", `╭${"─".repeat(w - 2)}╮`));
+		lines.push(fg("border", `│ ${fg("accent", "Blackhole Configuration")}${" ".repeat(Math.max(0, innerW + 1 - 24))}│`));
+		lines.push(fg("border", `├${"─".repeat(w - 2)}┤`));
+
+		let currentSection = "";
+
+		for (let i = 0; i < fields.length; i++) {
+			const f = fields[i];
+			const isSelected = i === selectedIndex;
+			const isEditing = isSelected && f.editing;
+
+			// Section header
+			if (f.def.section !== currentSection) {
+				currentSection = f.def.section;
+				if (i > 0) {
+					lines.push(fg("border", `│${" ".repeat(w - 2)}│`));
+				}
+				lines.push(fg("border", `│ ${fg("dim", `── ${currentSection} ──`)}${" ".repeat(Math.max(0, innerW + 1 - currentSection.length - 6))}│`));
+			}
+
+			// Field label
+			const prefix = isSelected ? fg("accent", isEditing ? ">>" : " >") : "  ";
+			const label = isSelected ? fg("accent", `${f.def.label}:`) : fg("text", `${f.def.label}:`);
+			const labelStr = `${prefix} ${label}`;
+			const labelVis = visibleWidth(labelStr);
+
+			// Value
+			let valueStr: string;
+			if (isEditing) {
+				const before = f.value.slice(0, f.cursor);
+				const cursorChar = f.cursor < f.value.length ? f.value[f.cursor] : " ";
+				const after = f.value.slice(f.cursor + 1);
+				valueStr = `${before}\x1b[7m${cursorChar}\x1b[27m${after}`;
+			} else {
+				switch (f.def.type) {
+					case "boolean":
+						valueStr = f.value === "on" ? fg("success", "on") : fg("muted", "off");
+						break;
+					default:
+						valueStr = f.value ? fg("text", f.value) : fg("dim", "(empty)");
+						break;
+				}
+			}
+
+			const valSpace = Math.max(10, innerW - labelVis - 1);
+			const truncated = visibleWidth(valueStr) > valSpace
+				? valueStr.slice(0, Math.max(0, valSpace - 3)) + "..."
+				: valueStr;
+			const remaining = innerW + 1 - labelVis - visibleWidth(truncated);
+
+			lines.push(fg("border", `│ ${labelStr}${truncated}${" ".repeat(Math.max(1, remaining))}│`));
+
+			// Help text for selected item
+			if (isSelected && f.def.helpText && !isEditing) {
+				const help = fg("dim", f.def.helpText);
+				const helpRemaining = innerW - visibleWidth(help);
+				lines.push(fg("border", `│  ${help}${" ".repeat(Math.max(1, helpRemaining))}│`));
+			}
+		}
+
+		// Bottom hints
+		lines.push(fg("border", `│${" ".repeat(w - 2)}│`));
+		const hintText = " Ctrl+S save  \u2191\u2193 navigate  Enter toggle  Esc cancel ";
+		lines.push(fg("border", `│${fg("accent", hintText)}${" ".repeat(Math.max(1, innerW + 2 - visibleWidth(hintText)))}│`));
+		lines.push(fg("border", `╰${"─".repeat(w - 2)}╯`));
+
+		cachedLines = lines;
+		return lines;
+	}
+
+	return { render, handleInput, invalidate, dispose: () => {} };
+}

package/src/om/consolidation.ts

@@ -16,7 +16,11 @@ 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 { effectiveContextWindow } from "./model-budget.js";
 import { serializeSourceAddressedBranchEntries } from "./serialize.js";
+
+/** Fixed overhead for system prompt, tool definitions, and turn scaffold in context window pre-check. */
+const AGENT_LOOP_RESERVE = 8_000;
 import {
 	readPendingState,
 	savePendingObservation,
@@ -55,9 +59,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 };
@@ -178,15 +182,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;
@@ -194,7 +199,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;
@@ -213,8 +228,12 @@ export function registerConsolidationTrigger(pi: ExtensionAPI, runtime: Runtime)
 
 function maybeLaunchConsolidation(pi: ExtensionAPI, runtime: Runtime, ctx: ConsolidationCtx): void {
 	runtime.ensureConfig(ctx.cwd);
-	if (runtime.config.passive === true) return;
 	if (runtime.config.memory === false) return;
+
+	// LEGACY: passive check — only applies when new keys are absent (unmigrated config)
+	if (runtime.config.compaction === undefined && runtime.config.compactionEngine === undefined) {
+		if (runtime.config.passive === true) return;
+	}
 	if (runtime.consolidationInFlight) return;
 	if (runtime.isConsolidationRetryGated()) return;
 
@@ -246,6 +265,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;
@@ -255,6 +276,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);
@@ -265,6 +288,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) {
@@ -363,6 +388,17 @@ async function runObserverStage(
 
 		// Resolve thinking level for the specific model (fallbacks may have their own thinking config)
 		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
+		const effectiveObsCtx = effectiveContextWindow(resolved.model as any, stageModelForThinking);
+		const observerEstimatedInput = runtime.config.observerChunkMaxTokens + 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");
+			if (ctx.hasUI && ctx.ui) ctx.ui.notify(`Observational memory: observer skipping ${(resolved.model as any).provider}/${(resolved.model as any).id} (context window ${effectiveObsCtx.toLocaleString()} too small for ~${observerEstimatedInput.toLocaleString()}-token input)`, "info");
+			continue;
+		}
+
 		try {
 			const result = await runObserver({
 				model: resolved.model as any,
@@ -497,6 +533,17 @@ async function runReflectorStage(
 
 		// Resolve thinking level for the specific model (fallbacks may have their own thinking config)
 		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
+		const effectiveRefCtx = effectiveContextWindow(resolved.model as any, stageModelForThinking);
+		const reflectorEstimatedInput = runtime.config.reflectorInputMaxTokens + 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");
+			if (ctx.hasUI && ctx.ui) ctx.ui.notify(`Observational memory: reflector skipping ${(resolved.model as any).provider}/${(resolved.model as any).id} (context window ${effectiveRefCtx.toLocaleString()} too small for ~${reflectorEstimatedInput.toLocaleString()}-token input)`, "info");
+			continue;
+		}
+
 		try {
 			// Existing memory summaries for context (capped).
 			// In noAutoCompact, merge accumulated pending batches with
@@ -643,6 +690,17 @@ async function runDropperStage(
 
 			// Resolve thinking level for the specific model (fallbacks may have their own thinking config)
 			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
+			const effectiveDropCtx = effectiveContextWindow(resolved.model as any, stageModelForThinking);
+			const dropperEstimatedInput = runtime.config.dropperInputMaxTokens + 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");
+				if (ctx.hasUI && ctx.ui) ctx.ui.notify(`Observational memory: dropper skipping ${(resolved.model as any).provider}/${(resolved.model as any).id} (context window ${effectiveDropCtx.toLocaleString()} too small for ~${dropperEstimatedInput.toLocaleString()}-token input)`, "info");
+				continue;
+			}
+
 			const droppedIds = await runDropper({
 				model: resolved.model as any,
 				apiKey: resolved.apiKey,

package/src/om/cooldown.ts

@@ -75,8 +75,13 @@ 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 {
+	// cooldownHours === 0 means cooldown disabled
+	if (model.cooldownHours === 0) return false;
+
 	const map = readCooldownMap();
 	const key = modelKey(model);
 	const entry = map[key];
@@ -97,11 +102,16 @@ export function isCooldownActive(model: OmModelConfig, now: Date = new Date()):
 /**
  * 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();

package/src/om/key-matcher.ts

@@ -0,0 +1,38 @@
+/**
+ * Terminal utilities shared by blackhole overlay components.
+ *
+ * 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.
+ */
+
+// ---------------------------------------------------------------------------
+// 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;
+}

package/src/om/model-budget.ts

@@ -1,4 +1,5 @@
 import type { Model } from "@earendil-works/pi-ai";
+import type { OmModelConfig } from "../core/unified-config.js";
 
 export const AGENT_LOOP_MAX_TOKENS = 32_000;
 
@@ -7,3 +8,24 @@ export function boundedMaxTokens(model: Model<any>, requested: number = AGENT_LO
 		? Math.min(model.maxTokens, requested)
 		: requested;
 }
+
+/**
+ * Get the effective context window for a resolved model.
+ *
+ * Resolution order:
+ * 1. Config override on the model config (OmModelConfig.contextWindow)
+ * 2. Pi's model registry value (model.contextWindow)
+ * 3. Fallback default (128000)
+ */
+export function effectiveContextWindow(
+	resolvedModel: Model<any>,
+	modelConfig?: OmModelConfig,
+): number {
+	if (modelConfig?.contextWindow !== undefined && modelConfig.contextWindow > 0) {
+		return modelConfig.contextWindow;
+	}
+	if (resolvedModel && typeof resolvedModel.contextWindow === "number" && resolvedModel.contextWindow > 0) {
+		return resolvedModel.contextWindow;
+	}
+	return 128_000;
+}