pi-mega-compact 0.11.2 → 0.11.4

package/dist/extensions/mega-config.js

@@ -148,6 +148,7 @@ export function loadConfig() {
         errorRetryBackoffMs: envFlag("MEGACOMPACT_ERROR_RETRY_BACKOFF_MS", 5000),
         errorRetrySessionMax: envFlag("MEGACOMPACT_ERROR_RETRY_SESSION_MAX", 3),
         poisonedContextRepeatThreshold: envFlag("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"),
@@ -165,6 +166,9 @@ export function loadConfig() {
         recallMaxTokens: envFlag("MEGACOMPACT_RECALL_MAX_TOKENS", 1500),
         windowDedupe: envBool("MEGACOMPACT_WINDOW_DEDUPE", true),
         tuiWidget: envBool("MEGACOMPACT_TUI_WIDGET", true),
+        // D.1: env-overridable recompact delta (minimum context growth % before
+        // re-compacting instead of replaying the cached live trim). Default 50.
+        recompactPctDelta: envFlag("MEGACOMPACT_RECOMPACT_PCT_DELTA", 50),
         debug: envBool("MEGACOMPACT_DEBUG", false),
     };
 }

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

@@ -1,12 +1,13 @@
 import { piCompactWouldNoop, runMemoryReview } from "../mega-pipeline.js";
 import { memoryReviewCadence } from "../mega-config.js";
-import { recordScore } from "../../src/store/sqlite.js";
+import { recordScore, readLatestCacheHitPct } from "../../src/store/sqlite.js";
 import { evaluateAndUnlockAchievements } from "../../src/store/sqlite/game-achievements.js";
 import { ensureConversationIdFor, recordTurnWrite, } from "../mega-turn-store.js";
 import { isMegaCache } from "../../src/game/scoring.js";
 import { resolveRepoRoot } from "../mega-config.js";
-import { classifyError, errorRetryBackoffMs, extractErrorSignature, } from "./error-classifier.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. */
 export function registerAgentHandlers(pi, runtime, config) {
@@ -255,7 +256,9 @@ export function registerAgentHandlers(pi, runtime, config) {
             if (runtime.getCachedGameState().game_mode_on) {
                 const repo = resolveRepoRoot(ctx.cwd) ?? runtime.currentStateDir;
                 const st = vectorStats(runtime.store, runtime.rt.sessionId);
-                const cachePct = st.dedupHitRate * 100;
+                // C.3: prefer provider cache hit rate, fall back to dedup hit rate
+                const providerPct = readLatestCacheHitPct(runtime.currentStateDir);
+                const cachePct = providerPct != null ? providerPct : st.dedupHitRate * 100;
                 const modelId = runtime.currentModel?.modelId ?? "unknown";
                 recordScore(runtime.currentStateDir, {
                     repo_root: repo,
@@ -334,14 +337,17 @@ export function registerAgentHandlers(pi, runtime, config) {
             }
             else {
                 const category = classifyError(event.message);
+                const detail = classifyErrorDetailed(event.message);
                 // R3: stateful poisoned-context signal — repeated identical error text
                 // across consecutive turns. The classifier is stateless, so this
                 // upgrade happens here. A 'transient' (or 'poisoned-context') turn
                 // whose normalized error signature matches the previous one bumps
                 // errorTextRepeatCount; once it crosses the threshold, the category
-                // is upgraded to 'poisoned-context' (the request is deterministic).
-                // Conservative: only upgrade, never downgrade, and only for transient
-                // (a 'permanent' auth error repeating is still permanent).
+                // is upgraded to 'poisoned-context' (the request is deterministic) —
+                // R7: unless the signature carries a known-retryable network/
+                // throughput marker (guard below). Conservative: only upgrade, never
+                // downgrade, and only for transient (a 'permanent' auth error
+                // repeating is still permanent).
                 let effectiveCategory = category;
                 const errSig = extractErrorSignature(event.message);
                 if (category === "transient" || category === "poisoned-context") {
@@ -356,7 +362,26 @@ export function registerAgentHandlers(pi, runtime, config) {
                         if (runtime.rt.errorTextRepeatCount >=
                             config.poisonedContextRepeatThreshold &&
                             category === "transient") {
-                            effectiveCategory = "poisoned-context";
+                            // R3/R7: upgrade only when the repeating error carries NO
+                            // known-retryable marker. Network/throughput failures (timeout,
+                            // ECONNRESET, 5xx, 429, connection lost, …) that repeat are
+                            // still retryable — the API is just flaky, and /clear cannot fix
+                            // them (2026-07-30 false-alarm incident). Only upgrade
+                            // transient → poisoned-context for errors that repeat identically
+                            // with no known-retryable cause, like the 2026-07-28 incident
+                            // where the provider returned "Request failed — please retry."
+                            // deterministically. The marker set is shared with classifyError
+                            // (error-classifier.ts) so the two never drift.
+                            if (!isKnownRetryableTransient(errSig)) {
+                                effectiveCategory = "poisoned-context";
+                            }
+                            else {
+                                runtime.logger.info("repeat-upgrade-declined", {
+                                    sessionId: runtime.rt.sessionId,
+                                    signature: (errSig || '').slice(0, 500),
+                                    repeatCount: runtime.rt.errorTextRepeatCount,
+                                });
+                            }
                         }
                     }
                 }
@@ -372,6 +397,9 @@ export function registerAgentHandlers(pi, runtime, config) {
                     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
@@ -471,18 +499,24 @@ export function registerAgentHandlers(pi, runtime, config) {
                     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) {
@@ -536,6 +570,8 @@ export function registerAgentHandlers(pi, runtime, config) {
                     }
                     // 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/dist/extensions/mega-events/context-handler.js

@@ -170,30 +170,24 @@ export function registerContextHandler(pi, runtime, config) {
             runtime.diagCtxFastGate++;
             return;
         }
-        // Debounce so we don't fire on every context event past threshold.
-        const now = Date.now();
-        if (now < runtime.debounceUntil) {
-            runtime.diagCtxDebounce++;
-            return;
-        }
-        runtime.debounceUntil = now + 2000;
+        // D.2: Replay MUST be exempt from debounce — replay is free (no compute,
+        // no re-write) and prevents unnecessary KV-cache invalidation. Check
+        // replay FIRST, before debounce, so two context events <2s apart both
+        // return the cached sentinel verbatim (re-stabilises the provider prefix).
+        //
         // v0.8.6 cache-stability: replay the cached trim view when still in the
         // same compaction epoch AND context hasn't grown enough to warrant a
-        // re-compact. This stabilizes the provider KV-cache prefix (the summary +
-        // cut are reused verbatim) instead of regenerating a fresh summary +
-        // sentinel every fire, which invalidated the prefix on every other turn
-        // (the alternating cache-miss regression). Re-compact only when context
-        // grew >=10% of the window (percent basis) or >=50% of the effective
-        // threshold (token basis, when percent is unavailable). The cached `cut`
-        // is only valid while the transcript grows within the epoch — it is
-        // cleared on session_compact (durable truncation) + resetRuntime, so we
-        // never replay a stale cut into a truncated transcript (PREVENT-PI-001/002).
-        const RECOMPACT_PCT_DELTA = 10;
+        // re-compact. Re-compact only when context grew >=config.recompactPctDelta%
+        // of the window (percent basis) or >=50% of the effective threshold
+        // (token basis, when percent is unavailable). The cached `cut` is only
+        // valid while the transcript grows within the epoch — it is cleared on
+        // session_compact (durable truncation) + resetRuntime, so we never replay
+        // a stale cut into a truncated transcript (PREVENT-PI-001/002).
         if (runtime.trimCache &&
             runtime.trimCache.checkpointId === runtime.rt.lastCheckpointId &&
             runtime.trimCache.cut <= messages.length) {
             const grewEnough = pct != null && runtime.trimCache.ctxPct != null
-                ? pct - runtime.trimCache.ctxPct >= RECOMPACT_PCT_DELTA
+                ? pct - runtime.trimCache.ctxPct >= config.recompactPctDelta
                 : currentTokens - (runtime.trimCache.ctxTokens ?? 0) >=
                     runtime.effectiveThreshold * 0.5;
             if (!grewEnough) {
@@ -209,6 +203,14 @@ export function registerContextHandler(pi, runtime, config) {
             }
             // else: context grew enough → fall through to re-compact (cache is stale)
         }
+        // Debounce so we don't fire on every context event past threshold.
+        // (Replay already returned above — only fresh compacts reach this point.)
+        const now = Date.now();
+        if (now < runtime.debounceUntil) {
+            runtime.diagCtxDebounce++;
+            return;
+        }
+        runtime.debounceUntil = now + 2000;
         // Adaptive compression (Fix E): scale compression strength + keepFrom depth
         // with how close we are to the model context limit. Null-safe: when the
         // token-fallback path ran (pct unavailable) use the token-basis pressure
@@ -219,8 +221,22 @@ export function registerContextHandler(pi, runtime, config) {
         const ran = runCompact(pi, runtime, config, ctx, messages, {
             compressionPressure: pressure,
         });
+        // D.3: skip paths fall back to replay instead of returning empty.
+        // If runCompact skipped and we have a valid trimCache, replay it
+        // (free stability win) — otherwise defer to the next event.
         if (ran.skipped) {
             runtime.diagCtxRunSkipped++;
+            if (runtime.trimCache &&
+                runtime.trimCache.checkpointId === runtime.rt.lastCheckpointId &&
+                runtime.trimCache.cut <= messages.length) {
+                const recent = messages.slice(runtime.trimCache.cut); // guardrails-allow PREVENT-PI-002
+                runtime.diagLiveTrimFires++;
+                runtime.diagLiveTrimReplays++;
+                runtime.snapshot(ctx);
+                return {
+                    messages: [{ ...runtime.trimCache.summaryAgentMsg }, ...recent],
+                };
+            }
             return;
         }
         // S27 DB-mirror: write checkpoint_epoch with deterministic nonce.
@@ -277,7 +293,9 @@ export function registerContextHandler(pi, runtime, config) {
                     }
                 }
                 catch (wikiErr) {
-                    runtime.logger.warn("wiki_rebuild_failed", { error: String(wikiErr) });
+                    runtime.logger.warn("wiki_rebuild_failed", {
+                        error: String(wikiErr),
+                    });
                 }
                 // S27 Task 6: Fire-and-forget dedup pipeline.
                 // Deduplicates raw_transcript rows for the compacted range.

package/dist/extensions/mega-events/error-classifier.js

@@ -11,42 +11,60 @@
  * compact per signature). Conservative: when unsure between transient and
  * poisoned, choose transient (bounded by R1 dedup + R2 session cap).
  */
-/** S38.2: classify a turn-end error/stop signal into a retry category.
+/** R7: known-retryable transient markers — network/throughput failures that
+ *  retry can fix and /clear cannot. SINGLE SOURCE OF TRUTH: classifyError uses
+ *  this for its transient-marker stage, and the agent-handlers R3 repeat
+ *  upgrade guard uses it to keep these errors out of poisoned-context. Add new
+ *  transient phrasings HERE only.
  *
- * `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) {
-    // Resolve a searchable text blob from a pi AgentMessage or raw string.
+ *  Non-obvious alternatives:
+ *  - `time(?:d[\s-]?out|out)` covers "timeout", "timed out", "timed-out" —
+ *    "timed out" does NOT match /timeout/ (the 2026-07-30 incident phrasing).
+ *  - `etimedout` is Node's timeout errno lowercased — does NOT contain the
+ *    substring "timeout".
+ *  - `socket hang up` is Node's ECONNRESET *message*; the errno lives in
+ *    error.code, which extractErrorSignature never sees.
+ *  - 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|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. */
+export function isKnownRetryableTransient(text) {
+    return KNOWN_RETRYABLE_TRANSIENT_PATTERN.test(text.toLowerCase());
+}
+/** R8: best-effort extraction of HTTP status from pi AgentMessage shapes. */
+function extractHttpStatus(m) {
+    for (const outer of [m.error, m]) {
+        if (!outer || typeof outer !== 'object')
+            continue;
+        for (const key of ['status', 'statusCode', 'code']) {
+            const v = outer[key];
+            if (typeof v === 'number' && v >= 100 && v <= 599)
+                return v;
+        }
+    }
+    return undefined;
+}
+/** 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) {
     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;
     if (typeof message === 'string') {
         text = message;
     }
     else if (message && typeof message === 'object') {
         const m = message;
         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.
+            return { category: null, signal: 'length-guard' };
         if (sr === 'aborted')
-            return 'cancelled';
-        // Success / normal tool flow — not an error, nothing to retry.
+            return { category: 'cancelled', signal: 'cancelled' };
         if (sr === 'stop' || sr === 'toolUse' || sr === 'tool_use')
-            return null;
-        // R3: extract usage tokens for the 0-token poisoned-context signal.
+            return { category: null, signal: 'success' };
         const usage = m.usage;
         usagePresent = usage != null && typeof usage === 'object';
         if (usagePresent) {
@@ -55,6 +73,7 @@ export function classifyError(message) {
                 (typeof u.inputTokens === 'number' ? u.inputTokens : 0) +
                     (typeof u.outputTokens === 'number' ? u.outputTokens : 0);
         }
+        httpStatus = extractHttpStatus(m);
         const parts = [];
         if (sr)
             parts.push(sr);
@@ -69,136 +88,75 @@ export function classifyError(message) {
             }
         }
         if (m.error) {
-            // Extract message from error objects for pattern matching.
             const err = m.error;
-            if (typeof err === 'string') {
+            if (typeof err === 'string')
                 parts.push(err);
-            }
             else if (err && typeof err === 'object') {
                 const errObj = err;
-                if (typeof errObj.message === 'string') {
+                if (typeof errObj.message === 'string')
                     parts.push(errObj.message);
-                }
-                else {
+                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 = { category: 'transient', signal: 'stream-death-no-stopreason' };
+            if (httpStatus !== undefined)
+                r.httpStatus = httpStatus;
+            return r;
         }
         text = parts.join(' ');
     }
     if (!text)
-        return null;
+        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';
-    }
-    // --- transient (specific markers FIRST — these override poisoned signals) ---
-    // R3: network failures (timeout, ECONNRESET, 5xx, 429) MUST stay transient
-    // even when usage is 0 tokens, because they are retryable. The specific
-    // markers below return before any poisoned signal is evaluated.
-    if (/max(imum)? output token/.test(s))
-        return 'transient';
-    if (/rate[\s.-]?limit|429|too many requests/.test(s))
-        return 'transient';
-    if (/5\d\d|internal server|bad gateway|service unavailable/.test(s))
-        return 'transient';
-    // 'connection aborted' is a network failure (ECONNABORTED), NOT a user ESC
-    // (which is stopReason 'aborted', handled by the early-return above). Added
-    // so "Connection aborted by peer" stays transient under R3. ECONNRESET and
-    // common errno names are included so a bare 0-token 'ECONNRESET' turn is not
-    // misclassified as poisoned (R6: ECONNRESET → transient).
-    if (/network|timeout|econnreset|econnrefused|epipe|connection (lost|refused|reset|aborted)|stream (interrupted|closed|ended|failed)|disconnected/.test(s))
-        return 'transient';
-    // --- 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).
+        return { category: 'context-overflow', signal: 'context-overflow' };
+    }
+    if (isKnownRetryableTransient(s)) {
+        const r = { 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 };
+    }
     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';
-    }
-    // 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.
+        return { category: 'poisoned-context', signal: 'poisoned-request-failed' };
+    }
     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'
-    }
-    // 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: 'transient', signal: 'generic-error' };
+    }
+    if (/auth|unauthorized|invalid (api )?key|permission/.test(s)) {
+        return { category: 'permanent', signal: 'permanent-auth' };
+    }
+    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) {
+    return classifyErrorDetailed(message).category;
 }
 /** S38.2: exponential backoff for error-retry nudges.
  *  count is 1-based (the retry about to fire). baseMs is the unit
@@ -219,10 +177,33 @@ export function errorRetryBackoffMs(count, baseMs = 5000) {
  *  '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) {
+    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) {
     if (typeof message === 'string')
-        return message.toLowerCase().trim();
+        return normalizeVolatileTokens(message.toLowerCase().trim());
     if (!message || typeof message !== 'object')
         return '';
     const m = message;
@@ -249,5 +230,14 @@ export function extractErrorSignature(message) {
                 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/dist/extensions/mega-events/outage-advisor.js

@@ -0,0 +1,53 @@
+/**
+ * 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 { safeSendUserMessage } from "./send-safe.js";
+/**
+ * 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, runtime, pi, config, detail) {
+    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/dist/extensions/mega-runtime/reset-runtime.js

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