pi-mega-compact 0.8.23 → 0.8.25

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

@@ -0,0 +1,181 @@
+/**
+ * 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;
+	// R7 (retry redesign): session-global cap + poisoned-context counters.
+	readonly sessionRetryCount: number;
+	readonly sessionRetryMax: number;
+	readonly poisonedCount: number;
+	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,
+			// R7 (retry redesign): additive session-cap + poisoned-context counters.
+			sessionRetryCount: ctx.sessionRetryCount,
+			sessionMax: ctx.sessionRetryMax,
+			poisonedCount: ctx.poisonedCount,
+		},
+	};
+}

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;
+}

package/extensions/mega-runtime/helpers.ts

@@ -44,10 +44,34 @@ export interface SessionRuntime {
 	cacheHitTokens: number; // tokens saved via cache hits (dedup + recall) this session
 	lengthStopPending: boolean; // S28: set on turn_end when stopReason==='length'
 	errorRetryCount: number; // S38: consecutive error turns, reset on success/turn_start
-	errorRetryUntil: number; // S38: wall-clock ms debounce for error-retry nudge
+	errorRetryUntil: number; // S38: wall-clock ms before which the next nudge is suppressed (R1: now gating)
 	// S38.6: circuit-breaker state — consecutive error turns across the session.
 	// When this exceeds maxConsecutiveErrors, the extension stops retrying.
 	consecutiveErrors: number; // reset to 0 on successful turn_end
+	// R1 (retry redesign): in-flight nudge dedup. A nudge queued via
+	// deliverAs:'followUp' must not be re-sent until it has been consumed by an
+	// actual new agent turn (turn_start) or superseded by a successful turn.
+	// Without this, a fast-erroring provider + a per-turn nudge → N nudges queue
+	// up and pi dispatches N retry turns, each re-submitting the same failing
+	// prompt (the 2026-07-28 incident: ~60-message spam storm).
+	lastErrorRetryAt: number; // wall-clock ms of the last fired nudge (diagnostics)
+	retryNudgePending: boolean; // true while a queued nudge awaits consumption
+	// R2: session-global cap. Total S38 nudges per session across ALL bursts;
+	// independent of the per-burst max and the circuit breaker. Hitting it is
+	// terminal for the session — the extension stops nudging entirely.
+	errorRetrySessionCount: number; // nudges fired this session (across all bursts)
+	// R3: poisoned-context detection state. The classifier is stateless; the
+	// stateful "repeated identical error text" signal is tracked here and upgrades
+	// a 'transient' classification to 'poisoned-context' after the threshold.
+	lastErrorText: string | undefined; // normalized error signature from the last error turn
+	errorTextRepeatCount: number; // consecutive count of identical error signatures
+	// R3b: one-per-session /clear advise message throttle.
+	poisonedAdviseSent: boolean; // true after the advise message fires once
+	// R3c: one guarded compact per error signature (avoids re-compacting the
+	// same poisoned region repeatedly).
+	poisonedCompactSignatures: Set<string>; // signatures already attempted a compact for
+	// R7: poisoned-context event counter for the dashboard.
+	poisonedCount: number;
 }
 
 // ── ownVersion ─────────────────────────────────────────────────────────────

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;
+	}
+}