pi-mega-compact 0.8.23 → 0.8.24

package/extensions/mega-runtime/bind-repo.ts

@@ -0,0 +1,81 @@
+/**
+ * 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";
+import type { MegaConfig } from "../mega-config.js";
+
+// ---------------------------------------------------------------------- types
+
+export interface BindRepoContext {
+	readonly config: MegaConfig;
+	activeRepoRoot: string | null;
+	currentStateDir: string;
+	store: VectorStore;
+	dashboard: Dashboard;
+	logger: Logger;
+	cachedGameState: import("../../src/store/sqlite.js").GameState | undefined;
+	gameStateBump: number;
+	ensureGameStateWatcher(): void;
+}
+
+// ------------------------------------------------------------------ bindRepo
+
+export function bindRepoImpl(ctx: BindRepoContext, cwd: string | undefined): string {
+	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/extensions/mega-runtime/capture-model.ts

@@ -0,0 +1,101 @@
+/**
+ * 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 type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { resolveRepoRoot } from "../mega-config.js";
+import { recordModelSnapshot, recordRepoModel } from "../../src/store/sqlite.js";
+import type { ModelSnapshot } from "../../src/store/sqlite.js";
+
+// ---------------------------------------------------------------------- types
+
+export interface CaptureModelContext {
+	readonly currentStateDir: string;
+	currentModel: (ModelSnapshot & { capturedAt: number }) | null | undefined;
+	diagCaptureModelCalls: number;
+	diagCaptureModelFails: number;
+	appendEvent(event: string, fields: Record<string, unknown>): void;
+}
+
+// -------------------------------------------------------------- captureModel
+
+export function captureModelImpl(ctx: CaptureModelContext, ectx: ExtensionContext): void {
+	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: string | null = null;
+	try {
+		providerName =
+			ectx.modelRegistry?.getProviderDisplayName(m.provider) ?? null;
+	} catch {
+		/* optional */
+	}
+	const snap: Omit<ModelSnapshot, "capturedAt"> = {
+		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/extensions/mega-runtime/dashboard-snapshot.ts

@@ -0,0 +1,173 @@
+/**
+ * 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.
+ */
+
+import type { DashboardSnapshot } from "../mega-dashboard.js";
+
+// ---------------------------------------------------------------------- types
+
+export interface SnapshotBuildContext {
+	// Config
+	readonly config: {
+		readonly tier: string;
+		readonly fastGatePct: number;
+		readonly tierPct: number | null;
+		readonly anchorUserMessages: number;
+		readonly preserveRecent: number;
+		readonly auto: boolean;
+		readonly autoInline: boolean;
+	};
+	// Runtime
+	readonly rt: {
+		readonly sessionId: string;
+		readonly persistedThisSession: boolean;
+		readonly lastCheckpointId: string | undefined;
+		readonly lastCompactedFrom: number;
+		readonly lastCompactedTokens: number;
+		readonly tokensSaved: number;
+		readonly compactCount: number;
+		readonly recallInjections: number;
+		readonly cacheHitTokens: number;
+		readonly dedupSkips: number;
+		readonly dedupAttempts: number;
+	};
+	// Live metrics
+	readonly pressureBand: string;
+	readonly pressure: number;
+	readonly effectiveThreshold: number;
+	readonly statusKey: string | undefined;
+	readonly lastCtxTokens: number | null;
+	readonly lastCtxPercent: number | null;
+	readonly lastCtxWindow: number;
+	readonly diagCtxFastGate: number;
+	readonly diagLiveTrimFires: number;
+	readonly diagLiveTrimReplays: number;
+	readonly errorRetryCount: number;
+	readonly consecutiveErrors: number;
+	readonly ERROR_RETRY_MAX_CONSECUTIVE: number;
+	readonly errorRetryHardStop: boolean;
+	readonly activeAgents: number;
+	readonly currentTurn: number;
+	readonly currentModel: { providerName: string | null; modelId: string; provider: string; inputRate: number; outputRate: number } | null | undefined;
+	// Store stats (precomputed by caller)
+	readonly st: { checkpointCount: number; totalTokenEstimate: number; originalTokens: number; tokensSaved: number; injectedCount: number; dedupHitRate: number; storageDedupRate: number; dedupAttempts: number; dedupCollapsed: number };
+	readonly repo: { checkpointCount: number; totalTokenEstimate: number; originalTokens: number; tokensSaved: number; sessionCount: number; dedupAttempts: number; dedupCollapsed: number; storageDedupRate: number };
+	readonly di: { regionsRetained: number; compressedOriginalBytes: number; duplicatesCollapsed: number; bytesPermanentlyDeleted: number };
+}
+
+// ---------------------------------------------------------- buildDashboardSnapshot
+
+/** Build the DashboardSnapshot object from precomputed store/live metrics.
+ *  Pure — no I/O, no side effects. */
+export function buildDashboardSnapshot(ctx: SnapshotBuildContext): DashboardSnapshot {
+	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/extensions/mega-runtime/effects.ts

@@ -0,0 +1,129 @@
+/**
+ * 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 type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { C } from "./widget.js";
+import type { TickerEntry } from "./widget.js";
+
+// ---------------------------------------------------------------------- types
+
+export interface EffectsContext {
+	// Effect state
+	activeEffect: { type: "pulse" | "flash"; role: "accent" | "mega" | "red"; startedAt: number; durationMs: number } | null;
+	// Flare state
+	megaCacheFlare: boolean;
+	megaCacheFlarePct: number;
+	achievementFlare: boolean;
+	achievementFlareTitles: string[];
+	// Tier trace
+	tierTrace: string | undefined;
+	// Ticker
+	ticker: TickerEntry[];
+	readonly TICKER_MAX: number;
+	lastActivityAt: number;
+	// Callback — the tier callback calls snapshot() to trigger a widget refresh
+	snapshot(ctx: ExtensionContext): void;
+}
+
+// --------------------------------------------------------------- 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: EffectsContext,
+	type: "pulse" | "flash",
+	role: "accent" | "mega" | "red",
+	durationMs: number,
+): void {
+	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: EffectsContext, peakPct: number): void {
+	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: EffectsContext, titles: string[]): void {
+	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: EffectsContext,
+	ectx: ExtensionContext,
+): (ev: {
+	tier: "L0" | "L1" | "L2" | "new";
+	status: "scanning" | "deduped" | "passed" | "stored";
+	detail?: string;
+}) => void {
+	const order: Array<"L0" | "L1" | "L2" | "new"> = ["L0", "L1", "L2", "new"];
+	const seen = new Map<string, string>();
+	const glyph = (status: string) =>
+		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: string[] = [];
+		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: EffectsContext, text: string): void {
+	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/extensions/mega-runtime/engine-view.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 type { AgentMessage } from "@earendil-works/pi-agent-core";
+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: AgentMessage[],
+): ReturnType<typeof toEngineMessages> {
+	return toEngineMessages(messages);
+}

package/extensions/mega-runtime/game-state.ts

@@ -0,0 +1,149 @@
+/**
+ * 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 type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { watch } from "node:fs";
+import { getGameState, type GameState } from "../../src/store/sqlite.js";
+import { getTheme } from "../../src/config/themes.js";
+import { disposePerf, type PerfContext } from "./perf.js";
+
+export interface GameWatcherLike {
+	close(): void;
+}
+
+export interface GameStateContext {
+	readonly currentStateDir: string;
+	cachedGameState: GameState | undefined;
+	gameStateBump: number;
+	gameStateWatcher?: GameWatcherLike;
+	gameStateWatchDir?: string;
+	lastWidgetCtx?: ExtensionContext;
+	widgetData: import("./widget.js").WidgetData | null;
+}
+
+export interface GameStateViewApi {
+	renderWidget(ctx: ExtensionContext): void;
+}
+
+export function getCachedGameStateImpl(self: GameStateContext): GameState {
+	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: GameStateContext,
+	view: GameStateViewApi,
+	ctx: ExtensionContext,
+): void {
+	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: GameStateContext): void {
+	self.cachedGameState = undefined;
+	self.gameStateBump++;
+}
+
+// ------------------------------------------------------------- disposeRuntime
+
+/**
+ * The slice of `MegaRuntime` dispose() touches: the S32 fs.watch game-state
+ * watcher (GameStateContext) plus the v0.8.8 perf cpu/mem sampling interval
+ * (PerfContext). `MegaRuntime` satisfies this structurally.
+ */
+export interface DisposeRuntimeContext extends GameStateContext, PerfContext {}
+
+/** 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: DisposeRuntimeContext): void {
+	if (self.gameStateWatcher) {
+		try { self.gameStateWatcher.close(); } catch { /* non-fatal */ }
+		self.gameStateWatcher = undefined;
+		self.gameStateWatchDir = undefined;
+	}
+	disposePerf(self);
+}
+
+export function ensureGameStateWatcherImpl(self: GameStateContext, view: GameStateViewApi): void {
+	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/extensions/mega-runtime/get-state-dir.ts

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+
+// ---------------------------------------------------------------------- types
+
+/** The slice of `MegaRuntime` getStateDir reads. */
+export interface GetStateDirContext {
+	readonly currentStateDir: string;
+}
+
+// --------------------------------------------------------------- getStateDir
+
+/** S21: state dir of the currently bound repo (where memories live). */
+export function getStateDirImpl(self: GetStateDirContext): string {
+	return self.currentStateDir;
+}