pi-mega-compact 0.11.3 → 0.11.4

package/extensions/mega-config.ts

@@ -107,6 +107,10 @@ export interface MegaConfig {
 	 *  classification is upgraded to 'poisoned-context' (the stateful repeat
 	 *  signal). Default 3. Raise to make the upgrade less aggressive. */
 	poisonedContextRepeatThreshold: number;
+	/** R10: consecutive transient errors at which a calm "provider outage"
+	 *  advisory is sent to the user (distinct from the poisoned /clear advise).
+	 *  Default 3. `0` disables the advisory entirely. */
+	providerOutageAdviseThreshold: number;
 	/** S29: override the auto-compact fire point for tiered configs, as a
 	 *  fraction of the context window (e.g. 0.85). null = inherit the tier's
 	 *  tierPct (default; preserves existing fire points). The context-handler
@@ -298,6 +302,10 @@ export function loadConfig(): MegaConfig {
 			"MEGACOMPACT_POISONED_REPEAT_THRESHOLD",
 			3,
 		),
+		providerOutageAdviseThreshold: envFlag(
+			"MEGACOMPACT_PROVIDER_OUTAGE_THRESHOLD",
+			3,
+		),
 		autoPctTrigger,
 		autoInlineK: envFlag("MEGACOMPACT_AUTO_INLINE_K", 3),
 		dedupSim: Number(process.env.MEGACOMPACT_DEDUP_SIM ?? "0.9"),

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

@@ -18,11 +18,13 @@ import { isMegaCache } from "../../src/game/scoring.js";
 import { resolveRepoRoot } from "../mega-config.js";
 import {
 	classifyError,
+	classifyErrorDetailed,
 	errorRetryBackoffMs,
 	extractErrorSignature,
 	isKnownRetryableTransient,
 } from "./error-classifier.js";
 import { safeSendUserMessage } from "./send-safe.js";
+import { maybeSendProviderOutageAdvisory } from "./outage-advisor.js";
 import { vectorStats } from "../../src/vectorStore.js";
 
 /** Register agent/turn tracking event handlers. */
@@ -393,6 +395,7 @@ export function registerAgentHandlers(
 				// S28 handles; nothing for S38 to do here.
 			} else {
 				const category = classifyError(event.message);
+				const detail = classifyErrorDetailed(event.message);
 				// R3: stateful poisoned-context signal — repeated identical error text
 				// across consecutive turns. The classifier is stateless, so this
 				// upgrade happens here. A 'transient' (or 'poisoned-context') turn
@@ -430,6 +433,12 @@ export function registerAgentHandlers(
 							// (error-classifier.ts) so the two never drift.
 							if (!isKnownRetryableTransient(errSig)) {
 								effectiveCategory = "poisoned-context";
+							} else {
+								runtime.logger.info("repeat-upgrade-declined", {
+									sessionId: runtime.rt.sessionId,
+									signature: (errSig || '').slice(0, 500),
+									repeatCount: runtime.rt.errorTextRepeatCount,
+								});
 							}
 						}
 					}
@@ -445,6 +454,9 @@ export function registerAgentHandlers(
 					runtime.rt.consecutiveErrors = 0; // S38.6: circuit-breaker reset on success
 					// R4: a successful assistant turn consumes any queued nudge.
 					runtime.rt.retryNudgePending = false;
+					// R10: reset outage advisory so a recovered-then-flapping
+					// provider re-advises once per episode.
+					runtime.rt.providerOutageAdvised = false;
 				} else if (effectiveCategory === "compaction-noop") {
 					// (4) pi race / manual compact catch — NOT retryable. The compaction
 					// already succeeded via pi's native path; retrying would race again
@@ -540,18 +552,24 @@ export function registerAgentHandlers(
 					runtime.rt.consecutiveErrors++; // still counts toward the circuit breaker
 					runtime.rt.poisonedCount++; // R7: dashboard counter
 					const sig = errSig || "unknown";
-					// (a) dashboard + log
+					// (a) dashboard + log — R11: include signal + rawText for forensics
 					runtime.dashboard.event("poisoned_context", {
 						signature: sig,
 						repeatCount: runtime.rt.errorTextRepeatCount,
 						turnIndex: event.turnIndex,
 						sessionId: runtime.rt.sessionId,
+						signal: detail.signal,
+						rawText: (errSig || '').slice(0, 500),
+						...(detail.httpStatus !== undefined ? { httpStatus: detail.httpStatus } : {}),
 					});
 					runtime.logger.warn("poisoned-context", {
 						sessionId: runtime.rt.sessionId,
 						turnIndex: event.turnIndex,
 						signature: sig,
 						repeatCount: runtime.rt.errorTextRepeatCount,
+						signal: detail.signal,
+						rawText: (errSig || '').slice(0, 500),
+						...(detail.httpStatus !== undefined ? { httpStatus: detail.httpStatus } : {}),
 					});
 					// (b) one-per-session advise message (throttled by poisonedAdviseSent)
 					if (!runtime.rt.poisonedAdviseSent) {
@@ -607,6 +625,11 @@ export function registerAgentHandlers(
 					}
 					// S38.6: circuit-breaker — stop retrying after too many consecutive errors.
 					runtime.rt.consecutiveErrors++;
+					// R10: send calm "provider outage" advisory once per episode.
+					await maybeSendProviderOutageAdvisory(
+						effectiveCategory, runtime, pi, config,
+						{ signal: detail.signal, rawText: (errSig || '').slice(0, 500) },
+					);
 					if (runtime.rt.consecutiveErrors > config.maxConsecutiveErrors) {
 						runtime.dashboard.event("error_retry_circuit_open", {
 							consecutive: runtime.rt.consecutiveErrors,

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

@@ -24,9 +24,11 @@
  *  - `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. */
+ *    error.code, which extractErrorSignature never sees.
+ *  - router phrasings (all targets failed / no healthy target / too many
+ *    concurrent) -- pi's status prefix is console-only (2026-07-30 incident). */
 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/;
+	/max(imum)? output token|rate[\s.-]?limit|429|too many requests|too many concurrent|overloaded|5\d\d|internal server|bad gateway|service unavailable|all targets failed|no healthy target|fetch failed|network|time(?:d[\s-]?out|out)|etimedout|econnreset|econnrefused|epipe|eai_again|socket|closed unexpectedly|premature close|other side closed|connection (lost|refused|reset|aborted?|was closed)|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. */
@@ -34,32 +36,60 @@ 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
- * exclusively (its agent_end nudge path is separate and must not be doubled).
- *
- * @param message  the event.message (a pi AgentMessage) or an error string
- * @returns 'transient' | 'permanent' | 'compaction-noop' | 'context-overflow' | 'cancelled' | 'poisoned-context' | null (success/unknown)
- */
-export function classifyError(message: unknown):
+/** R8: best-effort extraction of HTTP status from pi AgentMessage shapes. */
+function extractHttpStatus(m: Record<string, unknown>): number | undefined {
+	for (const outer of [m.error, m] as Array<Record<string, unknown> | undefined>) {
+		if (!outer || typeof outer !== 'object') continue;
+		for (const key of ['status', 'statusCode', 'code']) {
+			const v = (outer as Record<string, unknown>)[key];
+			if (typeof v === 'number' && v >= 100 && v <= 599) return v;
+		}
+	}
+	return undefined;
+}
+
+/** R11: signal tag identifying which classification rule fired. */
+export type ErrorSignal =
+	| 'length-guard'
+	| 'cancelled'
+	| 'success'
+	| 'stream-death-no-stopreason'
+	| 'compaction-noop'
+	| 'context-overflow'
+	| 'transient-marker'
+	| 'transient-status'
+	| 'permanent-status'
+	| 'poisoned-invalid-request'
+	| 'poisoned-request-failed'
+	| 'bare-0-token'
+	| 'generic-error'
+	| 'permanent-auth'
+	| 'unknown';
+
+export type ErrorCategory =
 	| 'transient'
 	| 'permanent'
 	| 'compaction-noop'
 	| 'context-overflow'
 	| 'cancelled'
 	| 'poisoned-context'
-	| null {
-	// Resolve a searchable text blob from a pi AgentMessage or raw string.
+	| null;
+
+/** R11: detailed classification result with the signal tag and optional httpStatus. */
+export interface ClassifyErrorDetail {
+	category: ErrorCategory;
+	signal: ErrorSignal;
+	httpStatus?: number;
+}
+
+/** R11: classify a turn-end error/stop signal into a retry category with a
+ *  diagnostic signal tag naming the rule that fired, plus the raw httpStatus
+ *  when extractHttpStatus found one. */
+export function classifyErrorDetailed(message: unknown): ClassifyErrorDetail {
 	let text = '';
-	// R3: usage-token signal. Only when `usage` is explicitly present with
-	// inputTokens=0 AND outputTokens=0 do we know the turn never reached the
-	// model. An ABSENT usage field means "unknown" (the event didn't carry
-	// token counts) — we do NOT treat that as the 0-token poisoned signal,
-	// because mid-response stream deaths and partial-content turns routinely
-	// omit usage while still being transient (preserves all pre-R3 tests).
 	let usagePresent = false;
 	let totalTokens = 0;
+	let httpStatus: number | undefined;
 	if (typeof message === 'string') {
 		text = message;
 	} else if (message && typeof message === 'object') {
@@ -70,14 +100,9 @@ export function classifyError(message: unknown):
 			usage?: { inputTokens?: number; outputTokens?: number } | undefined;
 		};
 		const sr = typeof m.stopReason === 'string' ? m.stopReason : '';
-		// S28 guard: length stopReason is handled exclusively by the S28 path.
-		if (sr === 'length') return null;
-		// User ESC / Ctrl-C abort — stopReason === 'aborted'. Not retryable:
-		// nudging would restart a task the user explicitly stopped.
-		if (sr === 'aborted') return 'cancelled';
-		// Success / normal tool flow — not an error, nothing to retry.
-		if (sr === 'stop' || sr === 'toolUse' || sr === 'tool_use') return null;
-		// R3: extract usage tokens for the 0-token poisoned-context signal.
+		if (sr === 'length') return { category: null, signal: 'length-guard' };
+		if (sr === 'aborted') return { category: 'cancelled', signal: 'cancelled' };
+		if (sr === 'stop' || sr === 'toolUse' || sr === 'tool_use') return { category: null, signal: 'success' };
 		const usage = m.usage;
 		usagePresent = usage != null && typeof usage === 'object';
 		if (usagePresent) {
@@ -86,6 +111,7 @@ export function classifyError(message: unknown):
 				(typeof u.inputTokens === 'number' ? u.inputTokens : 0) +
 				(typeof u.outputTokens === 'number' ? u.outputTokens : 0);
 		}
+		httpStatus = extractHttpStatus(m as Record<string, unknown>);
 		const parts: string[] = [];
 		if (sr) parts.push(sr);
 		const c = m.content;
@@ -98,119 +124,77 @@ export function classifyError(message: unknown):
 			}
 		}
 		if (m.error) {
-			// Extract message from error objects for pattern matching.
 			const err = m.error;
-			if (typeof err === 'string') {
-				parts.push(err);
-			} else if (err && typeof err === 'object') {
+			if (typeof err === 'string') parts.push(err);
+			else if (err && typeof err === 'object') {
 				const errObj = err as Record<string, unknown>;
-				if (typeof errObj.message === 'string') {
-					parts.push(errObj.message);
-				} else {
-					parts.push(JSON.stringify(err));
-				}
+				if (typeof errObj.message === 'string') parts.push(errObj.message);
+				else parts.push(JSON.stringify(err));
 			}
 		}
-		// S38: detect mid-response errors where the stream died without a
-		// proper stopReason (empty/undefined) — this catches provider failures
-		// that cut off the response mid-stream, INCLUDING the case where the
-		// provider emitted partial content before dying (a truncated response
-		// with no stop reason is a mid-stream death, not a success).
-		// A genuine success ALWAYS carries stop/tool_use/toolUse (which
-		// short-circuit to null at the top), so any message reaching here with a
-		// falsy stopReason is a stream failure → retryable.
 		if (!sr) {
-			return 'transient';
+			const r: ClassifyErrorDetail = { category: 'transient', signal: 'stream-death-no-stopreason' };
+			if (httpStatus !== undefined) r.httpStatus = httpStatus;
+			return r;
 		}
 		text = parts.join(' ');
 	}
-	if (!text) return null;
+	if (!text) return { category: null, signal: 'unknown' };
 	const s = text.toLowerCase();
-	// --- compaction-noop (ORDER FIRST: pi race / manual compact catch) ---
-	// FAIL-2026071701: these are NOT retryable — the compaction already
-	// succeeded via pi's native path; retrying would race again.
-	if (/already compacted/.test(s)) return 'compaction-noop';
-	if (/compaction failed/.test(s)) return 'compaction-noop';
-	if (/nothing to compact/.test(s)) return 'compaction-noop';
-	if (/auto[\s-]?compaction failed/.test(s)) return 'compaction-noop';
-	// --- context-overflow (ORDER BEFORE generic transient!) ---
-	// A 400 from the model meaning "the prompt is bigger than the context window."
-	// Catches BOTH provider phrasings so the classification does not depend on
-	// which backend the router landed on:
-	//   - pi/Anthropic wrapper: "too long for this model's context window even
-	//     after compaction. Reduce the conversation length..." ->
-	//     too long | context window | even after compaction | reduce the conversation
-	//   - OpenAI/OpenRouter provider-side (often wrapped in "All targets failed:
-	//     <model>. Last error: ..."): "This model's maximum context length is N
-	//     tokens. Your request requires at least M tokens. Please reduce your
-	//     input or max_tokens." -> maximum context length | context length
-	//     exceeded | requires at least N tokens | reduce your input
-	// All of these carry `invalid_request_error` (UNDERSCORE, not 'invalid
-	// request' space) and would otherwise fall through to the generic
-	// `s.includes('error')` transient branch below, misclassifying as
-	// 'transient' and firing up to 5 blind retry nudges that re-submit the same
-	// oversized prompt -> re-400 -> busy-loop. 'context-overflow' instead forces
-	// ONE deferred re-compact (debounce-bypassed, race-guarded) and fires NO
-	// blind retry nudge. The forced re-compact is shaped by the existing
-	// session_before_compact durable trim (it cannot lower pi's firstKeptEntryId).
+	if (/already compacted|compaction failed|nothing to compact|auto[\s-]?compaction failed/.test(s)) {
+		return { category: 'compaction-noop', signal: 'compaction-noop' };
+	}
 	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';
+		return { category: 'context-overflow', signal: 'context-overflow' };
+	}
+	if (isKnownRetryableTransient(s)) {
+		const r: ClassifyErrorDetail = { category: 'transient', signal: 'transient-marker' };
+		if (httpStatus !== undefined) r.httpStatus = httpStatus;
+		return r;
+	}
+	if (httpStatus === 429 || (httpStatus !== undefined && httpStatus >= 500)) {
+		return { category: 'transient', signal: 'transient-status', httpStatus };
+	}
+	if (httpStatus === 401 || httpStatus === 403) {
+		return { category: 'permanent', signal: 'permanent-status', httpStatus };
 	}
-	// --- 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
-	// the same prompt re-triggers the same rejection. The 2026-07-28 incident
-	// was a provider returning 0-token "Request failed — please retry." turns
-	// for every request; classifyError mapped stopReason 'error' → 'transient'
-	// and the session emitted ~9 nudge bursts (~60 context-bloating messages)
-	// before stopping.
-	//
-	// Signal 1: provider request-validation 400 that is NOT context-overflow
-	// (context-overflow already returned above). Orphaned tool result / malformed
-	// message structure / unexpected role ordering / empty content. These were
-	// previously classified 'permanent' (max 1 retry) — but a single retry
-	// re-submits the SAME malformed structure and re-400s, so they are poisoned,
-	// not permanent. Auth/permission 400s stay permanent (separate check below).
 	if (/invalid_request_error|invalid request|malformed|bad request|orphaned tool|tool (result )?(without|for )|unexpected role|role (ordering|sequence)|empty (content|message|request)/.test(s)) {
-		return 'poisoned-context';
+		return { category: 'poisoned-context', signal: 'poisoned-invalid-request' };
 	}
-	// Signal 2: generic catch-all "request failed" / "request error" with no
-	// specific transient marker (transient markers already returned above).
-	// This is the exact phrasing the 2026-07-28 incident used. Without a
-	// specific retryable cause, treat the rejection as deterministic.
 	if (/request failed|request error/.test(s)) {
-		return 'poisoned-context';
+		return { category: 'poisoned-context', signal: 'poisoned-request-failed' };
 	}
-	// Signal 3: stopReason 'error' + usage explicitly 0 tokens (the turn never
-	// reached the model). Conservative: only when `usage` is PRESENT and 0 — an
-	// absent usage field means "unknown" and stays transient (mid-response
-	// deaths / partial-content turns often omit usage). The transient markers
-	// above already returned, so reaching here with 'error' text and 0 tokens
-	// means the request was rejected before any model work.
 	if (usagePresent && totalTokens === 0 && /error/.test(s)) {
-		return 'poisoned-context';
+		return { category: 'transient', signal: 'bare-0-token' };
 	}
-	// --- transient (generic 'error' stopReason fallthrough) ---
-	// Reaches here for a generic stopReason 'error' with no specific marker and
-	// no 0-token signal (usage absent or > 0). Stays transient — conservative.
 	if (s.includes('error') && !/\b(auth|unauthorized|invalid (api )?key|permission)\b/.test(s)) {
-		return 'transient'; // generic pi stopReason 'error'
+		return { category: 'transient', signal: 'generic-error' };
+	}
+	if (/auth|unauthorized|invalid (api )?key|permission/.test(s)) {
+		return { category: 'permanent', signal: 'permanent-auth' };
 	}
-	// NOTE: 'aborted' stopReason is handled by the sr==='aborted' early-return above.
-	// The text-based s.includes('aborted') was removed — it was the old path that
-	// misclassified user ESC/Ctrl-C as 'transient' (5 retry nudges after cancel).
-	// --- permanent (NOT retryable beyond 1) ---
-	if (/auth|unauthorized|invalid (api )?key|permission/.test(s)) return 'permanent';
-	// Unknown — do not retry (avoid busy-looping on an unclassified signal).
-	return null;
+	return { category: null, signal: 'unknown' };
+}
+
+/** 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
+ * exclusively (its agent_end nudge path is separate and must not be doubled).
+ *
+ * Thin wrapper around classifyErrorDetailed — returns only the category.
+ *
+ * @param message  the event.message (a pi AgentMessage) or an error string
+ * @returns 'transient' | 'permanent' | 'compaction-noop' | 'context-overflow' | 'cancelled' | 'poisoned-context' | null (success/unknown)
+ */
+export function classifyError(message: unknown):
+	| 'transient'
+	| 'permanent'
+	| 'compaction-noop'
+	| 'context-overflow'
+	| 'cancelled'
+	| 'poisoned-context'
+	| null {
+	return classifyErrorDetailed(message).category;
 }
 
 /** S38.2: exponential backoff for error-retry nudges.
@@ -233,13 +217,39 @@ export function errorRetryBackoffMs(count: number, baseMs = 5000): number {
  *  'error' for retryable turns) so two turns with the same error content share
  *  a signature. Empty string when there is no error text (e.g. a bare
  *  stopReason 'error' with no content) — the caller skips repeat detection in
- *  that case (the stateless 0-token signal handles bare errors). */
+ *  that case (the stateless 0-token signal handles bare errors).
+ *
+ *  R9: when the joined text is empty AND stopReason is 'error' AND usage is
+ *  present with 0 total tokens, returns the constant "bare-0-token-error" so
+ *  the repeat detector can corroborate bare 0-token errors (first turn is
+ *  transient; repeated occurrences upgrade to poisoned at threshold). Bare
+ *  'error' WITHOUT usage keeps returning '' (absent usage = unknown; mid-
+ *  response deaths stay out of repeat tracking). */
+/** R12: normalize volatile tokens in an already-lowercased error string so that
+ *  equivalent errors with varied model aliases, IPs, hex request-ids, retry
+ *  counts, and long numeric ids produce the same signature.  Order matters.
+ *  3-digit HTTP status codes (429/500/502/etc.) survive — the long-number rule
+ *  only covers 4+ digits.  Invariant: normalizeVolatileTokens never empties a
+ *  non-empty string (every regex replaces with a non-empty literal token). */
+function normalizeVolatileTokens(s: string): string {
+	let n = s;
+	n = n.replace(/\b\d{1,3}(\.\d{1,3}){3}(:\d+)?\b/g, '<ip>');             // 1. IP:port / bare IPv4
+	n = n.replace(/\b[\w-]+(\/[\w.:+-]+)+/g, '<model>');                     // 2. slash-separated paths
+	n = n.replace(/\b[0-9a-f]{8,}\b/g, '<hex>');                            // 3. hex ids (8+ chars)
+	n = n.replace(/\b\d{4,}\b/g, '<n>');                                    // 4. long numbers (4+ digits)
+	n = n.replace(/\bafter \d+ attempts?\b/g, 'after <n> attempts');          // 5. attempt phrasing
+	n = n.replace(/\s+/g, ' ').trim();                                       // 6. collapse whitespace
+	return n;
+}
+
 export function extractErrorSignature(message: unknown): string {
-	if (typeof message === 'string') return message.toLowerCase().trim();
+	if (typeof message === 'string') return normalizeVolatileTokens(message.toLowerCase().trim());
 	if (!message || typeof message !== 'object') return '';
 	const m = message as {
 		content?: unknown;
 		error?: unknown;
+		stopReason?: string;
+		usage?: { inputTokens?: number; outputTokens?: number };
 	};
 	const parts: string[] = [];
 	const c = m.content;
@@ -260,5 +270,16 @@ export function extractErrorSignature(message: unknown): string {
 			else parts.push(JSON.stringify(err));
 		}
 	}
-	return parts.join(' ').toLowerCase().trim();
+	const joined = parts.join(' ').toLowerCase().trim();
+	const normalized = normalizeVolatileTokens(joined);
+	if (
+		normalized === '' &&
+		m.stopReason === 'error' &&
+		m.usage &&
+		typeof m.usage === 'object' &&
+		(m.usage.inputTokens ?? 0) + (m.usage.outputTokens ?? 0) === 0
+	) {
+		return 'bare-0-token-error';
+	}
+	return normalized;
 }

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

@@ -0,0 +1,73 @@
+/**
+ * outage-advisor.ts — R10: calm "provider outage" advisory.
+ *
+ * When a provider/router flaps (transient errors: timeouts, 5xx, 429s),
+ * the extension retries silently and eventually goes quiet after caps. This
+ * module sends ONE user-facing advisory per outage episode so the user knows
+ * to wait rather than running /clear.
+ *
+ * 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-004: local ctx call, no network.
+ */
+
+import type { MegaRuntime } from "../mega-runtime.js";
+import { safeSendUserMessage } from "./send-safe.js";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/** R11: optional diagnostic detail passed from the classifier. */
+export interface OutageDetail {
+	signal?: string;
+	rawText?: string;
+}
+
+/**
+ * Check the provider-outage advisory condition and fire once per episode.
+ *
+ * Called from the transient/permanent retry branch of the turn_end handler,
+ * AFTER consecutiveErrors is incremented.
+ *
+ * @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 config    — providerOutageAdviseThreshold config.
+ * @param detail    — R11: optional signal + rawText for forensics.
+ */
+export async function maybeSendProviderOutageAdvisory(
+	effectiveCategory: string,
+	runtime: MegaRuntime,
+	pi: ExtensionAPI,
+	config: { providerOutageAdviseThreshold: number },
+	detail?: OutageDetail,
+): Promise<void> {
+	if (effectiveCategory !== "transient") return;
+	if (config.providerOutageAdviseThreshold <= 0) return;
+	if (runtime.rt.providerOutageAdvised) return;
+	if (runtime.rt.consecutiveErrors < config.providerOutageAdviseThreshold)
+		return;
+
+	runtime.rt.providerOutageAdvised = true;
+
+	runtime.dashboard.event("provider_outage_advised", {
+		consecutiveErrors: runtime.rt.consecutiveErrors,
+		turnIndex: runtime.currentTurn,
+		sessionId: runtime.rt.sessionId,
+		...(detail?.signal !== undefined ? { signal: detail.signal } : {}),
+		...(detail?.rawText !== undefined ? { rawText: detail.rawText } : {}),
+	});
+
+	runtime.logger.info("provider-outage-advised", {
+		sessionId: runtime.rt.sessionId,
+		consecutiveErrors: runtime.rt.consecutiveErrors,
+		turnIndex: runtime.currentTurn,
+		...(detail?.signal !== undefined ? { signal: detail.signal } : {}),
+		...(detail?.rawText !== undefined ? { rawText: detail.rawText } : {}),
+	});
+
+	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.`,
+	);
+}

package/extensions/mega-runtime/helpers.ts

@@ -67,6 +67,8 @@ export interface SessionRuntime {
 	errorTextRepeatCount: number; // consecutive count of identical error signatures
 	// R3b: one-per-session /clear advise message throttle.
 	poisonedAdviseSent: boolean; // true after the advise message fires once
+	// R10: provider-outage advisory throttle (one per flapping episode).
+	providerOutageAdvised: boolean; // true after the outage advise message fires once
 	// R3c: one guarded compact per error signature (avoids re-compacting the
 	// same poisoned region repeatedly).
 	poisonedCompactSignatures: Set<string>; // signatures already attempted a compact for

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

@@ -68,6 +68,7 @@ export function resetRuntimeImpl(
 		lastErrorText: undefined,
 		errorTextRepeatCount: 0,
 		poisonedAdviseSent: false,
+		providerOutageAdvised: false,
 		poisonedCompactSignatures: new Set(),
 		poisonedCount: 0,
 	};

package/extensions/mega-runtime/runtime.ts

@@ -101,6 +101,7 @@ export class MegaRuntime {
 		lastErrorText: undefined,
 		errorTextRepeatCount: 0,
 		poisonedAdviseSent: false,
+		providerOutageAdvised: false,
 		poisonedCompactSignatures: new Set(),
 		poisonedCount: 0,
 	};

package/package.json

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