pi-mega-compact 0.7.9 → 0.8.0

package/dist/extensions/mega-game-cmds.js

@@ -0,0 +1,106 @@
+/**
+ * mega-game-cmds.ts — /mega-game slash command (S30).
+ *
+ * Backs the game-mode toggle + theme picker + TUI display mode. All state is
+ * the global `game_state` SQLite row (src/store/sqlite/game-state.ts) — local
+ * only (PREVENT-PI-004: no network; no guardrails-allow needed because this
+ * command touches no fetch/http). All SQL is parameterized (PREVENT-002) and
+ * lives in the src/ submodule, not here.
+ *
+ * Usage:
+ *   /mega-game                 print current state
+ *   /mega-game on              enable game mode (scoring + level-up + MEGA CACHE)
+ *   /mega-game off             disable game mode
+ *   /mega-game theme           list available themes
+ *   /mega-game theme <id>      set theme by id
+ *   /mega-game theme next      cycle to next theme
+ *   /mega-game tui full        full TUI widget (bars, stats, flair)
+ *   /mega-game tui minimal     one-line TUI widget (level + cache %)
+ *   /mega-game achievements     list unlocked achievements
+ */
+import { getGameState, setGameState, } from "../src/store/sqlite.js";
+import { listAchievements } from "../src/store/sqlite/game-achievements.js";
+import { THEMES, THEME_IDS, getTheme, isValidTheme, nextTheme, DEFAULT_THEME } from "../src/config/themes.js";
+/** Format the current state as a human-readable status line set. */
+function fmtState(s) {
+    return [
+        `[mega-game] game mode: ${s.game_mode_on ? "ON" : "off"}`,
+        `  theme: ${s.theme}${s.theme === DEFAULT_THEME ? " (default)" : ""}`,
+        `  tui:   ${s.tui_display_mode}`,
+    ];
+}
+/** Register the /mega-game command. */
+export function registerGameCommands(pi, runtime) {
+    pi.registerCommand("mega-game", {
+        description: "Game mode toggle + theme picker + TUI display mode. Usage: /mega-game [on|off|theme [id|next]|tui [full|minimal]|achievements]",
+        handler: async (args, ctx) => {
+            runtime.bindRepo(ctx.cwd);
+            const stateDir = runtime.currentStateDir;
+            const parts = args.trim().split(/\s+/).filter(Boolean);
+            // /mega-game  → print current state.
+            if (parts.length === 0) {
+                const s = getGameState(stateDir);
+                for (const line of fmtState(s))
+                    ctx.ui.notify(line);
+                return;
+            }
+            const sub = parts[0];
+            // /mega-game achievements — terse list of unlocked (hidden only once unlocked).
+            if (sub === "achievements") {
+                const rows = listAchievements(stateDir).filter((r) => r.unlocked_at != null);
+                ctx.ui.notify(`[mega-game] achievements unlocked (${rows.length}/9):`);
+                for (const r of rows) {
+                    ctx.ui.notify(`  ${r.icon ?? ""} ${r.title}`);
+                }
+                return;
+            }
+            // /mega-game on|off
+            if (sub === "on" || sub === "off") {
+                const s = setGameState({ game_mode_on: sub === "on" }, stateDir);
+                runtime.bumpGameState();
+                ctx.ui.notify(`[mega-game] game mode ${s.game_mode_on ? "ON" : "off"}`);
+                return;
+            }
+            // /mega-game theme [id|next]
+            if (sub === "theme") {
+                if (parts.length === 1) {
+                    // list themes
+                    ctx.ui.notify("[mega-game] themes:");
+                    for (const t of THEMES) {
+                        ctx.ui.notify(`  ${t.id.padEnd(14)} ${t.label}`);
+                    }
+                    return;
+                }
+                const arg = parts[1];
+                let id;
+                if (arg === "next") {
+                    id = nextTheme(getGameState(stateDir).theme);
+                }
+                else if (isValidTheme(arg)) {
+                    id = arg;
+                }
+                else {
+                    ctx.ui.notify(`[mega-game] unknown theme "${arg}". Valid: ${THEME_IDS.join(", ")}`);
+                    return;
+                }
+                const s = setGameState({ theme: id }, stateDir);
+                runtime.bumpGameState();
+                ctx.ui.notify(`[mega-game] theme → ${s.theme} (${getTheme(s.theme)?.label ?? ""})`);
+                return;
+            }
+            // /mega-game tui full|minimal
+            if (sub === "tui") {
+                const arg = parts[1];
+                if (arg !== "full" && arg !== "minimal") {
+                    ctx.ui.notify(`[mega-game] usage: /mega-game tui full|minimal`);
+                    return;
+                }
+                const s = setGameState({ tui_display_mode: arg }, stateDir);
+                runtime.bumpGameState();
+                ctx.ui.notify(`[mega-game] tui → ${s.tui_display_mode}`);
+                return;
+            }
+            ctx.ui.notify(`[mega-game] usage: /mega-game [on|off|theme [id|next]|tui [full|minimal]|achievements]`);
+        },
+    });
+}

package/dist/extensions/mega-game-cmds.test.js

@@ -0,0 +1,113 @@
+/**
+ * mega-game-cmds.test.ts — /mega-game command parsing matrix (S30).
+ * Uses an isolated state dir + a fake pi harness (mirrors mega-compact.test.ts).
+ * Pi runtime is mocked; the src/ helpers under test are pi-agnostic.
+ */
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mkdtempSync, rmSync } from "node:fs";
+import { createRequire } from "node:module";
+import { closeStore, getGameState } from "../src/store/sqlite.js";
+import { THEME_IDS } from "../src/config/themes.js";
+// ESM bootstrap so `require()` works in this .test.ts (mirrors
+// mega-compact.test.ts:20-24). Needed for the dynamic `require("./mega-game-cmds.js")`
+// that wires the command against a fake pi without binding to the real pi
+// module at load time.
+const require = createRequire(import.meta.url);
+function makeHarness(stateDir) {
+    const commands = {};
+    const notifies = [];
+    const runtime = { bindRepo: () => { }, currentStateDir: stateDir, bumpGameState: () => { } };
+    const ctx = {
+        cwd: stateDir,
+        ui: { notify: (s) => notifies.push(s) },
+    };
+    const fakePi = {
+        registerCommand: (name, opts) => {
+            commands[name] = opts;
+        },
+    };
+    // Import after env is set so stateDir resolves. Dynamic import keeps the
+    // test from binding to the real pi module at load time.
+    const mod = require("./mega-game-cmds.js");
+    mod.registerGameCommands(fakePi, runtime);
+    return { commands, notifies, ctx };
+}
+describe("/mega-game (S30)", () => {
+    let dir;
+    before(() => {
+        dir = mkdtempSync(join(tmpdir(), "mc-megagame-"));
+        process.env.MEGACOMPACT_STATE_DIR = dir;
+    });
+    after(() => {
+        closeStore(dir);
+        delete process.env.MEGACOMPACT_STATE_DIR;
+        rmSync(dir, { recursive: true, force: true });
+    });
+    async function run(args) {
+        const h = makeHarness(dir);
+        h.notifies.length = 0;
+        await h.commands["mega-game"].handler(args, h.ctx);
+        return h.notifies;
+    }
+    it("bare command prints current (default) state", async () => {
+        const lines = await run("");
+        assert.ok(lines.some((l) => l.includes("game mode: off")));
+        assert.ok(lines.some((l) => l.includes("transparent")));
+        assert.ok(lines.some((l) => l.includes("tui:")));
+    });
+    it("on enables game mode and persists", async () => {
+        await run("on");
+        assert.equal(getGameState().game_mode_on, true);
+    });
+    it("off disables game mode and persists", async () => {
+        await run("on");
+        await run("off");
+        assert.equal(getGameState().game_mode_on, false);
+    });
+    it("theme <id> sets a valid theme and persists", async () => {
+        await run("theme retro");
+        assert.equal(getGameState().theme, "retro");
+        await run("theme cyan-neon");
+        assert.equal(getGameState().theme, "cyan-neon");
+    });
+    it("theme <unknown> is rejected with a usage line and does not mutate", async () => {
+        await run("theme retro");
+        const lines = await run("theme bogus");
+        assert.ok(lines.some((l) => l.includes("unknown theme")));
+        assert.equal(getGameState().theme, "retro");
+    });
+    it("theme next cycles to the next theme and wraps", async () => {
+        await run(`theme ${THEME_IDS[0]}`);
+        await run("theme next");
+        assert.equal(getGameState().theme, THEME_IDS[1]);
+        // cycle to the end then wrap
+        await run(`theme ${THEME_IDS[THEME_IDS.length - 1]}`);
+        await run("theme next");
+        assert.equal(getGameState().theme, THEME_IDS[0]);
+    });
+    it("theme (bare) lists all themes", async () => {
+        const lines = await run("theme");
+        for (const id of THEME_IDS) {
+            assert.ok(lines.some((l) => l.includes(id)), `lists ${id}`);
+        }
+    });
+    it("tui full|minimal sets display mode and persists", async () => {
+        await run("tui minimal");
+        assert.equal(getGameState().tui_display_mode, "minimal");
+        await run("tui full");
+        assert.equal(getGameState().tui_display_mode, "full");
+    });
+    it("tui <bad> prints usage and does not mutate", async () => {
+        await run("tui minimal");
+        const lines = await run("tui huge");
+        assert.ok(lines.some((l) => l.includes("usage")));
+        assert.equal(getGameState().tui_display_mode, "minimal");
+    });
+    it("unknown subcommand prints usage", async () => {
+        const lines = await run("bogus");
+        assert.ok(lines.some((l) => l.includes("usage")));
+    });
+});

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

@@ -15,12 +15,15 @@ import { VectorStore } from "../../src/vectorStore.js";
 import { toEngineMessages } from "../../src/adapt.js";
 import { normalizeSessionId } from "../../src/store.js";
 import { Logger } from "../../src/log.js";
-import { recordModelSnapshot, latestModelSnapshot, upsertRepoRegistry, recordRepoModel, getDedupStats, getCompactCount, getRecallInjected, getCacheHitTokensSaved, } from "../../src/store/sqlite.js";
+import { recordModelSnapshot, latestModelSnapshot, upsertRepoRegistry, recordRepoModel, getDedupStats, getCompactCount, getRecallInjected, getCacheHitTokensSaved, getGameState, } from "../../src/store/sqlite.js";
 import { detectCrossRepoDrift } from "../../src/driftDetection.js";
 import { repoStateDir, resolveRepoRoot, pressureRatio, pressureFromPct, pressureBand, effectiveThresholdTokens, } from "../mega-config.js";
 import { Dashboard } from "../mega-dashboard.js";
 import { STATUS_KEY, WIDGET_KEY, TOKENS_PER_SEC_ESTIMATE, ownVersion, } from "./helpers.js";
 import { C, buildWidgetLines, } from "./widget.js";
+import { getTheme } from "../../src/config/themes.js";
+import { watch } from "node:fs";
+import { turnLevel } from "../../src/game/scoring.js";
 export class MegaRuntime {
     config;
     // Store/dashboard/logger are rebound per-repo by bindRepo() so each git repo
@@ -53,6 +56,22 @@ export class MegaRuntime {
     // Agent tracking for real-time widget updates
     activeAgents = 0;
     currentTurn = 0;
+    // S33: transient MEGA CACHE flare flag (armed by the turn_end scoring hook
+    // when cachePct > 100). Copied into widgetData.megaCacheFlare on the next
+    // snapshot() so the widget renders the oopsie gag, then reset (one cycle).
+    megaCacheFlare = false;
+    megaCacheFlarePct = 0;
+    levelUpFlare = false;
+    lastLevel = 0;
+    // S35: transient achievement-unlock flare (armed by the scoring hooks after
+    // evaluateAndUnlockAchievements returns newly-unlocked titles). Copied into
+    // widgetData.achievementFlare on the next snapshot() so the widget renders the
+    // unlock toast, then reset (one cycle — mirrors megaCacheFlare/levelUpFlare).
+    achievementFlare = false;
+    achievementFlareTitles = [];
+    // S33: last cumulative dedup-collapsed count seen by the session_compact
+    // hook, so we only record the DELTA as the dedupe score (leaderboard sums).
+    lastDedupCollapsed = 0;
     // Recall block produced by auto-inline (resume/branch) that the next
     // before_agent_start should prepend to the system prompt. Unset after use.
     pendingRecallBlock;
@@ -97,6 +116,23 @@ export class MegaRuntime {
     // Cached cross-repo drift status (recomputed at most every 30s — it opens the
     // machine-wide registry DB, so we don't want to do it on every render frame).
     driftCache = null;
+    // S31: cached game-mode state (game_mode_on/theme/tui_display_mode). Lazily
+    // read from the game_state SQLite row on the first widget render, then
+    // memoized until bumpGameState() evicts it (called by /mega-game after a
+    // write) so the widget picks up theme/mode/level changes live without
+    // re-querying the DB on every render frame.
+    cachedGameState;
+    // S32: fs.watch on the current repo's sqlite.db so cross-process writes
+    // (e.g. the dashboard server's PUT /api/game-state, which runs as a detached
+    // child with no MegaRuntime ref) evict the cached game-state memo. Without
+    // this, /mega-game's in-process bumpGameState() is the only eviction trigger
+    // and the widget would keep showing stale theme/mode/toggle after a dashboard
+    // edit until a restart. The watcher tracks currentStateDir — closed + re-opened
+    // by ensureGameStateWatcher() on every bindRepo repo switch. Non-fatal: any
+    // fs.watch failure (missing file / platform issue) is swallowed; the next
+    // getCachedGameState() snapshot re-queries the DB anyway.
+    gameStateWatcher;
+    gameStateWatchDir;
     /**
      * DIAG counters for the "team run doesn't relieve context" investigation.
      * Plain integers, incremented at the three compaction decision points. They
@@ -188,6 +224,7 @@ export class MegaRuntime {
         });
         this.dashboard = new Dashboard(config.stateDir);
         this.currentStateDir = config.stateDir;
+        this.ensureGameStateWatcher();
     }
     // ---- per-repo binding -----------------------------------------------------
     /**
@@ -204,6 +241,15 @@ export class MegaRuntime {
             return dir;
         this.activeRepoRoot = key;
         this.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().
+        this.cachedGameState = undefined;
+        // 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.
+        this.ensureGameStateWatcher();
         this.store = new VectorStore({
             dedupSim: this.config.dedupSim,
             stateDir: dir,
@@ -457,6 +503,16 @@ export class MegaRuntime {
             // Cross-repo drift status (cached, read-only).
             const driftStatus = this.driftStatus();
             const agentsActive = this.activeAgents > 0;
+            // S31: game-mode state for the widget (theme/mode/level + MEGA CACHE).
+            // Pulled from the cached game_state row; cachePct is the REAL dedup hit
+            // rate (may exceed 100% — that's the MEGA CACHE trigger). megaCacheFlare
+            // is false for now (S33.4 scoring hook arms it when cachePct > 100).
+            const gs = this.getCachedGameState();
+            // S34: derive the level-up flare from the turn count each snapshot.
+            const curLevel = this.getTurnLevel();
+            if (curLevel > this.lastLevel)
+                this.levelUpFlare = true;
+            const cachePct = st.dedupHitRate * 100;
             this.widgetData = {
                 version: ownVersion(),
                 tierLabel,
@@ -488,7 +544,30 @@ export class MegaRuntime {
                 lastWhy: this.lastWhy,
                 tierTrace: this.tierTrace,
                 pulsing: this.pulsing,
+                // S31 game-mode fields:
+                gameMode: gs.game_mode_on,
+                theme: getTheme(gs.theme) ? gs.theme : "transparent",
+                tuiMode: gs.tui_display_mode,
+                level: this.getTurnLevel(),
+                cachePct,
+                megaCacheFlare: this.megaCacheFlare,
+                megaCacheFlarePct: this.megaCacheFlarePct,
+                levelUpFlare: this.levelUpFlare,
+                achievementFlare: this.achievementFlare,
+                achievementFlareTitles: this.achievementFlareTitles,
             };
+            // S33: consume the flare after copying it into widgetData so it fires
+            // for exactly one render cycle (the gag flares once, then clears).
+            this.megaCacheFlare = false;
+            this.megaCacheFlarePct = 0;
+            // S34: consume the level-up flare after one render cycle (mirrors the
+            // megaCacheFlare one-shot semantics), and advance lastLevel.
+            this.levelUpFlare = false;
+            this.lastLevel = curLevel;
+            // S35: consume the achievement-unlock flare after one render cycle
+            // (mirrors the megaCacheFlare/levelUpFlare one-shot semantics).
+            this.achievementFlare = false;
+            this.achievementFlareTitles = [];
             // Auto-fit: register a factory so pi re-renders the panel at the REAL
             // terminal width every frame (tui.columns), instead of guessing with
             // process.stdout.columns. buildWidgetLines reads this.widgetData live.
@@ -563,6 +642,10 @@ export class MegaRuntime {
         this.pulsing = false;
         this.savedGoal = 50_000;
         this.lastWhy = undefined;
+        // S31 audit P2: symmetry with bindRepo — a reset can coincide with a context
+        // that re-binds the repo, so drop the memo too. Cheap; the next
+        // getCachedGameState() re-queries lazily.
+        this.cachedGameState = undefined;
     }
     /**
      * Capture the active model/provider from ctx.model and persist it so cost
@@ -665,6 +748,89 @@ export class MegaRuntime {
     getStateDir() {
         return this.currentStateDir;
     }
+    /** S32: (re)target the fs.watch cache-eviction watcher at the current
+     *  stateDir's sqlite.db. Called from the constructor + every bindRepo repo
+     *  switch so the watcher always tracks the NEW repo's db file. If a watcher
+     *  already exists for this dir, no-op; if the dir changed, close the old one
+     *  first. fs.watch can throw on a missing file / platform issues — wrapped
+     *  non-fatal; the next getCachedGameState() re-queries the DB anyway. */
+    ensureGameStateWatcher() {
+        if (this.gameStateWatcher && this.gameStateWatchDir === this.currentStateDir) {
+            return;
+        }
+        if (this.gameStateWatcher) {
+            try {
+                this.gameStateWatcher.close();
+            }
+            catch { /* non-fatal */ }
+            this.gameStateWatcher = undefined;
+            this.gameStateWatchDir = undefined;
+        }
+        try {
+            this.gameStateWatcher = watch(join(this.currentStateDir, "sqlite.db"), () => { this.cachedGameState = undefined; });
+            this.gameStateWatchDir = this.currentStateDir;
+        }
+        catch {
+            /* non-fatal: missing file / platform issue — next snapshot re-queries */
+        }
+    }
+    /** S32: release the fs.watch game-state watcher. 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). */
+    dispose() {
+        if (this.gameStateWatcher) {
+            try {
+                this.gameStateWatcher.close();
+            }
+            catch { /* non-fatal */ }
+            this.gameStateWatcher = undefined;
+            this.gameStateWatchDir = undefined;
+        }
+    }
+    /** S31: the cached game-mode state (game_mode_on/theme/tui_display_mode).
+     *  Lazily read from the game_state SQLite row on the first call, then
+     *  memoized until `bumpGameState()` evicts it. Reading is non-throwing
+     *  (getGameState returns DEFAULT_GAME_STATE on any error), so the widget
+     *  can call this on every render safely. */
+    getCachedGameState() {
+        if (!this.cachedGameState) {
+            try {
+                this.cachedGameState = getGameState(this.currentStateDir);
+            }
+            catch {
+                this.cachedGameState = {
+                    game_mode_on: false,
+                    theme: "transparent",
+                    tui_display_mode: "full",
+                };
+            }
+        }
+        return this.cachedGameState;
+    }
+    /** S31: evict the cached game-mode state so the next widget render re-reads
+     *  the game_state row. Called by /mega-game after every setGameState() so
+     *  the panel picks up theme/mode/toggle changes live. */
+    bumpGameState() {
+        this.cachedGameState = undefined;
+    }
+    /** S33: player level for game mode — floor(log2(turns+1))+1 (gentle).
+     *  Defensive: non-finite/negative collapses to 1 (never NaN). */
+    getTurnLevel() {
+        return turnLevel(this.currentTurn);
+    }
+    /** 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. */
+    armMegaCacheFlare(peakPct) {
+        this.megaCacheFlare = true;
+        this.megaCacheFlarePct = peakPct;
+    }
+    /** 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. */
+    armAchievementFlare(titles) {
+        this.achievementFlare = true;
+        this.achievementFlareTitles = titles;
+    }
     /** Build the sync onTier callback that paints the live per-tier trace. */
     makeTierCallback(ctx) {
         const order = ["L0", "L1", "L2", "new"];

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

@@ -0,0 +1,171 @@
+/**
+ * state.test.ts — S31 MegaRuntime game-state cache round-trip.
+ *
+ * getCachedGameState() lazily reads the game_state row; bumpGameState()
+ * evicts so the next read re-queries. Uses MEGACOMPACT_STATE_DIR + mkdtemp
+ * (G7). A minimal MegaRuntime is constructed directly (no pi runtime).
+ */
+import { describe, it, after } from "node:test";
+import assert from "node:assert/strict";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mkdtempSync, rmSync } from "node:fs";
+import { createRequire } from "node:module";
+import { execSync } from "node:child_process";
+import { closeStore, getGameState, setGameState } from "../../src/store/sqlite.js";
+import { DEFAULT_GAME_STATE } from "../../src/store/sqlite/game-state.js";
+const require = createRequire(import.meta.url);
+// Require the compiled JS (build output) so ESM import of pi-tui etc. resolves.
+const { MegaRuntime } = require("./state.js");
+/** Minimal MegaConfig — enough fields for the constructor; the snapshot path
+ *  isn't exercised here, only getCachedGameState/bumpGameState. */
+function minimalConfig(stateDir) {
+    return {
+        tier: "custom",
+        tierPct: null,
+        thresholdTokens: 100_000,
+        stateDir,
+        fastGatePct: 70,
+        anchorUserMessages: 3,
+        preserveRecent: 4,
+        preserveRecentMin: 2,
+        auto: false,
+        autoInline: false,
+        autoContinueLengthStop: false,
+        autoPctTrigger: null,
+        dedupSim: 0.9,
+        raptorEnabled: false,
+        legacyDurableTrim: false,
+        dbMirror: false,
+        crossRepoEnabled: false,
+        crossRepoCosine: 0.9,
+        memoryAutoReview: false,
+        memoryReviewInterval: 10,
+        recallMaxTokens: 1500,
+        windowDedupe: false,
+        debug: false,
+    };
+}
+/** Fresh isolated state dir per test — the game_state row is global and
+ *  persists across cases in a shared dir, so each case gets its own mkdtemp to
+ *  avoid cross-test contamination. */
+function freshDir() {
+    return mkdtempSync(join(tmpdir(), "mc-state-"));
+}
+describe("MegaRuntime game-state cache (S31)", () => {
+    const dirs = [];
+    after(() => {
+        for (const d of dirs) {
+            try {
+                closeStore(d);
+            }
+            catch { /* */ }
+        }
+        delete process.env.MEGACOMPACT_STATE_DIR;
+        for (const d of dirs)
+            rmSync(d, { recursive: true, force: true });
+    });
+    it("getCachedGameState returns defaults on a fresh install", () => {
+        const dir = freshDir();
+        dirs.push(dir);
+        process.env.MEGACOMPACT_STATE_DIR = dir;
+        const rt = new MegaRuntime(minimalConfig(dir));
+        const gs = rt.getCachedGameState();
+        assert.deepEqual(gs, { ...DEFAULT_GAME_STATE });
+    });
+    it("getCachedGameState memoizes (same ref across calls)", () => {
+        const dir = freshDir();
+        dirs.push(dir);
+        process.env.MEGACOMPACT_STATE_DIR = dir;
+        const rt = new MegaRuntime(minimalConfig(dir));
+        const a = rt.getCachedGameState();
+        const b = rt.getCachedGameState();
+        assert.equal(a, b, "memoized — same object ref");
+    });
+    it("bumpGameState evicts so the next read reflects a setGameState write", () => {
+        const dir = freshDir();
+        dirs.push(dir);
+        process.env.MEGACOMPACT_STATE_DIR = dir;
+        const rt = new MegaRuntime(minimalConfig(dir));
+        const before = rt.getCachedGameState();
+        assert.equal(before.game_mode_on, false);
+        // Write out-of-band (as /mega-game would).
+        setGameState({ game_mode_on: true, theme: "retro", tui_display_mode: "minimal" }, dir);
+        // Without bump, the stale memo is returned.
+        const stale = rt.getCachedGameState();
+        assert.equal(stale.game_mode_on, false, "stale cache before bump");
+        // After bump, the next read re-queries and reflects the write.
+        rt.bumpGameState();
+        const fresh = rt.getCachedGameState();
+        assert.equal(fresh.game_mode_on, true);
+        assert.equal(fresh.theme, "retro");
+        assert.equal(fresh.tui_display_mode, "minimal");
+        // And matches the authoritative getGameState read.
+        assert.deepEqual(fresh, getGameState(dir));
+    });
+    it("bumpGameState is idempotent (safe to call when cache is empty)", () => {
+        const dir = freshDir();
+        dirs.push(dir);
+        process.env.MEGACOMPACT_STATE_DIR = dir;
+        const rt = new MegaRuntime(minimalConfig(dir));
+        rt.bumpGameState(); // no cached state yet — must not throw
+        const gs = rt.getCachedGameState();
+        assert.deepEqual(gs, { ...DEFAULT_GAME_STATE });
+    });
+    it("bindRepo evicts cachedGameState so a repo switch reflects the new repo's game_state", () => {
+        // Two fresh git repos A and B simulate a real repo switch. Each holds its
+        // own per-repo state dir at <root>/.pi/mega-compact (what repoStateDir
+        // returns for a git cwd), and each holds its own game_state row, so a repo
+        // switch (bindRepo) must evict the cached memo or the widget shows A's
+        // theme/mode/toggle after moving to B. Uses MEGACOMPACT_STATE_DIR + mkdtemp
+        // + closeStore (G7); the global state dir stays separate.
+        const globalDir = freshDir();
+        dirs.push(globalDir);
+        const repoA = freshDir();
+        dirs.push(repoA);
+        const repoB = freshDir();
+        dirs.push(repoB);
+        const stateA = join(repoA, ".pi", "mega-compact");
+        const stateB = join(repoB, ".pi", "mega-compact");
+        // Make A and B real git roots so resolveRepoRoot(cwd) returns the root and
+        // repoStateDir produces <root>/.pi/mega-compact (the per-repo store).
+        execSync("git init -q", { cwd: repoA });
+        execSync("git init -q", { cwd: repoB });
+        // Seed A and B with distinct game_state rows in their per-repo dirs.
+        setGameState({ game_mode_on: true, theme: "retro", tui_display_mode: "minimal" }, stateA);
+        setGameState({ game_mode_on: false, theme: "cyan-neon", tui_display_mode: "full" }, stateB);
+        // Construct the runtime against the GLOBAL dir (the non-git fallback so a
+        // real bindRepo switch occurs once we point it at a git root).
+        process.env.MEGACOMPACT_STATE_DIR = globalDir;
+        const rt = new MegaRuntime(minimalConfig(globalDir));
+        // Point the runtime at repo A and prime the cache.
+        rt.bindRepo(repoA);
+        assert.equal(rt.currentStateDir, stateA, "bindRepo(A) switched to A's per-repo dir");
+        const a = rt.getCachedGameState();
+        assert.equal(a.game_mode_on, true, "A: game_mode_on primed");
+        assert.equal(a.theme, "retro", "A: theme primed");
+        assert.equal(a.tui_display_mode, "minimal", "A: tui_display_mode primed");
+        // Switch to repo B: bindRepo must evict cachedGameState so the next read
+        // re-queries B's row instead of returning A's stale memo.
+        rt.bindRepo(repoB);
+        assert.equal(rt.currentStateDir, stateB, "bindRepo(B) switched to B's per-repo dir");
+        const b = rt.getCachedGameState();
+        assert.equal(b.game_mode_on, false, "B: game_mode_on after switch (not A's stale true)");
+        assert.equal(b.theme, "cyan-neon", "B: theme after switch (not A's stale retro)");
+        assert.equal(b.tui_display_mode, "full", "B: tui_display_mode after switch (not A's stale minimal)");
+        assert.deepEqual(b, getGameState(stateB), "B matches authoritative getGameState read");
+        // Cleanup the per-repo DB handles.
+        try {
+            closeStore(globalDir);
+        }
+        catch { /* */ }
+        try {
+            closeStore(stateA);
+        }
+        catch { /* */ }
+        try {
+            closeStore(stateB);
+        }
+        catch { /* */ }
+    });
+});