pi-mega-compact 0.20.64 → 0.20.66

package/extensions/dashboard-server/routes-setup-enc2b.ts

@@ -0,0 +1,82 @@
+/**
+ * dashboard-server/routes-setup-enc2b.ts — ENC-2b native onnxruntime
+ * qualification retest (reader-only probe) + POST retest action.
+ *
+ * Extracted out of routes-setup.ts (which hovers at the 300-line source soft
+ * cap, mirroring the ENC-1b/ENC-2a sibling extracts) so the ENC-2b additive
+ * GET field — the native qualification retest result + effective backend —
+ * lives in a sibling impl file and routes-setup.ts stays a thin host.
+ *
+ * The retest's job is RE-QUALIFICATION: when the operator installed
+ * onnxruntime-node via the ENC-2a guide, the encoder read path does not
+ * automatically re-evaluate the qualification verdict. This sibling surface
+ * runs `runNativeRetest` (a bounded, reader-only, local probe) and:
+ *
+ *   - surfaces `nativeOrtRetestResult` + `nativeOrtBackendEffective` on the GET
+ *     when the flag is on AND a binding is installed — absent otherwise
+ *     (byte-identical to the ENC-2a-era shape on flag-off/none);
+ *   - handles the POST `nativeOrtRetest` key (`false` → 400
+ *     `retest_rejected_false_nothing_to_do`; `true` → run + echo the fresh
+ *     result; flag-off → the key is unrecognized, byte-identical predecessor).
+ *
+ * `nativeOrtBackendEffective` is `"native"` only when the retest verdict is
+ * `qualified`; any `degraded`/`failed` verdict keeps the backend `"wasm"` — the
+ * runtime never silently switches to a backend whose retest failed.
+ *
+ * Guardrails: PREVENT-PI-004 (local filesystem + in-process binding load only,
+ * zero network — the retest NEVER fetches), PREVENT-011 (no `any`).
+ */
+
+import { ENC_2B_ENABLED } from "../../src/config/vector-cortex.js";
+import {
+  runNativeRetest,
+  type RetestResult,
+} from "../../src/vector-cortex/encoder/native-qualify-retest.js";
+import type { SetupConfigureRequest } from "./api-contracts/setup.js";
+
+/**
+ * Resolve the ENC-2b additive GET fields. Returns BOTH fields when the flag is
+ * on AND a native binding is installed (the retest ran); returns `{}` on
+ * flag-off AND when no binding is installed — both fields are OMITTED (absent,
+ * not null), so the GET stays byte-identical to the ENC-2a-era shape and the
+ * client hides the retest card. Flag-off omits, never nulls: the ENC-2a-era
+ * host spreads `...{}` so no new key appears. Mirror of the ENC-2a/ENC-1b
+ * sibling idiom; async because the retest loads the binding in-process.
+ */
+export async function readEnc2bRetest(stateDir: string): Promise<{
+  nativeOrtRetestResult?: RetestResult;
+  nativeOrtBackendEffective?: "native" | "wasm";
+}> {
+  if (!ENC_2B_ENABLED()) return {};
+  const result = await runNativeRetest(stateDir);
+  if (result === null) return {};
+  return {
+    nativeOrtRetestResult: result,
+    nativeOrtBackendEffective: result.verdict === "qualified" ? "native" : "wasm",
+  };
+}
+
+/**
+ * ENC-2b POST retest-action key handling (flag-gated, additive).
+ *
+ * `true`  → { action: "run" } (the host runs the retest and returns the result)
+ * `false` → { action: "reject" } (400 `retest_rejected_false_nothing_to_do`)
+ * other   → null (key absent or flag off — falls through unrecognized,
+ *            byte-identical ENC-2a-era predecessor).
+ */
+export function enc2bRetestRequest(body: SetupConfigureRequest): "run" | "reject" | null {
+  if (!ENC_2B_ENABLED()) return null;
+  if (body.nativeOrtRetest === true) return "run";
+  if (body.nativeOrtRetest === false) return "reject";
+  return null;
+}
+
+/**
+ * Run the ENC-2b retest now (bounded, synchronous on the request) and return
+ * the fresh result. Flag-off or no binding → null. Used by the POST "run"
+ * branch; the result is returned on the response body, never persisted.
+ */
+export async function runEnc2bRetest(stateDir: string): Promise<RetestResult | null> {
+  if (!ENC_2B_ENABLED()) return null;
+  return runNativeRetest(stateDir);
+}

package/extensions/dashboard-server/routes-setup.ts

@@ -22,6 +22,7 @@ import {
 	enc2BudgetValidateCombined,
 } from "./routes-setup-enc2budget.js";
 import { readEnc2aGuide, enc2aGuideRequest } from "./routes-setup-enc2a.js";
+import { readEnc2bRetest, enc2bRetestRequest, runEnc2bRetest } from "./routes-setup-enc2b.js";
 import { writeEmbedderEnv } from "./routes-setup-env-upsert.js";
 import {
 	detectOllama,
@@ -94,7 +95,7 @@ export function handleSetupStatus(
 	// ENC-1a (flag-gated, additive): echo the persisted endpoint URL and an
 	// embeddingApiKeySet boolean ONLY — the raw API key is never returned. When
 	// the flag is off (or neither is set) both fields are simply omitted.
-	const body: SetupStatusResponse = {
+	const base: SetupStatusResponse = {
 		currentEmbedder: active,
 		configuredEmbedder: configured.embedder,
 		configuredUrl: configured.url,
@@ -109,9 +110,20 @@ export function handleSetupStatus(
 		...(enc2a.guide !== null ? { nativeOrtInstallGuide: enc2a.guide } : {}),
 		...(enc2a.installedVersion !== null ? { nativeOrtInstalledVersion: enc2a.installedVersion } : {}),
 	};
+	// ENC-2b (flag-gated, additive): the native qualification retest fields. The
+	// retest loads the on-disk binding in-process (bounded, never a fetch), so
+	// readEnc2bRetest is async; the handler returns true synchronously for the
+	// dispatch and writes the response after the await. Flag-off/none mutates
+	// the body additively and stays byte-identical to the ENC-2a-era shape.
 	// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
-	res.writeHead(200, { "Content-Type": "application/json" });
-	res.end(JSON.stringify(body));
+	readEnc2bRetest(ctx.stateDir).then((enc2b) => {
+		const body: SetupStatusResponse = { ...base, ...enc2b };
+		res.writeHead(200, { "Content-Type": "application/json" });
+		res.end(JSON.stringify(body));
+	}).catch(() => {
+		res.writeHead(200, { "Content-Type": "application/json" });
+		res.end(JSON.stringify(base));
+	});
 	return true;
 }
 
@@ -248,6 +260,30 @@ export function handleSetupConfigure(
 			res.end(JSON.stringify({ nativeOrtInstallGuide: readEnc2aGuide(ctx.stateDir).guide }));
 			return;
 		}
+		// ENC-2b retest-action key (flag-gated, additive): `false` → 400 (an
+		// operator-driven no-op — nothing to retest), `true` → run the bounded
+		// retest synchronously and return the fresh result. Flag-off: the key
+		// falls through unrecognized (byte-identical ENC-2a-era predecessor).
+		// The retest never fetches — the binding is on disk from the ENC-2a
+		// install (PREVENT-PI-004 clean).
+		const retestReq = enc2bRetestRequest(body);
+		// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+		if (retestReq === "reject") {
+			res.writeHead(400, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ error: "retest_rejected_false_nothing_to_do" }));
+			return;
+		}
+		if (retestReq === "run") {
+			// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+			runEnc2bRetest(ctx.stateDir).then((fresh) => {
+				res.writeHead(200, { "Content-Type": "application/json" });
+				res.end(JSON.stringify({ nativeOrtRetestResult: fresh }));
+			}).catch(() => {
+				res.writeHead(500, { "Content-Type": "application/json" });
+				res.end(JSON.stringify({ error: "retest_failed" }));
+			});
+			return;
+		}
 		if (tryEnc1aConfigure(body, res, ctx)) return;
 		if (tryEnc1bConfigure(body, res, ctx)) return; // pure ENC-1b configure (dim/headers/allow-remote/native)
 		// ENC-1b combined-payload validation: when a payload carries a valid

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

@@ -122,7 +122,7 @@ export function harness(opts: { keepTier?: boolean; keepThreshold?: boolean } =
 		registerCommand: () => {}, registerTool: () => {}, registerShortcut: () => {},
 		registerFlag: () => {}, getFlag: () => undefined,
 		registerMessageRenderer: () => {}, registerEntryRenderer: () => {},
-		sendMessage: () => {}, sendUserMessage: (m: string) => { sendUserMessages.push(m); },
+		sendMessage: (m: { content?: string }) => { if (typeof m?.content === "string") sendUserMessages.push(m.content); }, sendUserMessage: (m: string) => { sendUserMessages.push(m); },
 		appendEntry: (t: string, d: any) => appended.push({ t, d }),
 		setSessionName: () => {}, getSessionName: () => undefined, setLabel: () => {},
 		exec: async () => ({ stdout: "", stderr: "", code: 0 }),

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

@@ -197,7 +197,9 @@ export function harness(opts: { keepTier?: boolean; keepThreshold?: boolean } =
 		getFlag: () => undefined,
 		registerMessageRenderer: () => {},
 		registerEntryRenderer: () => {},
-		sendMessage: (_m: any) => {},
+		sendMessage: (m: { content?: string }) => {
+			if (typeof m?.content === "string") sendUserMessages.push(m.content);
+		},
 		sendUserMessage: (m: string) => {
 			sendUserMessages.push(m);
 		},

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

@@ -10,7 +10,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import type { MegaRuntime } from "../../mega-runtime.js";
 import { piCompactWouldNoop } from "../../mega-pipeline.js";
 import type { MegaConfig } from "../../mega-config.js";
-import { safeSendUserMessage } from "../send-safe.js";
+import { safeSendInvisibleMessage } from "../send-safe.js";
 
 /** Handle the `agent_end` pi event. Non-fatal end-to-end. */
 export async function handleAgentEnd(
@@ -228,7 +228,7 @@ export async function handleAgentEnd(
 					lengthStop && !didDurableTrim
 						? "[mega-compact] the last response hit the output-token cap; continue from where it stopped."
 						: "[mega-compact] continue from the compacted context above.";
-				await safeSendUserMessage(pi, nudgeMsg);
+				await safeSendInvisibleMessage(pi, nudgeMsg);
 			}
 		} catch {
 			/* non-fatal: a failed nudge never blocks */

package/extensions/mega-events/agent-handlers/turnEndHandler/errorRetry-transient.ts

@@ -0,0 +1,170 @@
+/**
+ * turnEndHandler/errorRetry-transient.ts — transient/permanent retry branch.
+ *
+ * Extracted from errorRetry.ts (delegate-shell split) to keep every source
+ * file under the extensions soft limit. Contains the S38.6 circuit breaker,
+ * R10 provider-outage advisory, per-burst max, R2 session cap, R1 in-flight
+ * dedup + gating backoff, and the actual retry nudge send.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { MegaRuntime } from "../../../mega-runtime.js";
+import type { MegaConfig } from "../../../mega-config.js";
+import { errorRetryBackoffMs } from "../../error-classifier.js";
+import { safeSendInvisibleMessage } from "../../send-safe.js";
+import { maybeSendProviderOutageAdvisory } from "../../outage-advisor.js";
+import type { TurnEndEvent } from "./event.js";
+
+/** Context needed from the caller's scope for the transient/permanent branch. */
+export interface TransientRetryContext {
+	readonly effectiveCategory: string;
+	readonly detail: { signal?: string };
+	readonly errSig: string | undefined;
+}
+
+/** Handle the transient or permanent error-retry path. Non-fatal. */
+export async function transientRetry(
+	event: TurnEndEvent,
+	_ctx: ExtensionContext,
+	pi: ExtensionAPI,
+	runtime: MegaRuntime,
+	config: MegaConfig,
+	tc: TransientRetryContext,
+): Promise<void> {
+	const { effectiveCategory, detail, errSig } = tc;
+	// S38.7: hard-stop switch — bypass ALL retry logic when set.
+	if (config.errorRetryHardStop) {
+		runtime.rt.errorRetryCount = 0;
+		runtime.dashboard.event("error_retry_disabled", {
+			category: effectiveCategory,
+			turnIndex: event.turnIndex,
+			reason: "hard-stop",
+		});
+		return; // early exit — no retry
+	}
+	// 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,
+			max: config.maxConsecutiveErrors,
+			turnIndex: event.turnIndex,
+		});
+		runtime.logger.warn("error-retry-circuit-open", {
+			sessionId: runtime.rt.sessionId,
+			consecutive: runtime.rt.consecutiveErrors,
+			max: config.maxConsecutiveErrors,
+		});
+		return; // early exit — circuit breaker tripped
+	}
+	const max =
+		effectiveCategory === "transient"
+			? config.autoRetryTransientMax
+			: config.autoRetryPermanentMax;
+	// max === 0 disables the category entirely (revert to S28-only).
+	if (max <= 0) {
+		runtime.rt.errorRetryCount = 0;
+		return;
+	}
+	runtime.rt.errorRetryCount++;
+	if (runtime.rt.errorRetryCount > max) {
+		// Exhausted — surface the error, reset for the next burst.
+		runtime.dashboard.event("error_retry_exhausted", {
+			category: effectiveCategory,
+			count: runtime.rt.errorRetryCount,
+			max,
+			turnIndex: event.turnIndex,
+		});
+		runtime.logger.info("error-retry-exhausted", {
+			sessionId: runtime.rt.sessionId,
+			category: effectiveCategory,
+			count: runtime.rt.errorRetryCount,
+			max,
+		});
+		runtime.rt.errorRetryCount = 0;
+		return;
+	}
+	// R2: session-global cap — total S38 nudges per session across ALL bursts.
+	// Independent of the per-burst max and the circuit breaker. Hitting it is
+	// terminal for the session: log + dashboard event, stop nudging. `0` disables.
+	if (
+		config.errorRetrySessionMax > 0 &&
+		runtime.rt.errorRetrySessionCount >= config.errorRetrySessionMax
+	) {
+		runtime.dashboard.event("error_retry_session_exhausted", {
+			count: runtime.rt.errorRetrySessionCount,
+			max: config.errorRetrySessionMax,
+			category: effectiveCategory,
+			turnIndex: event.turnIndex,
+		});
+		runtime.logger.warn("error-retry-session-exhausted", {
+			sessionId: runtime.rt.sessionId,
+			count: runtime.rt.errorRetrySessionCount,
+			max: config.errorRetrySessionMax,
+			category: effectiveCategory,
+		});
+		runtime.rt.errorRetryCount = 0;
+		return; // terminal for the session — no nudge
+	}
+	// R1: in-flight nudge dedup — a nudge queued via deliverAs:'followUp' must
+	// not be re-sent until consumed by an actual new agent turn (turn_start
+	// resets retryNudgePending). Without this, a fast-erroring provider + a
+	// per-turn nudge → N nudges queue up and pi dispatches N retry turns, each
+	// re-submitting the same failing prompt (the 2026-07-28 incident).
+	if (runtime.rt.retryNudgePending) {
+		runtime.dashboard.event("error_retry_dedup_skip", {
+			category: effectiveCategory,
+			count: runtime.rt.errorRetryCount,
+			max,
+			turnIndex: event.turnIndex,
+		});
+		return; // pending nudge not yet consumed — skip
+	}
+	// R1: gating backoff — errorRetryUntil is GATING. A nudge cannot fire before
+	// the previous backoff elapses. Paces retries (5s/10s/20s/30s default).
+	const now = Date.now();
+	if (now < runtime.rt.errorRetryUntil) {
+		runtime.dashboard.event("error_retry_backoff_skip", {
+			category: effectiveCategory,
+			count: runtime.rt.errorRetryCount,
+			max,
+			turnIndex: event.turnIndex,
+		});
+		return; // backoff not elapsed — skip
+	}
+	// Fire the retry nudge. Set pending (R1 dedup) + backoff (R1 pacing) +
+	// session count (R2 cap) BEFORE the await so a re-entrant turn_end during
+	// the send can't double-fire.
+	runtime.rt.retryNudgePending = true;
+	runtime.rt.lastErrorRetryAt = now;
+	runtime.rt.errorRetryUntil =
+		now +
+		errorRetryBackoffMs(
+			runtime.rt.errorRetryCount,
+			config.errorRetryBackoffMs,
+		);
+	runtime.rt.errorRetrySessionCount++;
+	runtime.dashboard.event("error_retry", {
+		category: effectiveCategory,
+		count: runtime.rt.errorRetryCount,
+		max,
+		turnIndex: event.turnIndex,
+	});
+	runtime.logger.info("error-retry", {
+		sessionId: runtime.rt.sessionId,
+		category: effectiveCategory,
+		count: runtime.rt.errorRetryCount,
+		max,
+	});
+	// PREVENT-PI-003: user-role only (queued + catch-guarded).
+	// Invisible: display:false so the retry trigger fires without
+	// rendering "Follow-up:" spam in the conversation UI.
+	await safeSendInvisibleMessage(
+		pi,
+		"[mega-compact] the last turn ended with an error; please retry.",
+	);
+}

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

@@ -17,12 +17,11 @@ import type { MegaConfig } 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 { safeSendInvisibleMessage } from "../../send-safe.js";
+import { transientRetry } from "./errorRetry-transient.js";
 import type { TurnEndEvent } from "./event.js";
 
 /** S38: broader error-retry safety net. Non-fatal end-to-end. */
@@ -232,7 +231,10 @@ export async function errorRetry(
 				// Default ON (advisoryChannel=true): dashboard-only, no user message.
 				if (!config.advisoryChannel) {
 					// PREVENT-PI-003: user-role sendUserMessage only.
-					await safeSendUserMessage(
+					// Invisible: display:false — the dashboard event + log already
+					// capture the poisoned-context signal; the user does not need a
+					// visible "Follow-up:" message.
+					await safeSendInvisibleMessage(
 						pi,
 						"[mega-compact] this session's context may be poisoned (the provider is rejecting every request). Run /clear or /new to start a fresh context.",
 					);
@@ -270,149 +272,12 @@ export async function errorRetry(
 				}
 			} else {
 				// (5) transient or permanent — retry with exponential backoff.
-				// S38.7: hard-stop switch — bypass ALL retry logic when set.
-				if (config.errorRetryHardStop) {
-					runtime.rt.errorRetryCount = 0;
-					runtime.dashboard.event("error_retry_disabled", {
-						category: effectiveCategory,
-						turnIndex: event.turnIndex,
-						reason: "hard-stop",
-					});
-					return; // early exit — no retry
-				}
-				// 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,
-						max: config.maxConsecutiveErrors,
-						turnIndex: event.turnIndex,
-					});
-					runtime.logger.warn("error-retry-circuit-open", {
-						sessionId: runtime.rt.sessionId,
-						consecutive: runtime.rt.consecutiveErrors,
-						max: config.maxConsecutiveErrors,
-					});
-					return; // early exit — circuit breaker tripped
-				}
-				const max =
-					effectiveCategory === "transient"
-						? config.autoRetryTransientMax
-						: config.autoRetryPermanentMax;
-				// max === 0 disables the category entirely (revert to S28-only).
-				if (max <= 0) {
-					runtime.rt.errorRetryCount = 0;
-				} else {
-					runtime.rt.errorRetryCount++;
-					if (runtime.rt.errorRetryCount > max) {
-						// Exhausted — surface the error, reset for the next burst.
-						runtime.dashboard.event("error_retry_exhausted", {
-							category: effectiveCategory,
-							count: runtime.rt.errorRetryCount,
-							max,
-							turnIndex: event.turnIndex,
-						});
-						runtime.logger.info("error-retry-exhausted", {
-							sessionId: runtime.rt.sessionId,
-							category: effectiveCategory,
-							count: runtime.rt.errorRetryCount,
-							max,
-						});
-						runtime.rt.errorRetryCount = 0;
-					} else {
-						// R2: session-global cap — total S38 nudges per session across
-						// ALL bursts. Independent of the per-burst max and the circuit
-						// breaker. Hitting it is terminal for the session: log +
-						// dashboard event, stop nudging. `0` disables (reverts to
-						// per-burst + circuit-breaker only).
-						if (
-							config.errorRetrySessionMax > 0 &&
-							runtime.rt.errorRetrySessionCount >= config.errorRetrySessionMax
-						) {
-							runtime.dashboard.event("error_retry_session_exhausted", {
-								count: runtime.rt.errorRetrySessionCount,
-								max: config.errorRetrySessionMax,
-								category: effectiveCategory,
-								turnIndex: event.turnIndex,
-							});
-							runtime.logger.warn("error-retry-session-exhausted", {
-								sessionId: runtime.rt.sessionId,
-								count: runtime.rt.errorRetrySessionCount,
-								max: config.errorRetrySessionMax,
-								category: effectiveCategory,
-							});
-							runtime.rt.errorRetryCount = 0;
-							return; // terminal for the session — no nudge
-						}
-						// R1: in-flight nudge dedup — a nudge queued via
-						// deliverAs:'followUp' must not be re-sent until it has been
-						// consumed by an actual new agent turn (turn_start resets
-						// retryNudgePending). Without this, a fast-erroring provider +
-						// a per-turn nudge → N nudges queue up and pi dispatches N
-						// retry turns, each re-submitting the same failing prompt
-						// (the 2026-07-28 incident). errorRetryCount still advances
-						// (this IS an error turn), so the per-burst max + circuit
-						// breaker still bound the burst.
-						if (runtime.rt.retryNudgePending) {
-							runtime.dashboard.event("error_retry_dedup_skip", {
-								category: effectiveCategory,
-								count: runtime.rt.errorRetryCount,
-								max,
-								turnIndex: event.turnIndex,
-							});
-							return; // pending nudge not yet consumed — skip
-						}
-						// R1: gating backoff — errorRetryUntil is now GATING
-						// (previously documented as non-gating). A nudge cannot fire
-						// before the previous backoff elapses. This paces retries
-						// (5s/10s/20s/30s by default) so a fast-erroring provider
-						// doesn't slam N nudges in <1s.
-						const now = Date.now();
-						if (now < runtime.rt.errorRetryUntil) {
-							runtime.dashboard.event("error_retry_backoff_skip", {
-								category: effectiveCategory,
-								count: runtime.rt.errorRetryCount,
-								max,
-								turnIndex: event.turnIndex,
-							});
-							return; // backoff not elapsed — skip
-						}
-						// Fire the retry nudge. Set pending (R1 dedup) + backoff
-						// (R1 pacing) + session count (R2 cap) BEFORE the await so a
-						// re-entrant turn_end during the send can't double-fire.
-						runtime.rt.retryNudgePending = true;
-						runtime.rt.lastErrorRetryAt = now;
-						runtime.rt.errorRetryUntil =
-							now +
-							errorRetryBackoffMs(
-								runtime.rt.errorRetryCount,
-								config.errorRetryBackoffMs,
-							);
-						runtime.rt.errorRetrySessionCount++;
-						runtime.dashboard.event("error_retry", {
-							category: effectiveCategory,
-							count: runtime.rt.errorRetryCount,
-							max,
-							turnIndex: event.turnIndex,
-						});
-						runtime.logger.info("error-retry", {
-							sessionId: runtime.rt.sessionId,
-							category: effectiveCategory,
-							count: runtime.rt.errorRetryCount,
-							max,
-						});
-						// PREVENT-PI-003: user-role sendUserMessage only (queued + catch-guarded).
-						await safeSendUserMessage(
-							pi,
-							"[mega-compact] the last turn ended with an error; please retry.",
-						);
-					}
-				}
+				// Delegated to errorRetry-transient.ts (delegate-shell split).
+				await transientRetry(event, ctx, pi, runtime, config, {
+					effectiveCategory,
+					detail,
+					errSig,
+				});
 			}
 		}
 	} catch {

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

@@ -22,7 +22,7 @@ import type { MegaConfig } from "../mega-config.js";
 import { recordScore, getDedupStats } from "../../src/store/sqlite.js";
 import { evaluateAndUnlockAchievements } from "../../src/store/sqlite/game-achievements.js";
 import { resolveRepoRoot } from "../mega-config.js";
-import { safeSendUserMessage } from "./send-safe.js";
+import { safeSendInvisibleMessage } from "./send-safe.js";
 
 /**
  * Build a minimal fallback compaction so pi never runs its throwing compact().
@@ -59,7 +59,7 @@ function fallbackCompaction(
  * Debounced resume-nudge: restart the agent loop after a compaction (which
  * may have stopped it). Idempotent — one nudge per 30s, never blocks.
  *
- * Uses safeSendUserMessage ({ deliverAs: 'followUp' } + catch-guard) so that a
+ * Uses safeSendInvisibleMessage ({ deliverAs: 'followUp' } + catch-guard) so that a
  * nudge fired during session_before_compact (which is mid-prompt-submission,
  * so the agent can be busy) QUEUES instead of throwing
  * "Agent is already processing. Specify streamingBehavior (steer or followUp)".
@@ -70,7 +70,7 @@ async function nudgeResume(pi: ExtensionAPI, runtime: MegaRuntime): Promise<void
 		if (now >= runtime.resumeNudgeUntil) {
 			runtime.resumeNudgeUntil = now + 30_000;
 			runtime.rt.extensionInitiatedTurn = true; // R13: suppress self-classification
-			await safeSendUserMessage(
+			await safeSendInvisibleMessage(
 				pi,
 				"[mega-compact] continue from the compacted context above.",
 			);

package/extensions/mega-events/outage-advisor.ts

@@ -9,12 +9,12 @@
  * Distinct from the poisoned-context /clear advise: the outage advisory is
  * for transient errors where the user's context is fine.
  *
- * PREVENT-PI-003: sends via safeSendUserMessage (user-role only).
+ * PREVENT-PI-003: sends via safeSendInvisibleMessage (user-role only).
  * PREVENT-PI-004: local ctx call, no network.
  */
 
 import type { MegaRuntime } from "../mega-runtime.js";
-import { safeSendUserMessage } from "./send-safe.js";
+import { safeSendInvisibleMessage } from "./send-safe.js";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 /** R11: optional diagnostic detail passed from the classifier. */
@@ -31,7 +31,7 @@ export interface OutageDetail {
  *
  * @param effectiveCategory — must be "transient" for the advisory to fire.
  * @param runtime   — the live MegaRuntime (mutated on advisory fire).
- * @param pi        — pi ExtensionAPI for safeSendUserMessage.
+ * @param pi        — pi ExtensionAPI for safeSendInvisibleMessage.
  * @param config    — providerOutageAdviseThreshold config.
  * @param detail    — R11: optional signal + rawText for forensics.
  */
@@ -70,8 +70,8 @@ export async function maybeSendProviderOutageAdvisory(
 	// injecting into the conversation scares users and triggers false-positive
 	// re-classification of the resulting turn (2026-07-31 incident).
 	if (!config.advisoryChannel) {
-		// Legacy path (flag OFF): user-role message injection.
-		await safeSendUserMessage(
+		// Legacy path (flag OFF): invisible user-role message (display:false).
+		await safeSendInvisibleMessage(
 			pi,
 			`[mega-compact] the provider is having issues (${runtime.rt.consecutiveErrors} consecutive failures — timeouts/5xx/rate-limits). Retries are bounded and continue automatically; your context is fine — do NOT clear or reset it. Work resumes as soon as the provider recovers.`,
 		);

package/extensions/mega-events/send-safe.ts

@@ -1,16 +1,20 @@
 /**
- * send-safe.ts — queue-safe wrapper for pi.sendUserMessage.
+ * send-safe.ts — queue-safe wrappers for pi.sendUserMessage / pi.sendMessage.
  *
  * All extension-initiated user-role nudges (resume after compaction, length-stop
- * continue, error-retry) MUST go through this wrapper. It:
- *   1. Passes { deliverAs: 'followUp' } so that when the agent is busy (e.g. a
+ * continue, error-retry) MUST go through these wrappers. They:
+ *   1. Pass { deliverAs: 'followUp' } so that when the agent is busy (e.g. a
  *      resume nudge fired during session_before_compact, which is mid-prompt
  *      submission) pi QUEUES the message instead of throwing
  *      "Agent is already processing. Specify streamingBehavior (steer or
  *      followUp) to queue the message" (pi agent-session.js:830).
- *   2. Awaits the call and catch-guards it so a failed/queued nudge never throws
+ *   2. Await the call and catch-guard it so a failed/queued nudge never throws
  *      or produces an unhandled rejection — it must never block the agent loop.
  *
+ * safeSendUserMessage renders the text in the conversation UI (visible).
+ * safeSendInvisibleMessage delivers via pi.sendMessage with display: false —
+ * the agent receives the retry trigger but the user never sees the text.
+ *
  * PREVENT-PI-003: user-role sendUserMessage only (no role:'system' injection).
  * PREVENT-PI-004: local pi ctx call, no network.
  */
@@ -19,6 +23,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 /**
  * safeSendUserMessage — await + catch-guard + queue-safe wrapper for
  * pi.sendUserMessage. Never throws; never produces an unhandled rejection.
+ * The message IS visible in the conversation UI ("Follow-up:").
  */
 export async function safeSendUserMessage(
 	pi: ExtensionAPI,
@@ -35,3 +40,29 @@ export async function safeSendUserMessage(
 		/* non-fatal: a failed/queued nudge never blocks the agent loop */
 	}
 }
+
+/**
+ * safeSendInvisibleMessage — like safeSendUserMessage but uses pi.sendMessage
+ * with `display: false` so the retry trigger is delivered to the agent WITHOUT
+ * rendering in the conversation UI. Fixes the "Follow-up: [mega-compact] ..."
+ * pile-up when the API retries repeatedly — the retry mechanism still fires,
+ * the user just doesn't see the queued messages.
+ */
+export async function safeSendInvisibleMessage(
+	pi: ExtensionAPI,
+	content: string,
+): Promise<void> {
+	try {
+		await (
+			pi.sendMessage as (
+				m: { customType: string; content: string; display: boolean },
+				o?: { deliverAs?: "steer" | "followUp" },
+			) => Promise<void> | void
+		)(
+			{ customType: "mega-compact-retry", content, display: false },
+			{ deliverAs: "followUp" },
+		);
+	} catch {
+		/* non-fatal: a failed/queued nudge never blocks the agent loop */
+	}
+}