pi-mega-compact 0.8.16 → 0.8.17

package/README.md

@@ -80,7 +80,7 @@ Detailed architecture: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
 
 ```bash
 npm run build     # TypeScript compile
-npm test          # Build + 353 tests
+npm test          # Build + 609 tests
 npm run lint      # Type check + guardrails scan
 ```
 

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

@@ -179,6 +179,39 @@ test("S38: classifyError returns 'compaction-noop' for 'Auto compaction failed'
     assert.equal(classifyErrorFn("Auto compaction failed"), "compaction-noop");
     assert.equal(classifyErrorFn("Auto-compaction failed"), "compaction-noop");
 });
+// ---- context-overflow classifier (S38.8: 400 "too long... even after compaction") ----
+test("S38: classifyError returns 'context-overflow' for the literal user 400 string", () => {
+    assert.equal(classifyErrorFn("Your conversation is too long for this model's context window even after compaction. Reduce the conversation length or enable/allow compaction."), "context-overflow");
+});
+test("S38: classifyError returns 'context-overflow' for 'All targets failed' wrapper", () => {
+    assert.equal(classifyErrorFn("All targets failed: ... Last error: ... too long ... context window even after compaction"), "context-overflow");
+});
+test("S38: classifyError returns 'context-overflow' for invalid_request_error JSON shape", () => {
+    assert.equal(classifyErrorFn('{"type":"invalid_request_error","message":"... too long for context window ..."}'), "context-overflow");
+});
+test("S38: classifyError returns 'context-overflow' for OpenRouter 'All targets failed' max-context 400 (FAIL-20260725)", () => {
+    // Regression: the OpenAI/OpenRouter provider-side phrasing
+    // "maximum context length is N tokens ... requires at least M tokens ...
+    // reduce your input or max_tokens" does NOT contain "too long" / "context
+    // window" / "reduce the conversation", so it slipped past the original S38.8
+    // regex and fell through to the generic transient branch, firing 5 blind
+    // retry nudges that re-submitted the same oversized prompt -> re-400 ->
+    // busy-loop. The exact user-facing wrapper string from the router:
+    assert.equal(classifyErrorFn('Error: 400: {"message":"All targets failed: neuralwatt/glm-5.2-short. Last error: This model\'s maximum context length is 200000 tokens. Your request requires at least 201070 tokens (201070 prompt + 0 max_tokens). Please reduce your input or max_tokens.","type":"invalid_request_error"}'), "context-overflow");
+});
+test("S38: classifyError returns 'context-overflow' for bare 'maximum context length' phrasing", () => {
+    assert.equal(classifyErrorFn("This model's maximum context length is 128000 tokens. Your request requires at least 130000 tokens. Please reduce your input or max_tokens."), "context-overflow");
+});
+test("S38: classifyError returns 'context-overflow' for 'context length exceeded' phrasing", () => {
+    assert.equal(classifyErrorFn("This model's context length exceeded: 200000 tokens"), "context-overflow");
+});
+test("S38: context-overflow fires NO blind retry nudge and logs 'context_overflow'", async () => {
+    const h = harness();
+    await s38TurnEnd(h, "error", "Your conversation is too long for this model's context window even after compaction. Reduce the conversation length or enable/allow compaction.");
+    const ev = eventTypes(h.stateDir);
+    assert.equal(h.sendUserMessages.length, 0, "context-overflow: NO blind retry nudge fired");
+    assert.ok(ev.includes("context_overflow"), "context-overflow: 'context_overflow' event logged");
+});
 // ---- integration tests (fire turn_end through the real extension) ----
 test("S38: compaction-noop logs 'compaction_noop_diagnostic' + resets counter + no retry fired", async () => {
     const h = harness();

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

@@ -5,6 +5,7 @@ import { evaluateAndUnlockAchievements } from "../../src/store/sqlite/game-achie
 import { isMegaCache } from "../../src/game/scoring.js";
 import { resolveRepoRoot } from "../mega-config.js";
 import { classifyError } from "./error-classifier.js";
+import { safeSendUserMessage } from "./send-safe.js";
 /** Register agent/turn tracking event handlers. */
 export function registerAgentHandlers(pi, runtime, config) {
     // ---- Agent tracking for real-time widget + status-line updates ---------
@@ -188,7 +189,7 @@ export function registerAgentHandlers(pi, runtime, config) {
                     const nudgeMsg = lengthStop && !didDurableTrim
                         ? "[mega-compact] the last response hit the output-token cap; continue from where it stopped."
                         : "[mega-compact] continue from the compacted context above.";
-                    pi.sendUserMessage(nudgeMsg);
+                    await safeSendUserMessage(pi, nudgeMsg);
                 }
             }
             catch {
@@ -312,6 +313,53 @@ export function registerAgentHandlers(pi, runtime, config) {
                         turnIndex: event.turnIndex,
                     });
                 }
+                else if (category === 'context-overflow') {
+                    // (4b) context-window overflow 400 ("too long... even after compaction").
+                    // NOT a blind retry: re-submitting the same oversized prompt would just
+                    // re-400 and busy-loop. Reset the counters (this turn is terminal, not
+                    // retryable in the S38 sense) and force ONE best-effort re-compact with
+                    // the debounce bypassed + the same race-guard (lastNativeCompactAt
+                    // cooldown + deferred setTimeout re-check) as the agent_end durable
+                    // trim. Resume after that forced compact is handled by the existing
+                    // nudgeResume() inside session_before_compact (it fires after
+                    // driveNativeCompaction supplies the compaction) — do NOT add a
+                    // separate nudge here.
+                    runtime.rt.errorRetryCount = 0;
+                    runtime.rt.consecutiveErrors = 0;
+                    runtime.dashboard.event('context_overflow', {
+                        turnIndex: event.turnIndex,
+                        sessionId: runtime.rt.sessionId,
+                    });
+                    runtime.logger.warn('context-overflow', {
+                        sessionId: runtime.rt.sessionId,
+                        turnIndex: event.turnIndex,
+                    });
+                    if (config.auto) {
+                        const now2 = Date.now();
+                        const cooldownMs2 = config.raceGuardStrict ? 30_000 : 10_000;
+                        const sinceCompact2 = now2 - (runtime.rt.lastNativeCompactAt ?? 0);
+                        if (sinceCompact2 >= cooldownMs2 && !piCompactWouldNoop(ctx)) {
+                            runtime.debounceUntil = now2 + 0;
+                            const stamp2 = runtime.rt.lastNativeCompactAt;
+                            const liveSid2 = runtime.rt.sessionId;
+                            setTimeout(() => {
+                                try {
+                                    if (runtime.rt.sessionId !== liveSid2)
+                                        return; // session reset
+                                    const since3 = Date.now() - (runtime.rt.lastNativeCompactAt ?? 0);
+                                    if (runtime.rt.lastNativeCompactAt !== stamp2 && since3 < cooldownMs2)
+                                        return;
+                                    if (piCompactWouldNoop(ctx))
+                                        return;
+                                    ctx.compact({ customInstructions: undefined }); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; deferred + re-validated. Forced re-compact after a context-overflow 400.
+                                }
+                                catch {
+                                    /* non-fatal */
+                                }
+                            }, 500);
+                        }
+                    }
+                }
                 else {
                     // (5) transient or permanent — retry with exponential backoff.
                     // S38.7: hard-stop switch — bypass ALL retry logic when set.
@@ -388,8 +436,8 @@ export function registerAgentHandlers(pi, runtime, config) {
                                 count: runtime.rt.errorRetryCount,
                                 max,
                             });
-                            // PREVENT-PI-003: user-role sendUserMessage only.
-                            pi.sendUserMessage('[mega-compact] the last turn ended with an error; please retry.');
+                            // PREVENT-PI-003: user-role sendUserMessage only (queued + catch-guarded).
+                            await safeSendUserMessage(pi, '[mega-compact] the last turn ended with an error; please retry.');
                         }
                     }
                 }

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

@@ -3,6 +3,7 @@ import { estimateBlockTokens } from "../../src/tokens.js";
 import { recordScore, getDedupStats } from "../../src/store/sqlite.js";
 import { evaluateAndUnlockAchievements } from "../../src/store/sqlite/game-achievements.js";
 import { resolveRepoRoot } from "../mega-config.js";
+import { safeSendUserMessage } from "./send-safe.js";
 /**
  * Build a minimal fallback compaction so pi never runs its throwing compact().
  *
@@ -34,13 +35,18 @@ function fallbackCompaction(event) {
 /**
  * Debounced resume-nudge: restart the agent loop after a compaction (which
  * may have stopped it). Idempotent — one nudge per 30s, never blocks.
+ *
+ * Uses safeSendUserMessage ({ deliverAs: 'followUp' } + catch-guard) so that a
+ * nudge fired during session_before_compact (which is mid-prompt-submission,
+ * so the agent can be busy) QUEUES instead of throwing
+ * "Agent is already processing. Specify streamingBehavior (steer or followUp)".
  */
-function nudgeResume(pi, runtime) {
+async function nudgeResume(pi, runtime) {
     try {
         const now = Date.now();
         if (now >= runtime.resumeNudgeUntil) {
             runtime.resumeNudgeUntil = now + 30_000;
-            pi.sendUserMessage("[mega-compact] continue from the compacted context above.");
+            await safeSendUserMessage(pi, "[mega-compact] continue from the compacted context above.");
         }
     }
     catch {
@@ -83,7 +89,7 @@ export function registerCompactHandlers(pi, runtime, config) {
                     tokensBefore: result.compaction.tokensBefore,
                     summaryTokens: result.compaction.estimatedTokensAfter,
                 });
-                nudgeResume(pi, runtime);
+                await nudgeResume(pi, runtime);
                 return { compaction: result.compaction };
             }
             // FIX "compacts but doesn't resume" + "Nothing to compact" regression:
@@ -104,7 +110,7 @@ export function registerCompactHandlers(pi, runtime, config) {
                     tokensBefore: fb.compaction.tokensBefore,
                     reason: event.reason,
                 });
-                nudgeResume(pi, runtime);
+                await nudgeResume(pi, runtime);
                 return { compaction: fb.compaction };
             }
         }

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

@@ -11,7 +11,7 @@
  * 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' | null (success/unknown)
+ * @returns 'transient' | 'permanent' | 'compaction-noop' | 'context-overflow' | null (success/unknown)
  */
 export function classifyError(message) {
     // Resolve a searchable text blob from a pi AgentMessage or raw string.
@@ -84,6 +84,29 @@ export function classifyError(message) {
         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 (/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 (retryable) ---
     if (s.includes('error') && !/\b(permanent|invalid request|malformed|bad request|auth|unauthorized|invalid (api )?key|permission)\b/.test(s)) {
         return 'transient'; // generic pi stopReason 'error' / 'aborted'

package/dist/extensions/mega-events/send-safe.js

@@ -0,0 +1,12 @@
+/**
+ * safeSendUserMessage — await + catch-guard + queue-safe wrapper for
+ * pi.sendUserMessage. Never throws; never produces an unhandled rejection.
+ */
+export async function safeSendUserMessage(pi, content) {
+    try {
+        await pi.sendUserMessage(content, { deliverAs: "followUp" });
+    }
+    catch {
+        /* non-fatal: a failed/queued nudge never blocks the agent loop */
+    }
+}

package/dist/extensions/mega-events.js

@@ -17,3 +17,4 @@ export * from "./mega-events/context-handler.js";
 export * from "./mega-events/compact-handlers.js";
 export * from "./mega-events/perf-handler.js";
 export * from "./mega-events/error-classifier.js";
+export * from "./mega-events/send-safe.js";

package/extensions/mega-compact-s38.test.ts

@@ -191,6 +191,69 @@ test("S38: classifyError returns 'compaction-noop' for 'Auto compaction failed'
 	assert.equal(classifyErrorFn("Auto-compaction failed"), "compaction-noop");
 });
 
+// ---- context-overflow classifier (S38.8: 400 "too long... even after compaction") ----
+
+test("S38: classifyError returns 'context-overflow' for the literal user 400 string", () => {
+	assert.equal(
+		classifyErrorFn("Your conversation is too long for this model's context window even after compaction. Reduce the conversation length or enable/allow compaction."),
+		"context-overflow",
+	);
+});
+
+test("S38: classifyError returns 'context-overflow' for 'All targets failed' wrapper", () => {
+	assert.equal(
+		classifyErrorFn("All targets failed: ... Last error: ... too long ... context window even after compaction"),
+		"context-overflow",
+	);
+});
+
+test("S38: classifyError returns 'context-overflow' for invalid_request_error JSON shape", () => {
+	assert.equal(
+		classifyErrorFn('{"type":"invalid_request_error","message":"... too long for context window ..."}'),
+		"context-overflow",
+	);
+});
+
+test("S38: classifyError returns 'context-overflow' for OpenRouter 'All targets failed' max-context 400 (FAIL-20260725)", () => {
+	// Regression: the OpenAI/OpenRouter provider-side phrasing
+	// "maximum context length is N tokens ... requires at least M tokens ...
+	// reduce your input or max_tokens" does NOT contain "too long" / "context
+	// window" / "reduce the conversation", so it slipped past the original S38.8
+	// regex and fell through to the generic transient branch, firing 5 blind
+	// retry nudges that re-submitted the same oversized prompt -> re-400 ->
+	// busy-loop. The exact user-facing wrapper string from the router:
+	assert.equal(
+		classifyErrorFn('Error: 400: {"message":"All targets failed: neuralwatt/glm-5.2-short. Last error: This model\'s maximum context length is 200000 tokens. Your request requires at least 201070 tokens (201070 prompt + 0 max_tokens). Please reduce your input or max_tokens.","type":"invalid_request_error"}'),
+		"context-overflow",
+	);
+});
+
+test("S38: classifyError returns 'context-overflow' for bare 'maximum context length' phrasing", () => {
+	assert.equal(
+		classifyErrorFn("This model's maximum context length is 128000 tokens. Your request requires at least 130000 tokens. Please reduce your input or max_tokens."),
+		"context-overflow",
+	);
+});
+
+test("S38: classifyError returns 'context-overflow' for 'context length exceeded' phrasing", () => {
+	assert.equal(
+		classifyErrorFn("This model's context length exceeded: 200000 tokens"),
+		"context-overflow",
+	);
+});
+
+test("S38: context-overflow fires NO blind retry nudge and logs 'context_overflow'", async () => {
+	const h = harness();
+	await s38TurnEnd(
+		h,
+		"error",
+		"Your conversation is too long for this model's context window even after compaction. Reduce the conversation length or enable/allow compaction.",
+	);
+	const ev = eventTypes(h.stateDir);
+	assert.equal(h.sendUserMessages.length, 0, "context-overflow: NO blind retry nudge fired");
+	assert.ok(ev.includes("context_overflow"), "context-overflow: 'context_overflow' event logged");
+});
+
 // ---- integration tests (fire turn_end through the real extension) ----
 
 test("S38: compaction-noop logs 'compaction_noop_diagnostic' + resets counter + no retry fired", async () => {

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

@@ -19,6 +19,7 @@ import { evaluateAndUnlockAchievements } from "../../src/store/sqlite/game-achie
 import { isMegaCache } from "../../src/game/scoring.js";
 import { resolveRepoRoot } from "../mega-config.js";
 import { classifyError } from "./error-classifier.js";
+import { safeSendUserMessage } from "./send-safe.js";
 
 /** Register agent/turn tracking event handlers. */
 export function registerAgentHandlers(
@@ -215,7 +216,7 @@ export function registerAgentHandlers(
 					const nudgeMsg = lengthStop && !didDurableTrim
 						? "[mega-compact] the last response hit the output-token cap; continue from where it stopped."
 						: "[mega-compact] continue from the compacted context above.";
-					pi.sendUserMessage(nudgeMsg);
+					await safeSendUserMessage(pi, nudgeMsg);
 				}
 			} catch {
 				/* non-fatal: a failed nudge never blocks */
@@ -346,6 +347,48 @@ export function registerAgentHandlers(
 						sessionId: runtime.rt.sessionId,
 						turnIndex: event.turnIndex,
 					});
+				} else if (category === 'context-overflow') {
+					// (4b) context-window overflow 400 ("too long... even after compaction").
+					// NOT a blind retry: re-submitting the same oversized prompt would just
+					// re-400 and busy-loop. Reset the counters (this turn is terminal, not
+					// retryable in the S38 sense) and force ONE best-effort re-compact with
+					// the debounce bypassed + the same race-guard (lastNativeCompactAt
+					// cooldown + deferred setTimeout re-check) as the agent_end durable
+					// trim. Resume after that forced compact is handled by the existing
+					// nudgeResume() inside session_before_compact (it fires after
+					// driveNativeCompaction supplies the compaction) — do NOT add a
+					// separate nudge here.
+					runtime.rt.errorRetryCount = 0;
+					runtime.rt.consecutiveErrors = 0;
+					runtime.dashboard.event('context_overflow', {
+						turnIndex: event.turnIndex,
+						sessionId: runtime.rt.sessionId,
+					});
+					runtime.logger.warn('context-overflow', {
+						sessionId: runtime.rt.sessionId,
+						turnIndex: event.turnIndex,
+					});
+					if (config.auto) {
+						const now2 = Date.now();
+						const cooldownMs2 = config.raceGuardStrict ? 30_000 : 10_000;
+						const sinceCompact2 = now2 - (runtime.rt.lastNativeCompactAt ?? 0);
+						if (sinceCompact2 >= cooldownMs2 && !piCompactWouldNoop(ctx)) {
+							runtime.debounceUntil = now2 + 0;
+							const stamp2 = runtime.rt.lastNativeCompactAt;
+							const liveSid2 = runtime.rt.sessionId;
+							setTimeout(() => {
+								try {
+									if (runtime.rt.sessionId !== liveSid2) return; // session reset
+									const since3 = Date.now() - (runtime.rt.lastNativeCompactAt ?? 0);
+									if (runtime.rt.lastNativeCompactAt !== stamp2 && since3 < cooldownMs2) return;
+									if (piCompactWouldNoop(ctx)) return;
+									ctx.compact({ customInstructions: undefined }); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; deferred + re-validated. Forced re-compact after a context-overflow 400.
+								} catch {
+									/* non-fatal */
+								}
+							}, 500);
+						}
+					}
 				} else {
 					// (5) transient or permanent — retry with exponential backoff.
 					// S38.7: hard-stop switch — bypass ALL retry logic when set.
@@ -421,8 +464,9 @@ export function registerAgentHandlers(
 									count: runtime.rt.errorRetryCount,
 									max,
 								});
-								// PREVENT-PI-003: user-role sendUserMessage only.
-								pi.sendUserMessage(
+								// PREVENT-PI-003: user-role sendUserMessage only (queued + catch-guarded).
+								await safeSendUserMessage(
+									pi,
 									'[mega-compact] the last turn ended with an error; please retry.',
 								);
 							}

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

@@ -22,6 +22,7 @@ import type { MegaConfig } from "../mega-config.js";
 import { recordScore, getDedupStats } from "../../src/store/sqlite.js";
 import { evaluateAndUnlockAchievements } from "../../src/store/sqlite/game-achievements.js";
 import { resolveRepoRoot } from "../mega-config.js";
+import { safeSendUserMessage } from "./send-safe.js";
 
 /**
  * Build a minimal fallback compaction so pi never runs its throwing compact().
@@ -57,13 +58,19 @@ function fallbackCompaction(
 /**
  * Debounced resume-nudge: restart the agent loop after a compaction (which
  * may have stopped it). Idempotent — one nudge per 30s, never blocks.
+ *
+ * Uses safeSendUserMessage ({ deliverAs: 'followUp' } + catch-guard) so that a
+ * nudge fired during session_before_compact (which is mid-prompt-submission,
+ * so the agent can be busy) QUEUES instead of throwing
+ * "Agent is already processing. Specify streamingBehavior (steer or followUp)".
  */
-function nudgeResume(pi: ExtensionAPI, runtime: MegaRuntime): void {
+async function nudgeResume(pi: ExtensionAPI, runtime: MegaRuntime): Promise<void> {
 	try {
 		const now = Date.now();
 		if (now >= runtime.resumeNudgeUntil) {
 			runtime.resumeNudgeUntil = now + 30_000;
-			pi.sendUserMessage(
+			await safeSendUserMessage(
+				pi,
 				"[mega-compact] continue from the compacted context above.",
 			);
 		}
@@ -113,7 +120,7 @@ export function registerCompactHandlers(
 						tokensBefore: result.compaction.tokensBefore,
 						summaryTokens: result.compaction.estimatedTokensAfter,
 					});
-					nudgeResume(pi, runtime);
+					await nudgeResume(pi, runtime);
 					return { compaction: result.compaction };
 				}
 				// FIX "compacts but doesn't resume" + "Nothing to compact" regression:
@@ -134,7 +141,7 @@ export function registerCompactHandlers(
 						tokensBefore: fb.compaction.tokensBefore,
 						reason: event.reason,
 					});
-					nudgeResume(pi, runtime);
+					await nudgeResume(pi, runtime);
 					return { compaction: fb.compaction };
 				}
 			} catch (err) {

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

@@ -12,12 +12,13 @@
  * 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' | null (success/unknown)
+ * @returns 'transient' | 'permanent' | 'compaction-noop' | 'context-overflow' | null (success/unknown)
  */
 export function classifyError(message: unknown):
 	| 'transient'
 	| 'permanent'
 	| 'compaction-noop'
+	| 'context-overflow'
 	| null {
 	// Resolve a searchable text blob from a pi AgentMessage or raw string.
 	let text = '';
@@ -81,6 +82,29 @@ export function classifyError(message: unknown):
 	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 (/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 (retryable) ---
 	if (s.includes('error') && !/\b(permanent|invalid request|malformed|bad request|auth|unauthorized|invalid (api )?key|permission)\b/.test(s)) {
 		return 'transient'; // generic pi stopReason 'error' / 'aborted'

package/extensions/mega-events/send-safe.ts

@@ -0,0 +1,37 @@
+/**
+ * send-safe.ts — queue-safe wrapper for pi.sendUserMessage.
+ *
+ * All extension-initiated user-role nudges (resume after compaction, length-stop
+ * continue, error-retry) MUST go through this wrapper. It:
+ *   1. Passes { deliverAs: 'followUp' } so that when the agent is busy (e.g. a
+ *      resume nudge fired during session_before_compact, which is mid-prompt
+ *      submission) pi QUEUES the message instead of throwing
+ *      "Agent is already processing. Specify streamingBehavior (steer or
+ *      followUp) to queue the message" (pi agent-session.js:830).
+ *   2. Awaits the call and catch-guards it so a failed/queued nudge never throws
+ *      or produces an unhandled rejection — it must never block the agent loop.
+ *
+ * PREVENT-PI-003: user-role sendUserMessage only (no role:'system' injection).
+ * PREVENT-PI-004: local pi ctx call, no network.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/**
+ * safeSendUserMessage — await + catch-guard + queue-safe wrapper for
+ * pi.sendUserMessage. Never throws; never produces an unhandled rejection.
+ */
+export async function safeSendUserMessage(
+	pi: ExtensionAPI,
+	content: string,
+): Promise<void> {
+	try {
+		await (
+			pi.sendUserMessage as (
+				c: string,
+				o?: { deliverAs?: "steer" | "followUp" },
+			) => Promise<void> | void
+		)(content, { deliverAs: "followUp" });
+	} catch {
+		/* non-fatal: a failed/queued nudge never blocks the agent loop */
+	}
+}

package/extensions/mega-events.ts

@@ -17,3 +17,4 @@ export * from "./mega-events/context-handler.js";
 export * from "./mega-events/compact-handlers.js";
 export * from "./mega-events/perf-handler.js";
 export * from "./mega-events/error-classifier.js";
+export * from "./mega-events/send-safe.js";

package/package.json

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