pi-mega-compact 0.7.9 → 0.8.0

package/extensions/mega-game-cmds.test.ts

@@ -0,0 +1,137 @@
+/**
+ * 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);
+
+type Cmd = { description?: string; handler: (args: string, ctx: any) => Promise<void> };
+
+type Harness = {
+  commands: Record<string, Cmd>;
+  notifies: string[];
+  ctx: any;
+};
+
+function makeHarness(stateDir: string): Harness {
+  const commands: Record<string, Cmd> = {};
+  const notifies: string[] = [];
+  const runtime = { bindRepo: () => {}, currentStateDir: stateDir, bumpGameState: () => {} };
+  const ctx = {
+    cwd: stateDir,
+    ui: { notify: (s: string) => notifies.push(s) },
+  };
+  const fakePi = {
+    registerCommand: (name: string, opts: Cmd) => {
+      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") as {
+    registerGameCommands: (pi: unknown, runtime: unknown) => void;
+  };
+  mod.registerGameCommands(fakePi, runtime);
+  return { commands, notifies, ctx };
+}
+
+describe("/mega-game (S30)", () => {
+  let dir: string;
+  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: string): Promise<string[]> {
+    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/extensions/mega-game-cmds.ts

@@ -0,0 +1,122 @@
+/**
+ * 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 type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { MegaRuntime } from "./mega-runtime.js";
+import {
+  getGameState,
+  setGameState,
+  type GameState,
+} 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: GameState): string[] {
+  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: ExtensionAPI, runtime: MegaRuntime): void {
+  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: string, ctx: ExtensionContext) => {
+      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: string;
+        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/extensions/mega-runtime/state.test.ts

@@ -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") as {
+	MegaRuntime: new (config: any) => any;
+};
+
+/** Minimal MegaConfig — enough fields for the constructor; the snapshot path
+ *  isn't exercised here, only getCachedGameState/bumpGameState. */
+function minimalConfig(stateDir: string): any {
+	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(): string {
+	return mkdtempSync(join(tmpdir(), "mc-state-"));
+}
+
+describe("MegaRuntime game-state cache (S31)", () => {
+	const dirs: string[] = [];
+	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 { /* */ }
+	});
+});

package/extensions/mega-runtime/state.ts

@@ -27,7 +27,9 @@ import {
 	getCompactCount,
 	getRecallInjected,
 	getCacheHitTokensSaved,
+	getGameState,
 	type ModelSnapshot,
+	type GameState,
 } from "../../src/store/sqlite.js";
 import { detectCrossRepoDrift } from "../../src/driftDetection.js";
 import {
@@ -54,6 +56,9 @@ import {
 	type TickerEntry,
 	type WidgetData,
 } from "./widget.js";
+import { getTheme } from "../../src/config/themes.js";
+import { watch, type FSWatcher } from "node:fs";
+import { turnLevel } from "../../src/game/scoring.js";
 
 export class MegaRuntime {
 	config: MegaConfig;
@@ -88,6 +93,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: string[] = [];
+	// 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: string | undefined;
@@ -134,6 +155,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).
 	private driftCache: { at: number; status: "ok" | "warn" } | null = 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.
+	private cachedGameState: GameState | undefined;
+	// 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.
+	private gameStateWatcher?: FSWatcher;
+	private gameStateWatchDir?: string;
 
 	/**
 	 * DIAG counters for the "team run doesn't relieve context" investigation.
@@ -235,6 +273,7 @@ export class MegaRuntime {
 		});
 		this.dashboard = new Dashboard(config.stateDir);
 		this.currentStateDir = config.stateDir;
+		this.ensureGameStateWatcher();
 	}
 
 	// ---- per-repo binding -----------------------------------------------------
@@ -252,6 +291,15 @@ export class MegaRuntime {
 		if (key === this.activeRepoRoot) 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,
@@ -520,6 +568,15 @@ export class MegaRuntime {
 			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,
@@ -551,7 +608,31 @@ 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.
@@ -638,6 +719,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;
 	}
 
 	/**
@@ -745,6 +830,91 @@ export class MegaRuntime {
 		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. */
+	private ensureGameStateWatcher(): void {
+		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(): void {
+		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(): GameState {
+		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(): void {
+		this.cachedGameState = undefined;
+	}
+
+	/** S33: player level for game mode — floor(log2(turns+1))+1 (gentle).
+	 *  Defensive: non-finite/negative collapses to 1 (never NaN). */
+	private getTurnLevel(): number {
+		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: number): void {
+		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: string[]): void {
+		this.achievementFlare = true;
+		this.achievementFlareTitles = titles;
+	}
+
 	/** Build the sync onTier callback that paints the live per-tier trace. */
 	makeTierCallback(
 		ctx: ExtensionContext,