pi-mega-compact 0.8.22 → 0.8.24

package/extensions/mega-runtime/perf.ts

@@ -0,0 +1,60 @@
+/**
+ * perf.ts — extracted perf-interval sampling for MegaRuntime.
+ *
+ * The 5s cpu/mem sampling interval + its teardown. Keeps the setInterval
+ * boilerplate out of the main state.ts class body.
+ */
+
+import { recordPerfSample } from "../../src/store/sqlite.js";
+
+// ---------------------------------------------------------------------- types
+
+export interface PerfContext {
+	readonly currentStateDir: string;
+	perfCpuInterval: NodeJS.Timeout | null;
+	perfCpuBaseline: { user: number; sys: number } | undefined;
+}
+
+// ---------------------------------------------------------- ensurePerfInterval
+
+/** v0.8.8: (re)start the 5s cpu/mem sampling interval (idempotent). One per
+ *  MegaRuntime; cleared in disposePerf(). Samples process.cpuUsage() (user/sys
+ *  delta vs the last tick → ms) + process.memoryUsage() (rss/heap → MB) and
+ *  records them as perf_samples. unref'd so it never keeps the process alive
+ *  on its own. Non-fatal: any failure is swallowed (instrumentation never
+ *  blocks the agent). PREVENT-PI-004: local process stats + SQLite only. */
+export function ensurePerfIntervalImpl(ctx: PerfContext): void {
+	if (ctx.perfCpuInterval) return;
+	ctx.perfCpuBaseline = undefined; // first tick sets the baseline (no delta)
+	ctx.perfCpuInterval = setInterval(() => {
+		try {
+			const dir = ctx.currentStateDir;
+			const cpu = process.cpuUsage();
+			const mem = process.memoryUsage();
+			if (ctx.perfCpuBaseline) {
+				const du = (cpu.user - ctx.perfCpuBaseline.user) / 1000; // μs → ms
+				const ds = (cpu.system - ctx.perfCpuBaseline.sys) / 1000;
+				recordPerfSample(dir, "cpu_user_ms", Math.max(0, du));
+				recordPerfSample(dir, "cpu_sys_ms", Math.max(0, ds));
+			}
+			ctx.perfCpuBaseline = { user: cpu.user, sys: cpu.system };
+			recordPerfSample(dir, "rss_mb", mem.rss / 1_000_000);
+			recordPerfSample(dir, "heap_mb", mem.heapUsed / 1_000_000);
+		} catch {
+			/* non-fatal */
+		}
+	}, 5000);
+	ctx.perfCpuInterval.unref?.();
+}
+
+// ------------------------------------------------------------------ disposePerf
+
+/** Stop the cpu/mem sampling interval on teardown. Re-armed lazily by
+ *  ensurePerfInterval() on the next turn_start. */
+export function disposePerf(ctx: PerfContext): void {
+	if (ctx.perfCpuInterval) {
+		clearInterval(ctx.perfCpuInterval);
+		ctx.perfCpuInterval = null;
+		ctx.perfCpuBaseline = undefined;
+	}
+}

package/extensions/mega-runtime/pressure-getters.ts

@@ -0,0 +1,96 @@
+/**
+ * pressure-getters.ts — extracted pressure accessors from the `MegaRuntime`
+ * class (runtime.ts): the `pressure` / `effectiveThreshold` / `pressureBand`
+ * getters, so the class body shrinks and the threshold logic is independently
+ * testable.
+ *
+ * Follows the same context-interface + free-function + thin-delegate pattern as
+ * effects.ts / game-state.ts / capture-model.ts / bind-repo.ts / perf.ts /
+ * runtime-helpers.ts.
+ */
+
+import {
+	pressureRatio,
+	pressureFromPct,
+	pressureBand,
+	effectiveThresholdTokens,
+	type MegaConfig,
+	type PressureBand,
+} from "../mega-config.js";
+
+// ---------------------------------------------------------------------- types
+
+/**
+ * The slice of `MegaRuntime` the pressure accessors read. `MegaRuntime`
+ * satisfies this structurally with no visibility changes — every field was
+ * already public.
+ */
+export interface PressureContext {
+	config: MegaConfig;
+	lastCtxTokens: number | null;
+	lastCtxPercent: number | null;
+	lastCtxWindow: number;
+}
+
+// ------------------------------------------------------------------ pressure
+
+/**
+ * Live 0–1 pressure — how full the context window is relative to the
+ * compaction threshold.
+ *
+ * RECONCILE (BACKLOG dual-basis flicker): when the model context window is
+ * known we base pressure consistently on the *percentage* basis
+ * (`lastCtxPercent / (tierPct*100)`). This keeps the band stable whether the
+ * latest context event carried a token count or only a percentage, so the
+ * threshold comparison doesn't jump when a token-count event arrives vs a
+ * percent-only event. We only fall back to the token-count basis
+ * (`config.thresholdTokens`) when the window is unknown (e.g. before the first
+ * context event, or a `custom` tier with no tierPct). Always finite + in [0,1].
+ */
+export function pressureImpl(self: PressureContext): number {
+	if (
+		self.lastCtxWindow > 0 &&
+		self.config.tierPct != null &&
+		self.lastCtxPercent != null
+	) {
+		// pressureFromPct(x) = x/100, and x = lastCtxPercent/tierPct, so this is
+		// exactly the intended lastCtxPercent/(tierPct*100) 0–1 ratio: at the
+		// fire point (lastCtxPercent == tierPct*100) pressure == 1.0, matching the
+		// token-based pressureRatio(currentTokens, effectiveThreshold) reading so
+		// the band doesn't jump when a token-count vs percent-only event arrives.
+		return pressureFromPct(self.lastCtxPercent / self.config.tierPct);
+	}
+	if (
+		self.lastCtxTokens != null &&
+		self.lastCtxTokens > 0 &&
+		self.config.thresholdTokens > 0
+	) {
+		return pressureRatio(self.lastCtxTokens, self.config.thresholdTokens);
+	}
+	return pressureFromPct(self.lastCtxPercent);
+}
+
+// -------------------------------------------------------- effectiveThreshold
+
+/**
+ * The live compaction FIRE POINT in tokens: the effective threshold scaled by
+ * the current model context window (`tierPct * window`) when known, else the
+ * boot fallback `config.thresholdTokens`. This is what the FAST GATE /
+ * `autoCompactCheck` / agent_end durable-trigger compare against, so
+ * compaction fires at tier% of the window for ANY model size (200k or 1M),
+ * always below pi's native auto-compaction (~80% of window).
+ */
+export function effectiveThresholdImpl(self: PressureContext): number {
+	return effectiveThresholdTokens({
+		tierPct: self.config.tierPct,
+		fallbackThreshold: self.config.thresholdTokens,
+		window: self.lastCtxWindow,
+	});
+}
+
+// -------------------------------------------------------------- pressureBand
+
+/** Live discrete pressure band (low/medium/high/ultra/mega) over `pressure`. */
+export function pressureBandImpl(self: PressureContext): PressureBand {
+	return pressureBand(pressureImpl(self));
+}

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

@@ -0,0 +1,41 @@
+/**
+ * render-widget.ts — extracted `MegaRuntime.renderWidget()`: the width-aware
+ * above-editor widget factory registration. Same thin-delegate pattern as the
+ * other runtime.ts extractions.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { WIDGET_KEY } from "./helpers.js";
+import { buildWidgetLines, type WidgetData } from "./widget.js";
+
+// ---------------------------------------------------------------------- types
+
+/** The slice of `MegaRuntime` renderWidget reads at render time. */
+export interface RenderWidgetContext {
+	readonly widgetData: WidgetData | null;
+	readonly activeAgents: number;
+}
+
+// -------------------------------------------------------------- renderWidget
+
+/** Register the above-editor widget as a width-aware factory so pi re-renders
+ *  it at the REAL terminal width every frame (auto-fit wide/narrow). The
+ *  factory returns a minimal Component whose render() reads self.widgetData. */
+export function renderWidgetImpl(
+	self: RenderWidgetContext,
+	ctx: ExtensionContext,
+): void {
+	ctx.ui.setWidget(
+		WIDGET_KEY,
+		(_tui, _theme) => ({
+			render: (width: number) =>
+				buildWidgetLines(
+					self.widgetData,
+					width > 0 ? width : 200,
+					self.activeAgents,
+				),
+			invalidate: () => {},
+		}),
+		{ placement: "aboveEditor" },
+	);
+}

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

@@ -0,0 +1,80 @@
+/**
+ * reset-runtime.ts — extracted `MegaRuntime.resetRuntime()`: the per-session
+ * state reset used by the session_start / session_tree handlers. The class
+ * keeps a thin `resetRuntimeImpl(this, sessionId)` delegate so every call
+ * site is unchanged.
+ *
+ * Follows the same context-interface + free-function + thin-delegate pattern as
+ * effects.ts / game-state.ts / capture-model.ts / bind-repo.ts / perf.ts /
+ * runtime-helpers.ts.
+ */
+
+import { normalizeSessionId } from "../../src/store.js";
+import type { TickerEntry } from "./widget.js";
+import type { GameState } from "../../src/store/sqlite.js";
+import type { SessionRuntime } from "./helpers.js";
+
+// ---------------------------------------------------------------------- types
+
+/**
+ * The slice of `MegaRuntime` resetRuntime mutates. `trimCache` is typed
+ * `unknown` — this function only ever *clears* it, so the precise
+ * snapshot-cache shape does not need to be imported.
+ */
+export interface ResetRuntimeContext {
+	rt: SessionRuntime;
+	trimCache: unknown;
+	ticker: TickerEntry[];
+	cachedGameState: GameState | undefined;
+	statusKey: string | undefined;
+	activeAgents: number;
+	currentTurn: number;
+	lastActivityAt: number;
+	tierTrace: string | undefined;
+	pulsing: boolean;
+	savedGoal: number;
+	lastWhy: string | undefined;
+}
+
+// --------------------------------------------------------------- resetRuntime
+
+export function resetRuntimeImpl(
+	self: ResetRuntimeContext,
+	sessionId: string | undefined,
+): void {
+	const sid = normalizeSessionId(sessionId);
+	if (self.rt.sessionId === sid && self.rt.persistedThisSession) return; // same session, keep checkpoint memory
+	self.rt = {
+		sessionId: sid,
+		persistedThisSession: false,
+		lastCheckpointId: undefined,
+		lastCompactedFrom: 0,
+		lastCompactedTokens: 0,
+		dedupSkips: 0,
+		dedupAttempts: 0,
+		tokensSaved: 0,
+		lastCompactAt: null,
+		lastNativeCompactAt: null,
+		compactCount: 0,
+		recallInjections: 0,
+		cacheHitTokens: 0,
+		lengthStopPending: false,
+		errorRetryCount: 0,
+		errorRetryUntil: 0,
+		consecutiveErrors: 0,
+	};
+	self.trimCache = null; // v0.8.6: never replay a stale trim into a new session
+	self.statusKey = undefined;
+	self.activeAgents = 0;
+	self.currentTurn = 0;
+	self.lastActivityAt = 0;
+	self.tierTrace = undefined;
+	self.ticker.length = 0;
+	self.pulsing = false;
+	self.savedGoal = 50_000;
+	self.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.
+	self.cachedGameState = undefined;
+}

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

@@ -0,0 +1,119 @@
+/**
+ * runtime-helpers.ts — extracted private helpers from the `MegaRuntime` class
+ * (runtime.ts) so the class body shrinks and the pure/instance logic is
+ * independently testable.
+ *
+ * Follows the same context-interface + free-function + thin-delegate pattern as
+ * effects.ts / game-state.ts / capture-model.ts / bind-repo.ts / perf.ts.
+ */
+
+import type { SessionRuntime } from "./helpers.js";
+import type { TickerEntry } from "./widget-types.js";
+import type { ModelSnapshot } from "../../src/store/sqlite.js";
+import { detectCrossRepoDrift } from "../../src/driftDetection.js";
+import { turnLevel } from "../../src/game/scoring.js";
+
+// ---------------------------------------------------------------------- types
+
+/**
+ * The slice of `MegaRuntime` the extracted helpers read (and, for `driftStatus`,
+ * write). `MegaRuntime` satisfies this structurally once `driftCache` is public.
+ */
+export interface RuntimeHelpersContext {
+	rt: SessionRuntime;
+	activeEffect: {
+		type: "pulse" | "flash";
+		role: "accent" | "mega" | "red";
+		startedAt: number;
+		durationMs: number;
+	} | null;
+	lastCtxTokens: number | null;
+	lastCtxPercent: number | null;
+	lastCtxWindow: number;
+	activeAgents: number;
+	currentTurn: number;
+	statusKey: string | undefined;
+	currentModel: ModelSnapshot | undefined;
+	gameStateBump: number;
+	megaCacheFlare: boolean;
+	megaCacheFlarePct: number;
+	levelUpFlare: boolean;
+	achievementFlare: boolean;
+	achievementFlareTitles: string[];
+	tierTrace: string | undefined;
+	lastWhy: string | undefined;
+	pulsing: boolean;
+	ticker: TickerEntry[];
+	/** Cross-repo drift cache (30s TTL). Mutated by `driftStatusImpl`. */
+	driftCache: { at: number; status: "ok" | "warn" } | null;
+}
+
+// -------------------------------------------------------------- materialSig
+
+/** v0.8.5: cheap material-change signature over live runtime fields (no
+ *  SQLite). Two snapshots with the same signature produce identical
+ *  dashboard.json + widgetData, so the 6 synchronous SQLite opens + the
+ *  writeFileSync(dashboard.json) can be skipped. Built from in-memory state
+ *  only; `gameStateBump` covers cross-process game_state edits (fs.watch) +
+ *  in-process /mega-game writes (bumpGameState) + repo switches (bindRepo).
+ *  The transient flare flags are included so a one-shot flare forces the
+ *  recompute that renders (then clears) it for exactly one cycle. */
+export function materialSigImpl(ctx: RuntimeHelpersContext): string {
+	const rt = ctx.rt;
+	const ae = ctx.activeEffect;
+	return JSON.stringify([
+		ctx.lastCtxTokens, ctx.lastCtxPercent, ctx.lastCtxWindow,
+		ctx.activeAgents, ctx.currentTurn,
+		rt.compactCount, rt.tokensSaved, rt.dedupSkips, rt.dedupAttempts,
+		rt.recallInjections, rt.cacheHitTokens, rt.persistedThisSession,
+		rt.lastCheckpointId ?? null, rt.lastCompactedFrom, rt.lastCompactedTokens,
+		ctx.statusKey ?? null,
+		ctx.currentModel?.modelId ?? null, ctx.currentModel?.provider ?? null,
+		ae ? `${ae.type}:${ae.role}:${ae.startedAt}` : null,
+		ctx.gameStateBump,
+		ctx.megaCacheFlare, ctx.megaCacheFlarePct,
+		ctx.levelUpFlare, ctx.achievementFlare,
+		ctx.achievementFlareTitles.join("|"),
+		ctx.tierTrace ?? null, ctx.lastWhy ?? null, ctx.pulsing,
+		ctx.ticker.length,
+	]);
+}
+
+// -------------------------------------------------------------- embedderName
+
+/** Active embedder name for the memory-store line (Trigram default / MiniLM).
+ *  Pure — reads only `process.env` (the same flag the embedder factory reads). */
+export function embedderNameImpl(): string {
+	// MINILM_EMBEDDER flag lives in src/config/dedup.ts; read the same env var
+	// the embedder factory uses so the label matches what's actually running.
+	return process.env.MEGACOMPACT_MINILM === "true" ||
+		process.env.MEGACOMPACT_MINILM === "1"
+		? "MiniLM"
+		: "Trigram";
+}
+
+// -------------------------------------------------------------- driftStatus
+
+/** Cross-repo drift status (ok | warn), cached for 30s (opens the registry DB). */
+export function driftStatusImpl(ctx: RuntimeHelpersContext): "ok" | "warn" {
+	const now = Date.now();
+	if (ctx.driftCache && now - ctx.driftCache.at < 30_000)
+		return ctx.driftCache.status;
+	let status: "ok" | "warn" = "ok";
+	try {
+		const report = detectCrossRepoDrift();
+		status = report.totals.warn > 0 ? "warn" : "ok";
+	} catch {
+		status = "ok";
+	}
+	ctx.driftCache = { at: now, status };
+	return status;
+}
+
+// -------------------------------------------------------------- getTurnLevel
+
+/** S33: player level for game mode — floor(log2(turns+1))+1 (gentle).
+ *  Defensive: non-finite/negative collapses to 1 (never NaN). */
+export function getTurnLevelImpl(ctx: RuntimeHelpersContext): number {
+	return turnLevel(ctx.currentTurn);
+}

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

@@ -0,0 +1,289 @@
+/**
+ * runtime-snapshot.ts — extracted `MegaRuntime.snapshot()` orchestration.
+ *
+ * The snapshot() body (dashboard write + S39 heartbeat + widget-data compute
+ * + flare/effect consumption + perf recording + the v0.8.5 material-change
+ * gate) is moved here verbatim. `MegaRuntime.snapshot()` becomes a thin
+ * delegate (`snapshotImpl(this, ctx)`), so the public method and every call
+ * site is unchanged.
+ *
+ * Follows the same context-interface + free-function + thin-delegate pattern
+ * as effects.ts / game-state.ts / capture-model.ts / runtime-helpers.ts.
+ * The pure widget-data computation lives in snapshot.ts (`computeMegaSnapshot`);
+ * this module is the orchestration that calls it. The pure/instance helpers
+ * materialSig/embedderName/driftStatus/getTurnLevel are called directly via
+ * their `*Impl` functions (imported from runtime-helpers.ts) — they were only
+ * ever called from snapshot(), so the in-class private delegates are removed
+ * from runtime.ts (dead code) rather than kept.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+import {
+	VectorStore,
+	vectorStats,
+	vectorRepoStats,
+	vectorDataInvariant,
+} from "../../src/vectorStore.js";
+import {
+	latestModelSnapshot,
+	recordPerfSample,
+	recordSessionHeartbeat,
+	appendTokenSample,
+	type GameState,
+} from "../../src/store/sqlite.js";
+import { resolveRepoRoot, type MegaConfig, type PressureBand } from "../mega-config.js";
+import { Dashboard } from "../mega-dashboard.js";
+import type { WidgetData } from "./widget.js";
+import { computeMegaSnapshot } from "./snapshot.js";
+import { buildDashboardSnapshot } from "./dashboard-snapshot.js";
+import {
+	type RuntimeHelpersContext,
+	materialSigImpl,
+	embedderNameImpl,
+	driftStatusImpl,
+	getTurnLevelImpl,
+} from "./runtime-helpers.js";
+
+// ---------------------------------------------------------------------- types
+
+/**
+ * The slice of `MegaRuntime` the snapshot orchestration reads + writes.
+ * Extends `RuntimeHelpersContext` (the fields materialSig/driftStatus/
+ * getTurnLevel read) so `self` can be passed straight to those `*Impl`
+ * functions. `MegaRuntime` satisfies this structurally once `lastSnapshotSig`
+ * is public — the same one-token visibility change Phase 2b made for
+ * `driftCache` (internal state, not an API contract).
+ */
+export interface RuntimeSnapshotContext extends RuntimeHelpersContext {
+	// ── owned state ──
+	store: VectorStore;
+	config: MegaConfig;
+	dashboard: Dashboard;
+	currentStateDir: string;
+	widgetData: WidgetData | null;
+	/** v0.8.5: material-change signature; read + written by snapshot(). Public so
+	 *  the extracted orchestration can reach it (internal state, not an API). */
+	lastSnapshotSig: string | null;
+	lastWidgetCtx?: ExtensionContext;
+	lastActivityAt: number;
+	lastLevel: number;
+	diagCtxFastGate: number;
+	diagLiveTrimFires: number;
+	diagLiveTrimReplays: number;
+
+	// ── public methods the orchestration calls ──
+	bindRepo(cwd: string | undefined): string;
+	renderWidget(ctx: ExtensionContext): void;
+	getCachedGameState(): GameState;
+	setEffect(
+		type: "pulse" | "flash",
+		role: "accent" | "mega" | "red",
+		durationMs: number,
+	): void;
+
+	// ── public getters ──
+	readonly pressureBand: PressureBand;
+	readonly pressure: number;
+	readonly effectiveThreshold: number;
+}
+
+// -------------------------------------------------------------- snapshotImpl
+
+/** Collect live state and write it to disk (+ paint the above-editor widget).
+ *  Extracted verbatim from `MegaRuntime.snapshot()` (runtime.ts); the public
+ *  method there is now `snapshotImpl(this, ctx)`. */
+export function snapshotImpl(self: RuntimeSnapshotContext, ctx?: ExtensionContext): void {
+	if (ctx) self.lastWidgetCtx = ctx;
+	if (ctx) self.bindRepo(ctx.cwd);
+	// v0.8.5: gate the expensive body (6 sync SQLite opens +
+	// writeFileSync(dashboard.json)) behind a cheap material-change signature.
+	// During typing / idle / no-compaction streaming, the 'context' event
+	// fires repeatedly with NO material change — skip the recompute + write and
+	// just re-register the (live) widget factory, which reads the cached
+	// widgetData every frame. This removes the per-event main-thread block
+	// WITHOUT changing write timing, so tests that read dashboard.json
+	// synchronously after a compaction still see it written (compaction changes
+	// compactCount/tokensSaved → the signature changes → the full recompute +
+	// write runs).
+	const sig = materialSigImpl(self);
+	if (ctx && self.widgetData && self.lastSnapshotSig === sig) {
+		self.renderWidget(ctx);
+		return;
+	}
+	const perfT0 = performance.now();
+	const st = vectorStats(self.store, self.rt.sessionId);
+	const repo = vectorRepoStats(self.store);
+	const di = vectorDataInvariant(self.store);
+	// Effective threshold + armed/ready status for the dashboard.
+	// effectiveThresholdPct: the live fire point as a % of the window (null for
+	// `custom`, which has no tierPct). S29: honors MEGACOMPACT_AUTO_PCT_TRIGGER
+	// override so the dashboard's armed/ready match the context-handler gate
+	// (which fires on this same %). Used by armed/ready + the dashboard.
+	const effectiveThresholdPct =
+		self.config.tierPct != null
+			? (self.config.autoPctTrigger ?? self.config.tierPct) * 100
+			: null;
+	// armed lights at/above the REAL fire point: max(effectiveThresholdPct,
+	// fastGatePct). fastGatePct already equals tierPct*100 by default, but a
+	// MEGACOMPACT_FAST_GATE_PCT override can raise it, so we take the max.
+	const armed =
+		self.lastCtxPercent != null &&
+		self.lastCtxPercent >=
+			Math.max(effectiveThresholdPct ?? 0, self.config.fastGatePct);
+	// S29: ready mirrors the context-handler gate's basis — percent for tiered
+	// (the gate fires on pct), tokens for custom (the gate fires on tokens).
+	// Previously this always required tokens, so the dashboard could show
+	// "armed" (percent high) but never "ready" when tokens were under-reported
+	// — the same inconsistency the S29 gate fix removes.
+	const ready =
+		self.config.tierPct != null
+			? armed && (self.lastCtxPercent ?? 0) >= (effectiveThresholdPct ?? 0)
+			: armed && (self.lastCtxTokens ?? 0) >= self.effectiveThreshold;
+	self.dashboard.snapshot(
+		buildDashboardSnapshot({
+			config: self.config,
+			rt: self.rt,
+			pressureBand: self.pressureBand,
+			pressure: self.pressure,
+			effectiveThreshold: self.effectiveThreshold,
+			statusKey: self.statusKey,
+			lastCtxTokens: self.lastCtxTokens,
+			lastCtxPercent: self.lastCtxPercent,
+			lastCtxWindow: self.lastCtxWindow,
+			diagCtxFastGate: self.diagCtxFastGate,
+			diagLiveTrimFires: self.diagLiveTrimFires,
+			diagLiveTrimReplays: self.diagLiveTrimReplays,
+			errorRetryCount: self.rt.errorRetryCount,
+			consecutiveErrors: self.rt.consecutiveErrors,
+			ERROR_RETRY_MAX_CONSECUTIVE: self.config.maxConsecutiveErrors,
+			errorRetryHardStop: self.config.errorRetryHardStop,
+			activeAgents: self.activeAgents,
+			currentTurn: self.currentTurn,
+			currentModel: self.currentModel,
+			st,
+			repo,
+			di,
+		}),
+	);
+	const perfDiskMs = self.dashboard.lastWriteMs;
+
+	// S39: record a session heartbeat + token sample into the shared
+	// machine-wide index.sqlite so the dashboard can show a real-time
+	// stacked-memory graph across all active pi processes. Behind the
+	// material-change gate (this code only runs when sig changed). Non-fatal
+	// try/catch mirrors the recordPerfSample pattern below. Skip the token
+	// sample when lastCtxTokens is null (no context data yet).
+	try {
+		const repo = resolveRepoRoot(ctx?.cwd ?? self.currentStateDir) ?? self.currentStateDir;
+		recordSessionHeartbeat(
+			process.pid,
+			self.rt.sessionId,
+			repo,
+			self.currentStateDir,
+			self.lastCtxWindow || 0,
+		);
+		if (self.lastCtxTokens != null) {
+			appendTokenSample(
+				self.rt.sessionId,
+				repo,
+				self.lastCtxTokens,
+				self.lastCtxPercent ?? 0,
+				self.lastCtxWindow || 0,
+			join(self.currentStateDir, "events.log"),
+			);
+		}
+	} catch {
+		/* non-fatal: S39 monitoring must never block the snapshot path */
+	}
+
+	// Live stats widget above the editor
+	if (ctx) {
+		// S31: game-mode state — fetched before the widget computation so the
+		// pure function gets a plain value rather than another callback.
+		const gs = self.getCachedGameState();
+		// S34: derive the level-up flare from the turn count. This side-effect
+		// check must happen BEFORE computeMegaSnapshot so the flare and the
+		// ambient effect are armed for the current frame.
+		const curLevel = getTurnLevelImpl(self);
+		if (curLevel > self.lastLevel) {
+			self.levelUpFlare = true;
+			// v0.8.3: arm a pulse border effect to celebrate the level-up.
+			self.setEffect("pulse", "accent", 1500);
+		}
+		// ── gather widget data (computed per snapshot, rendered per frame) ────
+		const modelSnap = latestModelSnapshot(self.currentStateDir);
+		const _snapResult = computeMegaSnapshot({
+			lastCtxTokens: self.lastCtxTokens,
+			lastCtxWindow: self.lastCtxWindow,
+			lastCtxPercent: self.lastCtxPercent,
+			activeAgents: self.activeAgents,
+			currentTurn: self.currentTurn,
+			statusKey: self.statusKey,
+			st,
+			repo,
+			rtTokensSaved: self.rt.tokensSaved,
+			lastCompactAt: self.rt.lastCompactAt,
+			ticker: self.ticker,
+			lastWhy: self.lastWhy,
+			tierTrace: self.tierTrace,
+			pulsing: self.pulsing,
+			getCachedGameState: () => gs,
+			getTurnLevel: () => getTurnLevelImpl(self),
+			embedderName: () => embedderNameImpl(),
+			driftStatus: () => driftStatusImpl(self),
+			megaCacheFlare: self.megaCacheFlare,
+			megaCacheFlarePct: self.megaCacheFlarePct,
+			levelUpFlare: self.levelUpFlare,
+			achievementFlare: self.achievementFlare,
+			achievementFlareTitles: self.achievementFlareTitles,
+			activeEffect: self.activeEffect,
+			lastActivityAt: self.lastActivityAt,
+			pressureBand: self.pressureBand,
+			configTier: self.config.tier,
+			ready,
+			armed,
+			modelSnap,
+		});
+		self.widgetData = _snapResult.widgetData;
+		// S33: consume the flare after copying it into widgetData so it fires
+		// for exactly one render cycle (the gag flares once, then clears).
+		self.megaCacheFlare = false;
+		self.megaCacheFlarePct = 0;
+
+		// S34: consume the level-up flare after one render cycle (mirrors the
+		// megaCacheFlare one-shot semantics), and advance lastLevel.
+		self.levelUpFlare = false;
+		self.lastLevel = curLevel;
+		// S35: consume the achievement-unlock flare after one render cycle
+		// (mirrors the megaCacheFlare/levelUpFlare one-shot semantics).
+		self.achievementFlare = false;
+		self.achievementFlareTitles = [];
+		// v0.8.3: expire the ambient border effect once its time window has
+		// elapsed. SEPARATE from the one-shot flares above (those are per-cycle
+		// consumes; activeEffect is time-windowed and cleared when Date.now()
+		// crosses startedAt + durationMs). The widget also defends this per-frame
+		// (effectBorderSgr returns '' once expired), so this is bookkeeping to
+		// free the slot and prevent a stale effect lingering between snapshots.
+		if (
+			self.activeEffect &&
+			Date.now() - self.activeEffect.startedAt >=
+				self.activeEffect.durationMs
+		) {
+			self.activeEffect = null;
+		}
+		// 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.
+		self.renderWidget(ctx);
+	}
+	// v0.8.5: record the material-change signature computed at the top so the
+	// next snapshot() can skip this whole body when nothing material changed.
+	try {
+		recordPerfSample(self.currentStateDir, "db_recompute_ms", performance.now() - perfT0);
+		recordPerfSample(self.currentStateDir, "disk_write_ms", perfDiskMs);
+	} catch {
+		/* non-fatal: perf instrumentation never blocks the agent */
+	}
+	self.lastSnapshotSig = sig;
+}