pi-mega-compact 0.8.14 → 0.8.16

package/dist/extensions/dashboard-client/src/hooks/useSSE.js

@@ -0,0 +1,63 @@
+/**
+ * dashboard-client/src/hooks/useSSE.ts — Server-Sent Events hook.
+ *
+ * Connects to /api/events, provides real-time event stream.
+ * SPRINT-B1: basic connection. SPRINT-D1: reconnect with backoff.
+ */
+import { useState, useEffect, useRef, useCallback } from 'react';
+// SPRINT-D1-REMAINING: exponential backoff (1s → 2s → 4s → max 30s).
+// SPRINT-D1-REMAINING: after 5 failures, set status='disconnected'.
+export function useSSE(options = {}) {
+    const { maxEvents = 500, maxReconnects = 5 } = options;
+    const [events, setEvents] = useState([]);
+    const [status, setStatus] = useState('connecting');
+    const [eventCount, setEventCount] = useState(0);
+    const [lastEventAt, setLastEventAt] = useState(null);
+    const reconnectCount = useRef(0);
+    const sourceRef = useRef(null);
+    const connect = useCallback(() => {
+        if (sourceRef.current) {
+            sourceRef.current.close();
+        }
+        setStatus('connecting');
+        const source = new EventSource('/api/events');
+        sourceRef.current = source;
+        source.onopen = () => {
+            setStatus('connected');
+            reconnectCount.current = 0;
+        };
+        source.onmessage = (event) => {
+            try {
+                const parsed = JSON.parse(event.data);
+                setEvents(prev => {
+                    const next = [...prev, parsed];
+                    return next.length > maxEvents ? next.slice(-maxEvents) : next;
+                });
+                setEventCount(c => c + 1);
+                setLastEventAt(Date.now());
+            }
+            catch {
+                // non-fatal: skip malformed events
+            }
+        };
+        source.onerror = () => {
+            source.close();
+            if (reconnectCount.current < maxReconnects) {
+                reconnectCount.current += 1;
+                setStatus('connecting');
+                // SPRINT-D1: use exponential backoff instead of fixed delay
+                setTimeout(connect, 1000);
+            }
+            else {
+                setStatus('disconnected');
+            }
+        };
+    }, [maxEvents, maxReconnects]);
+    useEffect(() => {
+        connect();
+        return () => {
+            sourceRef.current?.close();
+        };
+    }, [connect]);
+    return { events, status, eventCount, lastEventAt };
+}

package/dist/extensions/dashboard-server/html.js

@@ -176,8 +176,8 @@ export function dashboardHtml(tierName) {
 
 <div class="settings-strip">
   <label title="Turn game mode on/off (themes the widget + dashboard)"><input type="checkbox" id="set-game-mode"> Game mode</label>
-  <label title="Visual theme (applies instantly)">Theme <select id="set-theme">${THEME_OPTIONS}</select></label>
-  <label title="TUI widget display density">TUI <select id="set-tui-mode"><option value="full">Full</option><option value="minimal">Minimal</option></select></label>
+  <label title="Visual theme (applies instantly)">Theme <select id="set-theme">${THEME_OPTIONS}</select> <button type="button" id="set-theme-next" title="Cycle to the next theme (P3)">Next theme →</button></label>
+  <label title="TUI widget display density">TUI <select id="set-tui-mode"><option value="full">Full</option><option value="minimal">Minimal</option></select> <span class="tui-mode-hint">(affects the in-app TUI widget; not shown here)</span></label>
 </div>
 
 <nav class="tabs">
@@ -869,6 +869,19 @@ export function dashboardHtml(tierName) {
   }
   if (gmCheckbox) gmCheckbox.addEventListener('change', function() { putGameState({ game_mode_on: gmCheckbox.checked }); });
   if (gmTheme) gmTheme.addEventListener('change', function() { putGameState({ theme: gmTheme.value }); });
+  // P3: client-side theme cycling (no new endpoint). Reads the already-fetched
+  // <option> values from the theme select, so it stays in sync with the server's
+  // THEMES list without a second fetch.
+  var gmThemeNext = document.getElementById('set-theme-next');
+  if (gmThemeNext) gmThemeNext.addEventListener('click', function() {
+    var opts = gmTheme ? gmTheme.options : [];
+    var n = opts.length;
+    var cur = gmTheme ? gmTheme.value : 'transparent';
+    var idx = -1;
+    for (var i = 0; i < n; i++) { if (opts[i].value === cur) { idx = i; break; } }
+    var next = n > 0 ? opts[(idx < 0 ? 0 : (idx + 1) % n)].value : 'transparent';
+    putGameState({ theme: next });
+  });
   if (gmTui) gmTui.addEventListener('change', function() { putGameState({ tui_display_mode: gmTui.value }); });
   pollGameState();
   setInterval(pollGameState, 5000);

package/dist/extensions/mega-cache-replay.test.js

@@ -96,7 +96,8 @@ function harness() {
         };
     }
     const pi = {
-        on: (ev, h) => { handlers[ev] = h; },
+        on: (ev, h) => { if (!handlers[ev])
+            handlers[ev] = []; handlers[ev].push(h); },
         registerCommand: () => { }, registerTool: () => { }, registerShortcut: () => { },
         registerFlag: () => { }, getFlag: () => undefined, registerMessageRenderer: () => { },
         registerEntryRenderer: () => { }, sendMessage: () => { }, sendUserMessage: () => { },
@@ -109,7 +110,8 @@ function harness() {
     const mod = require("./mega-compact.js");
     mod.default(pi);
     const { lastRuntime } = require("./mega-events.js");
-    const fire = (ev, event, ctx) => handlers[ev](event, ctx);
+    const fire = async (ev, event, ctx) => { let r; for (const h of handlers[ev] || [])
+        r = await h(event, ctx); return r; };
     return {
         stateDir, handlers, compactCalls, fire, ctx: makeCtx, usage, buildSession,
         runtime: lastRuntime, // MegaRuntime with diag* counters + rt + trimCache

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

@@ -0,0 +1,317 @@
+/**
+ * mega-compact.s38-error-retry.test.ts — S38 error-retry safety net tests.
+ *
+ * Extracted from mega-compact.test.ts so the error-retry feature has a focused,
+ * fast-isolated test file. Exercises the real extension entry through a mock pi:
+ *   - classifyError classifier (transient / permanent / compaction-noop / null)
+ *   - turn_end retry nudges (max 5 transient, max 1 permanent)
+ *   - compaction-noop DOES NOT retry (pi race guard)
+ *   - MAX=0 disables transient retries
+ *   - mid-response errors (stream died without a stopReason)
+ *   - S38.5 race-guard (strict deferred vs synchronous)
+ *
+ * The harness is duplicated from mega-compact.test.ts (per guardrails guidance to
+ * keep each test file self-contained; the harness is ~200 lines and does not
+ * warrant a shared helper module that would itself exceed the 500-line target).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createRequire } from "node:module";
+import { closeVectorIndex } from "../src/store/vectorIndex.js";
+const require = createRequire(import.meta.url);
+const baseTmp = mkdtempSync(join(tmpdir(), "mc-s38-"));
+// Isolate the machine-wide repo index so test runs never pollute the real one.
+process.env.MEGACOMPACT_INDEX_DIR = join(baseTmp, "index");
+let counter = 0;
+/** Read events.log and return an array of event type strings. */
+function eventTypes(stateDir) {
+    const { readFileSync: rf, existsSync: ex } = require("node:fs");
+    const { join: j } = require("node:path");
+    const logPath = j(stateDir, "events.log");
+    if (!ex(logPath))
+        return [];
+    const content = rf(logPath, "utf-8").trim();
+    if (content.length === 0)
+        return [];
+    return content
+        .split("\n")
+        .map((line) => { try {
+        return JSON.parse(line).type;
+    }
+    catch {
+        return undefined;
+    } })
+        .filter((t) => typeof t === "string");
+}
+/** Build a mock pi + ctx and load the extension into them. */
+function harness(opts = {}) {
+    const stateDir = join(baseTmp, `run-${counter++}`);
+    process.env.MEGACOMPACT_STATE_DIR = stateDir;
+    process.env.MEGACOMPACT_DEBUG = "true";
+    if (!opts.keepThreshold)
+        process.env.MEGACOMPACT_THRESHOLD_TOKENS = "50";
+    if (!opts.keepTier)
+        delete process.env.MEGACOMPACT_TIER;
+    process.env.MEGACOMPACT_FAST_GATE_PCT = "1";
+    const handlers = {};
+    const appended = [];
+    const sendUserMessages = [];
+    const compactCalls = [];
+    const session = [
+        { role: "user", content: "read src/vec.ts and understand the index", timestamp: 0 },
+        { role: "assistant", content: [{ type: "toolCall", name: "Read", id: "c1", arguments: {} }], api: "anthropic-messages", provider: "anthropic", model: "m", usage: { inputTokens: 1, outputTokens: 1, cacheReadTokens: 0, cacheWriteTokens: 0 }, stopReason: "tool_use", timestamp: 0 },
+        { role: "user", content: "edit src/vec.ts to add a cosine helper", timestamp: 0 },
+        { role: "assistant", content: [{ type: "toolCall", name: "Edit", id: "c1", arguments: {} }], api: "anthropic-messages", provider: "anthropic", model: "m", usage: { inputTokens: 1, outputTokens: 1, cacheReadTokens: 0, cacheWriteTokens: 0 }, stopReason: "tool_use", timestamp: 0 },
+    ];
+    const toEntry = (m, i) => ({ type: "message", id: `e${i}`, parentId: null, timestamp: String(i), message: m });
+    const sessionManager = { getSessionId: () => "sess_ext_001", getEntries: () => session.map(toEntry), getBranch: () => session.map(toEntry) };
+    function makeCtx(over = {}) {
+        return {
+            ui: { setStatus: () => { }, notify: () => { }, select: () => { }, confirm: async () => true, input: async () => "", setWidget: () => { } },
+            mode: "tui", hasUI: true, cwd: stateDir, sessionManager,
+            modelRegistry: {}, model: undefined,
+            isIdle: () => true, isProjectTrusted: () => true,
+            signal: undefined, abort: () => { }, hasPendingMessages: () => false, shutdown: () => { },
+            getContextUsage: () => ({ tokens: 200000, contextWindow: 200000, percent: 100 }),
+            compact: (opts) => {
+                compactCalls.push(opts);
+                const _sbc = handlers["session_before_compact"];
+                if (_sbc && _sbc.length)
+                    return _sbc[0]({ type: "session_before_compact", reason: "threshold", willRetry: false, signal: undefined, preparation: { firstKeptEntryId: "e2", messagesToSummarize: session.slice(0, 2), tokensBefore: 500 } }, makeCtx());
+                return undefined;
+            },
+            getSystemPrompt: () => "system base", ...over,
+        };
+    }
+    const pi = {
+        on: (ev, h) => { if (!handlers[ev])
+            handlers[ev] = []; handlers[ev].push(h); },
+        registerCommand: () => { }, registerTool: () => { }, registerShortcut: () => { },
+        registerFlag: () => { }, getFlag: () => undefined,
+        registerMessageRenderer: () => { }, registerEntryRenderer: () => { },
+        sendMessage: () => { }, sendUserMessage: (m) => { sendUserMessages.push(m); },
+        appendEntry: (t, d) => appended.push({ t, d }),
+        setSessionName: () => { }, getSessionName: () => undefined, setLabel: () => { },
+        exec: async () => ({ stdout: "", stderr: "", code: 0 }),
+        getActiveTools: () => [], getAllTools: () => { }, setActiveTools: () => { },
+        getCommands: () => [], setModel: async () => false,
+        getThinkingLevel: () => "off", setThinkingLevel: () => { },
+    };
+    const mod = require("./mega-compact.js");
+    mod.default(pi);
+    return {
+        stateDir, handlers, appended, compactCalls, sendUserMessages,
+        fire: async (ev, event, ctx) => { let r; for (const h of handlers[ev] || [])
+            r = await h(event, ctx); return r; },
+        ctx: makeCtx, session,
+    };
+}
+const { classifyError: classifyErrorFn } = require("./mega-events.js");
+/** S38 helper: fire a turn_end with a given stopReason + optional text, using a
+ *  low-pressure ctx so the durable-trim branch (ctx.compact) does NOT fire. */
+async function s38TurnEnd(h, stopReason, text) {
+    const lowCtx = h.ctx({ isIdle: () => true, hasPendingMessages: () => false, getContextUsage: () => ({ tokens: 100, contextWindow: 200000, percent: 0 }) });
+    const message = { role: "assistant" };
+    if (stopReason !== undefined)
+        message.stopReason = stopReason;
+    if (text)
+        message.content = text;
+    await h.fire("turn_end", { type: "turn_end", turnIndex: 1, message }, lowCtx);
+}
+// ---- classifier unit tests (no extension harness needed) ----
+test("S38: classifyError returns 'transient' for error/aborted stopReasons", () => {
+    assert.equal(classifyErrorFn({ stopReason: "error" }), "transient");
+    assert.equal(classifyErrorFn({ stopReason: "aborted" }), "transient");
+});
+test("S38: classifyError returns 'transient' for max-output-token text", () => {
+    assert.equal(classifyErrorFn({ stopReason: "error", content: "reached the maximum output token limit" }), "transient");
+    assert.equal(classifyErrorFn("max output token exceeded"), "transient");
+});
+test("S38: classifyError returns 'permanent' for auth/unauthorized text", () => {
+    assert.equal(classifyErrorFn("unauthorized: invalid api key"), "permanent");
+    assert.equal(classifyErrorFn("permission denied"), "permanent");
+});
+test("S38: classifyError returns null for stop/toolUse stopReasons (success)", () => {
+    assert.equal(classifyErrorFn({ stopReason: "stop" }), null);
+    assert.equal(classifyErrorFn({ stopReason: "toolUse" }), null);
+    assert.equal(classifyErrorFn({ stopReason: "tool_use" }), null);
+});
+test("S38: classifyError returns null for 'length' stopReason (S28 guard)", () => {
+    assert.equal(classifyErrorFn({ stopReason: "length" }), null);
+});
+test("S38: classifyError returns 'transient' for mid-response errors with no stopReason", () => {
+    assert.equal(classifyErrorFn({}), "transient");
+    assert.equal(classifyErrorFn({ content: [] }), "transient");
+    assert.equal(classifyErrorFn({ stopReason: undefined }), "transient");
+    assert.equal(classifyErrorFn({ stopReason: "" }), "transient");
+});
+test("S38: classifyError returns 'transient' for error objects with message field", () => {
+    assert.equal(classifyErrorFn({ error: { message: "Stream interrupted" } }), "transient");
+    assert.equal(classifyErrorFn({ error: { message: "Connection lost" } }), "transient");
+    assert.equal(classifyErrorFn({ error: { message: "500 Internal Server Error" } }), "transient");
+    assert.equal(classifyErrorFn({ error: "Connection lost" }), "transient");
+});
+test("S38: classifyError returns 'transient' for mid-response stream failures in content", () => {
+    assert.equal(classifyErrorFn({ content: [{ type: "text", text: "Processing... Error: connection reset" }] }), "transient");
+    assert.equal(classifyErrorFn({ content: [{ type: "text", text: "Here is the answer..." }], stopReason: "error" }), "transient");
+});
+test("S38: classifyError returns 'transient' for partial content with NO stopReason (stream died after emitting text)", () => {
+    // The mid-response disconnect case: provider streamed partial content then
+    // died without a stopReason. MUST be transient (retryable), NOT null.
+    assert.equal(classifyErrorFn({ role: "assistant", content: [{ type: "text", text: "partial response..." }], stopReason: undefined }), "transient");
+    assert.equal(classifyErrorFn({ role: "assistant", content: [{ type: "text", text: "Here is the start of the answer" }] }), "transient");
+    assert.equal(classifyErrorFn({ role: "assistant", content: "partial response..." }), "transient");
+});
+test("S38: classifyError returns null for success stopReasons even with empty content", () => {
+    assert.equal(classifyErrorFn({ stopReason: "stop", content: [] }), null);
+    assert.equal(classifyErrorFn({ stopReason: "tool_use", content: [] }), null);
+});
+test("S38: classifyError returns 'compaction-noop' for 'Already compacted' text", () => {
+    assert.equal(classifyErrorFn("Error: Already compacted"), "compaction-noop");
+});
+test("S38: classifyError returns 'compaction-noop' for 'Nothing to compact' text", () => {
+    assert.equal(classifyErrorFn("Nothing to compact (session too small)"), "compaction-noop");
+});
+test("S38: classifyError returns 'compaction-noop' for 'Auto compaction failed' text", () => {
+    assert.equal(classifyErrorFn("Auto compaction failed"), "compaction-noop");
+    assert.equal(classifyErrorFn("Auto-compaction failed"), "compaction-noop");
+});
+// ---- 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();
+    await s38TurnEnd(h, "error", "Already compacted");
+    const ev = eventTypes(h.stateDir);
+    assert.ok(ev.includes("compaction_noop_diagnostic"), "compaction-noop: diagnostic event logged");
+    assert.equal(h.sendUserMessages.length, 0, "compaction-noop: NO retry nudge fired");
+});
+test("S38: compaction-noop does NOT fire pi.sendUserMessage (NOT retryable)", async () => {
+    const h = harness();
+    await s38TurnEnd(h, "error", "Nothing to compact");
+    assert.equal(h.sendUserMessages.length, 0, "compaction-noop: no sendUserMessage");
+    assert.ok(eventTypes(h.stateDir).includes("compaction_noop_diagnostic"));
+});
+test("S38: retry fires up to max (5) for transient errors, then stops", async () => {
+    const h = harness();
+    for (let i = 0; i < 5; i++)
+        await s38TurnEnd(h, "error", "internal server error");
+    assert.equal(h.sendUserMessages.length, 5, "transient: 5 retry nudges (<= max 5)");
+    await s38TurnEnd(h, "error", "internal server error");
+    assert.equal(h.sendUserMessages.length, 5, "transient: exhausted -> no 6th nudge");
+    assert.ok(eventTypes(h.stateDir).includes("error_retry_exhausted"), "exhausted event logged");
+});
+test("S38: retry fires 1x for permanent errors then stops", async () => {
+    const h = harness();
+    await s38TurnEnd(h, "error", "invalid api key");
+    assert.equal(h.sendUserMessages.length, 1, "permanent: 1 retry nudge (<= max 1)");
+    await s38TurnEnd(h, "error", "invalid api key");
+    assert.equal(h.sendUserMessages.length, 1, "permanent: exhausted -> no 2nd nudge");
+    assert.ok(eventTypes(h.stateDir).includes("error_retry_exhausted"), "permanent exhausted logged");
+});
+test("S38: successful turn (stop/toolUse) resets the retry counter", async () => {
+    const h = harness();
+    await s38TurnEnd(h, "error", "5xx server error");
+    assert.equal(h.sendUserMessages.length, 1, "first transient: 1 nudge");
+    await s38TurnEnd(h, "stop");
+    await s38TurnEnd(h, "error", "5xx server error");
+    assert.equal(h.sendUserMessages.length, 2, "success reset counter -> transient fires again from count=1");
+});
+test("S38: error_retry_exhausted event logged when max exceeded", async () => {
+    const h = harness();
+    await s38TurnEnd(h, "error", "malformed bad request");
+    await s38TurnEnd(h, "error", "malformed bad request");
+    assert.ok(eventTypes(h.stateDir).includes("error_retry_exhausted"), "error_retry_exhausted logged");
+});
+test("S38: MEGACOMPACT_AUTO_RETRY_TRANSIENT_MAX=0 disables transient retries cleanly", async () => {
+    const prev = process.env.MEGACOMPACT_AUTO_RETRY_TRANSIENT_MAX;
+    process.env.MEGACOMPACT_AUTO_RETRY_TRANSIENT_MAX = "0";
+    try {
+        const h = harness();
+        await s38TurnEnd(h, "error", "network timeout");
+        assert.equal(h.sendUserMessages.length, 0, "max=0: no transient retry nudge");
+        assert.ok(!eventTypes(h.stateDir).includes("error_retry"), "max=0: no error_retry event");
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env.MEGACOMPACT_AUTO_RETRY_TRANSIENT_MAX;
+        else
+            process.env.MEGACOMPACT_AUTO_RETRY_TRANSIENT_MAX = prev;
+    }
+});
+test("S38: retry fires for mid-response errors (no stopReason — stream died silently)", async () => {
+    const h = harness();
+    const lowCtx = h.ctx({ isIdle: () => true, hasPendingMessages: () => false, getContextUsage: () => ({ tokens: 100, contextWindow: 200000, percent: 0 }) });
+    await h.fire("turn_end", { type: "turn_end", turnIndex: 1, message: { role: "assistant" } }, lowCtx);
+    assert.equal(h.sendUserMessages.length, 1, "mid-response silent failure: 1 retry nudge fired");
+    assert.ok(eventTypes(h.stateDir).includes("error_retry"), "error_retry event logged for mid-response failure");
+});
+test("S38: retry fires for error objects with message field", async () => {
+    const h = harness();
+    const lowCtx = h.ctx({ isIdle: () => true, hasPendingMessages: () => false, getContextUsage: () => ({ tokens: 100, contextWindow: 200000, percent: 0 }) });
+    await h.fire("turn_end", { type: "turn_end", turnIndex: 1, message: { role: "assistant", error: { message: "Connection reset by peer" } } }, lowCtx);
+    assert.equal(h.sendUserMessages.length, 1, "error object with message: 1 retry nudge fired");
+});
+test("S38: retry fires for partial content with no stopReason (disconnect after emitting text)", async () => {
+    // The post-resume disconnect case: provider streamed partial content then
+    // died mid-stream with NO stopReason. Must fire a retry nudge.
+    const h = harness();
+    const lowCtx = h.ctx({ isIdle: () => true, hasPendingMessages: () => false, getContextUsage: () => ({ tokens: 100, contextWindow: 200000, percent: 0 }) });
+    await h.fire("turn_end", {
+        type: "turn_end",
+        turnIndex: 1,
+        message: { role: "assistant", content: [{ type: "text", text: "Here is the start of the answer" }], stopReason: undefined },
+    }, lowCtx);
+    assert.equal(h.sendUserMessages.length, 1, "partial-content mid-response failure: 1 retry nudge fired");
+    assert.ok(eventTypes(h.stateDir).includes("error_retry"), "error_retry event logged for partial-content failure");
+});
+// ---- S38.5: race-guard strengthening (cooldown 10s->30s + deferred re-check) ---
+test("S38.5: MEGACOMPACT_RACE_GUARD_STRICT=false reverts to synchronous 10s guard", async () => {
+    const prev = process.env.MEGACOMPACT_RACE_GUARD_STRICT;
+    const prevFloor = process.env.MEGACOMPACT_DURABLE_TRIM_FLOOR;
+    process.env.MEGACOMPACT_RACE_GUARD_STRICT = "false";
+    process.env.MEGACOMPACT_DURABLE_TRIM_FLOOR = "0";
+    try {
+        const h = harness();
+        const hiCtx = h.ctx({ isIdle: () => true, hasPendingMessages: () => false, getContextUsage: () => ({ tokens: 200000, contextWindow: 200000, percent: 100 }) });
+        await h.fire("agent_end", { type: "agent_end", messages: [] }, hiCtx);
+        assert.ok(h.compactCalls.length >= 1, "non-strict: synchronous ctx.compact() fired");
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env.MEGACOMPACT_RACE_GUARD_STRICT;
+        else
+            process.env.MEGACOMPACT_RACE_GUARD_STRICT = prev;
+        if (prevFloor === undefined)
+            delete process.env.MEGACOMPACT_DURABLE_TRIM_FLOOR;
+        else
+            process.env.MEGACOMPACT_DURABLE_TRIM_FLOOR = prevFloor;
+    }
+});
+test("S38.5: strict (default) defers ctx.compact() via setTimeout re-check", async () => {
+    const prevFloor = process.env.MEGACOMPACT_DURABLE_TRIM_FLOOR;
+    process.env.MEGACOMPACT_DURABLE_TRIM_FLOOR = "0";
+    try {
+        const h = harness();
+        const hiCtx = h.ctx({ isIdle: () => true, hasPendingMessages: () => false, getContextUsage: () => ({ tokens: 200000, contextWindow: 200000, percent: 100 }) });
+        await h.fire("agent_end", { type: "agent_end", messages: [] }, hiCtx);
+        assert.equal(h.compactCalls.length, 0, "strict: ctx.compact() NOT called synchronously (deferred)");
+        await new Promise((r) => setTimeout(r, 700));
+        assert.ok(h.compactCalls.length >= 1, "strict: deferred ctx.compact() fired after re-check");
+    }
+    finally {
+        if (prevFloor === undefined)
+            delete process.env.MEGACOMPACT_DURABLE_TRIM_FLOOR;
+        else
+            process.env.MEGACOMPACT_DURABLE_TRIM_FLOOR = prevFloor;
+    }
+});
+test("cleanup", async () => {
+    // PGlite WASM close can hang; race with a timeout to prevent 40-min hangs.
+    try {
+        await Promise.race([closeVectorIndex(), new Promise((r) => setTimeout(r, 3000))]);
+    }
+    catch { /* ignore */ }
+    rmSync(baseTmp, { recursive: true, force: true });
+});

package/dist/extensions/mega-compact.js

@@ -35,6 +35,20 @@ import { registerDbCommands } from "./mega-db-cmds.js";
 import { registerGameCommands } from "./mega-game-cmds.js";
 export default function (pi) {
     const config = loadConfig();
+    // S38.9: preflight env validation — check for obviously invalid values at startup.
+    // Non-fatal: log warnings and fall back to defaults.
+    if (config.autoRetryTransientMax < 0) {
+        console.warn('[mega-compact] MEGACOMPACT_AUTO_RETRY_TRANSIENT_MAX must be >= 0; using default 5');
+        config.autoRetryTransientMax = 5;
+    }
+    if (config.autoRetryPermanentMax < 0) {
+        console.warn('[mega-compact] MEGACOMPACT_AUTO_RETRY_PERMANENT_MAX must be >= 0; using default 1');
+        config.autoRetryPermanentMax = 1;
+    }
+    if (config.maxConsecutiveErrors < 1) {
+        console.warn('[mega-compact] MEGACOMPACT_MAX_CONSECUTIVE_ERRORS must be >= 1; using default 10');
+        config.maxConsecutiveErrors = 10;
+    }
     const runtime = new MegaRuntime(config);
     registerEventHandlers(pi, runtime, config);
     registerCommands(pi, runtime, config);

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

@@ -144,8 +144,9 @@ function harness(opts = {}) {
             // session_before_compact handler (where WE supply the durable trim).
             compact: (opts) => {
                 compactCalls.push(opts);
-                if (handlers["session_before_compact"]) {
-                    return handlers["session_before_compact"]({
+                const _sbc = handlers["session_before_compact"];
+                if (_sbc && _sbc.length) {
+                    return _sbc[0]({
                         type: "session_before_compact",
                         reason: "threshold",
                         willRetry: false,
@@ -167,7 +168,9 @@ function harness(opts = {}) {
     }
     const pi = {
         on: (ev, h) => {
-            handlers[ev] = h;
+            if (!handlers[ev])
+                handlers[ev] = [];
+            handlers[ev].push(h);
         },
         registerCommand: (name, opts) => {
             commands[name] = opts;
@@ -209,7 +212,8 @@ function harness(opts = {}) {
         notifies,
         compactCalls,
         sendUserMessages,
-        fire: (ev, event, ctx) => handlers[ev](event, ctx),
+        fire: async (ev, event, ctx) => { let r; for (const h of handlers[ev] || [])
+            r = await h(event, ctx); return r; },
         ctx: makeCtx,
         session,
     };
@@ -235,6 +239,11 @@ test("auto-trigger (legacy): past threshold persists a chkpt and starts a durabl
             }),
         });
         const res = await h.fire("context", { type: "context", messages }, ctx);
+        // S38.5: the strict race guard (default) defers ctx.compact() via a
+        // setTimeout(500) re-check. The synchronous return is still undefined
+        // (no local drop), but ctx.compact() only lands after the timer — wait
+        // for it before asserting the durable-trim call count.
+        await new Promise((r) => setTimeout(r, 700));
         // L1->L4 ran: a checkpoint was persisted to the SQLite store + a marker entry written.
         const { listCheckpoints } = await import("../src/store/sqlite.js");
         assert.ok(listCheckpoints("sess_ext_001", h.stateDir).length > 0, "checkpoint persisted to local vector db");
@@ -919,23 +928,36 @@ test("S28: length_stop + length_stop_continue dashboard events fire on the right
     assert.ok(afterAgentEnd.includes("length_stop_continue"), "length stop: length_stop_continue dashboard event fired on agent_end");
     assert.equal(h.sendUserMessages.length, 1, "length stop: exactly one nudge");
 });
-test("S28: non-length stopReasons do not arm the flag (no nudge, no length_stop event)", async () => {
+test("S28: non-length stopReasons do not arm the length-stop flag (no length_stop event); S38 owns error/aborted retries", async () => {
     const h = harness();
     const lowPressureCtx = h.ctx({
         isIdle: () => true,
         hasPendingMessages: () => false,
         getContextUsage: () => ({ tokens: 100, contextWindow: 200000, percent: 0 }),
     });
-    // Every other pi-ai StopReason must leave the flag unset → no nudge + no event.
+    // S28 contract: every non-length StopReason must leave lengthStopPending unset,
+    // so no length_stop event fires and no length-stop resume nudge is armed.
+    // (S38 separately owns error/aborted — it WILL fire error-retry nudges for those;
+    // this test only asserts the S28 length-stop flag is not armed.)
+    let transientRetries = 0;
     for (const stopReason of ["tool_use", "error", "aborted"]) {
+        const before = h.sendUserMessages.length;
         await h.fire("turn_end", {
             type: "turn_end",
             turnIndex: 1,
             message: { role: "assistant", stopReason },
         }, lowPressureCtx);
         await h.fire("agent_end", { type: "agent_end", messages: [] }, lowPressureCtx);
+        // tool_use is success (0 nudges); error/aborted are transient under S38 (1 each).
+        if (stopReason === "tool_use") {
+            assert.equal(h.sendUserMessages.length - before, 0, "tool_use (success): no nudge");
+        }
+        else {
+            transientRetries += h.sendUserMessages.length - before;
+        }
     }
-    assert.equal(h.sendUserMessages.length, 0, "non-length stopReasons: no nudge");
+    // error + aborted each produced one S38 transient retry nudge (2 total).
+    assert.equal(transientRetries, 2, "S38 owns error/aborted: 1 transient retry each");
     assert.ok(!eventTypes(h.stateDir).includes("length_stop"), "non-length stopReasons: no length_stop dashboard event");
 });
 // ---- S29: percent-based auto-compact trigger (gate on context %, not tokens) -
@@ -1078,6 +1100,13 @@ test("cleanup", async () => {
     // Terminate the global PGlite cross-repo index (WASM worker thread) so the
     // test process can exit. Without this, node --test never returns even though
     // every test passed — the leaked worker keeps the event loop alive.
-    await closeVectorIndex();
+    // Race with a timeout to prevent 40-min hangs if PGlite WASM close stalls.
+    try {
+        await Promise.race([
+            closeVectorIndex(),
+            new Promise((r) => setTimeout(r, 3000)),
+        ]);
+    }
+    catch { /* ignore */ }
     rmSync(baseTmp, { recursive: true, force: true });
 });

package/dist/extensions/mega-config.js

@@ -140,6 +140,11 @@ export function loadConfig() {
         auto: envBool("MEGACOMPACT_AUTO", true),
         autoInline: envBool("MEGACOMPACT_AUTO_INLINE", true),
         autoContinueLengthStop: envBool("MEGACOMPACT_AUTO_CONTINUE_LENGTH_STOP", true),
+        autoRetryTransientMax: envFlag("MEGACOMPACT_AUTO_RETRY_TRANSIENT_MAX", 5),
+        autoRetryPermanentMax: envFlag("MEGACOMPACT_AUTO_RETRY_PERMANENT_MAX", 1),
+        raceGuardStrict: envBool("MEGACOMPACT_RACE_GUARD_STRICT", true),
+        maxConsecutiveErrors: envFlag("MEGACOMPACT_MAX_CONSECUTIVE_ERRORS", 10),
+        errorRetryHardStop: envBool("MEGACOMPACT_ERROR_RETRY_HARD_STOP", false),
         autoPctTrigger,
         autoInlineK: envFlag("MEGACOMPACT_AUTO_INLINE_K", 3),
         dedupSim: Number(process.env.MEGACOMPACT_DEDUP_SIM ?? "0.9"),