pi-mega-compact 0.11.3 → 0.11.5

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 (/^(stop|tool_?use|end_?turn|max_?tokens|complete|finished|done)$/i.test(sr)) 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,88 @@ 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';
+			// A missing stopReason alone is not sufficient evidence of stream death.
+			// Require at least one corroborating signal: an error field, or 0 total tokens
+			// (indicating the stream died before producing anything). A normal completion
+			// from a runtime that omits stopReason has content and tokens — not an error.
+			const hasError = (m.error != null && m.error !== undefined && m.error !== '') ||
+				(typeof (m as { errorMessage?: unknown }).errorMessage === 'string' && (m as { errorMessage?: string }).errorMessage !== '');
+			if (hasError || (usagePresent && totalTokens === 0)) {
+				const r: ClassifyErrorDetail = { category: 'transient', signal: 'stream-death-no-stopreason' };
+				if (httpStatus !== undefined) r.httpStatus = httpStatus;
+				return r;
+			}
+			// No stopReason, no error field, tokens present — likely a normal completion
+			// from a runtime that omits stopReason (pi-crew, etc.). Not an error.
+			return { category: null, signal: 'success' };
 		}
 		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 +228,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 +281,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/mirror-append.ts

@@ -0,0 +1,155 @@
+/**
+ * mirror-append.ts — extracted DB-mirror append logic for context-handler.ts
+ * (F3 sprint: high-water mark incremental append).
+ *
+ * Follows the repo's delegate-shell pattern: the context handler shell delegates
+ * to this impl module for the mirror-append concern. Returns `rowsProcessed`
+ * so callers (including tests) can observe how many new rows were written
+ * without adding test-only hooks.
+ */
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { DatabaseSync } from "node:sqlite";
+import { appendRawTranscript, type RawTranscriptRow } from "../../src/store/sqlite.js";
+import { computeContentDigest } from "../../src/dedup/digest.js";
+import {
+	ensureHwmTable,
+	readHwm,
+	writeHwm,
+	dropHwm,
+} from "./context-hwm.js";
+
+export interface MirrorAppendResult {
+	rowsProcessed: number;
+}
+
+/**
+ * Append incoming messages to raw_transcript with HWM incremental support.
+ *
+ * On fork/rewind (shorter message list or boundary hash mismatch), the HWM
+ * is dropped and all messages are reprocessed.
+ */
+export function appendMirrorMessages(
+	db: DatabaseSync,
+	messages: AgentMessage[],
+	sessionId: string,
+	epochId: string,
+	currentTurn: number | undefined,
+): MirrorAppendResult {
+	ensureHwmTable(db);
+	const hwm = readHwm(db, sessionId);
+
+	let tailStart = 0;
+	let needDrop = false;
+
+	if (hwm) {
+		if (messages.length <= hwm.lastSeq) {
+			// Session was shortened (fork/rewind/clear) — full reprocess.
+			needDrop = true;
+		} else {
+			// Verify boundary integrity: hash of message at hwm.lastSeq-1
+			// must match the stored hash.
+			const boundaryMsg = messages[hwm.lastSeq - 1];
+			const boundaryHash = contentHashOf(
+				(boundaryMsg as { content?: unknown }).content,
+			);
+			if (boundaryHash === hwm.lastContentHash) {
+				tailStart = hwm.lastSeq;
+			} else {
+				needDrop = true;
+			}
+		}
+	}
+
+	if (needDrop) {
+		dropHwm(db, sessionId);
+	}
+
+	// Process tail (or all if tailStart === 0).
+	let rowsProcessed = 0;
+	for (let i = tailStart; i < messages.length; i++) {
+		const raw = toRawRow(messages[i], sessionId, epochId, currentTurn);
+		if (raw) {
+			appendRawTranscript(db, raw);
+			rowsProcessed++;
+		}
+	}
+
+	// Write new HWM.
+	if (messages.length > 0) {
+		const lastMsg = messages[messages.length - 1];
+		writeHwm(db, {
+			sessionId,
+			lastSeq: messages.length,
+			lastContentHash: contentHashOf(
+				(lastMsg as { content?: unknown }).content,
+			),
+		});
+	}
+
+	return { rowsProcessed };
+}
+
+/** Single rule for hashing message content on BOTH sides of the HWM
+ *  (write + boundary check) — a mismatch here silently defeats the
+ *  incremental path (every event would full-reprocess). null/undefined → "". */
+function contentHashOf(content: unknown): string {
+	if (content == null) return "";
+	const bytes =
+		typeof content === "string"
+			? content
+			: JSON.stringify(canonicalize(content));
+	return computeContentDigest(bytes).contentHash;
+}
+
+/**
+ * Canonicalize a value for deterministic JSON serialization (keys sorted).
+ * This is the same logic as the inline function in context-handler.ts.
+ */
+function canonicalize(value: unknown): unknown {
+	if (value === null || value === undefined) return value;
+	if (typeof value !== "object") return value;
+	if (Array.isArray(value)) return value.map(canonicalize);
+	const sorted = Object.keys(value as Record<string, unknown>).sort();
+	const out: Record<string, unknown> = {};
+	for (const k of sorted) {
+		(out as Record<string, unknown>)[k] = canonicalize(
+			(value as Record<string, unknown>)[k],
+		);
+	}
+	return out;
+}
+
+/** Convert an AgentMessage to a RawTranscriptRow (same logic as toRawTranscriptRow in context-handler.ts). */
+function toRawRow(
+	msg: AgentMessage,
+	sessionId: string,
+	epochId: string,
+	currentTurn: number | undefined,
+): RawTranscriptRow | null {
+	const m = msg as {
+		role?: string;
+		content?: unknown;
+		timestamp?: number;
+		toolName?: string;
+	};
+	const content = m.content;
+	if (content == null || content === "") return null;
+	const contentBytes =
+		typeof content === "string"
+			? content
+			: JSON.stringify(canonicalize(content));
+	return {
+		contentHash: computeContentDigest(contentBytes).contentHash,
+		sessionId,
+		seq: 0, // assigned by appendRawTranscript
+		role: m.role ?? "unknown",
+		contentBytes,
+		toolName: m.toolName ?? null,
+		messageTimestamp: m.timestamp ?? null,
+		checkpointEpoch: epochId,
+		turnIndex: currentTurn ?? null,
+	};
+}
+
+// Re-export for convenience when the handler only needs the table ensure.
+export { ensureHwmTable, readHwm, writeHwm, dropHwm };

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

@@ -0,0 +1,79 @@
+/**
+ * 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; advisoryChannel?: boolean },
+	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 } : {}),
+	});
+
+	// Advisory is dashboard-only (events tab + log). No user-visible message —
+	// 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.`,
+		);
+	}
+}