pi-mega-compact 0.20.65 → 0.20.66

package/dist/extensions/mega-compact-s38.test/_helpers.js

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

package/dist/extensions/mega-compact.test/_helpers.js

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

package/dist/extensions/mega-events/agent-handlers/agentEndHandler.js

@@ -1,5 +1,5 @@
 import { piCompactWouldNoop } from "../../mega-pipeline.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(ctx, pi, runtime, config) {
     runtime.activeAgents = Math.max(0, runtime.activeAgents - 1);
@@ -200,7 +200,7 @@ export async function handleAgentEnd(ctx, pi, runtime, config) {
                 const nudgeMsg = 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 {

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

@@ -0,0 +1,131 @@
+import { errorRetryBackoffMs } from "../../error-classifier.js";
+import { safeSendInvisibleMessage } from "../../send-safe.js";
+import { maybeSendProviderOutageAdvisory } from "../../outage-advisor.js";
+/** Handle the transient or permanent error-retry path. Non-fatal. */
+export async function transientRetry(event, _ctx, pi, runtime, config, tc) {
+    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/dist/extensions/mega-events/agent-handlers/turnEndHandler/errorRetry.js

@@ -1,7 +1,7 @@
 import { piCompactWouldNoop } from "../../../mega-pipeline.js";
-import { classifyError, classifyErrorDetailed, errorRetryBackoffMs, extractErrorSignature, isKnownRetryableTransient, } from "../../error-classifier.js";
-import { safeSendUserMessage } from "../../send-safe.js";
-import { maybeSendProviderOutageAdvisory } from "../../outage-advisor.js";
+import { classifyError, classifyErrorDetailed, extractErrorSignature, isKnownRetryableTransient, } from "../../error-classifier.js";
+import { safeSendInvisibleMessage } from "../../send-safe.js";
+import { transientRetry } from "./errorRetry-transient.js";
 /** S38: broader error-retry safety net. Non-fatal end-to-end. */
 export async function errorRetry(event, ctx, pi, runtime, config) {
     // S38: broader error-retry safety net. S28 only catches stopReason==='length';
@@ -209,7 +209,10 @@ export async function errorRetry(event, ctx, pi, runtime, config) {
                 // Default ON (advisoryChannel=true): dashboard-only, no user message.
                 if (!config.advisoryChannel) {
                     // PREVENT-PI-003: user-role sendUserMessage only.
-                    await safeSendUserMessage(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.");
+                    // 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.");
                 }
                 // (c) one guarded compact per error signature (attempt to remove
                 // the poisoned region). Race-guarded + deferred, mirroring the
@@ -245,139 +248,12 @@ export async function errorRetry(event, ctx, pi, runtime, config) {
             }
             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,
+                });
             }
         }
     }

package/dist/extensions/mega-events/compact-handlers.js

@@ -3,7 +3,7 @@ import { estimateBlockTokens } from "../../src/tokens.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().
  *
@@ -36,7 +36,7 @@ function fallbackCompaction(event) {
  * 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)".
@@ -47,7 +47,7 @@ async function nudgeResume(pi, runtime) {
         if (now >= runtime.resumeNudgeUntil) {
             runtime.resumeNudgeUntil = now + 30_000;
             runtime.rt.extensionInitiatedTurn = true; // R13: suppress self-classification
-            await safeSendUserMessage(pi, "[mega-compact] continue from the compacted context above.");
+            await safeSendInvisibleMessage(pi, "[mega-compact] continue from the compacted context above.");
         }
     }
     catch {

package/dist/extensions/mega-events/outage-advisor.js

@@ -9,10 +9,10 @@
  * 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 { safeSendUserMessage } from "./send-safe.js";
+import { safeSendInvisibleMessage } from "./send-safe.js";
 /**
  * Check the provider-outage advisory condition and fire once per episode.
  *
@@ -21,7 +21,7 @@ import { safeSendUserMessage } from "./send-safe.js";
  *
  * @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.
  */
@@ -53,7 +53,7 @@ export async function maybeSendProviderOutageAdvisory(effectiveCategory, runtime
     // 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(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.`);
+        // 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/dist/extensions/mega-events/send-safe.js

@@ -1,6 +1,7 @@
 /**
  * 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, content) {
     try {
@@ -10,3 +11,18 @@ export async function safeSendUserMessage(pi, content) {
         /* 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, content) {
+    try {
+        await pi.sendMessage({ customType: "mega-compact-retry", content, display: false }, { deliverAs: "followUp" });
+    }
+    catch {
+        /* non-fatal: a failed/queued nudge never blocks the agent loop */
+    }
+}

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 */
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.65",
+  "version": "0.20.66",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",