pi-mega-compact 0.11.1 → 0.11.3

package/extensions/mega-compact-s38.test.ts

@@ -624,9 +624,11 @@ test("R6(e): success resets retry-nudge-pending state", async () => {
 
 test("R3: repeated identical transient error text upgrades to poisoned-context at threshold", async () => {
 	// The stateful repeat signal: 3 consecutive identical transient errors
-	// (default threshold) upgrade to poisoned. Uses "5xx server error" (5xx
-	// marker → transient) so the classifier returns transient, then the repeat
-	// tracker upgrades it. auto=false to skip the compact attempt.
+	// (default threshold) upgrade to poisoned. Uses "5xx server error" —
+	// deliberately NO known-retryable marker ("5xx" is not /5\d\d/, and
+	// "server error" alone matches nothing): the classifier returns transient
+	// via the generic 'error' fallthrough, then the repeat tracker upgrades it.
+	// auto=false to skip the compact attempt.
 	const prevAuto = process.env.MEGACOMPACT_AUTO;
 	const prevBackoff = process.env.MEGACOMPACT_ERROR_RETRY_BACKOFF_MS;
 	process.env.MEGACOMPACT_AUTO = "false";
@@ -652,6 +654,204 @@ test("R3: repeated identical transient error text upgrades to poisoned-context a
 	}
 });
 
+// ---- R7 regression tests: network/throughput errors must NEVER upgrade to ----
+// ---- poisoned-context (2026-07-30 false-alarm incident) ----
+
+/** R7 helper: fire the same transient error text `count` times with turn_start
+ *  + elapsed backoff between turns so each turn's nudge can fire. */
+async function r7RepeatTurns(h: ReturnType<typeof harness>, text: string, count: number) {
+	for (let i = 0; i < count; i++) {
+		await s38TurnEnd(h, "error", text);
+		await h.fire("turn_start", { type: "turn_start", turnIndex: i + 2 }, h.ctx());
+		await new Promise((r) => setTimeout(r, 3));
+	}
+}
+
+/** R7 helper: shared assertions for "stays transient" — no poisoned upgrade,
+ *  no /clear advise, and the transient retry path actually ran. */
+function assertStaysTransient(h: ReturnType<typeof harness>, label: string) {
+	assert.ok(
+		!eventTypes(h.stateDir).includes("poisoned_context"),
+		`${label}: no poisoned_context event (network errors never upgrade)`,
+	);
+	assert.ok(
+		!h.sendUserMessages.some((m) => m.includes("/clear")),
+		`${label}: no /clear advise message`,
+	);
+	assert.ok(
+		eventTypes(h.stateDir).includes("error_retry"),
+		`${label}: transient retry path ran (error_retry event)`,
+	);
+}
+
+test("R7(a): repeated 'timed out' phrasing (2026-07-30 incident text) stays transient — no poisoned upgrade", async () => {
+	// The incident error text was "Request timed out or failed. Try again" —
+	// "timed out" (two words) does NOT match the old guard's /timeout/, so the
+	// 3rd repeat fired the /clear poisoned advise. Must stay transient.
+	const prevAuto = process.env.MEGACOMPACT_AUTO;
+	const prevBackoff = process.env.MEGACOMPACT_ERROR_RETRY_BACKOFF_MS;
+	process.env.MEGACOMPACT_AUTO = "false";
+	process.env.MEGACOMPACT_ERROR_RETRY_BACKOFF_MS = "1";
+	try {
+		const h = harness();
+		await r7RepeatTurns(h, "Request timed out or failed. Try again", 3);
+		assertStaysTransient(h, "timed out x3");
+	} finally {
+		if (prevAuto === undefined) delete process.env.MEGACOMPACT_AUTO;
+		else process.env.MEGACOMPACT_AUTO = prevAuto;
+		if (prevBackoff === undefined) delete process.env.MEGACOMPACT_ERROR_RETRY_BACKOFF_MS;
+		else process.env.MEGACOMPACT_ERROR_RETRY_BACKOFF_MS = prevBackoff;
+	}
+});
+
+test("R7(b): repeated ETIMEDOUT errno stays transient", async () => {
+	// Node's timeout errno lowercases to "etimedout" — does NOT contain the
+	// substring "timeout". Slipped through the old guard.
+	const prevAuto = process.env.MEGACOMPACT_AUTO;
+	const prevBackoff = process.env.MEGACOMPACT_ERROR_RETRY_BACKOFF_MS;
+	process.env.MEGACOMPACT_AUTO = "false";
+	process.env.MEGACOMPACT_ERROR_RETRY_BACKOFF_MS = "1";
+	try {
+		const h = harness();
+		await r7RepeatTurns(h, "connect ETIMEDOUT 142.250.80.46:443", 3);
+		assertStaysTransient(h, "ETIMEDOUT x3");
+	} finally {
+		if (prevAuto === undefined) delete process.env.MEGACOMPACT_AUTO;
+		else process.env.MEGACOMPACT_AUTO = prevAuto;
+		if (prevBackoff === undefined) delete process.env.MEGACOMPACT_ERROR_RETRY_BACKOFF_MS;
+		else process.env.MEGACOMPACT_ERROR_RETRY_BACKOFF_MS = prevBackoff;
+	}
+});
+
+test("R7(c): repeated 'socket hang up' stays transient", async () => {
+	// Node surfaces ECONNRESET as the message "socket hang up" (the errno lives
+	// in error.code, which extractErrorSignature never sees).
+	const prevAuto = process.env.MEGACOMPACT_AUTO;
+	const prevBackoff = process.env.MEGACOMPACT_ERROR_RETRY_BACKOFF_MS;
+	process.env.MEGACOMPACT_AUTO = "false";
+	process.env.MEGACOMPACT_ERROR_RETRY_BACKOFF_MS = "1";
+	try {
+		const h = harness();
+		await r7RepeatTurns(h, "socket hang up", 3);
+		assertStaysTransient(h, "socket hang up x3");
+	} finally {
+		if (prevAuto === undefined) delete process.env.MEGACOMPACT_AUTO;
+		else process.env.MEGACOMPACT_AUTO = prevAuto;
+		if (prevBackoff === undefined) delete process.env.MEGACOMPACT_ERROR_RETRY_BACKOFF_MS;
+		else process.env.MEGACOMPACT_ERROR_RETRY_BACKOFF_MS = prevBackoff;
+	}
+});
+
+test("R7(d): repeated 429 rate-limit stays transient", async () => {
+	// /clear cannot fix a rate limit — the classifier explicitly keeps 429
+	// transient, so the repeat-upgrade must not override that verdict.
+	const prevAuto = process.env.MEGACOMPACT_AUTO;
+	const prevBackoff = process.env.MEGACOMPACT_ERROR_RETRY_BACKOFF_MS;
+	process.env.MEGACOMPACT_AUTO = "false";
+	process.env.MEGACOMPACT_ERROR_RETRY_BACKOFF_MS = "1";
+	try {
+		const h = harness();
+		await r7RepeatTurns(h, "429 Too Many Requests: rate limit exceeded", 3);
+		assertStaysTransient(h, "429 x3");
+	} finally {
+		if (prevAuto === undefined) delete process.env.MEGACOMPACT_AUTO;
+		else process.env.MEGACOMPACT_AUTO = prevAuto;
+		if (prevBackoff === undefined) delete process.env.MEGACOMPACT_ERROR_RETRY_BACKOFF_MS;
+		else process.env.MEGACOMPACT_ERROR_RETRY_BACKOFF_MS = prevBackoff;
+	}
+});
+
+test("R7(e): 0-token 'timed out' turn is NOT poisoned on first occurrence", async () => {
+	// Deeper gap: with usage PRESENT at 0 tokens, the classifier's 0-token
+	// poisoned signal fires on turn ONE for "timed out" phrasing (the stopReason
+	// 'error' is in the text blob and no transient marker matched). The network
+	// markers must be checked before that signal so this returns transient.
+	const prevAuto = process.env.MEGACOMPACT_AUTO;
+	process.env.MEGACOMPACT_AUTO = "false";
+	try {
+		const h = harness();
+		await s38TurnEndUsage(h, "error", "Request timed out or failed. Try again", 0);
+		assert.ok(
+			!eventTypes(h.stateDir).includes("poisoned_context"),
+			"0-token timed out: no poisoned_context on first turn",
+		);
+		assert.ok(
+			!h.sendUserMessages.some((m) => m.includes("/clear")),
+			"0-token timed out: no /clear advise on first turn",
+		);
+	} finally {
+		if (prevAuto === undefined) delete process.env.MEGACOMPACT_AUTO;
+		else process.env.MEGACOMPACT_AUTO = prevAuto;
+	}
+});
+
+test("R7(f): repeated non-network transient still upgrades to poisoned-context (control)", async () => {
+	// True-positive control: an error with NO known-retryable marker that
+	// repeats identically must still upgrade (the R3 feature itself).
+	const prevAuto = process.env.MEGACOMPACT_AUTO;
+	const prevBackoff = process.env.MEGACOMPACT_ERROR_RETRY_BACKOFF_MS;
+	process.env.MEGACOMPACT_AUTO = "false";
+	process.env.MEGACOMPACT_ERROR_RETRY_BACKOFF_MS = "1";
+	try {
+		const h = harness();
+		await r7RepeatTurns(h, "upstream rejected the request", 3);
+		assert.ok(
+			eventTypes(h.stateDir).includes("poisoned_context"),
+			"non-network repeat: poisoned_context event logged",
+		);
+		assert.ok(
+			h.sendUserMessages.some((m) => m.includes("/clear")),
+			"non-network repeat: /clear advise fired",
+		);
+	} finally {
+		if (prevAuto === undefined) delete process.env.MEGACOMPACT_AUTO;
+		else process.env.MEGACOMPACT_AUTO = prevAuto;
+		if (prevBackoff === undefined) delete process.env.MEGACOMPACT_ERROR_RETRY_BACKOFF_MS;
+		else process.env.MEGACOMPACT_ERROR_RETRY_BACKOFF_MS = prevBackoff;
+	}
+});
+
+test("R7(g): 'Request failed — please retry.' 0-token stays poisoned-context (2026-07-28 control)", async () => {
+	// The deterministic-rejection incident that motivated R3 must remain
+	// poisoned: the shared marker pattern must NOT match this text.
+	const prevAuto = process.env.MEGACOMPACT_AUTO;
+	process.env.MEGACOMPACT_AUTO = "false";
+	try {
+		const h = harness();
+		await s38TurnEndUsage(h, "error", "Request failed — please retry.", 0);
+		assert.ok(
+			eventTypes(h.stateDir).includes("poisoned_context"),
+			"deterministic rejection: poisoned_context event logged",
+		);
+		assert.ok(h.sendUserMessages.some((m) => m.includes("/clear")), "deterministic rejection: /clear advise fired");
+	} finally {
+		if (prevAuto === undefined) delete process.env.MEGACOMPACT_AUTO;
+		else process.env.MEGACOMPACT_AUTO = prevAuto;
+	}
+});
+
+test("R7 classifier: 0-token 'timed out' error → transient (not poisoned)", () => {
+	// Unit-level pin of the R7(e) gap.
+	assert.equal(
+		classifyErrorFn({
+			stopReason: "error",
+			content: "Request timed out or failed. Try again",
+			usage: { inputTokens: 0, outputTokens: 0 },
+		}),
+		"transient",
+	);
+});
+
+test("R7 classifier: bare network phrasings → transient", () => {
+	assert.equal(classifyErrorFn("socket hang up"), "transient");
+	assert.equal(classifyErrorFn("the operation timed out"), "transient");
+	assert.equal(classifyErrorFn("connect ETIMEDOUT 10.0.0.1:443"), "transient");
+});
+
+test("R7 classifier: 429/rate-limit → transient (control)", () => {
+	assert.equal(classifyErrorFn("429 Too Many Requests: rate limit exceeded"), "transient");
+});
+
 test("cleanup", async () => {
 	// PGlite WASM close can hang; race with a timeout to prevent 40-min hangs.
 	try {
@@ -661,8 +861,12 @@ test("cleanup", async () => {
 	// Force-exit: each harness() creates a MegaRuntime with an fs.watch
 	// game-state watcher that is never disposed (no session_shutdown in tests).
 	// Those handles keep the event loop alive indefinitely after all tests
-	// complete, so `node --test` (without --test-force-exit) would hang. The
-	// streaming reporter has already printed every test result by this point;
-	// process.exit(0) just forces the exit the watchers are preventing.
+	// complete, so `node --test` (without --test-force-exit) would hang.
+	// Drain stdout/stderr, then defer the exit: a bare process.exit() discards
+	// unflushed pipe buffers — observed 2026-07-30: when piped, the trailing
+	// tests' results and the run summary silently vanished from the report.
+	await new Promise((r) => process.stdout.write("", r));
+	await new Promise((r) => process.stderr.write("", r));
+	await new Promise((r) => setTimeout(r, 1500));
 	process.exit(0);
 });

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;
@@ -312,6 +315,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,
@@ -20,6 +20,7 @@ import {
 	classifyError,
 	errorRetryBackoffMs,
 	extractErrorSignature,
+	isKnownRetryableTransient,
 } from "./error-classifier.js";
 import { safeSendUserMessage } from "./send-safe.js";
 import { vectorStats } from "../../src/vectorStore.js";
@@ -301,7 +302,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,
@@ -394,9 +398,11 @@ export function registerAgentHandlers(
 				// 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 +418,19 @@ 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 {

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.

package/extensions/mega-events/error-classifier.ts

@@ -12,6 +12,28 @@
  * poisoned, choose transient (bounded by R1 dedup + R2 session cap).
  */
 
+/** R7: known-retryable transient markers — network/throughput failures that
+ *  retry can fix and /clear cannot. SINGLE SOURCE OF TRUTH: classifyError uses
+ *  this for its transient-marker stage, and the agent-handlers R3 repeat
+ *  upgrade guard uses it to keep these errors out of poisoned-context. Add new
+ *  transient phrasings HERE only.
+ *
+ *  Non-obvious alternatives:
+ *  - `time(?:d[\s-]?out|out)` covers "timeout", "timed out", "timed-out" —
+ *    "timed out" does NOT match /timeout/ (the 2026-07-30 incident phrasing).
+ *  - `etimedout` is Node's timeout errno lowercased — does NOT contain the
+ *    substring "timeout".
+ *  - `socket hang up` is Node's ECONNRESET *message*; the errno lives in
+ *    error.code, which extractErrorSignature never sees. */
+export const KNOWN_RETRYABLE_TRANSIENT_PATTERN =
+	/max(imum)? output token|rate[\s.-]?limit|429|too many requests|overloaded|5\d\d|internal server|bad gateway|service unavailable|network|time(?:d[\s-]?out|out)|etimedout|econnreset|econnrefused|epipe|eai_again|socket hang up|premature close|other side closed|connection (lost|refused|reset|aborted?)|stream (interrupted|closed|ended|failed)|disconnected/;
+
+/** R7: true when the error text carries a known-retryable transient marker.
+ *  Defensively lowercases so callers can pass raw or normalized text. */
+export function isKnownRetryableTransient(text: string): boolean {
+	return KNOWN_RETRYABLE_TRANSIENT_PATTERN.test(text.toLowerCase());
+}
+
 /** S38.2: classify a turn-end error/stop signal into a retry category.
  *
  * `length` is returned as null — S28 owns the max-output-token length stopReason
@@ -134,19 +156,14 @@ export function classifyError(message: unknown):
 	if (/too long|context window|maximum context length|context length exceeded|requires at least \d+ tokens|even after compaction|reduce the conversation|reduce your input/.test(s)) {
 		return 'context-overflow';
 	}
-	// --- transient (specific markers FIRST — these override poisoned signals) ---
-	// R3: network failures (timeout, ECONNRESET, 5xx, 429) MUST stay transient
-	// even when usage is 0 tokens, because they are retryable. The specific
-	// markers below return before any poisoned signal is evaluated.
-	if (/max(imum)? output token/.test(s)) return 'transient';
-	if (/rate[\s.-]?limit|429|too many requests/.test(s)) return 'transient';
-	if (/5\d\d|internal server|bad gateway|service unavailable/.test(s)) return 'transient';
-	// 'connection aborted' is a network failure (ECONNABORTED), NOT a user ESC
-	// (which is stopReason 'aborted', handled by the early-return above). Added
-	// so "Connection aborted by peer" stays transient under R3. ECONNRESET and
-	// common errno names are included so a bare 0-token 'ECONNRESET' turn is not
-	// misclassified as poisoned (R6: ECONNRESET → transient).
-	if (/network|timeout|econnreset|econnrefused|epipe|connection (lost|refused|reset|aborted)|stream (interrupted|closed|ended|failed)|disconnected/.test(s)) return 'transient';
+	// --- transient (known-retryable markers FIRST — these override poisoned signals) ---
+	// R3: network/throughput failures (timeout, ECONNRESET, 5xx, 429) MUST stay
+	// transient even when usage is 0 tokens, because they are retryable and
+	// /clear cannot fix them. 'connection aborted' is a network failure
+	// (ECONNABORTED), NOT a user ESC (stopReason 'aborted', early-return above).
+	// The marker set is shared with the agent-handlers R3 repeat-upgrade guard
+	// (isKnownRetryableTransient) so the two never drift.
+	if (isKnownRetryableTransient(s)) return 'transient';
 	// --- poisoned-context (R3: ORDER AFTER specific transient markers, BEFORE
 	// the generic 'error' transient fallthrough) ---
 	// A DETERMINISTIC request-rejection that retrying cannot fix. Re-submitting

package/extensions/mega-runtime/runtime-snapshot.ts

@@ -20,20 +20,25 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { join } from "node:path";
 import {
-	VectorStore,
+	type VectorStore,
 	vectorStats,
 	vectorRepoStats,
 	vectorDataInvariant,
 } from "../../src/vectorStore.js";
 import {
 	latestModelSnapshot,
+	readLatestCacheHitPct,
 	recordPerfSample,
 	recordSessionHeartbeat,
 	appendTokenSample,
 	type GameState,
 } from "../../src/store/sqlite.js";
-import { resolveRepoRoot, type MegaConfig, type PressureBand } from "../mega-config.js";
-import { Dashboard } from "../mega-dashboard.js";
+import {
+	resolveRepoRoot,
+	type MegaConfig,
+	type PressureBand,
+} from "../mega-config.js";
+import type { Dashboard } from "../mega-dashboard.js";
 import type { WidgetData } from "./widget.js";
 import { computeMegaSnapshot } from "./snapshot.js";
 import { buildDashboardSnapshot } from "./dashboard-snapshot.js";
@@ -93,7 +98,10 @@ export interface RuntimeSnapshotContext extends RuntimeHelpersContext {
 /** Collect live state and write it to disk (+ paint the above-editor widget).
  *  Extracted verbatim from `MegaRuntime.snapshot()` (runtime.ts); the public
  *  method there is now `snapshotImpl(this, ctx)`. */
-export function snapshotImpl(self: RuntimeSnapshotContext, ctx?: ExtensionContext): void {
+export function snapshotImpl(
+	self: RuntimeSnapshotContext,
+	ctx?: ExtensionContext,
+): void {
 	if (ctx) self.lastWidgetCtx = ctx;
 	if (ctx) self.bindRepo(ctx.cwd);
 	// v0.8.5: gate the expensive body (6 sync SQLite opens +
@@ -179,7 +187,8 @@ export function snapshotImpl(self: RuntimeSnapshotContext, ctx?: ExtensionContex
 	// try/catch mirrors the recordPerfSample pattern below. Skip the token
 	// sample when lastCtxTokens is null (no context data yet).
 	try {
-		const repo = resolveRepoRoot(ctx?.cwd ?? self.currentStateDir) ?? self.currentStateDir;
+		const repo =
+			resolveRepoRoot(ctx?.cwd ?? self.currentStateDir) ?? self.currentStateDir;
 		recordSessionHeartbeat(
 			process.pid,
 			self.rt.sessionId,
@@ -194,7 +203,7 @@ export function snapshotImpl(self: RuntimeSnapshotContext, ctx?: ExtensionContex
 				self.lastCtxTokens,
 				self.lastCtxPercent ?? 0,
 				self.lastCtxWindow || 0,
-			join(self.currentStateDir, "events.log"),
+				join(self.currentStateDir, "events.log"),
 			);
 		}
 	} catch {
@@ -217,6 +226,15 @@ export function snapshotImpl(self: RuntimeSnapshotContext, ctx?: ExtensionContex
 		}
 		// ── gather widget data (computed per snapshot, rendered per frame) ────
 		const modelSnap = latestModelSnapshot(self.currentStateDir);
+		// Provider prompt cache hit % for the widget (B/C): latest
+		// cache_hit_pct sample. Non-fatal — one extra sync open per
+		// material-change-gated recompute, acceptably cheap.
+		let providerCachePct = 0;
+		try {
+			providerCachePct = readLatestCacheHitPct(self.currentStateDir);
+		} catch {
+			/* non-fatal */
+		}
 		const _snapResult = computeMegaSnapshot({
 			lastCtxTokens: self.lastCtxTokens,
 			lastCtxWindow: self.lastCtxWindow,
@@ -248,6 +266,7 @@ export function snapshotImpl(self: RuntimeSnapshotContext, ctx?: ExtensionContex
 			ready,
 			armed,
 			modelSnap,
+			providerCachePct,
 		});
 		self.widgetData = _snapResult.widgetData;
 		// S33: consume the flare after copying it into widgetData so it fires
@@ -271,8 +290,7 @@ export function snapshotImpl(self: RuntimeSnapshotContext, ctx?: ExtensionContex
 		// free the slot and prevent a stale effect lingering between snapshots.
 		if (
 			self.activeEffect &&
-			Date.now() - self.activeEffect.startedAt >=
-				self.activeEffect.durationMs
+			Date.now() - self.activeEffect.startedAt >= self.activeEffect.durationMs
 		) {
 			self.activeEffect = null;
 		}
@@ -284,7 +302,11 @@ export function snapshotImpl(self: RuntimeSnapshotContext, ctx?: ExtensionContex
 	// v0.8.5: record the material-change signature computed at the top so the
 	// next snapshot() can skip this whole body when nothing material changed.
 	try {
-		recordPerfSample(self.currentStateDir, "db_recompute_ms", performance.now() - perfT0);
+		recordPerfSample(
+			self.currentStateDir,
+			"db_recompute_ms",
+			performance.now() - perfT0,
+		);
 		recordPerfSample(self.currentStateDir, "disk_write_ms", perfDiskMs);
 	} catch {
 		/* non-fatal: perf instrumentation never blocks the agent */