pi-mega-compact 0.8.22 → 0.8.24

package/LICENSE

@@ -1,6 +1,6 @@
-BSD 2-Clause License
+BSD 3-Clause License
 
-Copyright (c) 2026 TheArchitectit
+Copyright (c) 2026, TheArchitectit
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:
@@ -12,6 +12,10 @@ modification, are permitted provided that the following conditions are met:
    this list of conditions and the following disclaimer in the documentation
    and/or other materials provided with the distribution.
 
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE

package/README.md

@@ -88,7 +88,7 @@ Testing guide: [`TESTER_GUIDE.md`](TESTER_GUIDE.md)
 
 ## License
 
-BSD-2-Clause
+BSD 3-Clause
 
 ## ☕ Support
 

package/dist/extensions/dashboard-server/api-contracts/endpoints.js

@@ -8,6 +8,14 @@
  * Sprint A1 — PREVENT-PI-004: zero network code (type definitions only).
  * PREVENT-011: no `any` type — all types are explicit.
  */
+// ─── Game Score & Achievement Types ─────────────────────────────────────────
+// (moved to game-types.ts; re-exported for backwards compatibility)
+// ─── Sessions Memory Graph (S39) ─────────────────────────────────────────
+// (moved to game-types.ts; re-exported for backwards compatibility)
+// ─── Game State Patch (PUT request body) ────────────────────────────────────
+// (moved to game-types.ts; re-exported for backwards compatibility)
+// ─── SSE Endpoint Definition ────────────────────────────────────────────────
+// (moved to game-types.ts; re-exported for backwards compatibility)
 // ─── ENDPOINTS Registry ─────────────────────────────────────────────────────
 /**
  * Central registry of all 13 dashboard API endpoints. Each entry is an

package/dist/extensions/dashboard-server/api-contracts/game-types.js

@@ -0,0 +1,7 @@
+/**
+ * api-contracts/game-types.ts — Split-out dashboard API types.
+ *
+ * Contains the “Game Score & Achievement Types” and “Sessions Memory Graph”
+ * related type definitions that previously lived in endpoints.ts.
+ */
+export {};

package/dist/extensions/mega-runtime/append-event.js

@@ -0,0 +1,24 @@
+/**
+ * append-event.ts — extracted `MegaRuntime.appendEvent()`: the structured
+ * events.log diagnostics sink. Same context-interface + free-function +
+ * thin-delegate pattern as runtime-helpers.ts / effects.ts / game-state.ts.
+ */
+import { join } from "node:path";
+import { appendFileSync, mkdirSync } from "node:fs";
+// ---------------------------------------------------------------- appendEvent
+/**
+ * Append a structured line to the repo's events.log — the always-on
+ * diagnostics sink the dashboard live-streams. Unlike the runtime logger
+ * (gated by config.debug), this fires in production, so capture failures
+ * surface during a real capture even with debugging off. Best-effort +
+ * non-fatal.
+ */
+export function appendEventImpl(self, event, fields) {
+    try {
+        mkdirSync(self.currentStateDir, { recursive: true });
+        appendFileSync(join(self.currentStateDir, "events.log"), JSON.stringify({ ts: Date.now(), event, ...fields }) + "\n");
+    }
+    catch {
+        /* non-fatal */
+    }
+}

package/dist/extensions/mega-runtime/bind-repo.js

@@ -0,0 +1,65 @@
+/**
+ * bind-repo.ts — extracted per-repo binding for MegaRuntime.
+ *
+ * Point store/dashboard/logger at the current repo's state dir. Rebuilds the
+ * instances only when the repo root changes, so cross-repo dedup stats, db,
+ * and events are fully isolated. Falls back to the global default outside git.
+ */
+import { join } from "node:path";
+import { VectorStore, vectorRepoStats, vectorDataInvariant } from "../../src/vectorStore.js";
+import { repoStateDir, resolveRepoRoot } from "../mega-config.js";
+import { upsertRepoRegistry } from "../../src/store/sqlite.js";
+import { Logger } from "../../src/log.js";
+import { Dashboard } from "../mega-dashboard.js";
+// ------------------------------------------------------------------ bindRepo
+export function bindRepoImpl(ctx, cwd) {
+    const dir = cwd
+        ? repoStateDir(cwd, ctx.config.stateDir)
+        : ctx.config.stateDir;
+    const key = cwd ? (resolveRepoRoot(cwd) ?? dir) : dir;
+    if (key === ctx.activeRepoRoot)
+        return dir;
+    ctx.activeRepoRoot = key;
+    ctx.currentStateDir = dir;
+    // S31 audit P2: bindRepo switched currentStateDir but left cachedGameState
+    // memoized -> the widget kept showing the previous repo's theme/mode/toggle
+    // until /mega-game or a restart. The game_state row is per-repo (per
+    // stateDir), so evict the memo on every repo switch; the next widget render
+    // re-queries lazily via getCachedGameState().
+    ctx.cachedGameState = undefined;
+    ctx.gameStateBump++;
+    // S32: re-target the fs.watch cache-eviction watcher at the NEW stateDir's
+    // sqlite.db so cross-process writes (dashboard server) still evict the memo.
+    ctx.ensureGameStateWatcher();
+    ctx.store = new VectorStore({
+        dedupSim: ctx.config.dedupSim,
+        stateDir: dir,
+    });
+    ctx.logger = new Logger({
+        enabled: ctx.config.debug,
+        path: join(dir, "mega-compact.log"),
+    });
+    ctx.dashboard = new Dashboard(dir);
+    // Aggregate this repo into the machine-wide index so the multi-repo
+    // dashboard (Summary / All-repos tabs) can show it alongside every other
+    // repo. Best-effort + non-fatal: a read-only index dir or contention must
+    // never break the per-repo compaction path. Runs only on repo-switch
+    // (this branch), so it's infrequent — not per-context-event.
+    try {
+        const repo = vectorRepoStats(ctx.store);
+        const di = vectorDataInvariant(ctx.store);
+        const root = key !== dir ? key : (resolveRepoRoot(cwd ?? dir) ?? dir);
+        upsertRepoRegistry({
+            repoRoot: root,
+            displayName: root.split(/[\\/]/).filter(Boolean).pop() ?? root,
+            stateDir: dir,
+            checkpointCount: repo.checkpointCount,
+            tokensSaved: repo.tokensSaved,
+            compressedOriginalBytes: di.compressedOriginalBytes,
+        });
+    }
+    catch {
+        /* non-fatal: index aggregation must not block compaction */
+    }
+    return dir;
+}

package/dist/extensions/mega-runtime/capture-model.js

@@ -0,0 +1,87 @@
+/**
+ * capture-model.ts — extracted model-capture logic for MegaRuntime.
+ *
+ * Captures the active model/provider from ctx.model and persists it so cost
+ * estimation + the dashboard can read real pricing. Cheap + idempotent-ish:
+ * only writes a new row when the model id changes (models change rarely).
+ */
+import { resolveRepoRoot } from "../mega-config.js";
+import { recordModelSnapshot, recordRepoModel } from "../../src/store/sqlite.js";
+// -------------------------------------------------------------- captureModel
+export function captureModelImpl(ctx, ectx) {
+    const m = ectx.model;
+    if (!m) {
+        ctx.appendEvent("captureModel:no-model", { cwd: ectx.cwd });
+        return;
+    }
+    if (ctx.currentModel &&
+        ctx.currentModel.modelId === m.id &&
+        ctx.currentModel.provider === m.provider)
+        return;
+    let providerName = null;
+    try {
+        providerName =
+            ectx.modelRegistry?.getProviderDisplayName(m.provider) ?? null;
+    }
+    catch {
+        /* optional */
+    }
+    const snap = {
+        provider: m.provider,
+        providerName,
+        modelId: m.id,
+        modelName: m.name ?? null,
+        inputRate: m.cost?.input ?? 0,
+        outputRate: m.cost?.output ?? 0,
+        contextWindow: m.contextWindow ?? 0,
+        maxTokens: m.maxTokens ?? 0,
+        reasoning: !!m.reasoning,
+    };
+    ctx.currentModel = { ...snap, capturedAt: Date.now() };
+    ctx.diagCaptureModelCalls++;
+    const repo = resolveRepoRoot(ectx.cwd) ?? ctx.currentStateDir;
+    // S26: previously a single silent `catch {}` hid every capture failure, so
+    // model_snapshots stayed empty and the cost card read $0.00 with zero signal.
+    // Split per-write + append to events.log (always-on, dashboard live-streams
+    // it) + bump a DIAG counter so a live capture surfaces the root cause.
+    try {
+        recordModelSnapshot(repo, snap, ctx.currentStateDir);
+        ctx.appendEvent("captureModel:recorded", {
+            repo,
+            modelId: snap.modelId,
+            provider: snap.provider,
+            inputRate: snap.inputRate,
+            outputRate: snap.outputRate,
+        });
+    }
+    catch (e) {
+        ctx.diagCaptureModelFails++;
+        ctx.appendEvent("captureModel:record-failed", {
+            repo,
+            modelId: snap.modelId,
+            error: e instanceof Error ? e.message : String(e),
+            stack: e instanceof Error ? e.stack : undefined,
+        });
+    }
+    try {
+        // Denormalize the active model into the machine-wide index so the
+        // All-repos dashboard table can show provider/model per repo without
+        // opening every repo's DB. Best-effort + non-fatal.
+        recordRepoModel(repo, {
+            provider: snap.provider,
+            providerName: snap.providerName,
+            modelName: snap.modelName,
+            inputRate: snap.inputRate,
+            outputRate: snap.outputRate,
+            stateDir: ctx.currentStateDir,
+            displayName: repo.split(/[\\/]/).filter(Boolean).pop() ?? repo,
+        });
+    }
+    catch (e) {
+        ctx.appendEvent("captureModel:index-record-failed", {
+            repo,
+            modelId: snap.modelId,
+            error: e instanceof Error ? e.message : String(e),
+        });
+    }
+}

package/dist/extensions/mega-runtime/dashboard-snapshot.js

@@ -0,0 +1,118 @@
+/**
+ * dashboard-snapshot.ts — extracted DashboardSnapshot builder for MegaRuntime.
+ *
+ * Builds the ~130-line DashboardSnapshot data object that was previously
+ * inlined inside MegaRuntime.snapshot(). Pure data-gathering — no I/O, no
+ * side effects.
+ */
+// ---------------------------------------------------------- buildDashboardSnapshot
+/** Build the DashboardSnapshot object from precomputed store/live metrics.
+ *  Pure — no I/O, no side effects. */
+export function buildDashboardSnapshot(ctx) {
+    const armed = (ctx.lastCtxTokens ?? 0) >= ctx.effectiveThreshold * ctx.config.fastGatePct;
+    const ready = armed && (ctx.lastCtxTokens ?? 0) >= ctx.effectiveThreshold;
+    return {
+        version: 1,
+        updatedAt: new Date().toISOString(),
+        tier: ctx.pressureBand,
+        presetTier: ctx.config.tier,
+        pressure: ctx.pressure,
+        config: {
+            fastGatePct: ctx.config.fastGatePct,
+            thresholdTokens: ctx.effectiveThreshold,
+            tierPct: ctx.config.tierPct,
+            effectiveThresholdPct: ctx.config.tierPct != null ? ctx.config.tierPct * 100 : null,
+            anchorUserMessages: ctx.config.anchorUserMessages,
+            preserveRecent: ctx.config.preserveRecent,
+            auto: ctx.config.auto,
+            autoInline: ctx.config.autoInline,
+        },
+        session: {
+            id: ctx.rt.sessionId,
+            state: ctx.statusKey ?? "idle",
+            persistedThisSession: ctx.rt.persistedThisSession,
+            lastCheckpointId: ctx.rt.lastCheckpointId ?? null,
+            lastCompactedFrom: ctx.rt.lastCompactedFrom,
+            lastCompactedTokens: ctx.rt.lastCompactedTokens,
+            dedupSkips: ctx.rt.dedupSkips,
+            dedupAttempts: ctx.rt.dedupAttempts,
+        },
+        context: {
+            tokens: ctx.lastCtxTokens,
+            percent: ctx.lastCtxPercent,
+            contextWindow: ctx.lastCtxWindow,
+        },
+        trigger: {
+            armed,
+            ready,
+            currentTokens: ctx.lastCtxTokens,
+            thresholdTokens: ctx.effectiveThreshold,
+            fastGatePct: ctx.config.fastGatePct,
+            tierPct: ctx.config.tierPct,
+            effectiveThresholdPct: ctx.config.tierPct != null ? ctx.config.tierPct * 100 : null,
+        },
+        store: ctx.st,
+        crew: {
+            activeAgents: ctx.activeAgents,
+            currentTurn: ctx.currentTurn,
+        },
+        repo: ctx.repo,
+        compression: {
+            session: {
+                tokensIn: ctx.rt.tokensSaved + (ctx.st.totalTokenEstimate - ctx.st.originalTokens),
+                tokensOut: ctx.st.totalTokenEstimate,
+                tokensFreed: ctx.rt.tokensSaved,
+                compressionPct: ctx.rt.tokensSaved / Math.max(1, ctx.rt.tokensSaved + (ctx.st.totalTokenEstimate - ctx.st.originalTokens)),
+                dedupPct: ctx.rt.dedupAttempts > 0 ? ctx.rt.dedupSkips / ctx.rt.dedupAttempts : 0,
+            },
+            repo: {
+                tokensIn: ctx.repo.tokensSaved + (ctx.repo.totalTokenEstimate - ctx.repo.originalTokens),
+                tokensOut: ctx.repo.totalTokenEstimate,
+                tokensFreed: ctx.repo.tokensSaved,
+                compressionPct: ctx.repo.tokensSaved / Math.max(1, ctx.repo.tokensSaved + (ctx.repo.totalTokenEstimate - ctx.repo.originalTokens)),
+                dedupPct: ctx.repo.dedupAttempts > 0 ? ctx.repo.dedupCollapsed / ctx.repo.dedupAttempts : 0,
+            },
+        },
+        integrity: ctx.di,
+        cacheHits: {
+            session: ctx.rt.dedupSkips + ctx.rt.recallInjections,
+            total: ctx.st.dedupCollapsed + ctx.st.injectedCount,
+            sessionTokensSaved: ctx.rt.cacheHitTokens,
+            totalTokensSaved: ctx.st.dedupCollapsed > 0 ? ctx.st.dedupCollapsed * 100 : 0,
+        },
+        compacts: {
+            session: ctx.rt.compactCount,
+            total: ctx.st.checkpointCount,
+        },
+        timeSaved: {
+            compact: {
+                sessionSec: ctx.rt.tokensSaved / 1000,
+                totalSec: ctx.repo.tokensSaved / 1000,
+            },
+            cacheHit: {
+                sessionSec: ctx.rt.cacheHitTokens / 1000,
+                totalSec: (ctx.st.dedupCollapsed * 100) / 1000,
+            },
+        },
+        model: ctx.currentModel
+            ? {
+                name: ctx.currentModel.modelId,
+                provider: ctx.currentModel.provider,
+                providerName: ctx.currentModel.providerName ?? ctx.currentModel.provider,
+                inputRate: ctx.currentModel.inputRate,
+                outputRate: ctx.currentModel.outputRate,
+            }
+            : undefined,
+        diag: {
+            ctxFastGate: ctx.diagCtxFastGate,
+            liveTrimFires: ctx.diagLiveTrimFires,
+            liveTrimReplays: ctx.diagLiveTrimReplays,
+        },
+        retries: {
+            errorRetryCount: ctx.errorRetryCount,
+            consecutiveErrors: ctx.consecutiveErrors,
+            maxConsecutiveErrors: ctx.ERROR_RETRY_MAX_CONSECUTIVE,
+            errorRetryHardStop: ctx.errorRetryHardStop,
+        },
+    };
+}

package/dist/extensions/mega-runtime/effects.js

@@ -0,0 +1,86 @@
+/**
+ * effects.ts — extracted effect/flare/ticker logic for MegaRuntime.
+ *
+ * Pure implementations of ambient effects, flare arming, tier-trace callback,
+ * and the recall/activity ticker. Each function takes a typed context object so
+ * the class methods in state.ts become thin one-line delegates.
+ */
+import { C } from "./widget.js";
+// --------------------------------------------------------------- setEffect
+/** v0.8.3: arm an ambient border effect (animated pulse/flash on the panel
+ *  borders). Replaces any in-flight effect (last call wins). The widget reads
+ *  activeEffect each frame and computes the per-frame phase from startedAt vs
+ *  Date.now(); it renders '' once the window elapses. */
+export function setEffectImpl(ctx, type, role, durationMs) {
+    ctx.activeEffect = { type, role, startedAt: Date.now(), durationMs };
+}
+// -------------------------------------------------------- armMegaCacheFlare
+/** S33: arm the transient MEGA CACHE flare so the next snapshot() copies it
+ *  into widgetData and the widget renders the oopsie gag for one cycle.
+ *  v0.8.3: also arm a 'flash' ambient effect on the panel borders (mega
+ *  color) for 1.2s. */
+export function armMegaCacheFlareImpl(ctx, peakPct) {
+    ctx.megaCacheFlare = true;
+    ctx.megaCacheFlarePct = peakPct;
+    setEffectImpl(ctx, "flash", "mega", 1200);
+}
+// ------------------------------------------------------ armAchievementFlare
+/** S35: arm the transient achievement-unlock flare with the newly-unlocked
+ *  titles so the next snapshot() copies them into widgetData and the widget
+ *  renders the one-time unlock toast for one render cycle.
+ *  v0.8.3: also arm a 'pulse' ambient effect on the panel borders (accent
+ *  color) for 2s to celebrate the unlock. */
+export function armAchievementFlareImpl(ctx, titles) {
+    ctx.achievementFlare = true;
+    ctx.achievementFlareTitles = titles;
+    setEffectImpl(ctx, "pulse", "accent", 2000);
+}
+// -------------------------------------------------------- makeTierCallback
+/** Build the sync onTier callback that paints the live per-tier trace. */
+export function makeTierCallbackImpl(ctx, ectx) {
+    const order = ["L0", "L1", "L2", "new"];
+    const seen = new Map();
+    const glyph = (status) => status === "deduped"
+        ? `${C.green}✓${C.reset}`
+        : status === "passed"
+            ? `${C.dim}○${C.reset}`
+            : status === "scanning"
+                ? `${C.amber}…${C.reset}`
+                : `${C.cyan}●${C.reset}`;
+    return (ev) => {
+        const label = ev.tier === "new"
+            ? `${C.cyan}stored${C.reset}`
+            : `${ev.tier} ${glyph(ev.status)}` +
+                (ev.detail ? ` ${C.gray}(${ev.detail})${C.reset}` : "");
+        // Show the most recent outcome per tier (collapses re-fires).
+        seen.set(ev.tier, label);
+        const show = [];
+        for (const t of order)
+            if (seen.has(t))
+                show.push(seen.get(t));
+        ctx.tierTrace = `${C.teal}⚙${C.reset} ${show.join(` ${C.gray}→${C.reset} `)}`;
+        ctx.lastActivityAt = Date.now();
+        try {
+            ctx.snapshot(ectx);
+        }
+        catch {
+            /* non-fatal */
+        }
+    };
+}
+// -------------------------------------------------------------- pushTicker
+/** Phase 3 — recall/activity ticker ring buffer.
+ *  Dedupe consecutive identical entries — skip the append when the last
+ *  entry's text matches, so a re-fired compact/recall/dedup event doesn't
+ *  flood the ring (keeps it at TICKER_MAX for real variety). `at` is NOT
+ *  refreshed on a skip (the original event time stands). */
+export function pushTickerImpl(ctx, text) {
+    if (ctx.ticker[ctx.ticker.length - 1]?.text === text) {
+        ctx.lastActivityAt = Date.now();
+        return;
+    }
+    ctx.ticker.push({ text, at: Date.now() });
+    while (ctx.ticker.length > ctx.TICKER_MAX)
+        ctx.ticker.shift();
+    ctx.lastActivityAt = Date.now();
+}

package/dist/extensions/mega-runtime/engine-view.js

@@ -0,0 +1,11 @@
+/**
+ * engine-view.ts — extracted `MegaRuntime.engineView()`: the pi→engine message
+ * adapter passthrough. A one-liner in its own module per the maximal-split
+ * convention.
+ */
+import { toEngineMessages } from "../../src/adapt.js";
+// ------------------------------------------------------------------ engineView
+/** Convert the messages pi hands us in the `context` event into the engine view. */
+export function engineViewImpl(messages) {
+    return toEngineMessages(messages);
+}

package/dist/extensions/mega-runtime/game-state.js

@@ -0,0 +1,116 @@
+/**
+ * game-state.ts — extracted game-state management for MegaRuntime.
+ *
+ * This module keeps the game-state logic cohesive while leaving the class fields
+ * and public method signatures in state.ts. The original methods become thin
+ * delegates so runtime behavior stays byte-for-byte identical.
+ */
+import { watch } from "node:fs";
+import { getGameState } from "../../src/store/sqlite.js";
+import { getTheme } from "../../src/config/themes.js";
+import { disposePerf } from "./perf.js";
+export function getCachedGameStateImpl(self) {
+    if (!self.cachedGameState) {
+        try {
+            self.cachedGameState = getGameState(self.currentStateDir);
+        }
+        catch {
+            self.cachedGameState = {
+                game_mode_on: false,
+                theme: "transparent",
+                tui_display_mode: "full",
+            };
+        }
+    }
+    return self.cachedGameState;
+}
+export function refreshWidgetGameStateImpl(self, view, ctx) {
+    if (!self.widgetData || !ctx)
+        return;
+    const gs = getCachedGameStateImpl(self);
+    self.widgetData.gameMode = gs.game_mode_on;
+    self.widgetData.theme = getTheme(gs.theme) ? gs.theme : "transparent";
+    self.widgetData.tuiMode = gs.tui_display_mode;
+    view.renderWidget(ctx);
+}
+export function bumpGameStateImpl(self) {
+    self.cachedGameState = undefined;
+    self.gameStateBump++;
+}
+/** S32: release the fs.watch game-state watcher AND stop the v0.8.8 perf
+ *  sampling interval. Called when the runtime is torn down (no existing
+ *  dispose path — the process exit reclaims the fd, but explicit close is
+ *  correct for any in-process reload / test reuse). Extracted from
+ *  MegaRuntime.dispose(); the class keeps a thin delegate. */
+export function disposeRuntimeImpl(self) {
+    if (self.gameStateWatcher) {
+        try {
+            self.gameStateWatcher.close();
+        }
+        catch { /* non-fatal */ }
+        self.gameStateWatcher = undefined;
+        self.gameStateWatchDir = undefined;
+    }
+    disposePerf(self);
+}
+export function ensureGameStateWatcherImpl(self, view) {
+    if (self.gameStateWatcher && self.gameStateWatchDir === self.currentStateDir) {
+        return;
+    }
+    if (self.gameStateWatcher) {
+        try {
+            self.gameStateWatcher.close();
+        }
+        catch {
+            /* non-fatal */
+        }
+        self.gameStateWatcher = undefined;
+        self.gameStateWatchDir = undefined;
+    }
+    try {
+        // Watch the state DIR (not just sqlite.db) and filter by filename.
+        // Why: the store is WAL-mode (openStore sets PRAGMA journal_mode=WAL).
+        // Cross-process writes (dashboard server child) append to sqlite.db-wal
+        // and do NOT modify sqlite.db until a checkpoint — and a long-lived
+        // parent connection (VectorStore + dashboard readers) keeps the WAL
+        // uncheckpointed, so a watcher on sqlite.db alone never fires and
+        // cachedGameState stays stale (theme stuck after a dashboard edit).
+        // Watching the dir + matching sqlite.db* catches the main db, the -wal
+        // sidecar, and -shm, so the memo evicts on any cross-process write. The
+        // filter also excludes events.log / *.log noise in the same dir.
+        self.gameStateWatcher = watch(self.currentStateDir, (_eventType, filename) => {
+            if (typeof filename === "string" && filename.startsWith("sqlite.db")) {
+                self.cachedGameState = undefined;
+                self.gameStateBump++;
+                // P2: force a widget re-render so a dashboard-made theme/toggle/
+                // tui-mode change reflects in the live TUI immediately, even when
+                // pi is idle (no context event to drive snapshot()). Use the
+                // LIGHTWEIGHT refreshWidgetGameState() — NOT the full snapshot():
+                // snapshot() recomputes 6 sync SQLite opens + writes dashboard.json
+                // + writes to the store, and those store writes RETRIGGER this
+                // same fs.watch callback (it fires on every sqlite.db* write) →
+                // re-entrant thrash → 190s test timeout under mega-compact.test.js
+                // / mega-teamrun.test.js. The lightweight path re-reads ONLY the
+                // game_state row and patches the three game-mode fields on the
+                // existing widgetData, then re-registers the factory via
+                // renderWidget() — it writes nothing to the store or
+                // dashboard.json, so it cannot retrigger itself. Guard: skip until
+                // the first snapshot stashed a ctx (no widget registered yet →
+                // nothing to refresh). Non-fatal: next context event re-snapshots.
+                const ctx = self.lastWidgetCtx;
+                if (ctx) {
+                    try {
+                        refreshWidgetGameStateImpl(self, view, ctx);
+                    }
+                    catch {
+                        /* non-fatal */
+                    }
+                }
+            }
+        });
+        self.gameStateWatchDir = self.currentStateDir;
+    }
+    catch {
+        /* non-fatal: missing dir / platform issue — next snapshot re-queries */
+    }
+}

package/dist/extensions/mega-runtime/get-state-dir.js

@@ -0,0 +1,10 @@
+/**
+ * get-state-dir.ts — extracted `MegaRuntime.getStateDir()` (S21). A one-liner
+ * in its own module per the maximal-split convention: no method bodies left in
+ * runtime.ts.
+ */
+// --------------------------------------------------------------- getStateDir
+/** S21: state dir of the currently bound repo (where memories live). */
+export function getStateDirImpl(self) {
+    return self.currentStateDir;
+}

package/dist/extensions/mega-runtime/perf.js

@@ -0,0 +1,49 @@
+/**
+ * perf.ts — extracted perf-interval sampling for MegaRuntime.
+ *
+ * The 5s cpu/mem sampling interval + its teardown. Keeps the setInterval
+ * boilerplate out of the main state.ts class body.
+ */
+import { recordPerfSample } from "../../src/store/sqlite.js";
+// ---------------------------------------------------------- ensurePerfInterval
+/** v0.8.8: (re)start the 5s cpu/mem sampling interval (idempotent). One per
+ *  MegaRuntime; cleared in disposePerf(). Samples process.cpuUsage() (user/sys
+ *  delta vs the last tick → ms) + process.memoryUsage() (rss/heap → MB) and
+ *  records them as perf_samples. unref'd so it never keeps the process alive
+ *  on its own. Non-fatal: any failure is swallowed (instrumentation never
+ *  blocks the agent). PREVENT-PI-004: local process stats + SQLite only. */
+export function ensurePerfIntervalImpl(ctx) {
+    if (ctx.perfCpuInterval)
+        return;
+    ctx.perfCpuBaseline = undefined; // first tick sets the baseline (no delta)
+    ctx.perfCpuInterval = setInterval(() => {
+        try {
+            const dir = ctx.currentStateDir;
+            const cpu = process.cpuUsage();
+            const mem = process.memoryUsage();
+            if (ctx.perfCpuBaseline) {
+                const du = (cpu.user - ctx.perfCpuBaseline.user) / 1000; // μs → ms
+                const ds = (cpu.system - ctx.perfCpuBaseline.sys) / 1000;
+                recordPerfSample(dir, "cpu_user_ms", Math.max(0, du));
+                recordPerfSample(dir, "cpu_sys_ms", Math.max(0, ds));
+            }
+            ctx.perfCpuBaseline = { user: cpu.user, sys: cpu.system };
+            recordPerfSample(dir, "rss_mb", mem.rss / 1_000_000);
+            recordPerfSample(dir, "heap_mb", mem.heapUsed / 1_000_000);
+        }
+        catch {
+            /* non-fatal */
+        }
+    }, 5000);
+    ctx.perfCpuInterval.unref?.();
+}
+// ------------------------------------------------------------------ disposePerf
+/** Stop the cpu/mem sampling interval on teardown. Re-armed lazily by
+ *  ensurePerfInterval() on the next turn_start. */
+export function disposePerf(ctx) {
+    if (ctx.perfCpuInterval) {
+        clearInterval(ctx.perfCpuInterval);
+        ctx.perfCpuInterval = null;
+        ctx.perfCpuBaseline = undefined;
+    }
+}