pi-mega-compact 0.11.2 → 0.11.4

package/extensions/mega-config.ts

@@ -63,6 +63,9 @@ export interface MegaConfig {
 	/** High-pressure floor for preserveRecent — when context is near the limit
 	 *  we compact deeper, but never below this (keeps recent turns for coherence). */
 	preserveRecentMin: number;
+	/** D.1: minimum context-growth percentage delta before re-compacting instead of
+	 *  replaying the cached trim (Default 50). Set via MEGACOMPACT_RECOMPACT_PCT_DELTA.*/
+	recompactPctDelta: number;
 	auto: boolean;
 	autoInline: boolean;
 	autoInlineK: number;
@@ -104,6 +107,10 @@ export interface MegaConfig {
 	 *  classification is upgraded to 'poisoned-context' (the stateful repeat
 	 *  signal). Default 3. Raise to make the upgrade less aggressive. */
 	poisonedContextRepeatThreshold: number;
+	/** R10: consecutive transient errors at which a calm "provider outage"
+	 *  advisory is sent to the user (distinct from the poisoned /clear advise).
+	 *  Default 3. `0` disables the advisory entirely. */
+	providerOutageAdviseThreshold: number;
 	/** S29: override the auto-compact fire point for tiered configs, as a
 	 *  fraction of the context window (e.g. 0.85). null = inherit the tier's
 	 *  tierPct (default; preserves existing fire points). The context-handler
@@ -295,6 +302,10 @@ export function loadConfig(): MegaConfig {
 			"MEGACOMPACT_POISONED_REPEAT_THRESHOLD",
 			3,
 		),
+		providerOutageAdviseThreshold: envFlag(
+			"MEGACOMPACT_PROVIDER_OUTAGE_THRESHOLD",
+			3,
+		),
 		autoPctTrigger,
 		autoInlineK: envFlag("MEGACOMPACT_AUTO_INLINE_K", 3),
 		dedupSim: Number(process.env.MEGACOMPACT_DEDUP_SIM ?? "0.9"),
@@ -312,6 +323,9 @@ export function loadConfig(): MegaConfig {
 		recallMaxTokens: envFlag("MEGACOMPACT_RECALL_MAX_TOKENS", 1500),
 		windowDedupe: envBool("MEGACOMPACT_WINDOW_DEDUPE", true),
 		tuiWidget: envBool("MEGACOMPACT_TUI_WIDGET", true),
+		// D.1: env-overridable recompact delta (minimum context growth % before
+		// re-compacting instead of replaying the cached live trim). Default 50.
+		recompactPctDelta: envFlag("MEGACOMPACT_RECOMPACT_PCT_DELTA", 50),
 		debug: envBool("MEGACOMPACT_DEBUG", false),
 	};
 }

package/extensions/mega-events/agent-handlers.ts

@@ -8,7 +8,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { MegaRuntime } from "../mega-runtime.js";
 import { piCompactWouldNoop, runMemoryReview } from "../mega-pipeline.js";
 import { memoryReviewCadence, type MegaConfig } from "../mega-config.js";
-import { recordScore } from "../../src/store/sqlite.js";
+import { recordScore, readLatestCacheHitPct } from "../../src/store/sqlite.js";
 import { evaluateAndUnlockAchievements } from "../../src/store/sqlite/game-achievements.js";
 import {
 	ensureConversationIdFor,
@@ -18,10 +18,13 @@ import { isMegaCache } from "../../src/game/scoring.js";
 import { resolveRepoRoot } from "../mega-config.js";
 import {
 	classifyError,
+	classifyErrorDetailed,
 	errorRetryBackoffMs,
 	extractErrorSignature,
+	isKnownRetryableTransient,
 } from "./error-classifier.js";
 import { safeSendUserMessage } from "./send-safe.js";
+import { maybeSendProviderOutageAdvisory } from "./outage-advisor.js";
 import { vectorStats } from "../../src/vectorStore.js";
 
 /** Register agent/turn tracking event handlers. */
@@ -301,7 +304,10 @@ export function registerAgentHandlers(
 			if (runtime.getCachedGameState().game_mode_on) {
 				const repo = resolveRepoRoot(ctx.cwd) ?? runtime.currentStateDir;
 				const st = vectorStats(runtime.store, runtime.rt.sessionId);
-				const cachePct = st.dedupHitRate * 100;
+				// C.3: prefer provider cache hit rate, fall back to dedup hit rate
+				const providerPct = readLatestCacheHitPct(runtime.currentStateDir);
+				const cachePct =
+					providerPct != null ? providerPct : st.dedupHitRate * 100;
 				const modelId = runtime.currentModel?.modelId ?? "unknown";
 				recordScore(runtime.currentStateDir, {
 					repo_root: repo,
@@ -389,14 +395,17 @@ export function registerAgentHandlers(
 				// S28 handles; nothing for S38 to do here.
 			} else {
 				const category = classifyError(event.message);
+				const detail = classifyErrorDetailed(event.message);
 				// R3: stateful poisoned-context signal — repeated identical error text
 				// across consecutive turns. The classifier is stateless, so this
 				// upgrade happens here. A 'transient' (or 'poisoned-context') turn
 				// whose normalized error signature matches the previous one bumps
 				// errorTextRepeatCount; once it crosses the threshold, the category
-				// is upgraded to 'poisoned-context' (the request is deterministic).
-				// Conservative: only upgrade, never downgrade, and only for transient
-				// (a 'permanent' auth error repeating is still permanent).
+				// is upgraded to 'poisoned-context' (the request is deterministic) —
+				// R7: unless the signature carries a known-retryable network/
+				// throughput marker (guard below). Conservative: only upgrade, never
+				// downgrade, and only for transient (a 'permanent' auth error
+				// repeating is still permanent).
 				let effectiveCategory = category;
 				const errSig = extractErrorSignature(event.message);
 				if (category === "transient" || category === "poisoned-context") {
@@ -412,7 +421,25 @@ export function registerAgentHandlers(
 								config.poisonedContextRepeatThreshold &&
 							category === "transient"
 						) {
-							effectiveCategory = "poisoned-context";
+							// R3/R7: upgrade only when the repeating error carries NO
+							// known-retryable marker. Network/throughput failures (timeout,
+							// ECONNRESET, 5xx, 429, connection lost, …) that repeat are
+							// still retryable — the API is just flaky, and /clear cannot fix
+							// them (2026-07-30 false-alarm incident). Only upgrade
+							// transient → poisoned-context for errors that repeat identically
+							// with no known-retryable cause, like the 2026-07-28 incident
+							// where the provider returned "Request failed — please retry."
+							// deterministically. The marker set is shared with classifyError
+							// (error-classifier.ts) so the two never drift.
+							if (!isKnownRetryableTransient(errSig)) {
+								effectiveCategory = "poisoned-context";
+							} else {
+								runtime.logger.info("repeat-upgrade-declined", {
+									sessionId: runtime.rt.sessionId,
+									signature: (errSig || '').slice(0, 500),
+									repeatCount: runtime.rt.errorTextRepeatCount,
+								});
+							}
 						}
 					}
 				} else {
@@ -427,6 +454,9 @@ export function registerAgentHandlers(
 					runtime.rt.consecutiveErrors = 0; // S38.6: circuit-breaker reset on success
 					// R4: a successful assistant turn consumes any queued nudge.
 					runtime.rt.retryNudgePending = false;
+					// R10: reset outage advisory so a recovered-then-flapping
+					// provider re-advises once per episode.
+					runtime.rt.providerOutageAdvised = false;
 				} else if (effectiveCategory === "compaction-noop") {
 					// (4) pi race / manual compact catch — NOT retryable. The compaction
 					// already succeeded via pi's native path; retrying would race again
@@ -522,18 +552,24 @@ export function registerAgentHandlers(
 					runtime.rt.consecutiveErrors++; // still counts toward the circuit breaker
 					runtime.rt.poisonedCount++; // R7: dashboard counter
 					const sig = errSig || "unknown";
-					// (a) dashboard + log
+					// (a) dashboard + log — R11: include signal + rawText for forensics
 					runtime.dashboard.event("poisoned_context", {
 						signature: sig,
 						repeatCount: runtime.rt.errorTextRepeatCount,
 						turnIndex: event.turnIndex,
 						sessionId: runtime.rt.sessionId,
+						signal: detail.signal,
+						rawText: (errSig || '').slice(0, 500),
+						...(detail.httpStatus !== undefined ? { httpStatus: detail.httpStatus } : {}),
 					});
 					runtime.logger.warn("poisoned-context", {
 						sessionId: runtime.rt.sessionId,
 						turnIndex: event.turnIndex,
 						signature: sig,
 						repeatCount: runtime.rt.errorTextRepeatCount,
+						signal: detail.signal,
+						rawText: (errSig || '').slice(0, 500),
+						...(detail.httpStatus !== undefined ? { httpStatus: detail.httpStatus } : {}),
 					});
 					// (b) one-per-session advise message (throttled by poisonedAdviseSent)
 					if (!runtime.rt.poisonedAdviseSent) {
@@ -589,6 +625,11 @@ export function registerAgentHandlers(
 					}
 					// S38.6: circuit-breaker — stop retrying after too many consecutive errors.
 					runtime.rt.consecutiveErrors++;
+					// R10: send calm "provider outage" advisory once per episode.
+					await maybeSendProviderOutageAdvisory(
+						effectiveCategory, runtime, pi, config,
+						{ signal: detail.signal, rawText: (errSig || '').slice(0, 500) },
+					);
 					if (runtime.rt.consecutiveErrors > config.maxConsecutiveErrors) {
 						runtime.dashboard.event("error_retry_circuit_open", {
 							consecutive: runtime.rt.consecutiveErrors,

package/extensions/mega-events/context-handler.ts

@@ -174,7 +174,12 @@ export function registerContextHandler(
 				const db = openStore(runtime.currentStateDir);
 				const epochId = epochIdFor(runtime.rt.sessionId);
 				for (const msg of messages) {
-					const raw = toRawTranscriptRow(msg, runtime.rt.sessionId, epochId, runtime.currentTurn);
+					const raw = toRawTranscriptRow(
+						msg,
+						runtime.rt.sessionId,
+						epochId,
+						runtime.currentTurn,
+					);
 					if (raw) appendRawTranscript(db, raw);
 				}
 			} catch (e) {
@@ -214,26 +219,19 @@ export function registerContextHandler(
 			return;
 		}
 
-		// Debounce so we don't fire on every context event past threshold.
-		const now = Date.now();
-		if (now < runtime.debounceUntil) {
-			runtime.diagCtxDebounce++;
-			return;
-		}
-		runtime.debounceUntil = now + 2000;
-
+		// D.2: Replay MUST be exempt from debounce — replay is free (no compute,
+		// no re-write) and prevents unnecessary KV-cache invalidation. Check
+		// replay FIRST, before debounce, so two context events <2s apart both
+		// return the cached sentinel verbatim (re-stabilises the provider prefix).
+		//
 		// v0.8.6 cache-stability: replay the cached trim view when still in the
 		// same compaction epoch AND context hasn't grown enough to warrant a
-		// re-compact. This stabilizes the provider KV-cache prefix (the summary +
-		// cut are reused verbatim) instead of regenerating a fresh summary +
-		// sentinel every fire, which invalidated the prefix on every other turn
-		// (the alternating cache-miss regression). Re-compact only when context
-		// grew >=10% of the window (percent basis) or >=50% of the effective
-		// threshold (token basis, when percent is unavailable). The cached `cut`
-		// is only valid while the transcript grows within the epoch — it is
-		// cleared on session_compact (durable truncation) + resetRuntime, so we
-		// never replay a stale cut into a truncated transcript (PREVENT-PI-001/002).
-		const RECOMPACT_PCT_DELTA = 10;
+		// re-compact. Re-compact only when context grew >=config.recompactPctDelta%
+		// of the window (percent basis) or >=50% of the effective threshold
+		// (token basis, when percent is unavailable). The cached `cut` is only
+		// valid while the transcript grows within the epoch — it is cleared on
+		// session_compact (durable truncation) + resetRuntime, so we never replay
+		// a stale cut into a truncated transcript (PREVENT-PI-001/002).
 		if (
 			runtime.trimCache &&
 			runtime.trimCache.checkpointId === runtime.rt.lastCheckpointId &&
@@ -241,7 +239,7 @@ export function registerContextHandler(
 		) {
 			const grewEnough =
 				pct != null && runtime.trimCache.ctxPct != null
-					? pct - runtime.trimCache.ctxPct >= RECOMPACT_PCT_DELTA
+					? pct - runtime.trimCache.ctxPct >= config.recompactPctDelta
 					: currentTokens - (runtime.trimCache.ctxTokens ?? 0) >=
 						runtime.effectiveThreshold * 0.5;
 			if (!grewEnough) {
@@ -258,6 +256,15 @@ export function registerContextHandler(
 			// else: context grew enough → fall through to re-compact (cache is stale)
 		}
 
+		// Debounce so we don't fire on every context event past threshold.
+		// (Replay already returned above — only fresh compacts reach this point.)
+		const now = Date.now();
+		if (now < runtime.debounceUntil) {
+			runtime.diagCtxDebounce++;
+			return;
+		}
+		runtime.debounceUntil = now + 2000;
+
 		// Adaptive compression (Fix E): scale compression strength + keepFrom depth
 		// with how close we are to the model context limit. Null-safe: when the
 		// token-fallback path ran (pct unavailable) use the token-basis pressure
@@ -269,8 +276,24 @@ export function registerContextHandler(
 		const ran = runCompact(pi, runtime, config, ctx, messages, {
 			compressionPressure: pressure,
 		});
+		// D.3: skip paths fall back to replay instead of returning empty.
+		// If runCompact skipped and we have a valid trimCache, replay it
+		// (free stability win) — otherwise defer to the next event.
 		if (ran.skipped) {
 			runtime.diagCtxRunSkipped++;
+			if (
+				runtime.trimCache &&
+				runtime.trimCache.checkpointId === runtime.rt.lastCheckpointId &&
+				runtime.trimCache.cut <= messages.length
+			) {
+				const recent = messages.slice(runtime.trimCache.cut); // guardrails-allow PREVENT-PI-002
+				runtime.diagLiveTrimFires++;
+				runtime.diagLiveTrimReplays++;
+				runtime.snapshot(ctx);
+				return {
+					messages: [{ ...runtime.trimCache.summaryAgentMsg }, ...recent],
+				};
+			}
 			return;
 		}
 
@@ -295,7 +318,12 @@ export function registerContextHandler(
 				// them (compression-by-conversation-epoch metrics). Isolated-store
 				// only; best-effort + non-fatal.
 				try {
-					stampTurnsEpochFor(config, runtime.rt.sessionId, epoch.epochId, runtime.currentStateDir);
+					stampTurnsEpochFor(
+						config,
+						runtime.rt.sessionId,
+						epoch.epochId,
+						runtime.currentStateDir,
+					);
 				} catch {
 					/* non-fatal: epoch stamping never breaks compaction */
 				}
@@ -304,7 +332,10 @@ export function registerContextHandler(
 				// AUTO_WIKI_ENABLED; best-effort + non-fatal (never breaks compaction).
 				try {
 					if (config.autoWikiEnabled && config.turnsDbEnabled) {
-						const every = Math.max(1, TurnsConfig.WIKI_REBUILD_EVERY_N_COMPACTS);
+						const every = Math.max(
+							1,
+							TurnsConfig.WIKI_REBUILD_EVERY_N_COMPACTS,
+						);
 						const tdb = openTurnStore(runtime.currentStateDir);
 						const n = bumpWikiCompactCounter(tdb);
 						if (n % every === 0) {
@@ -314,7 +345,9 @@ export function registerContextHandler(
 								restarts: 5,
 								seed: 0x9e3779b9,
 							});
-							createTopicStore(runtime.currentStateDir).replaceTopicModel(model);
+							createTopicStore(runtime.currentStateDir).replaceTopicModel(
+								model,
+							);
 							runtime.logger.info("wiki_rebuild", {
 								clusterCount: model.k,
 								totalChunks: model.totalChunks,
@@ -326,7 +359,9 @@ export function registerContextHandler(
 						}
 					}
 				} catch (wikiErr) {
-					runtime.logger.warn("wiki_rebuild_failed", { error: String(wikiErr) });
+					runtime.logger.warn("wiki_rebuild_failed", {
+						error: String(wikiErr),
+					});
 				}
 				// S27 Task 6: Fire-and-forget dedup pipeline.
 				// Deduplicates raw_transcript rows for the compacted range.