pi-mega-compact 0.8.12 → 0.8.15

package/README.md

@@ -6,10 +6,10 @@ sessions into a **local SQLite store** and offers **deduped inline recall** —
 running **locally inside the extension**, with **no remote MCP server** and
 **zero network calls at runtime** (PREVENT-PI-004).
 
-> **Status - v0.7.9.** Storage uses the built-in `node:sqlite` backend
-> (`DatabaseSync`, Node >=22.13): zero native build step, fully local, and zero
-> network at runtime. See [RELEASE_NOTES.md](RELEASE_NOTES.md) for the full
-> changelog.
+> **Status - v0.8.14.** The React dashboard (8 tabs, responsive scaling from
+> 1280×720 to 4K) now ships in the npm tarball alongside the fallback html.ts.
+> Game Mode adds themes, levels, achievements, and leaderboards. See
+> [RELEASE_NOTES.md](RELEASE_NOTES.md) for the full changelog.
 
 ---
 
@@ -19,7 +19,9 @@ running **locally inside the extension**, with **no remote MCP server** and
 - **Two-layer compaction** - a non-destructive live summary every LLM call, plus durable checkpoints that relieve context mid-run (not just at the end).
 - **Vector store + dedup** - each checkpoint is embedded and stored locally; an L0->L2 + RAPTOR cascade collapses duplicate work so storage and recall stay lean.
 - **Automatic recall** - the most relevant checkpoints are re-inlined on resume or branch switch; cross-repo memory-RAG augments a thin store with decisions from other repos.
-- **Live dashboard** - a localhost-only view of token usage, store stats, savings, per-repo activity, and an **Active Repos tab** that shows every currently-open session (last 30 minutes) side by side — so running multiple sessions at once is visible in one place.
+- **Game Mode** - optional progression layer with 6 themes, player levels (one per turn-doubling), 9 achievements (8 visible + 1 hidden easter-egg), and per-metric leaderboards. Toggle with `/mega-compact-settings`.
+- **Live dashboard** - React-based 8-tab dashboard (Overview, Repos, Events, Config, Metrics, Cache, Game, Achievements) with responsive scaling from laptop (1280×720) to ultrawide/4K. Active Repos tab shows every currently-open session side by side.
+- **Perf metrics** - Model latency (turn/provider p50/p95), throughput (TPS/cache hit %), process (RSS/heap/CPU), snapshot cost (DB recompute/disk write), and TUI lag proxy — all polled on a 2s interval while the dashboard is open.
 - **Database maintenance** - `/mega-db-*` commands plus best-effort auto-maintenance on session start.
 
 ## Table of contents
@@ -198,6 +200,15 @@ building.
 > To validate a real install, bump the version, `npm publish`, then
 > `pi update --extensions` on the device. (`.gitignore` rejects `*.tgz` so one can't
 > be committed by accident.)
+>
+> **Releasing (authoritative pipeline):** every release MUST go through
+> `./scripts/deploy.sh <new-version>`. It enforces a clean tree, the full gate
+> (`build` + `test` + `lint` + `regression_check` + `guardrails-scan`), builds the
+> React dashboard, and — critically — verifies `extensions/dashboard-client/dist/index.html`
+> is present AND listed by `npm pack --dry-run` **before** `npm publish`. This is
+> the gate that was missing when v0.8.5 shipped without the dashboard bundle. The
+> script then bumps the version, commits, publishes via npm only, tags, pushes,
+> and prints device-side verification steps. Never publish by hand.
 
 ### Storage
 
@@ -246,6 +257,7 @@ The commands (slash commands inside pi):
 | --- | --- |
 | `/mega-compact [summary...]` | Manually compact the current session. A summary arg is used verbatim; otherwise the COLLAPSE heuristics build one. Persists a `chkpt_xxx`. |
 | `/mega-compact off` | Disable auto-compaction for this session. |
+| `/mega-compact-settings [on\|off\|theme [id\|next]\|tui [full\|minimal]\|achievements]` | Toggle game mode, pick a theme, switch TUI display mode, list unlocked achievements. (Alias: `/mega-game`.) |
 | `/mega-status` | Show config + current context usage + store stats (checkpoint count, dedup rate, tokens saved) + the **installed version**. |
 | `/mega-recall [query]` | Semantic-search the local store, dedupe against the current window, and inline the top-K relevant checkpoints. No query → uses your latest message. `--cross-repo` searches all repos. |
 | `/mega-memory save <text>` / `save <category> <text>` / `list` / `search <query>` / `forget <text>` / `consolidate` | Manage durable memories (decisions, facts, preferences) written by auto-review and recalled as RAG context. Also `/m` shortform. |
@@ -267,13 +279,23 @@ The commands (slash commands inside pi):
 
 The **tier** you see in the toolbar and dashboard is a *live pressure band* (`low` → `medium` → `high` → `ultra` → `mega`) that climbs automatically as your context window fills and falls back as it's relieved — it is driven by `currentTokens / effectiveThreshold`, not a manual setting. The base compaction *threshold* is set by `MEGACOMPACT_TIER` at startup as a **% of the model context window** (`low` 50% · `medium` 60% · `high` 70% · `ultra` 70% · `mega` 75%; default `low`) — the fire point is `tierPct × contextWindow`, so it always lands below pi's native ~80% auto-compaction (any model size). The old static token amounts (50k/100k/200k/1M/10M) are now only the boot fallback used before the first context event reports a window. `/mega-tier` was removed in v0.7.6. Higher pressure also deepens the live trim and reviews durable memory more often — the whole system reacts as one.
 
+### Game Mode
+
+Optional progression layer (toggle with `/mega-compact-settings on`):
+
+- **6 themes** — transparent (default), neon, retro, ocean, forest, cyber. CSS-variable skins for the TUI widget and dashboard.
+- **Player levels** — one level per turn-doubling (`turnLevel(n) = floor(log2(n+1))+1`). Level-up fires a one-cycle ANSI blink on the TUI + a CSS pulse on the dashboard.
+- **Achievements** — 9 total (8 visible + 1 hidden easter-egg). Unlock conditions: First Compact, Compact Streak (5 in one session), Turn Veteran (25 turns), Level 5, Dedupe Master (100 chunks), Repo Explorer (3 repos), Night Owl (00:00–05:00), Flawless (exactly 100% cache), and Opie's Wild Ride (hidden: push cache past 100%).
+- **Leaderboards** — per-metric (Cache %, Dedupe collapsed, Turns LVL, MEGA CACHE trophies) with repos badge. Stored in SQLite `game_scores`.
+- **MEGA CACHE easter-egg** — when the dedup hit rate exceeds 100% (real ratio > 1), a transient "oopsie" toast fires (TUI + dashboard) and the hidden Opie achievement unlocks.
+
 ### Live stats widget
 
 Above the pi editor the extension shows a compact widget:
 
 ```
- ⚡ high·low v0.7.9 │ 142k/200k tokens (71%) │ 3 chkpts │ 🤖 2 agents │ turn 5
-   ◐ armed │ dedup: 92% │ saved: 45k tok
+ ⚡ high·low v0.8.14 │ 142k/200k tokens (71%) │ 3 chkpts │ 🤖 2 agents │ turn 5
+   ◐ armed │ dedup: 92% │ saved: 45k tok │ LVL 4
 ```
 
 - **Version** — the installed npm version (read from `package.json` at runtime),
@@ -285,6 +307,7 @@ Above the pi editor the extension shows a compact widget:
 - **Trigger state** — ○ idle, ◐ armed, ● ready
 - **Dedup hit rate** — % of checkpoints collapsed as duplicates
 - **Active agents / turn** — sub-agent count and conversation turn (when > 0)
+- **LVL** — player level (one per turn-doubling; game mode only)
 
 > **DB housekeeping** — `/mega-db-stats` / `prune` / `vacuum` / `check` / `reconcile`
 > give you manual control over the SQLite store. In addition, a best-effort
@@ -365,20 +388,20 @@ store. It reads the machine-wide `repo_registry`
 (`~/.mega-compact-index/index.sqlite`) plus the current repo's own `node:sqlite`
 store.
 
-### Tabs
-
-- **Current repo** — the live single-session view: context-window gauge, trigger
-  status, the Vector Store (checkpoints / dropped / kept / freed / injected /
-  dedup / collapsed), the repo-wide aggregate, the Data Safety card, the live
-  Model & Cost Savings card, and crew/agent activity.
-- **All repos** — a machine-wide table aggregated from `repo_registry`
-  (`GET /api/index`): one row per repo with checkpoints, tokens saved,
-  compressed-originals, last-compacted, and active model. Each row opens a
-  per-repo detail modal. Currently-open sessions are badged **active** (see
-  below).
-- **Summary** — machine-wide header tiles plus a **savings-by-model** table
-  (tokens in/out/freed, context window, $ saved) grouped by the model you were
-  running.
+### Tabs (React dashboard)
+
+The dashboard (started with `/mega-dashboard`) now ships as a React SPA with 8 tabs, responsive scaling from 1280×720 to 4K:
+
+- **Overview** — context-window gauge (green/yellow/red), trigger status (armed/ready/idle), Vector Store (9 fields + compression bar), Repo (all sessions, 7 fields), Data Safety shield (regions retained, dedup %), Configuration (tier/preset/threshold), Model & Cost Savings ($, rates), Crew/Agents (active agents/turn/status), "What these numbers mean" legend.
+- **Repos** — All Repositories table, Active Repos live table, Savings by Model table, per-repo detail modal, summary tiles.
+- **Events** — live SSE stream with category filter (all/compact/recall/config/crew/game).
+- **Config** — game mode toggle, theme picker (6 themes), TUI display mode (full/minimal), read-only config display.
+- **Metrics** — model latency (turn/provider p50/p95), throughput (TPS/cache hit %), process (RSS/heap/CPU), snapshot cost (DB recompute/disk write), TUI lag proxy. Per-model cache status table.
+- **Cache** — Cache Hits (session/total), Tokens Saved (session/total), Compactions (session/total), Time Saved (session/total).
+- **Game** — MEGA CACHE banner, Opie unlock tile, leaderboards (Cache %, Dedupe collapsed, Turns LVL, MEGA CACHE trophies), repos badge, achievements sub-section.
+- **Achievements** — achievement tiles grid with unlock states, toast area.
+
+The older html.ts fallback (1071 lines, all data) is retained for environments without the React build.
 
 ### Active Repos tab
 

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"),