pi-mega-compact 0.21.2 → 0.21.4

package/extensions/mega-config.ts

@@ -234,6 +234,11 @@ export function loadConfig(): MegaConfig {
 		// 3WF-1: TriggerGuard — guarantee a staged recall block on every context
 		// event even when session_start never fires. Default ON; OFF = byte-identical.
 		threeWayFailback: envBool("MEGACOMPACT_THREE_WAY_FAILBACK", true),
+		// Sprint A: Mega↔ithacus bridge — gate the child extension + bridge usage.
+		// Default ON; OFF (=0/`=false`) = byte-identical pre-bridge behavior.
+		// Runtime reads envBool(plain key), mirroring threeWayFailback (plain-write
+		// convention, not _DISABLED).
+		ithacusBridge: envBool("MEGACOMPACT_ITHACUS_BRIDGE", true),
 		// 3WF-2: ThrashGuard re-arm budget as a fraction of effectiveThreshold.
 		// 0.10 default (10% of the effective threshold) — see mega-config-types.
 		// Clamped to [0.01, 0.5]: below 1% the guard is almost never armed (any

package/extensions/mega-events/agent-handlers/turnEndHandler/recordTurnRow.ts

@@ -8,7 +8,7 @@
  */
 import type { MegaRuntime } from "../../../mega-runtime.js";
 import type { MegaConfig } from "../../../mega-config.js";
-import { ensureConversationIdFor, recordTurnWrite } from "../../../mega-turn-store.js";
+import { ensureConversationIdFor, recordTurnWrite, turnReaderFor } from "../../../mega-turn-store.js";
 import type { TurnEndEvent } from "./event.js";
 
 /** S43: record one turn row with the cached metrics. Best-effort + non-fatal. */
@@ -28,12 +28,18 @@ export function recordTurnRow(
 			runtime.rt.sessionId,
 			runtime.currentStateDir,
 		);
+		// S49R: store the conversation-monotonic index (MAX+1) instead of the
+		// per-session event.turnIndex, which restarts at 0 on resume and would
+		// collide with UNIQUE(conversation_id, turn_index). Carry the session
+		// counter as sessionTurnIndex for the raw_transcript metrics join.
+		const turnIndex = turnReaderFor(runtime.currentStateDir).nextTurnIndexFor(convId);
 		recordTurnWrite(
 			config,
 			{
 				conversationId: convId,
 				sessionId: runtime.rt.sessionId,
-				turnIndex: event.turnIndex,
+				turnIndex,
+				sessionTurnIndex: event.turnIndex,
 				role: (event as { role?: string }).role ?? "assistant",
 				endedAt: Date.now(),
 				startedAt: undefined,
@@ -57,5 +63,9 @@ export function recordTurnRow(
 			error: e instanceof Error ? e.message : String(e),
 			stack: e instanceof Error ? e.stack?.split("\n").slice(0, 3).join(" | ") : undefined,
 		});
+		// Sprint H (Finding 3 / Option A): the turn-row write is an internal
+		// store-write failure the API-error `errorRate` ring never sees. Feed the
+		// separate `storeErrorRate` 6th axis.
+		runtime.recordInternalError("store_write");
 	}
 }

package/extensions/mega-events/context-handler/afterCompact.ts

@@ -77,6 +77,8 @@ export async function persistEpochAndMaintain(
 			writeCheckpointEpoch(db, epoch);
 		} catch (e) {
 			runtime.logger.warn("planv2-epoch-fail", { error: String(e) });
+			// Sprint H (Option A): checkpoint_epoch write failure.
+			runtime.recordInternalError("store_write");
 		}
 	}
 
@@ -181,6 +183,9 @@ export async function persistEpochAndMaintain(
 				runtime.logger.warn("wiki_rebuild_failed", {
 					error: String(wikiErr),
 				});
+				// Sprint H (Option A): wiki rebuild writes (topic model / overrides)
+				// to the isolated store — internal store write.
+				runtime.recordInternalError("store_write");
 			}
 
 			// D1: seed the topic model from raw_transcript when context_chunks is
@@ -263,6 +268,9 @@ export async function persistEpochAndMaintain(
 				runtime.logger.warn("wiki_seed_failed", {
 					error: String(seedErr),
 				});
+				// Sprint H (Option A): wiki seed rebuild writes to the isolated
+				// store — internal store write.
+				runtime.recordInternalError("store_write");
 			}
 
 				// S27 Task 6: Fire-and-forget dedup pipeline.
@@ -280,6 +288,9 @@ export async function persistEpochAndMaintain(
 				}
 		} catch (e) {
 			runtime.logger.warn("db-mirror-epoch-fail", { error: String(e) });
+			// Sprint H (Option A): db-mirror downstream maintenance writes
+			// (stamp turns epoch / wiki / seed / dedup) — internal store writes.
+			runtime.recordInternalError("store_write");
 		}
 	}
 

package/extensions/mega-events/context-handler/dbMirrorAppend.ts

@@ -105,6 +105,9 @@ export function appendMirrorAndLedger(
 			}
 		} catch (e) {
 			runtime.logger.warn("db-mirror-append-fail", { error: String(e) });
+			// Sprint H (Option A): raw_transcript / thread / tool_results write
+			// failure — internal store write. Feed the `storeErrorRate` axis.
+			runtime.recordInternalError("store_write");
 		}
 	}
 
@@ -121,5 +124,10 @@ export function appendMirrorAndLedger(
 		);
 	} catch (e) {
 		runtime.logger.warn("vc1b-ledger-append-fail", { error: String(e) });
+		// Sprint H (Option A): the v2 vector-cortex ledger append is a cortex
+		// write — this is the host-side hook for the cortex seam (the cortex
+		// contract forbids the store from holding a runtime handle, so the ring
+		// push happens here in the adapter, not inside src/vector-cortex).
+		runtime.recordInternalError("vector_index");
 	}
 }

package/extensions/mega-events/health-handler.ts

@@ -10,6 +10,7 @@
  */
 
 import type { MegaRuntime } from "../mega-runtime.js";
+import { RING_MAX } from "../mega-runtime/runtime.js";
 import type { MegaConfig } from "../mega-config.js";
 import { defaultEmbedder } from "../../src/embedder.js";
 import { computeOutputQuality } from "../../src/contextHealth/outputQuality.js";
@@ -34,8 +35,6 @@ import {
 } from "../../src/store/sqlite/context-health.js";
 import { getHealthMitigate } from "../../src/store/sqlite/meta.js";
 
-const RING_MAX = 5;
-
 /** Extract assistant text from the turn_end event message. */
 function extractAssistantText(event: { message?: { role?: string; content?: unknown } }): string {
 	const msg = event.message;
@@ -108,9 +107,17 @@ export function handleTurnEndHealth(
 			drift = computeDriftScore(topic, error, prefix);
 		}
 
-		// Error rate sub-score (1 = no errors)
+		// Error rate sub-score (1 = no errors) — API-retry errors only.
 		const errorScore = computeErrorEscalation(runtime.recentErrorCategories);
 
+		// Sprint H (B2): store-error sub-score (1 = no store-write failures).
+		// Distinct from errorScore — internal store/service-write failures
+		// (turn rows, recall, dbMirror, ledger, epoch, stats, memory consolidate,
+		// compact persist, vector index, embedder, migration) never reach the
+		// API-retry errorRate ring. Mirrors computeErrorEscalation: 1 - (n/RING_MAX).
+		const recentInternalCount = Math.min(runtime.recentInternalErrors.length, RING_MAX);
+		const storeErrorScore = 1 - recentInternalCount / RING_MAX;
+
 		// Cache health (from perf-handler)
 		const cacheHealth = runtime.rt._lastCacheHealthScore ?? 1.0;
 
@@ -154,6 +161,7 @@ export function handleTurnEndHealth(
 			errorRate: errorScore,
 			cacheHealth,
 			cachePoison,
+			storeErrorRate: storeErrorScore,
 		};
 		const composite = computeHealthScore(sub);
 
@@ -168,6 +176,7 @@ export function handleTurnEndHealth(
 			cacheHealth,
 			cachePoison,
 			composite,
+			storeErrorScore,
 			modelId: runtime.currentModel?.modelId,
 			repetitionRatio,
 			coherenceScore,
@@ -180,6 +189,7 @@ export function handleTurnEndHealth(
 			drift,
 			outputQuality,
 			errorRate: errorScore,
+			storeErrorRate: storeErrorScore,
 			cacheHealth,
 			cachePoison,
 			turnIndex: event.turnIndex,

package/extensions/mega-events/session-handlers.ts

@@ -111,6 +111,7 @@ export function registerSessionHandlers(
 				runtime.logger.info("db-auto-maintain", { result: m });
 		} catch (e) {
 			runtime.logger.warn("db-auto-maintain-fail", { error: String(e) });
+			runtime.recordInternalError("store_write");
 		}
 		runtime.dashboard.event("session_start", {
 			reason: event.reason,

package/extensions/mega-pipeline/compact/run.ts

@@ -166,6 +166,9 @@ function doCompact(
 		touchSession(sid, root, runtime.currentStateDir);
 		logDaily(sid, "compact", result.checkpointId, saved, runtime.currentStateDir);
 	} catch {
+		// Sprint H (Option A): session-activity / daily-log write is an internal
+		// store-write failure — feed the separate `storeErrorRate` axis.
+		runtime.recordInternalError("store_write");
 		/* non-fatal: stats bookkeeping only */
 	}
 
@@ -183,10 +186,14 @@ function doCompact(
 					if (n > 0) runtime.pushTicker(`${C.green}∫${C.reset} consolidated ${n} memory dup${n === 1 ? "" : "s"}`);
 				},
 				() => {
+					// Sprint H (Option A): memory-consolidation write failure.
+					runtime.recordInternalError("store_write");
 					/* swallow: consolidate failures must never surface to the user */
 				},
 			);
 		} catch {
+			// Sprint H (Option A): memory-consolidation write failure (sync throw).
+			runtime.recordInternalError("store_write");
 			/* non-fatal */
 		}
 	}
@@ -259,6 +266,8 @@ function doCompact(
 				}
 			}
 		} catch {
+			// Sprint H (Option A): RAPTOR tree-refresh write failure.
+			runtime.recordInternalError("vector_index");
 			/* non-fatal: tree refresh never blocks a compaction */
 		}
 	}
@@ -278,6 +287,8 @@ function doCompact(
 					latest.checkpointId,
 					latest.embedding,
 				).catch(() => {
+					// Sprint H (Option A): async global vector-index upsert failure.
+					runtime.recordInternalError("vector_index");
 					/* non-fatal: index refresh never blocks a compaction */
 				});
 			}

package/extensions/mega-runtime/helpers.ts

@@ -9,6 +9,7 @@
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readFileSync } from "node:fs";
+import { normalizeSessionId } from "../../src/store.js";
 
 // ── Public string constants ────────────────────────────────────────────────
 // Exported via the barrel — consumers (mega-events.ts, mega-pipeline.ts) use
@@ -111,3 +112,48 @@ export function ownVersion(): string {
 	CACHED_VERSION = v;
 	return v;
 }
+
+/**
+ * createSessionRuntime() — the default per-session runtime state.
+ *
+ * Extracted from runtime.ts (delegate-shell split) so the MegaRuntime class
+ * stays a field-declarations + 1-line-delegate shell. Returns a fresh
+ * SessionRuntime for each session (reset on session_start / session_tree).
+ * Mirrors the neuralwatt-mcr per-session closure.
+ */
+export function createSessionRuntime(): SessionRuntime {
+	return {
+		sessionId: normalizeSessionId(undefined),
+		persistedThisSession: false,
+		lastCheckpointId: undefined,
+		lastCompactedFrom: 0,
+		lastCompactedTokens: 0,
+		dedupSkips: 0,
+		dedupAttempts: 0,
+		tokensSaved: 0,
+		lastCompactAt: null,
+		lastRecallAt: null,
+		lastInjectAt: null,
+		_prevCacheHitPct: null,
+		_lastCacheHealthScore: undefined,
+		lastNativeCompactAt: null,
+		compactCount: 0,
+		recallInjections: 0,
+		cacheHitTokens: 0,
+		lengthStopPending: false,
+		errorRetryCount: 0,
+		errorRetryUntil: 0,
+		consecutiveErrors: 0,
+		lastErrorRetryAt: 0,
+		retryNudgePending: false,
+		errorRetrySessionCount: 0,
+		lastErrorText: undefined,
+		errorTextRepeatCount: 0,
+		poisonedAdviseSent: false,
+		providerOutageAdvised: false,
+		poisonedCompactSignatures: new Set(),
+		recallInjectedThisTurn: false,
+		poisonedCount: 0,
+		extensionInitiatedTurn: false,
+	};
+}

package/extensions/mega-runtime/internal-errors.ts

@@ -0,0 +1,30 @@
+/**
+ * internal-errors.ts — Sprint H (Finding 3 / Option A) instrumentation.
+ *
+ * Free-function + context-interface sibling of `runtime.ts` (delegate-shell
+ * pattern). Holds the body of `recordInternalError(category)` so the
+ * `MegaRuntime` class stays a field-declarations + 1-line-delegate shell.
+ *
+ * Pushes a store/service-write failure category into the `recentInternalErrors`
+ * ring (capped at RING_MAX, shift when over). Called AT each failure emit site
+ * (see the §2.3a audit in docs/specs/c2-resume-and-health-fixes.md) — never by
+ * a central events.log filter. Feeds the distinct `storeErrorRate` 6th health
+ * axis (committed separately in Sprint H axis work).
+ */
+import type { MegaRuntime } from "./runtime.js";
+
+/**
+ * RING_MAX — the cap for the rolling health ring buffers
+ * (`recentTurnEmbeddings`, `recentErrorCategories`, `recentInternalErrors`).
+ * Defined here (with the ring writer) and re-exported from runtime.ts so the
+ * ring + its writer live together; health-handler.ts imports it.
+ */
+export const RING_MAX = 5;
+
+/** Push a category into the internal-error ring. Mirrors `recentErrorCategories`. */
+export function recordInternalErrorImpl(rt: MegaRuntime, category: string): void {
+	rt.recentInternalErrors.push(category);
+	if (rt.recentInternalErrors.length > RING_MAX) {
+		rt.recentInternalErrors.shift();
+	}
+}

package/extensions/mega-runtime/runtime-instrumentation.ts

@@ -0,0 +1,195 @@
+/**
+ * runtime-instrumentation.ts — base class holding MegaRuntime's field
+ * declarations (diagnostic counters + context-health ring buffers + the Sprint-H
+ * internal-error ring + live display/cache-stability state).
+ *
+ * Extracted from runtime.ts (delegate-shell split) so the MegaRuntime class
+ * stays a field-declarations + 1-line-delegate shell. As a base class, the
+ * field NAMES are unchanged (`this.diagLiveTrimFires`, `this.trimCache`, etc.) —
+ * call sites across the codebase and tests need no edits.
+ */
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ModelSnapshot, GameState } from "../../src/store/sqlite.js";
+import type { TickerEntry, WidgetData } from "./widget.js";
+import type { FSWatcher } from "node:fs";
+
+/**
+ * DIAG counters for the "team run doesn't relieve context" investigation.
+ * Plain integers, incremented at the three compaction decision points. They
+ * let a headless test drive the real event handlers and assert the firing
+ * cadence without scraping log files. Inert in production (the live-trim and
+ * before-compact probes also emit logger.info, but these counters are always
+ * updated and cost nothing).
+ */
+export class RuntimeInstrumentation {
+	diagLiveTrimFires = 0; // context handler returned a trimmed view
+	diagLiveTrimReplays = 0; // v0.8.6: trim view returned via cached replay (skipped re-compact)
+	diagBeforeCompactFires = 0; // session_before_compact handler entered
+	diagBeforeCompactSupplied = 0; // session_before_compact supplied our trim
+	diagAgentEndIdle = 0; // agent_end with activeAgents===0
+	diagAgentEndDurable = 0; // agent_end fired ctx.compact() (mid-run durable trim)
+	diagAgentEndDurableSkipRecent = 0; // agent_end skipped ctx.compact() — compaction in last 10s (race guard)
+	// Per-skip-path counters for the team-run diagnosis.
+	diagCtxFastGate = 0; // returned at token fast-gate (below threshold)
+	diagCtxNoCompact = 0; // autoCompactCheck().shouldCompact === false
+	diagCtxDebounce = 0; // debounceUntil not yet elapsed
+	diagCtxRunSkipped = 0; // runCompact() returned skipped
+	diagCtxCutNull = 0; // computeLiveTrimCut returned null (anchor/boundary)
+	diagCtxThrown = 0; // live-trim try threw (caught)
+
+	// Context health instrumentation (v0.12): rolling ring buffers for
+	// drift detection + cache poison Layer 1 hash baseline.
+	recentTurnEmbeddings: number[][] = [];
+	recentErrorCategories: (string | null)[] = [];
+	lastPrefixHash: string | null = null;
+	lastErrorCategory: string | null = null;
+
+	// Sprint H (Finding 3): a SEPARATE internal-error ring fed by explicit
+	// `recordInternalError(category)` calls at each store/service-write failure
+	// emit site (Option A — NOT a central events.log filter). This captures
+	// internal store-write failures which the API-error `errorRate` ring never
+	// sees. The health-handler computes a distinct `storeErrorRate` 6th axis.
+	// Mirrors `recentErrorCategories` / `lastErrorCategory` exactly (cap = RING_MAX).
+	recentInternalErrors: string[] = [];
+
+	/**
+	 * S26 capture instrumentation: the "model_snapshots empty → $0.00 cost card"
+	 * bug was invisible because captureModel swallowed the DB write in a silent
+	 * `catch {}`. These always-updated counters (zero cost) let a headless test or
+	 * a live capture tell whether captureModel ran and whether the snapshot landed.
+	 */
+	diagCaptureModelCalls = 0; // captureModel entered with a populated ctx.model
+	diagCaptureModelFails = 0; // recordModelSnapshot threw → model_snapshots stays empty
+
+	// ── Live display / cache-stability state (moved from runtime.ts shell) ────
+
+	// v0.8.6 cache-stability: the cached live-trim view for the current
+	// compaction epoch. Set after a fresh runCompact + computeLiveTrimCut, and
+	// replayed verbatim on subsequent gated context events in the SAME epoch
+	// (same checkpointId) so the provider KV-cache prefix stays stable instead
+	// of being invalidated by a freshly regenerated summary + sentinel every
+	// fire. Invalidated on session restart (resetRuntime) and on any native
+	// durable compaction (session_compact) that truncates the transcript.
+	trimCache: {
+		checkpointId: string;
+		cut: number;
+		summaryAgentMsg: AgentMessage;
+		ctxPct: number | null;
+		ctxTokens: number | null;
+	} | null = null;
+	debounceUntil = 0;
+	// S16: debounce for the agent_end resume nudge (avoid busy-loops).
+	resumeNudgeUntil = 0;
+	// 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;
+	/** v0.8.3: ambient effect state for animated panel borders keyed off
+	 *  status transitions (level-up, mega-cache overshoot, achievement unlock,
+	 *  compaction start). Threaded into widgetData as `activeEffect`; the widget
+	 *  computes the per-frame phase from startedAt vs Date.now() (non-expired).
+	 *  Null when idle/expired. */
+	activeEffect: { type: "pulse" | "flash"; role: "accent" | "mega" | "red"; startedAt: number; durationMs: number } | null = null;
+	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;
+	// S21: memory recall block, parallel to pendingRecallBlock. Same one-shot
+	// semantics; composed with the checkpoint block in before_agent_start.
+	pendingMemoryRecallBlock: string | undefined;
+	statusKey: string | undefined; // current status text for dashboard
+	// Active model/provider (for real cost estimation). Captured from ctx.model
+	// on model_select + session_start; persisted to SQL so cost + the dashboard
+	// can read it without a live ctx.
+	currentModel: ModelSnapshot | undefined;
+	// Live "what it's doing right now" timestamp, used for the fresh-window.
+	lastActivityAt = 0;
+	// Live per-tier dedup trace (Phase 1): e.g. "L0 ✓ → L1 ✓ → L2 0.91 → stored".
+	// Built from the store's sync onTier callback during a compaction so the user
+	// watches each tier evaluate in real time. Cleared once the outcome settles.
+	tierTrace: string | undefined;
+	// Phase 3 — standout toolbar state.
+	// Recall/activity ticker: a small ring buffer (≤5) of recent compact/recall
+	// events so the widget shows a live history instead of a single last action.
+	ticker: TickerEntry[] = [];
+	readonly TICKER_MAX = 5;
+	// Pulsing status: set true while a compaction is in flight, cleared on result.
+	pulsing = false;
+	// S21.2: set by `applyMemoryOps` when a memory add/replace/remove lands in
+	// the current compaction. The pipeline reads this after a successful compact
+	// to decide whether to fire `consolidateMemories` (skip the work entirely
+	// when no memory rows changed).
+	memoriesTouchedThisCompaction = 0;
+	// Rolling "saved" goal for the progress bar — grows as we save more, so the
+	// bar always has a meaningful denominator (never sits at 100% forever).
+	savedGoal = 50_000;
+	// Last explain-why line (dedup reason / anchor-kept / superseded), surfaced
+	// while fresh.
+	lastWhy: string | undefined = undefined;
+	// v0.8.8 Perf dashboard instrumentation: turn/provider start timestamps +
+	// the 5s cpu/mem interval handle (one per MegaRuntime, cleared in dispose()).
+	perfTurnStart = 0;
+	perfProviderStart = 0;
+	perfCpuInterval: ReturnType<typeof setInterval> | null = null;
+	perfCpuBaseline: { user: number; sys: number } | undefined;
+
+	// Context tracking for the dashboard (updated in the context handler).
+	lastCtxTokens: number | null = null;
+	lastCtxPercent: number | null = null;
+	lastCtxWindow = 0;
+
+	// Latest computed widget payload (recomputed per snapshot, rendered per frame).
+	widgetData: WidgetData | null = null;
+	// v0.8.5: material-change signature from the last full snapshot() body. When
+	// the next snapshot()'s signature matches, the expensive recompute (6 sync
+	// SQLite opens) + writeFileSync(dashboard.json) are skipped — only the
+	// (already-registered) widget factory is refreshed. Kills the per-event
+	// main-thread block during typing/idle streaming with no material change.
+	lastSnapshotSig: string | null = null;
+	lastHeartbeatAt: number = 0;
+	// v0.8.5: bumped whenever the cached game-state memo is evicted (bumpGameState
+	// for in-process /mega-game writes, the fs.watch callback for cross-process
+	// dashboard-server writes, and bindRepo on repo switch) so the snapshot gate
+	// invalidates and the widget re-reads theme/mode after the change.
+	gameStateBump = 0;
+	// 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: { 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.
+	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.
+	gameStateWatcher?: FSWatcher;
+	gameStateWatchDir?: string;
+	// P2: the last ExtensionContext handed to snapshot()/renderWidget(), stashed
+	// so the fs.watch game-state callback can force a widget re-render without
+	// a context event (cross-process dashboard edits while pi is idle). Cleared
+	// implicitly on construction (undefined → watcher skips until first snap).
+	lastWidgetCtx?: ExtensionContext;
+}