pi-mega-compact 0.7.9 → 0.8.1

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,105 @@ 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 {
+			// 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.
+			this.gameStateWatcher = watch(
+				this.currentStateDir,
+				(_eventType, filename) => {
+					if (typeof filename === "string" && filename.startsWith("sqlite.db")) {
+						this.cachedGameState = undefined;
+					}
+				},
+			);
+			this.gameStateWatchDir = this.currentStateDir;
+		} catch {
+			/* non-fatal: missing dir / 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,

package/extensions/mega-runtime/widget.test.ts

@@ -0,0 +1,185 @@
+/**
+ * widget.test.ts — S31 buildWidgetLines render snapshot matrix.
+ *
+ * buildWidgetLines is a free function (no pi runtime needed), so we drive it
+ * directly with a fake WidgetData across the full matrix:
+ *   6 themes × {full,minimal} × {gameMode on/off} × {cachePct<100, >=100}
+ * and assert the S31 invariants:
+ *  (a) transparent theme → no '\x1b[48;' bg fill on any line
+ *  (b) non-transparent themes → at least one line carries '\x1b[48;'
+ *  (c) minimal mode → exactly one content line (between the two panel bars)
+ *  (d) gameMode off → no 'LVL' + no 'MEGA CACHE'
+ *  (e) megaCacheFlare + gameMode on + cachePct>=100 → 'MEGA CACHE' text present
+ *  (f) every line visibleWidth <= the terminal width passed in
+ *
+ * Uses MEGACOMPACT_STATE_DIR + mkdtemp (G7). No pi runtime.
+ */
+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 { visibleWidth } from "@earendil-works/pi-tui";
+import { buildWidgetLines, type WidgetData } from "./widget.js";
+import { THEME_IDS, DEFAULT_THEME, getTheme } from "../../src/config/themes.js";
+
+/** A minimal but complete WidgetData (all required fields populated). The S31
+ *  game-mode fields are overridden per-case. */
+function baseWd(overrides: Partial<WidgetData> = {}): WidgetData {
+	return {
+		version: "0.0.0-test",
+		tierLabel: "low",
+		triggerLabel: "idle",
+		pctStr: "42%",
+		tokStr: "10k",
+		maxStr: "200k",
+		ctxPct: 0.42,
+		chk: 3,
+		agentStr: "",
+		turnStr: "",
+		dedupStr: "12%",
+		sessIn: 1000,
+		sessKept: 800,
+		sTxt: "20",
+		repoIn: 5000,
+		repoKept: 4000,
+		rTxt: "20",
+		repoChk: 9,
+		repoSess: 2,
+		modelStr: "test-model",
+		sinceCompact: null,
+		embedderName: "Trigram",
+		compStr: "1.2x",
+		driftStatus: "ok",
+		agentsActive: false,
+		fresh: false,
+		ticker: [],
+		lastWhy: undefined,
+		tierTrace: undefined,
+		pulsing: false,
+		...overrides,
+	};
+}
+
+const WIDTH = 120;
+
+function contentLines(lines: string[]): string[] {
+	// Strip the top + bottom panel bars; what's left is the content body.
+	return lines.slice(1, lines.length - 1);
+}
+
+describe("buildWidgetLines (S31)", () => {
+	let dir: string;
+	before(() => {
+		dir = mkdtempSync(join(tmpdir(), "mc-widget-"));
+		process.env.MEGACOMPACT_STATE_DIR = dir;
+	});
+	after(() => {
+		delete process.env.MEGACOMPACT_STATE_DIR;
+		rmSync(dir, { recursive: true, force: true });
+	});
+
+	it("null wd → warm-up panel (3 lines, all width-safe)", () => {
+		const lines = buildWidgetLines(null, WIDTH, 0);
+		assert.equal(lines.length, 3);
+		for (const l of lines) assert.ok(visibleWidth(l) <= WIDTH, "width safe");
+	});
+
+	for (const theme of THEME_IDS) {
+		for (const tuiMode of ["full", "minimal"] as const) {
+			for (const gameMode of [false, true] as const) {
+				for (const cachePct of [42, 150] as const) {
+					const flare = cachePct >= 100;
+					const label = `theme=${theme} tui=${tuiMode} game=${gameMode} cache=${cachePct}`;
+					it(label, () => {
+						const wd = baseWd({
+							theme,
+							tuiMode,
+							gameMode,
+							level: 1,
+							cachePct,
+							megaCacheFlare: flare,
+						});
+						const lines = buildWidgetLines(wd, WIDTH, 0);
+						const body = contentLines(lines);
+						const joined = lines.join("\n");
+
+						// (f) every line width <= terminal (truncateToWidth respected)
+						for (const l of lines) {
+							assert.ok(
+								visibleWidth(l) <= WIDTH,
+								`width safe: ${visibleWidth(l)} > ${WIDTH}`,
+							);
+						}
+
+						// (a) transparent theme → no '\x1b[48;' bg fill anywhere
+						if (theme === DEFAULT_THEME) {
+							assert.ok(
+								!joined.includes("\x1b[48;"),
+								`transparent has no 48; bg fill: ${label}`,
+							);
+						} else {
+							// (b) non-transparent themes → their bg SGR appears on some line.
+							// (Themes may use 3-bit bg like \x1b[40m, not just 48;5; form.)
+							const bgParams = getTheme(theme)!.ansi.bg!;
+							const bgEsc = `\x1b[${bgParams}m`;
+							assert.ok(
+								joined.includes(bgEsc),
+								`themed has bg fill ${bgEsc}: ${label}`,
+							);
+						}
+
+						// (c) minimal mode → exactly one content line
+						if (tuiMode === "minimal") {
+							assert.equal(body.length, 1, `minimal one line: ${label}`);
+						}
+
+						// (d) gameMode off → no LVL + no MEGA CACHE
+						if (!gameMode) {
+							assert.ok(!joined.includes("LVL"), `no LVL when off: ${label}`);
+							assert.ok(
+								!joined.includes("MEGA CACHE"),
+								`no MEGA CACHE when off: ${label}`,
+							);
+						} else {
+							// gameMode on → LVL shown (in full mode header, or minimal line)
+							assert.ok(joined.includes("LVL"), `LVL shown when on: ${label}`);
+						}
+
+						// (e) MEGA CACHE flare text appears only when flare + gameMode on
+						const expectMega = flare && gameMode;
+						const hasMega = joined.includes("MEGA CACHE");
+						assert.equal(
+							hasMega,
+							expectMega,
+							`MEGA CACHE flare: ${label} (got ${hasMega}, want ${expectMega})`,
+						);
+					});
+				}
+			}
+		}
+	}
+});
+
+
+describe("buildWidgetLines achievement flare (S35)", () => {
+  const achBase = (overrides: Partial<WidgetData> = {}): WidgetData => baseWd({
+    theme: DEFAULT_THEME, tuiMode: "full", gameMode: true, level: 1, cachePct: 42, ...overrides,
+  });
+  it("achievementFlare + titles -> renders the unlock toast line", () => {
+    const lines = buildWidgetLines(achBase({ achievementFlare: true, achievementFlareTitles: ["First Compact"] }), WIDTH, 0);
+    assert.ok(lines.some((l) => l.includes("Achievement unlocked: First Compact")), "toast line present");
+  });
+  it("achievementFlare off -> no toast line", () => {
+    const lines = buildWidgetLines(achBase({ achievementFlare: false, achievementFlareTitles: ["First Compact"] }), WIDTH, 0);
+    assert.ok(!lines.some((l) => l.includes("Achievement unlocked")), "no toast when flare off");
+  });
+  it("gameMode off -> no toast even if flare set", () => {
+    const lines = buildWidgetLines(achBase({ gameMode: false, achievementFlare: true, achievementFlareTitles: ["X"] }), WIDTH, 0);
+    assert.ok(!lines.some((l) => l.includes("Achievement unlocked")), "no toast when game off");
+  });
+  it("achievement toast is width-safe", () => {
+    const lines = buildWidgetLines(achBase({ achievementFlare: true, achievementFlareTitles: ["First Compact", "Turn Veteran"] }), 60, 0);
+    for (const l of lines) assert.ok(visibleWidth(l) <= 60, "width safe");
+  });
+});

package/extensions/mega-runtime/widget.ts

@@ -14,6 +14,7 @@
 // off-by-one can trip the strict `> width` guard. (Fix for the
 // `Rendered line N exceeds terminal width (W > W-1)` crash.)
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { getTheme, DEFAULT_THEME } from "../../src/config/themes.js";
 
 // ── ANSI palette ───────────────────────────────────────────────────────────
 // The pi TUI's Text component preserves ANSI escape codes (see wrapTextWithAnsi),
@@ -43,16 +44,47 @@ const PULSE = ["◐", "◓", "◑", "◒"];
 // real terminal width with a background fill. NOTE: C.reset is a FULL SGR
 // reset, so we re-apply the panel bg after every reset to keep the background
 // continuous under colored text (and under pi's own trailing reset).
-const PANEL_BG = "\x1b[48;5;236m"; // dark slate panel background
-const PANEL_RST = "\x1b[0m" + PANEL_BG; // reset fg but retain panel bg
+/** Default panel background (dark slate). Used when no theme is threaded or
+ *  the theme is transparent (no bg fill). Parametrized per-render via the
+ *  `panelTheme` arg so game-mode themes can restyle the panel background.
+ *  A transparent theme yields `""` so panelLine/panelBar still call
+ *  truncateToWidth (the width guard holds — empty prefix adds zero cells). */
+const DEFAULT_PANEL_BG = "\x1b[48;5;236m"; // dark slate panel background
+
+/** Resolve the panel-background SGR prefix for a theme id. Transparent themes
+ *  (bg=null) and unknown themes yield `""` (no bg fill) — the width guard in
+ *  panelLine/panelBar still applies via truncateToWidth. */
+function panelBgFor(theme: string | undefined): string {
+	if (!theme || theme === DEFAULT_THEME) return "";
+	const t = getTheme(theme);
+	const bg = t?.ansi.bg;
+	return bg ? `\x1b[${bg}m` : "";
+}
+
+/** Resolve a theme ANSI accent/mega/fg SGR prefix (`\x1b[<params>m`) for the
+ *  given role. Falls back to `""` (no SGR) for transparent/unknown themes so
+ *  game-mode text still renders in the default fg without color noise. */
+function themeAnsi(theme: string | undefined, role: "fg" | "accent" | "mega"): string {
+	const t = theme ? getTheme(theme) : undefined;
+	const params = t?.ansi[role];
+	return params ? `\x1b[${params}m` : "";
+}
+
+/** Emit a full SGR reset, OR `""` if `sgr` is empty (transparent theme). Keeps
+ *  the panel bg continuous by NOT clobbering it with a bare reset when the
+ *  accent/mega prefix was a no-op. */
+function sgrReset(sgr: string): string {
+	return sgr ? "\x1b[0m" : "";
+}
 
 // (Visible-width measurement is delegated to pi-tui's `visibleWidth` — imported
 // above — so our width math can never diverge from pi-tui's render-width check.)
 
 /** Wrap a string (with ANSI codes) to fit within `maxWidth` visible chars.
  *  Splits at │ separators or whitespace when possible. */
-function wrapLine(text: string, maxWidth: number): string[] {
+function wrapLine(text: string, maxWidth: number, panelBg: string): string[] {
 	if (maxWidth <= 0) return [text];
+	const panelRst = "\x1b[0m" + panelBg;
 	const result: string[] = [];
 	let current = "";
 	let currentW = 0;
@@ -60,7 +92,7 @@ function wrapLine(text: string, maxWidth: number): string[] {
 	const segments = text.split("│");
 	for (let i = 0; i < segments.length; i++) {
 		const seg = (i > 0 ? "│" : "") + segments[i];
-		const segW = visibleWidth(PANEL_BG + seg.replace(/\x1b\[0m/g, PANEL_RST));
+		const segW = visibleWidth(panelBg + seg.replace(/\x1b\[0m/g, panelRst));
 		if (currentW + segW <= maxWidth || currentW === 0) {
 			current += seg;
 			currentW += segW;
@@ -74,11 +106,12 @@ function wrapLine(text: string, maxWidth: number): string[] {
 	return result;
 }
 
-function panelLine(content: string, width: number): string {
+function panelLine(content: string, width: number, panelBg: string = DEFAULT_PANEL_BG): string {
 	if (width <= 0) return "";
+	const panelRst = "\x1b[0m" + panelBg;
 	// Apply the panel background; swap every inner full-reset for a reset that
 	// re-applies the bg so the fill stays continuous under colored text.
-	const withBg = PANEL_BG + content.replace(/\x1b\[0m/g, PANEL_RST);
+	const withBg = panelBg + content.replace(/\x1b\[0m/g, panelRst);
 	// truncateToWidth(line, width, "", true) returns EXACTLY `width` visible cells
 	// (by pi-tui's measure), ANSI-preserved, space-padded. It hard-clips overflow
 	// — so even a segment wider than `width` (or a width-rule mismatch) can never
@@ -87,12 +120,12 @@ function panelLine(content: string, width: number): string {
 }
 
 /** A full-width hairline bar (top/bottom border of the panel). */
-function panelBar(width: number, ch = "─"): string {
+function panelBar(width: number, ch = "─", panelBg: string = DEFAULT_PANEL_BG): string {
 	// `─` (U+2500) is narrow (1 cell) in both our measure and pi-tui's, so a
 	// `ch.repeat(width)` bar is exactly `width` cells and already passes the
 	// `> width` guard. truncateToWidth is belt-and-suspenders in case `ch` is
 	// ever swapped for a wide/fullwidth character.
-	return truncateToWidth(PANEL_BG + ch.repeat(Math.max(0, width)), width, "", false) + "\x1b[0m";
+	return truncateToWidth(panelBg + ch.repeat(Math.max(0, width)), width, "", false) + "\x1b[0m";
 }
 
 /** Token-count formatter: M at/above 1e6, k at/above 1e3, raw below.
@@ -177,6 +210,27 @@ export interface WidgetData {
 	lastWhy: string | undefined;
 	tierTrace: string | undefined;
 	pulsing: boolean;
+	// ── S31: game-mode theming + display modes + level + MEGA CACHE flare ──
+	/** Game mode on (shows level + MEGA CACHE flare; hides them when off). */
+	gameMode?: boolean;
+	/** Theme id (src/config/themes). Drives the panel bg + accent/mega ANSI. */
+	theme?: string;
+	/** TUI display mode: 'full' (default) = the full stats panel; 'minimal' = a
+	 *  one-line `LVL n | cache NN%` view flanked by panel bars. */
+	tuiMode?: "full" | "minimal";
+	/** Player level (game-mode). Stub = 1 until S33 wires the real scoring. */
+	level?: number;
+	/** Cache hit rate as a percent (0..100+, may exceed 100 → MEGA CACHE). */
+	cachePct?: number;
+	/** MEGA CACHE flare armed (fires at cachePct >= 100 + gameMode on). Adds the
+	 *  ANSI MEGA CACHE banner + the oopsie gag to the header. */
+	megaCacheFlare?: boolean;
+	/** The peak cache % that armed the flare (for the oopsie toast text). */
+	megaCacheFlarePct?: number;
+	levelUpFlare?: boolean;
+	/** S35: achievement-unlock flare -- renders a one-line toast for one cycle. */
+	achievementFlare?: boolean;
+	achievementFlareTitles?: string[];
 }
 
 // ── buildWidgetLines ───────────────────────────────────────────────────────
@@ -191,20 +245,59 @@ export function buildWidgetLines(
 	width: number,
 	activeAgents: number,
 ): string[] {
+	// Resolve the panel background from the threaded theme (transparent → "",
+	// unknown → default dark slate). Computed once per render; threaded into
+	// every panelLine/panelBar/wrapLine so the bg stays continuous and the width
+	// guard (truncateToWidth) still holds for transparent themes.
+	const panelBg = wd?.theme ? panelBgFor(wd.theme) : DEFAULT_PANEL_BG;
 	if (!wd) {
 		return [
-			panelBar(width, "─"),
-			panelLine(" mega-compact: warming up…", width),
-			panelBar(width, "─"),
+			panelBar(width, "─", panelBg),
+			panelLine(" mega-compact: warming up…", width, panelBg),
+			panelBar(width, "─", panelBg),
+		];
+	}
+	// S31: minimal TUI mode — a single content line `LVL n | cache NN%` flanked
+	// by panel bars. Built through the same panelLine/panelBar helpers so the
+	// width guard + theme bg apply identically to the full panel. Level is shown
+	// only when game mode is on (otherwise just the cache %).
+	if (wd.tuiMode === "minimal") {
+		const lvl = wd.gameMode ? wd.level ?? 1 : undefined;
+		const cachePct = wd.cachePct ?? 0;
+		const cacheStr = `${Math.round(cachePct * 10) / 10}%`;
+		const accent = themeAnsi(wd.theme, "accent");
+		const mega = themeAnsi(wd.theme, "mega");
+		const megaFlare =
+			wd.gameMode && wd.megaCacheFlare && cachePct >= 100
+				? ` ${mega}MEGA CACHE${sgrReset(mega)}`
+				: "";
+		const body =
+			lvl != null
+				? `${accent}${wd.gameMode && wd.levelUpFlare ? "\x1b[5m" : ""}LVL ${lvl}${wd.gameMode && wd.levelUpFlare ? "\x1b[0m" : ""}${sgrReset(accent)} ${C.dim}|${C.reset} cache ${cacheStr}${megaFlare}`
+				: `cache ${cacheStr}${megaFlare}`;
+		return [
+			panelBar(width, "─", panelBg),
+			panelLine(` ${body}`, width, panelBg),
+			panelBar(width, "─", panelBg),
 		];
 	}
 	const pulse = wd.pulsing
 		? `${C.cyan}${PULSE[Math.floor(Date.now() / 250) % PULSE.length]}${C.reset} `
 		: "";
 	const sep = ` ${C.dim}│${C.reset} `;
+	// S31: game-mode header prefix — `LVL n` (accent) prepended to content[0],
+	// and a MEGA CACHE flare (mega ansi) + oopsie gag appended when armed. Both
+	// hidden when game mode is off (keeps the legacy panel byte-for-byte).
+	const lvlPrefix = wd.gameMode
+		? `${themeAnsi(wd.theme, "accent")}${wd.gameMode && wd.levelUpFlare ? "\x1b[5m" : ""}LVL ${wd.level ?? 1}${wd.gameMode && wd.levelUpFlare ? "\x1b[0m" : ""}${sgrReset(themeAnsi(wd.theme, "accent"))} `
+		: "";
+	const megaFlareSuffix =
+		wd.gameMode && wd.megaCacheFlare && (wd.cachePct ?? 0) >= 100
+			? `${sep}${themeAnsi(wd.theme, "mega")}MEGA CACHE! (oops, you cached so hard the dedup caught fire)${sgrReset(themeAnsi(wd.theme, "mega"))}`
+			: "";
 	// Build one long content line — let terminal wrap it naturally
 	const content = [
-		`${C.amber}⚡ ${wd.tierLabel}${C.reset} v${C.bold}${wd.version}${C.reset} ${ramp(wd.ctxPct, 20)} ${C.bold}${wd.pctStr}${C.reset} ${wd.tokStr}/${wd.maxStr}`,
+		`${lvlPrefix}${C.amber}⚡ ${wd.tierLabel}${C.reset} v${C.bold}${wd.version}${C.reset} ${ramp(wd.ctxPct, 20)} ${C.bold}${wd.pctStr}${C.reset} ${wd.tokStr}/${wd.maxStr}${megaFlareSuffix}`,
 		wd.triggerLabel,
 		`${C.cyan}${wd.modelStr}${C.reset}`,
 		`${wd.chk} chk${wd.agentStr}${wd.turnStr}`,
@@ -217,10 +310,10 @@ export function buildWidgetLines(
 		`${C.gray}compact${C.reset} ${sinceCompactStr(wd.sinceCompact)}`,
 	].join(sep);
 	// Wrap to terminal width and pad each line
-	const wrapped = wrapLine(content, width - 2); // 2-char indent
+	const wrapped = wrapLine(content, width - 2, panelBg); // 2-char indent
 	const lines: string[] = [
-		panelBar(width, "─"),
-		...wrapped.map((l) => panelLine(l, width)),
+		panelBar(width, "─", panelBg),
+		...wrapped.map((l) => panelLine(l, width, panelBg)),
 	];
 	// L4 — agents block (S27, count + status; per-agent tokens gated on P0)
 	if (wd.agentsActive) {
@@ -228,12 +321,13 @@ export function buildWidgetLines(
 			panelLine(
 				`   ${C.cyan}🤖 ${activeAgents} active${wd.turnStr}${C.reset}`,
 				width,
+				panelBg,
 			),
 		);
 	}
 	// L5 — live ticker / activity (♻ deduped … why, or tier trace, or pulsing)
 	if (wd.tierTrace && wd.fresh) {
-		lines.push(panelLine(`   ${pulse}${wd.tierTrace}`, width));
+		lines.push(panelLine(`   ${pulse}${wd.tierTrace}`, width, panelBg));
 	} else if (wd.ticker.length > 0) {
 		const step = Math.floor(Date.now() / 250);
 		const idx = wd.ticker.length - 1 - (step % wd.ticker.length);
@@ -247,12 +341,19 @@ export function buildWidgetLines(
 			panelLine(
 				`   ${wd.fresh ? C.teal : C.dim}${head}${why}${more}${C.reset}`,
 				width,
+				panelBg,
 			),
 		);
 	} else if (wd.pulsing) {
-		lines.push(panelLine(`   ${pulse}${C.teal}compacting…${C.reset}`, width));
+		lines.push(panelLine(`   ${pulse}${C.teal}compacting…${C.reset}`, width, panelBg));
+	}
+	// S35: achievement-unlock toast (one-line, accent) -- fires for one render cycle.
+	if (wd.gameMode && wd.achievementFlare && wd.achievementFlareTitles?.length) {
+		const accentSgr = themeAnsi(wd.theme, "accent");
+		const titlesStr = wd.achievementFlareTitles.join(", ");
+		lines.push(panelLine(`   ${accentSgr}🏆 Achievement unlocked: ${titlesStr}${sgrReset(accentSgr)}`, width, panelBg));
 	}
 	// bottom border
-	lines.push(panelBar(width, "─"));
+	lines.push(panelBar(width, "─", panelBg));
 	return lines;
 }