@matthewfl/pi-contemplator 0.0.1

package/src/config.ts

@@ -0,0 +1,284 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ModelThinkingLevel } from "@earendil-works/pi-ai";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export interface ConfiguredModel {
+	provider: string;
+	id: string;
+	thinking?: ModelThinkingLevel;
+}
+
+/**
+ * How `compactAfterTokens` is interpreted.
+ *
+ * - `"calibrated"` (default): use the static `compactAfterTokens` value directly.
+ *   Backwards-compatible with all existing V3 configs.
+ *
+ * - `"ratio"`: compute the effective threshold as
+ *   `floor(model.contextWindow * compactAfterTokensRatio)`. This auto-scales the
+ *   proactive compaction trigger to the active model's context window, so a 1M
+ *   context model is not preempted at the same 81K threshold as a 128K model.
+ *
+ *   Some models advertise a large context window but lose attention at long
+ *   range; users can lower `compactAfterTokensRatio` to compact earlier on such
+ *   models without giving up the window on models that stay sharp.
+ *
+ *   When the active model's `contextWindow` is unavailable (undefined, 0, or
+ *   negative), ratio mode falls back to the calibrated `compactAfterTokens`
+ *   value so compaction still triggers safely.
+ */
+export type CompactAfterTokensMode = "calibrated" | "ratio";
+
+export interface Config {
+	observeAfterTokens: number;
+	reflectAfterTokens: number;
+	/**
+	 * Maximum estimated source tokens serialized into a single observer chunk.
+	 * Unset (default) derives the cap from the resolved memory model's context
+	 * window; see {@link resolveObserverChunkMaxTokens}.
+	 */
+	observerChunkMaxTokens?: number;
+	compactAfterTokens: number;
+	compactAfterTokensMode: CompactAfterTokensMode;
+	compactAfterTokensRatio: number;
+	observationsPoolMaxTokens: number;
+	observationsPoolTargetTokens: number;
+	agentMaxTurns: number;
+	model?: ConfiguredModel;
+	showWorkerNotifications: boolean;
+	passive: boolean;
+	/** Run the asynchronous observer when a compaction begins. */
+	compactionObserverEnabled: boolean;
+	contemplatorEnabled: boolean;
+	contemplatorModel?: ConfiguredModel;
+	/** Allow the contemplator to commission scoped structural reviewers. */
+	reviewerEnabled: boolean;
+	/** Optional model override used only by short-lived structural reviewers. */
+	reviewerModel?: ConfiguredModel;
+	contemplatorMinNewObservations: number;
+	contemplatorMinNewReflections: number;
+	contemplatorMinTurns: number;
+	debugLog: boolean;
+}
+
+export const DEFAULTS: Config = {
+	observeAfterTokens: 10_000,
+	reflectAfterTokens: 20_000,
+	compactAfterTokens: 81_000,
+	compactAfterTokensMode: "calibrated",
+	compactAfterTokensRatio: 0.68,
+	observationsPoolMaxTokens: 20_000,
+	observationsPoolTargetTokens: 10_000,
+	agentMaxTurns: 16,
+	showWorkerNotifications: true,
+	passive: false,
+	compactionObserverEnabled: true,
+	contemplatorEnabled: true,
+	reviewerEnabled: true,
+	contemplatorMinNewObservations: 8,
+	contemplatorMinNewReflections: 1,
+	contemplatorMinTurns: 10,
+	debugLog: false,
+};
+
+export const COMPACT_AFTER_TOKENS_MODE_VALUES: readonly CompactAfterTokensMode[] = ["calibrated", "ratio"] as const;
+
+/**
+ * Resolve the effective proactive-compaction token threshold for the given
+ * config and active model context window.
+ *
+ * In `"calibrated"` mode this is always `config.compactAfterTokens`.
+ *
+ * In `"ratio"` mode this is `floor(contextWindow * compactAfterTokensRatio)`
+ * (clamped to a minimum of 1) when `contextWindow` is a positive number, and
+ * falls back to `config.compactAfterTokens` otherwise.
+ */
+export function resolveCompactAfterTokens(config: Config, contextWindow: number | undefined): number {
+	if (config.compactAfterTokensMode === "ratio" && typeof contextWindow === "number" && contextWindow > 0) {
+		return Math.max(1, Math.floor(contextWindow * config.compactAfterTokensRatio));
+	}
+	return config.compactAfterTokens;
+}
+
+export const THINKING_LEVEL_VALUES: readonly ModelThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+
+/** Observer chunk cap used when no config is set and the model's context window is unknown. */
+export const OBSERVER_CHUNK_FALLBACK_MAX_TOKENS = 60_000;
+
+/** Smallest useful observer chunk: enough for labels, omission markers, and source context. */
+export const OBSERVER_CHUNK_MIN_TOKENS = 256;
+
+/**
+ * Fraction of the memory model's context window used for the derived observer
+ * chunk cap. Chunk sizes are estimated at ~4 chars/token, which can undercount
+ * real tokens by up to ~4x on non-ASCII content, so 0.2 keeps even the worst
+ * case at ~80% of the window with room left for the system prompt, prior
+ * memory, and the response.
+ */
+export const OBSERVER_CHUNK_CONTEXT_RATIO = 0.2;
+
+/**
+ * Resolve the maximum estimated tokens the observer serializes into one chunk.
+ *
+ * An explicit `observerChunkMaxTokens` config value always wins. Otherwise the
+ * cap is `floor(contextWindow * OBSERVER_CHUNK_CONTEXT_RATIO)` for the resolved
+ * memory model, falling back to {@link OBSERVER_CHUNK_FALLBACK_MAX_TOKENS} when
+ * the context window is unavailable.
+ *
+ * Without a cap, a backlog that outgrows the model's context window (e.g.
+ * after repeated observer failures, or when the extension is enabled mid-way
+ * into a long session) makes every observer call fail, so coverage never
+ * advances and the session can never recover. With the cap, oversized backlogs
+ * are drained oldest-first across successive runs.
+ */
+export function resolveObserverChunkMaxTokens(config: Config, contextWindow: number | undefined): number {
+	if (config.observerChunkMaxTokens !== undefined && config.observerChunkMaxTokens > 0) {
+		return Math.max(OBSERVER_CHUNK_MIN_TOKENS, config.observerChunkMaxTokens);
+	}
+	if (typeof contextWindow === "number" && Number.isFinite(contextWindow) && contextWindow > 0) {
+		return Math.max(
+			OBSERVER_CHUNK_MIN_TOKENS,
+			Math.floor(contextWindow * OBSERVER_CHUNK_CONTEXT_RATIO),
+		);
+	}
+	return OBSERVER_CHUNK_FALLBACK_MAX_TOKENS;
+}
+
+const SETTINGS_KEY = "observational-memory";
+const PASSIVE_ENV = "PI_OBSERVATIONAL_MEMORY_PASSIVE";
+
+function positiveIntegerOrUndefined(value: unknown): number | undefined {
+	return Number.isInteger(value) && typeof value === "number" && value > 0 ? value : undefined;
+}
+
+function validTargetOrUndefined(value: unknown, maxTokens: number): number | undefined {
+	const target = positiveIntegerOrUndefined(value);
+	return target !== undefined && target < maxTokens ? target : undefined;
+}
+
+function derivedObservationPoolTarget(maxTokens: number): number {
+	return Math.floor(maxTokens / 2);
+}
+
+function isThinkingLevel(value: unknown): value is ModelThinkingLevel {
+	return typeof value === "string" && (THINKING_LEVEL_VALUES as readonly string[]).includes(value);
+}
+
+function isCompactAfterTokensMode(value: unknown): value is CompactAfterTokensMode {
+	return typeof value === "string" && (COMPACT_AFTER_TOKENS_MODE_VALUES as readonly string[]).includes(value);
+}
+
+/**
+ * A valid ratio is a finite number strictly between 0 and 1.
+ * 0 would never trigger; >= 1 would compact at/after the full window with no
+ * room left for the response.
+ */
+function validRatioOrUndefined(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 && value < 1 ? value : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function normalizeModel(value: unknown): ConfiguredModel | undefined {
+	if (!isRecord(value)) return undefined;
+	const provider = nonEmptyString(value.provider);
+	const id = nonEmptyString(value.id);
+	if (!provider || !id) return undefined;
+	const model: ConfiguredModel = { provider, id };
+	if (isThinkingLevel(value.thinking)) model.thinking = value.thinking;
+	return model;
+}
+
+function normalizeSettingsConfig(value: Record<string, unknown>): Partial<Config> {
+	const normalized: Partial<Config> = {};
+	const numberKeys = [
+		"observeAfterTokens",
+		"reflectAfterTokens",
+		"observerChunkMaxTokens",
+		"compactAfterTokens",
+		"observationsPoolMaxTokens",
+		"observationsPoolTargetTokens",
+		"agentMaxTurns",
+		"contemplatorMinNewObservations",
+		"contemplatorMinNewReflections",
+		"contemplatorMinTurns",
+	] as const;
+	for (const key of numberKeys) {
+		const normalizedValue = positiveIntegerOrUndefined(value[key]);
+		if (normalizedValue !== undefined) normalized[key] = normalizedValue;
+	}
+	if (isCompactAfterTokensMode(value.compactAfterTokensMode)) {
+		normalized.compactAfterTokensMode = value.compactAfterTokensMode;
+	}
+	const ratio = validRatioOrUndefined(value.compactAfterTokensRatio);
+	if (ratio !== undefined) normalized.compactAfterTokensRatio = ratio;
+	if (typeof value.showWorkerNotifications === "boolean") normalized.showWorkerNotifications = value.showWorkerNotifications;
+	if (typeof value.passive === "boolean") normalized.passive = value.passive;
+	if (typeof value.compactionObserverEnabled === "boolean") normalized.compactionObserverEnabled = value.compactionObserverEnabled;
+	if (typeof value.contemplatorEnabled === "boolean") normalized.contemplatorEnabled = value.contemplatorEnabled;
+	if (typeof value.reviewerEnabled === "boolean") normalized.reviewerEnabled = value.reviewerEnabled;
+	if (typeof value.debugLog === "boolean") normalized.debugLog = value.debugLog;
+	const model = normalizeModel(value.model);
+	if (model) normalized.model = model;
+	const contemplatorModel = normalizeModel(value.contemplatorModel);
+	if (contemplatorModel) normalized.contemplatorModel = contemplatorModel;
+	const reviewerModel = normalizeModel(value.reviewerModel);
+	if (reviewerModel) normalized.reviewerModel = reviewerModel;
+	return normalized;
+}
+
+export function readEnvConfig(env: NodeJS.ProcessEnv = process.env): Partial<Config> {
+	const result: Partial<Config> = {};
+	const rawPassive = env[PASSIVE_ENV];
+	if (rawPassive !== undefined) {
+		const passive = rawPassive.trim().toLowerCase();
+		if (["1", "true", "yes", "on"].includes(passive)) result.passive = true;
+		if (["0", "false", "no", "off"].includes(passive)) result.passive = false;
+	}
+	const compactionObserver = env.PI_OBSERVATIONAL_MEMORY_COMPACTION_OBSERVER?.trim().toLowerCase();
+	if (["1", "true", "yes", "on"].includes(compactionObserver ?? "")) result.compactionObserverEnabled = true;
+	if (["0", "false", "no", "off"].includes(compactionObserver ?? "")) result.compactionObserverEnabled = false;
+	return result;
+}
+
+function readNamespacedConfig(path: string): Partial<Config> {
+	if (!existsSync(path)) return {};
+	try {
+		const raw = JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown>;
+		const nested = raw[SETTINGS_KEY];
+		return isRecord(nested) ? normalizeSettingsConfig(nested) : {};
+	} catch {
+		return {};
+	}
+}
+
+export function loadConfig(cwd: string, env: NodeJS.ProcessEnv = process.env): Config {
+	const globalPath = join(getAgentDir(), "settings.json");
+	const projectPath = join(cwd, ".pi", "settings.json");
+	const globalConfig = readNamespacedConfig(globalPath);
+	const projectConfig = readNamespacedConfig(projectPath);
+	const envConfig = readEnvConfig(env);
+	const merged = {
+		...DEFAULTS,
+		observationsPoolTargetTokens: undefined,
+		...globalConfig,
+		...projectConfig,
+		...envConfig,
+	};
+	const target = validTargetOrUndefined(
+		merged.observationsPoolTargetTokens,
+		merged.observationsPoolMaxTokens,
+	) ?? derivedObservationPoolTarget(merged.observationsPoolMaxTokens);
+
+	return {
+		...merged,
+		observationsPoolTargetTokens: target,
+	};
+}

package/src/debug-log.ts

@@ -0,0 +1,72 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { existsSync, mkdirSync, renameSync, statSync, unlinkSync, appendFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export const DEBUG_LOG_MAX_BYTES = 10 * 1024 * 1024;
+export const DEBUG_LOG_RELATIVE_PATH = join("observational-memory", "debug.ndjson");
+export const DEBUG_LOG_SESSION_DIR_RELATIVE_PATH = join("observational-memory", "debug");
+
+export interface DebugLogContext {
+	enabled: boolean;
+	cwd?: string;
+	sessionId?: string;
+	sessionFile?: string;
+	runId?: string;
+}
+
+const storage = new AsyncLocalStorage<DebugLogContext>();
+
+export function withDebugLogContext<T>(context: DebugLogContext, fn: () => T): T {
+	const parent = storage.getStore();
+	return storage.run({ ...parent, ...context }, fn);
+}
+
+export function safeDebugLogSessionId(sessionId: string | undefined): string | undefined {
+	const trimmed = sessionId?.trim();
+	if (!trimmed) return undefined;
+	const sanitized = trimmed
+		.replace(/[^A-Za-z0-9._-]+/g, "_")
+		.replace(/^_+|_+$/g, "")
+		.slice(0, 128);
+	if (!/[A-Za-z0-9]/.test(sanitized)) return undefined;
+	return sanitized;
+}
+
+export function debugLogRelativePath(context: Pick<DebugLogContext, "sessionId">): string {
+	const safeSessionId = safeDebugLogSessionId(context.sessionId);
+	return safeSessionId
+		? join(DEBUG_LOG_SESSION_DIR_RELATIVE_PATH, `${safeSessionId}.ndjson`)
+		: DEBUG_LOG_RELATIVE_PATH;
+}
+
+export function debugLog(event: string, data: Record<string, unknown> = {}): void {
+	const context = storage.getStore();
+	if (context?.enabled !== true) return;
+
+	try {
+		const path = join(getAgentDir(), debugLogRelativePath(context));
+		mkdirSync(dirname(path), { recursive: true });
+		rotateIfNeeded(path);
+		const payload = {
+			ts: new Date().toISOString(),
+			event,
+			cwd: context.cwd,
+			sessionId: context.sessionId,
+			sessionFile: context.sessionFile,
+			runId: context.runId,
+			data,
+		};
+		appendFileSync(path, `${JSON.stringify(payload)}\n`, "utf-8");
+	} catch {
+		// Debug logging must never affect memory behavior.
+	}
+}
+
+function rotateIfNeeded(path: string): void {
+	if (!existsSync(path)) return;
+	if (statSync(path).size < DEBUG_LOG_MAX_BYTES) return;
+	const backupPath = `${path}.1`;
+	if (existsSync(backupPath)) unlinkSync(backupPath);
+	renameSync(path, backupPath);
+}

package/src/hooks/compaction-hook.ts

@@ -0,0 +1,99 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { computeSessionSettings, type Runtime } from "../runtime.js";
+import { launchCompactionObserver, type ConsolidationCtx } from "./consolidation-trigger.js";
+import { buildCompactionProjection, renderSummary, type Entry } from "../session-ledger/index.js";
+import { watchForNativeCompactionResume } from "./compaction-resume.js";
+
+const DEFAULT_OBSERVATIONS_POOL_MAX_TOKENS = 20_000;
+const COMPACTION_STATUS_KEY = "observational-memory-compaction";
+
+function observationsPoolMaxTokens(runtime: Runtime): number {
+	const value = (runtime.config as { observationsPoolMaxTokens?: unknown }).observationsPoolMaxTokens;
+	return typeof value === "number" && Number.isFinite(value) && value > 0
+		? value
+		: DEFAULT_OBSERVATIONS_POOL_MAX_TOKENS;
+}
+
+export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void {
+	pi.on("session_before_compact", async (event: any, ctx: any) => {
+		if (runtime.compactHookInFlight) {
+			if (ctx.hasUI) {
+				ctx.ui.notify(
+					"Observational memory: another compaction is already in progress; cancelling duplicate",
+					"warning",
+				);
+			}
+			return { cancel: true };
+		}
+
+		const initiatedByOm = runtime.compactInFlight && event.reason === "manual";
+		const reason = initiatedByOm ? (runtime.compactOrigin ?? "proactive") : event.reason;
+		if (ctx.hasUI) {
+			let pending = "";
+			if (event.willRetry) pending = ", retry pending";
+			else if (initiatedByOm) pending = ", resume pending";
+			ctx.ui.setStatus?.(COMPACTION_STATUS_KEY, `OM compaction: running (${reason}${pending})`);
+			if (!initiatedByOm) {
+				const continuation = event.willRetry ? "; the interrupted agent run will resume automatically" : "";
+				ctx.ui.notify(`Observational memory: compaction started (${reason})${continuation}`, "info");
+			}
+		}
+		event.signal?.addEventListener?.("abort", () => {
+			if (ctx.hasUI) ctx.ui.setStatus?.(COMPACTION_STATUS_KEY, undefined);
+		}, { once: true });
+
+		runtime.compactHookInFlight = true;
+		try {
+			runtime.ensureConfig(ctx.cwd);
+			const { preparation, branchEntries } = event;
+			const branch = branchEntries as Entry[];
+			// Start memory capture without delaying compaction. This is configurable so
+			// users can compare native compaction with and without the observer sidecar.
+			if (runtime.config.compactionObserverEnabled !== false) {
+				launchCompactionObserver(pi, runtime, ctx as ConsolidationCtx, branch);
+			}
+			const { firstKeptEntryId, tokensBefore } = preparation;
+			const projection = buildCompactionProjection(
+				branch,
+				firstKeptEntryId,
+				{ observationsPoolMaxTokens: observationsPoolMaxTokens(runtime) },
+			);
+			const summary = renderSummary(projection.reflections, projection.observations);
+			// Compaction removes older custom entries from the active branch. Keep
+			// session-scoped overrides in the compaction details so they can be
+			// restored after a reload from the surviving branch. Bake the merged
+			// branch intent (live om.settings entries winning over earlier snapshots)
+			// rather than the raw in-memory overlay, which can lag out-of-band
+			// om.settings appends and would otherwise silently override newer entries
+			// at the next restore.
+			const details = {
+				...projection.details,
+				sessionSettings: computeSessionSettings(branch),
+			};
+
+			return {
+				compaction: {
+					summary,
+					firstKeptEntryId,
+					tokensBefore,
+					details,
+				},
+			};
+		} finally {
+			runtime.compactHookInFlight = false;
+		}
+	});
+
+	pi.on("session_compact", (event: any, ctx: any) => {
+		const initiatedByOm = runtime.compactInFlight && event.reason === "manual";
+		const reason = initiatedByOm ? (runtime.compactOrigin ?? "proactive") : event.reason;
+		if (event.willRetry) watchForNativeCompactionResume(pi, runtime, ctx);
+		if (!ctx.hasUI) return;
+		ctx.ui.setStatus?.(COMPACTION_STATUS_KEY, undefined);
+		let continuation = "";
+		if (event.willRetry) continuation = "; resuming the interrupted agent run";
+		else if (initiatedByOm) continuation = "; resuming the agent run";
+		ctx.ui.notify(`Observational memory: compaction complete (${reason})${continuation}`, "info");
+	});
+}

package/src/hooks/compaction-resume.ts

@@ -0,0 +1,124 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { Runtime } from "../runtime.js";
+
+const NATIVE_RESUME_GRACE_MS = 5_000;
+const RESUME_RETRY_DELAYS_MS = [250, 1_000] as const;
+
+interface ResumeCtx {
+	hasUI: boolean;
+	ui?: {
+		notify?: (message: string, level?: "info" | "warning" | "error") => void;
+	};
+}
+
+function clearResumeWatch(runtime: Runtime): void {
+	if (runtime.compactionResumeTimer !== undefined) {
+		clearTimeout(runtime.compactionResumeTimer);
+		runtime.compactionResumeTimer = undefined;
+	}
+	runtime.compactionResumePending = false;
+}
+
+function beginResumeWatch(runtime: Runtime): number {
+	clearResumeWatch(runtime);
+	runtime.compactionResumePending = true;
+	runtime.compactionResumeGeneration += 1;
+	return runtime.compactionResumeGeneration;
+}
+
+function isCurrentWatch(runtime: Runtime, generation: number): boolean {
+	return runtime.compactionResumePending && runtime.compactionResumeGeneration === generation;
+}
+
+function sendResumeMessage(pi: ExtensionAPI, ctx: ResumeCtx, afterFailure: boolean): void {
+	try {
+		pi.sendMessage({
+			customType: "om.compaction.resume",
+			content: afterFailure
+				? "Context compaction failed. Continue the current task without waiting for another user message."
+				: "Continue the current task from the compacted context without waiting for another user message.",
+			display: false,
+		}, {
+			deliverAs: "followUp",
+			triggerTurn: true,
+		});
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		ctx.ui?.notify?.(`Observational memory: failed to request continuation: ${message}`, "error");
+	}
+}
+
+function scheduleResumeRetries(
+	pi: ExtensionAPI,
+	runtime: Runtime,
+	ctx: ResumeCtx,
+	generation: number,
+	afterFailure: boolean,
+	retryIndex = 0,
+): void {
+	if (!isCurrentWatch(runtime, generation)) return;
+	if (retryIndex >= RESUME_RETRY_DELAYS_MS.length) {
+		runtime.compactionResumeTimer = setTimeout(() => {
+			if (!isCurrentWatch(runtime, generation)) return;
+			clearResumeWatch(runtime);
+			ctx.ui?.notify?.(
+				"Observational memory: the agent did not acknowledge continuation after compaction",
+				"error",
+			);
+		}, RESUME_RETRY_DELAYS_MS.at(-1));
+		return;
+	}
+
+	runtime.compactionResumeTimer = setTimeout(() => {
+		if (!isCurrentWatch(runtime, generation)) return;
+		ctx.ui?.notify?.(
+			`Observational memory: continuation did not start; retrying (${retryIndex + 1}/${RESUME_RETRY_DELAYS_MS.length})`,
+			"warning",
+		);
+		sendResumeMessage(pi, ctx, afterFailure);
+		scheduleResumeRetries(pi, runtime, ctx, generation, afterFailure, retryIndex + 1);
+	}, RESUME_RETRY_DELAYS_MS[retryIndex]);
+}
+
+/** Send OM's continuation immediately, then retry unless a new agent run acknowledges it. */
+export function resumeAfterCompaction(
+	pi: ExtensionAPI,
+	runtime: Runtime,
+	ctx: ResumeCtx,
+	afterFailure = false,
+): void {
+	const generation = beginResumeWatch(runtime);
+	sendResumeMessage(pi, ctx, afterFailure);
+	scheduleResumeRetries(pi, runtime, ctx, generation, afterFailure);
+}
+
+/**
+ * Pi normally retries native overflow compaction itself. If no new agent_start
+ * arrives after the compaction event settles, send OM's hidden continuation as
+ * a fallback. This also covers length-stop retries that cannot continue from an
+ * assistant message.
+ */
+export function watchForNativeCompactionResume(
+	pi: ExtensionAPI,
+	runtime: Runtime,
+	ctx: ResumeCtx,
+): void {
+	const generation = beginResumeWatch(runtime);
+	runtime.compactionResumeTimer = setTimeout(() => {
+		if (!isCurrentWatch(runtime, generation)) return;
+		ctx.ui?.notify?.(
+			"Observational memory: native compaction did not resume the agent; sending fallback continuation",
+			"warning",
+		);
+		sendResumeMessage(pi, ctx, false);
+		scheduleResumeRetries(pi, runtime, ctx, generation, false);
+	}, NATIVE_RESUME_GRACE_MS);
+}
+
+/** Any new agent run proves that the post-compaction continuation started. */
+export function registerCompactionResumeAcknowledgement(pi: ExtensionAPI, runtime: Runtime): void {
+	pi.on("agent_start", () => {
+		if (!runtime.compactionResumePending) return;
+		clearResumeWatch(runtime);
+	});
+}