pi-mega-compact 0.11.2 → 0.11.4

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

@@ -12,32 +12,84 @@
  * poisoned, choose transient (bounded by R1 dedup + R2 session cap).
  */
 
-/** 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).
+/** 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.
  *
- * @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):
+ *  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: string): boolean {
+	return KNOWN_RETRYABLE_TRANSIENT_PATTERN.test(text.toLowerCase());
+}
+
+/** 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') {
@@ -48,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) {
@@ -64,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;
@@ -76,124 +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';
-	}
-	// --- 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: 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 };
+	}
 	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: unknown):
+	| 'transient'
+	| 'permanent'
+	| 'compaction-noop'
+	| 'context-overflow'
+	| 'cancelled'
+	| 'poisoned-context'
+	| null {
+	return classifyErrorDetailed(message).category;
 }
 
 /** S38.2: exponential backoff for error-retry nudges.
@@ -216,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;
@@ -243,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-snapshot.ts

@@ -20,20 +20,25 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { join } from "node:path";
 import {
-	VectorStore,
+	type VectorStore,
 	vectorStats,
 	vectorRepoStats,
 	vectorDataInvariant,
 } from "../../src/vectorStore.js";
 import {
 	latestModelSnapshot,
+	readLatestCacheHitPct,
 	recordPerfSample,
 	recordSessionHeartbeat,
 	appendTokenSample,
 	type GameState,
 } from "../../src/store/sqlite.js";
-import { resolveRepoRoot, type MegaConfig, type PressureBand } from "../mega-config.js";
-import { Dashboard } from "../mega-dashboard.js";
+import {
+	resolveRepoRoot,
+	type MegaConfig,
+	type PressureBand,
+} from "../mega-config.js";
+import type { Dashboard } from "../mega-dashboard.js";
 import type { WidgetData } from "./widget.js";
 import { computeMegaSnapshot } from "./snapshot.js";
 import { buildDashboardSnapshot } from "./dashboard-snapshot.js";
@@ -93,7 +98,10 @@ export interface RuntimeSnapshotContext extends RuntimeHelpersContext {
 /** Collect live state and write it to disk (+ paint the above-editor widget).
  *  Extracted verbatim from `MegaRuntime.snapshot()` (runtime.ts); the public
  *  method there is now `snapshotImpl(this, ctx)`. */
-export function snapshotImpl(self: RuntimeSnapshotContext, ctx?: ExtensionContext): void {
+export function snapshotImpl(
+	self: RuntimeSnapshotContext,
+	ctx?: ExtensionContext,
+): void {
 	if (ctx) self.lastWidgetCtx = ctx;
 	if (ctx) self.bindRepo(ctx.cwd);
 	// v0.8.5: gate the expensive body (6 sync SQLite opens +
@@ -179,7 +187,8 @@ export function snapshotImpl(self: RuntimeSnapshotContext, ctx?: ExtensionContex
 	// try/catch mirrors the recordPerfSample pattern below. Skip the token
 	// sample when lastCtxTokens is null (no context data yet).
 	try {
-		const repo = resolveRepoRoot(ctx?.cwd ?? self.currentStateDir) ?? self.currentStateDir;
+		const repo =
+			resolveRepoRoot(ctx?.cwd ?? self.currentStateDir) ?? self.currentStateDir;
 		recordSessionHeartbeat(
 			process.pid,
 			self.rt.sessionId,
@@ -194,7 +203,7 @@ export function snapshotImpl(self: RuntimeSnapshotContext, ctx?: ExtensionContex
 				self.lastCtxTokens,
 				self.lastCtxPercent ?? 0,
 				self.lastCtxWindow || 0,
-			join(self.currentStateDir, "events.log"),
+				join(self.currentStateDir, "events.log"),
 			);
 		}
 	} catch {
@@ -217,6 +226,15 @@ export function snapshotImpl(self: RuntimeSnapshotContext, ctx?: ExtensionContex
 		}
 		// ── gather widget data (computed per snapshot, rendered per frame) ────
 		const modelSnap = latestModelSnapshot(self.currentStateDir);
+		// Provider prompt cache hit % for the widget (B/C): latest
+		// cache_hit_pct sample. Non-fatal — one extra sync open per
+		// material-change-gated recompute, acceptably cheap.
+		let providerCachePct = 0;
+		try {
+			providerCachePct = readLatestCacheHitPct(self.currentStateDir);
+		} catch {
+			/* non-fatal */
+		}
 		const _snapResult = computeMegaSnapshot({
 			lastCtxTokens: self.lastCtxTokens,
 			lastCtxWindow: self.lastCtxWindow,
@@ -248,6 +266,7 @@ export function snapshotImpl(self: RuntimeSnapshotContext, ctx?: ExtensionContex
 			ready,
 			armed,
 			modelSnap,
+			providerCachePct,
 		});
 		self.widgetData = _snapResult.widgetData;
 		// S33: consume the flare after copying it into widgetData so it fires
@@ -271,8 +290,7 @@ export function snapshotImpl(self: RuntimeSnapshotContext, ctx?: ExtensionContex
 		// free the slot and prevent a stale effect lingering between snapshots.
 		if (
 			self.activeEffect &&
-			Date.now() - self.activeEffect.startedAt >=
-				self.activeEffect.durationMs
+			Date.now() - self.activeEffect.startedAt >= self.activeEffect.durationMs
 		) {
 			self.activeEffect = null;
 		}
@@ -284,7 +302,11 @@ export function snapshotImpl(self: RuntimeSnapshotContext, ctx?: ExtensionContex
 	// v0.8.5: record the material-change signature computed at the top so the
 	// next snapshot() can skip this whole body when nothing material changed.
 	try {
-		recordPerfSample(self.currentStateDir, "db_recompute_ms", performance.now() - perfT0);
+		recordPerfSample(
+			self.currentStateDir,
+			"db_recompute_ms",
+			performance.now() - perfT0,
+		);
 		recordPerfSample(self.currentStateDir, "disk_write_ms", perfDiskMs);
 	} catch {
 		/* non-fatal: perf instrumentation never blocks the agent */

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,
 	};