pi-mega-compact 0.13.7 → 0.14.1

package/extensions/dashboard-client/src/styles/base.css

@@ -30,7 +30,8 @@ body {
 }
 
 .dashboard-app {
-	max-width: min(1600px, 96vw);
+	width: 100%;
+	max-width: 100vw;
 	margin: 0 auto;
 	padding: clamp(8px, 2vw, 24px);
 }
@@ -210,9 +211,6 @@ body {
 }
 
 @media (min-width: 1601px) {
-	.dashboard-app {
-		max-width: min(1800px, 96vw);
-	}
 	.card-grid {
 		grid-template-columns: repeat(4, 1fr);
 	}

package/extensions/dashboard-client/src/tabs/MemoryMapTab/RaptorTreeView.tsx

@@ -7,8 +7,12 @@
  */
 import type React from "react";
 import { useEffect, useState } from "react";
-import { fetchRaptorTree } from "../../api/client";
-import type { RaptorTreeResponse, RaptorNodeDTO } from "@contracts";
+import { fetchRaptorTree, fetchRaptorBuildHistory } from "../../api/client";
+import type {
+	RaptorTreeResponse,
+	RaptorNodeDTO,
+	RaptorBuildHistoryResponse,
+} from "@contracts";
 
 /** Per-level border color for node cards. */
 function levelColor(level: number): string {
@@ -68,6 +72,7 @@ function NodeCard({ node }: { node: RaptorNodeDTO }): React.ReactElement {
 
 export default function RaptorTreeView(): React.ReactElement {
 	const [data, setData] = useState<RaptorTreeResponse | null>(null);
+	const [history, setHistory] = useState<RaptorBuildHistoryResponse | null>(null);
 	const [loading, setLoading] = useState<boolean>(true);
 	const [error, setError] = useState<string | null>(null);
 
@@ -75,10 +80,11 @@ export default function RaptorTreeView(): React.ReactElement {
 		let cancelled = false;
 		setLoading(true);
 		setError(null);
-		fetchRaptorTree()
-			.then((d) => {
+		Promise.all([fetchRaptorTree(), fetchRaptorBuildHistory()])
+			.then(([d, h]) => {
 				if (!cancelled) {
 					setData(d);
+					setHistory(h);
 					setLoading(false);
 				}
 			})
@@ -120,6 +126,11 @@ export default function RaptorTreeView(): React.ReactElement {
 		);
 	}
 
+	const latestBuild = history && !history.empty ? history.builds[0] : null;
+	const coherencePct = latestBuild?.coherenceScore != null
+		? Math.round(latestBuild.coherenceScore * 100)
+		: null;
+
 	return (
 		<div className="w-full p-4">
 			<div className="mb-4 flex items-center gap-6 text-sm text-muted-foreground">
@@ -130,7 +141,50 @@ export default function RaptorTreeView(): React.ReactElement {
 					<strong>{data.levels + 1}</strong> levels
 				</span>
 				<span>Built {formatDate(data.builtAt ?? 0)}</span>
+				{latestBuild && (
+					<>
+						<span>
+							Coherence:{" "}
+							<strong style={{ color: coherencePct != null && coherencePct >= 70 ? "#22c55e" : "#f59e0b" }}>
+								{coherencePct != null ? `${coherencePct}%` : "—"}
+							</strong>
+						</span>
+						<span>
+							Leaves: <strong>{latestBuild.leafCount}</strong>
+						</span>
+						<span>
+							Depth: <strong>{latestBuild.depth}</strong>
+						</span>
+						{latestBuild.timedOut && (
+							<span style={{ color: "#ef4444" }}>budget timeout</span>
+						)}
+					</>
+				)}
 			</div>
+			{history && !history.empty && history.builds.length > 1 && (
+				<details className="mb-4">
+					<summary className="cursor-pointer text-xs text-muted-foreground">
+						Build history ({history.builds.length} builds)
+					</summary>
+					<div className="mt-2 space-y-1">
+						{history.builds.slice(0, 10).map((b) => (
+							<div key={b.buildId} className="flex items-center gap-4 text-xs text-muted-foreground">
+								<span>{formatDate(b.completedAt)}</span>
+								<span>{b.nodeCount} nodes</span>
+								<span>{b.leafCount} leaves</span>
+								<span>depth {b.depth}</span>
+								<span>
+									coherence{" "}
+									{b.coherenceScore != null
+										? `${Math.round(b.coherenceScore * 100)}%`
+										: "—"}
+								</span>
+								{b.timedOut && <span style={{ color: "#ef4444" }}>timeout</span>}
+							</div>
+						))}
+					</div>
+				</details>
+			)}
 			{data.nodes.map((node) => (
 				<NodeCard key={node.id} node={node} />
 			))}

package/extensions/dashboard-client/tailwind.config.js

@@ -6,7 +6,7 @@ export default {
     container: {
       center: true,
       padding: "1.5rem",
-      screens: { "2xl": "1600px" },
+      screens: { "2xl": "100%" },
     },
     extend: {
       colors: {

package/extensions/dashboard-server/api-contracts/endpoints/registry.ts

@@ -15,7 +15,7 @@ import type { IndexesSummaryResponse } from "../multi-repo.js";
 import type { GameStateResponse } from "../game.js";
 import type { SseEvent } from "../index.js";
 import type { ProviderCacheResponse } from "../provider-cache.js";
-import type { RaptorTreeResponse } from "../raptor.js";
+import type { RaptorTreeResponse, RaptorBuildHistoryResponse } from "../raptor.js";
 import type { MemoryStatusResponse } from "../memory.js";
 import type { SetupStatusResponse, SetupDetectResponse, SetupConfigureRequest, SetupConfigureResponse } from "../setup.js";
 import type { EmbedderHealthResponse } from "../embedder-health.js";
@@ -424,6 +424,14 @@ export const ENDPOINTS = {
 			"Hierarchical RAPTOR tree (summary nodes by level) for a session; defaults to the latest session with nodes.",
 	} as const satisfies EndpointDef<"GET", undefined, RaptorTreeResponse>,
 
+	/** GET /api/raptor-build-history — Build history (coherence, depth, timeout) for a session. */
+	raptorBuildHistory: {
+		method: "GET",
+		path: "/api/raptor-build-history",
+		description:
+			"RAPTOR build history rows (node/leaf count, depth, coherence score, timed_out) for a session; defaults to the latest session with builds.",
+	} as const satisfies EndpointDef<"GET", undefined, RaptorBuildHistoryResponse>,
+
 	/** GET /api/embedder-health — Round-trip a test embed through the active embedder. */
 	embedderHealth: {
 		method: "GET",

package/extensions/dashboard-server/api-contracts/index.ts

@@ -241,8 +241,8 @@ export type {
 	GraphValidationReport,
 } from "./memory-map.js";
 
-// Part B — RAPTOR tree
-export type { RaptorNodeDTO, RaptorTreeResponse } from "./raptor.js";
+// Part B — RAPTOR tree + build history
+export type { RaptorNodeDTO, RaptorTreeResponse, RaptorBuildHistoryDTO, RaptorBuildHistoryResponse } from "./raptor.js";
 
 // A3 — cache stripe distribution + health
 export type {

package/extensions/dashboard-server/api-contracts/raptor.ts

@@ -47,3 +47,22 @@ export interface RaptorTreeResponse {
 	/** True when there are no RAPTOR nodes for the resolved session. */
 	readonly empty: boolean;
 }
+
+/** A single build-history row (client-safe). */
+export interface RaptorBuildHistoryDTO {
+	readonly buildId: string;
+	readonly sessionId: string;
+	readonly startedAt: number;
+	readonly completedAt: number;
+	readonly nodeCount: number;
+	readonly leafCount: number;
+	readonly depth: number;
+	readonly coherenceScore: number | null;
+	readonly timedOut: boolean;
+}
+
+/** Response body for GET /api/raptor-build-history. */
+export interface RaptorBuildHistoryResponse {
+	readonly builds: RaptorBuildHistoryDTO[];
+	readonly empty: boolean;
+}

package/extensions/dashboard-server/index-reader.ts

@@ -18,6 +18,7 @@ import {
 	readProviderCacheForRepo,
 } from "../../src/store/sqlite/perf-samples.js";
 import { lookupModelInputRate } from "../../src/pricing.js";
+import { costApiConfig, lookupCostApiPricing } from "../../src/costApi.js";
 
 export function getIndexDir(): string {
 	const override = process.env.MEGACOMPACT_INDEX_DIR;
@@ -41,7 +42,29 @@ export function readIndex(): IndexIndex | null {
 		const rows = db
 			.prepare("SELECT * FROM repo_registry ORDER BY last_seen DESC")
 			.all() as Record<string, unknown>[];
-		const mapped: IndexRepo[] = rows.map((r) => ({
+		// Lazily fetch cost-API pricing once per readIndex call (cached for 1 hour
+		// inside costApi.ts). Avoids per-row network calls.
+		const costApi = costApiConfig();
+		const mapped: IndexRepo[] = rows.map((r) => {
+			const modelName = String(r.model_name ?? "");
+			const localRate = (r.input_rate as number | null) ||
+				lookupModelInputRate(modelName) ||
+				null;
+			let inputRate = localRate;
+			let outputRate = (r.output_rate as number | null) ?? null;
+			// Fall back to the cost API when the local table has no data.
+			if (costApi.enabled && (inputRate == null || outputRate == null) && modelName) {
+				const apiPricing = lookupCostApiPricing(modelName);
+				if (apiPricing) {
+					if (inputRate == null && apiPricing.inputRate != null) {
+						inputRate = apiPricing.inputRate;
+					}
+					if (outputRate == null && apiPricing.outputRate != null) {
+						outputRate = apiPricing.outputRate;
+					}
+				}
+			}
+			return {
 			repoRoot: String(r.repo_root ?? ""),
 			displayName: String(r.display_name ?? ""),
 			stateDir: String(r.state_dir ?? ""),
@@ -52,9 +75,8 @@ export function readIndex(): IndexIndex | null {
 			provider: (r.provider as string | null) ?? null,
 			providerName: (r.provider_name as string | null) ?? null,
 			modelName: (r.model_name as string | null) ?? null,
-			inputRate: ((r.input_rate as number | null) ||
-				lookupModelInputRate(String(r.model_name ?? ""))) ?? null,
-			outputRate: (r.output_rate as number | null) ?? null,
+			inputRate,
+			outputRate,
 			lastSeen: Number(r.last_seen ?? 0),
 			// Defaults — enriched below from each repo's own store.
 			tokensKept: 0,
@@ -66,7 +88,8 @@ export function readIndex(): IndexIndex | null {
 			providerCachePct: null,
 			providerCacheRead: null,
 			providerCacheWrite: null,
-		}));
+		};
+		});
 		// Enrich each repo with per-store token + model detail read directly via
 		// node:sqlite (same zero-dependency invariant as readIndex; no store graph
 		// import). Best-effort: a missing/corrupt store degrades to the defaults

package/extensions/dashboard-server/routes-cache.ts

@@ -13,7 +13,8 @@ import { createRequire } from "node:module";
 import type { IncomingMessage, ServerResponse } from "node:http";
 
 import type { RouteContext } from "./routes-core.js";
-import { computeCacheSavings } from "../../src/pricing.js";
+import { computeCacheSavings, lookupModelInputRate } from "../../src/pricing.js";
+import { costApiConfig, lookupCostApiPricing } from "../../src/costApi.js";
 
 // ---------------------------------------------------------------------------
 // handleProviderCache — "/api/provider-cache"
@@ -118,18 +119,29 @@ export function handleProviderCache(
 			} | null = null;
 			try {
 				const snap = latestModelSnapshot(stateDir); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
-				if (snap && snap.inputRate > 0) {
+				let rate = snap?.inputRate ?? 0;
+				let modelName = snap?.modelName ?? snap?.modelId ?? "unknown";
+				// Fallback chain: SQLite snapshot → local pricing table → cost API
+				if (rate <= 0 && modelName !== "unknown") {
+					rate = lookupModelInputRate(modelName) ?? 0;
+				}
+				if (rate <= 0 && costApiConfig().enabled && modelName !== "unknown") {
+					// guardrails-allow PREVENT-PI-004: cost API pricing lookup (user-opted-in)
+					const apiPricing = lookupCostApiPricing(modelName);
+					rate = apiPricing?.inputRate ?? 0;
+				}
+				if (rate > 0) {
 					const s = computeCacheSavings(
 						lifetime.totalCacheRead,
 						lifetime.totalCacheWrite,
-						snap.inputRate,
+						rate,
 					);
 					savings = {
 						cacheReadSaved: s.cacheReadSaved,
 						cacheWriteCost: s.cacheWriteCost,
 						netSaved: s.netSaved,
-						model: snap.modelName ?? snap.modelId ?? "unknown",
-						inputRate: snap.inputRate,
+						model: modelName,
+						inputRate: rate,
 					};
 				}
 			} catch {

package/extensions/dashboard-server/routes-rag-settings-helpers.ts

@@ -272,6 +272,23 @@ export const SETTINGS: ReadonlyArray<{
 			num("MEGACOMPACT_EMBED_CACHE", "Embed Cache Size", "Embedding cache entries (0 = disabled)", 256, 0, 10000),
 		],
 	},
+	{
+		name: "Cost API",
+		settings: [
+			boolDirect(
+				"MEGACOMPACT_COST_API_ENABLED",
+				"Cost API Lookup",
+				"Fetch model pricing from an external API (PREVENT-PI-004 network exception — opt-in). Enriches the dashboard Cache/Repos tabs with real $/token rates for models not in the local pricing table.",
+				false,
+			),
+			str(
+				"MEGACOMPACT_COST_API_URL",
+				"Cost API URL",
+				"OpenRouter-compatible model pricing endpoint (e.g. https://openrouter.ai/api/v1/models). Only contacted when Cost API Lookup is ON.",
+				"",
+			),
+		],
+	},
 ];
 
 /** Flat index of every setting by key for O(1) lookup + validation. */

package/extensions/dashboard-server/routes-raptor.ts

@@ -10,7 +10,7 @@ import { createRequire } from "node:module";
 import type { ServerResponse, IncomingMessage } from "node:http";
 import { parse as parseUrl } from "node:url";
 import type { RouteContext } from "./routes-core.js";
-import type { RaptorTreeResponse, RaptorNodeDTO } from "./api-contracts/raptor.js";
+import type { RaptorTreeResponse, RaptorNodeDTO, RaptorBuildHistoryResponse, RaptorBuildHistoryDTO } from "./api-contracts/raptor.js";
 import { openStore } from "../../src/store/sqlite.js";
 
 const _req = createRequire(import.meta.url);
@@ -126,3 +126,90 @@ export function handleRaptorTree(
 		return true;
 	}
 }
+
+/** Find the most recent session that has build history rows (else null). */
+function latestBuildSession(stateDir: string): string | null {
+	try {
+		const db = openStore(stateDir);
+		const row = db
+			.prepare(
+				"SELECT DISTINCT session_id FROM raptor_build_history ORDER BY completed_at DESC LIMIT 1",
+			)
+			.get() as { session_id: string } | undefined;
+		return row?.session_id ?? null;
+	} catch {
+		return null;
+	}
+}
+
+export function handleRaptorBuildHistory(
+	req: IncomingMessage,
+	res: ServerResponse,
+	ctx: RouteContext,
+): boolean {
+	if (req.method !== "GET") return false;
+	const parsed = parseUrl(req.url ?? "", true);
+	if (parsed.pathname !== "/api/raptor-build-history") return false;
+
+	try {
+		const { listBuildHistory } = _req(
+			"../../src/dedup/raptor/buildHistory.js",
+		) as {
+			listBuildHistory: (
+				sessionId: string,
+				stateDir: string,
+			) => Array<{
+				buildId: string;
+				sessionId: string;
+				startedAt: number;
+				completedAt: number;
+				nodeCount: number;
+				leafCount: number;
+				depth: number;
+				coherenceScore: number | null;
+				timedOut: boolean;
+			}>;
+		};
+
+		let sessionId =
+			typeof parsed.query.sessionId === "string" ? parsed.query.sessionId : "";
+
+		if (!sessionId) {
+			sessionId = latestBuildSession(ctx.stateDir) ?? "";
+			if (!sessionId) {
+				const body: RaptorBuildHistoryResponse = { builds: [], empty: true };
+				res.writeHead(200, { "Content-Type": "application/json" });
+				res.end(JSON.stringify(body));
+				return true;
+			}
+		}
+
+		const rows = listBuildHistory(sessionId, ctx.stateDir);
+		if (rows.length === 0) {
+			const body: RaptorBuildHistoryResponse = { builds: [], empty: true };
+			res.writeHead(200, { "Content-Type": "application/json" });
+			res.end(JSON.stringify(body));
+			return true;
+		}
+
+		const dtos: RaptorBuildHistoryDTO[] = rows.map((r) => ({
+			buildId: r.buildId,
+			sessionId: r.sessionId,
+			startedAt: r.startedAt,
+			completedAt: r.completedAt,
+			nodeCount: r.nodeCount,
+			leafCount: r.leafCount,
+			depth: r.depth,
+			coherenceScore: r.coherenceScore,
+			timedOut: r.timedOut,
+		}));
+		const body: RaptorBuildHistoryResponse = { builds: dtos, empty: false };
+		res.writeHead(200, { "Content-Type": "application/json" });
+		res.end(JSON.stringify(body));
+		return true;
+	} catch (e) {
+		res.writeHead(500, { "Content-Type": "application/json" });
+		res.end(JSON.stringify({ error: String(e) }));
+		return true;
+	}
+}

package/extensions/dashboard-server/routes.ts

@@ -23,7 +23,7 @@ export { handleProviderCache } from "./routes-cache.js";
 export { handleMemoryStatus } from "./routes-memory.js";
 export { handleSetupStatus, handleSetupDetect, handleSetupConfigure } from "./routes-setup.js";
 export { handleMemoryMap } from "./routes-memory-map.js";
-export { handleRaptorTree } from "./routes-raptor.js";
+export { handleRaptorTree, handleRaptorBuildHistory } from "./routes-raptor.js";
 export { handleCacheStripes } from "./routes-cache.js";
 export { handleContextHealth, handleCachePoison, handleHealthSettings } from "./routes-health.js";
 export { handleEmbedderHealth } from "./routes-embedder-health.js";

package/extensions/dashboard-server/server.ts

@@ -46,6 +46,7 @@ import {
 	handleSetupConfigure,
 	handleMemoryMap,
 	handleRaptorTree,
+	handleRaptorBuildHistory,
 	handleContextHealth,
 	handleCachePoison,
 	handleHealthSettings,
@@ -260,6 +261,7 @@ export async function launchDashboardServer(
 		if (handleSetupConfigure(req, res, ctx)) return;
 		if (handleMemoryMap(req, res, ctx)) return;
 		if (handleRaptorTree(req, res, ctx)) return;
+		if (handleRaptorBuildHistory(req, res, ctx)) return;
 		if (handleContextHealth(req, res, ctx)) return;
 		if (handleCachePoison(req, res, ctx)) return;
 		if (handleHealthSettings(req, res, ctx)) return;

package/extensions/mega-pipeline/recall.ts

@@ -107,16 +107,23 @@ export function doRecall(
 		);
 		runtime.lastWhy = `why: recalled@${scorePct}% (${result.toInject.length} chkpt)`;
 	}
+	let sumTokens = 0;
+	for (const h of result.toInject) sumTokens += h.checkpoint.tokenEstimate;
 	if (result.toInject.length > 0) {
-		let sumTokens = 0;
-		for (const h of result.toInject) sumTokens += h.checkpoint.tokenEstimate;
 		runtime.rt.recallInjections += result.toInject.length;
 		runtime.rt.cacheHitTokens += sumTokens;
 		incRecallInjected(result.toInject.length, runtime.currentStateDir);
 		incCacheHitTokens(sumTokens, runtime.currentStateDir);
-		// S43: record recall provenance — which checkpoints/summaries served this
-		// turn, their score + source path. Linked to the turn row written at
-		// turn_end via the conversation+turnIndex. Best-effort + non-fatal.
+	}
+	// S43: record recall provenance — which checkpoints/summaries served this
+	// turn, their score + source path. Linked to the turn row written at
+	// turn_end via the conversation+turnIndex. Best-effort + non-fatal.
+	// Persists telemetry (HyDE + recall metrics) even when recall returned
+	// no hits, so empty-recall HyDE invocations are still visible in the
+	// dashboard Turns/Metrics tabs.
+	const hasTelemetry =
+		result.hydeInfo != null || result.recallMetrics != null;
+	if (result.toInject.length > 0 || hasTelemetry) {
 		try {
 			const convId = ensureConversationIdFor(
 				config,
@@ -136,22 +143,24 @@ export function doRecall(
 				},
 				runtime.currentStateDir,
 			);
-			recordRecallWrite(
-				config,
-				turnId,
-				result.toInject.map((h) => ({
-					checkpointId: h.checkpoint.checkpointId,
-					score: h.score,
-					source:
-						h.raptorLevel !== undefined
-							? "raptor"
-							: h.repoId
-								? "cross-repo"
-								: "flat",
-					raptorLevel: h.raptorLevel,
-				})),
-				runtime.currentStateDir,
-			);
+			if (result.toInject.length > 0) {
+				recordRecallWrite(
+					config,
+					turnId,
+					result.toInject.map((h) => ({
+						checkpointId: h.checkpoint.checkpointId,
+						score: h.score,
+						source:
+							h.raptorLevel !== undefined
+								? "raptor"
+								: h.repoId
+									? "cross-repo"
+									: "flat",
+						raptorLevel: h.raptorLevel,
+					})),
+					runtime.currentStateDir,
+				);
+			}
 		} catch {
 			/* non-fatal: recall provenance never breaks the recall path */
 		}

package/extensions/mega-runtime/capture-model.ts

@@ -11,6 +11,7 @@ import { resolveRepoRoot } from "../mega-config.js";
 import { recordModelSnapshot, recordRepoModel } from "../../src/store/sqlite.js";
 import type { ModelSnapshot } from "../../src/store/sqlite.js";
 import { lookupModelInputRate } from "../../src/pricing.js";
+import { costApiConfig, lookupCostApiPricing } from "../../src/costApi.js";
 
 // ---------------------------------------------------------------------- types
 
@@ -45,13 +46,24 @@ export function captureModelImpl(ctx: CaptureModelContext, ectx: ExtensionContex
 	}
 	const modelId = m.id;
 	const fallbackInput = lookupModelInputRate(modelId);
+	let inputRate = m.cost?.input || fallbackInput || 0;
+	let outputRate = m.cost?.output ?? 0;
+	// Cost API last-resort fallback for models not in the local pricing table
+	if (inputRate <= 0 && costApiConfig().enabled) {
+		// guardrails-allow PREVENT-PI-004: cost API pricing lookup (user-opted-in)
+		const apiPricing = lookupCostApiPricing(modelId);
+		if (apiPricing) {
+			inputRate = apiPricing.inputRate ?? 0;
+			if (outputRate <= 0) outputRate = apiPricing.outputRate ?? 0;
+		}
+	}
 	const snap: Omit<ModelSnapshot, "capturedAt"> = {
 		provider: m.provider,
 		providerName,
 		modelId,
 		modelName: m.name ?? null,
-		inputRate: m.cost?.input || fallbackInput || 0,
-		outputRate: m.cost?.output ?? 0,
+		inputRate,
+		outputRate,
 		contextWindow: m.contextWindow ?? 0,
 		maxTokens: m.maxTokens ?? 0,
 		reasoning: !!m.reasoning,

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

@@ -72,6 +72,9 @@ export interface RuntimeSnapshotContext extends RuntimeHelpersContext {
 	lastSnapshotSig: string | null;
 	lastWidgetCtx?: ExtensionContext;
 	lastActivityAt: number;
+	/** Timestamp (ms) of the last session heartbeat write. Used by the
+	 *  material-change gate fast path to refresh heartbeats on a cadence. */
+	lastHeartbeatAt: number;
 	lastLevel: number;
 	diagCtxFastGate: number;
 	diagLiveTrimFires: number;
@@ -117,6 +120,12 @@ export function snapshotImpl(
 	const sig = materialSigImpl(self);
 	if (ctx && self.widgetData && self.lastSnapshotSig === sig) {
 		self.renderWidget(ctx);
+		// Refresh heartbeat on a time cadence even when material state hasn't
+		// changed, so the session doesn't appear stale and get pruned by the
+		// dashboard's 30-min cutoff. The full snapshot recompute is still gated
+		// (expensive SQLite opens + writeFileSync), but a heartbeat row is
+		// cheap (single INSERT OR REPLACE on the index DB).
+		refreshHeartbeatIfStale(self, ctx, 10_000);
 		return;
 	}
 	const perfT0 = performance.now();
@@ -313,4 +322,35 @@ export function snapshotImpl(
 		/* non-fatal: perf instrumentation never blocks the agent */
 	}
 	self.lastSnapshotSig = sig;
+	self.lastHeartbeatAt = Date.now();
+}
+
+// ----------------------------------------------------------- heartbeat refresh
+
+/** Refresh the session heartbeat if enough time has elapsed since the last
+ *  write. Called from the material-change gate fast path (where the full
+ *  snapshot recompute is skipped) so the session stays visible in the
+ *  dashboard during idle/typing periods. Non-fatal — best-effort like the
+ *  main heartbeat write. */
+function refreshHeartbeatIfStale(
+	self: RuntimeSnapshotContext,
+	ctx: ExtensionContext | undefined,
+	intervalMs: number,
+): void {
+	const now = Date.now();
+	if (now - self.lastHeartbeatAt < intervalMs) return;
+	try {
+		const repo =
+			resolveRepoRoot(ctx?.cwd ?? self.currentStateDir) ?? self.currentStateDir;
+		recordSessionHeartbeat(
+			process.pid,
+			self.rt.sessionId,
+			repo,
+			self.currentStateDir,
+			self.lastCtxWindow || 0,
+		);
+		self.lastHeartbeatAt = now;
+	} catch {
+		/* non-fatal: heartbeat refresh must never block the snapshot path */
+	}
 }

package/extensions/mega-runtime/runtime.ts

@@ -209,6 +209,7 @@ export class MegaRuntime {
 	// (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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.13.7",
+  "version": "0.14.1",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",

package/src/config/dedup.ts

@@ -89,7 +89,8 @@ export function loadDedupConfig(): DedupConfigShape {
     L2_ENABLED: envBool("MEGACOMPACT_L2_ENABLED", true),
     // Fix D: RAPTOR promoted to live recall. Default ON; canary.ts sequences it
     // last (L0→L1→L2→RAPTOR) and auto-disables on p95 breach, so promotion is
-    // safe. `RAPTOR_SHADOW_MODE=false` still gates serving during transition.
+    // safe. Shadow mode (RAPTOR_SHADOW_MODE=true) opts out of serving while
+    // still building + persisting the tree (transition/eval use).
     RAPTOR_ENABLED: envBool("MEGACOMPACT_RAPTOR_ENABLED", true),
     MARK_ONLY_L0: envBool("MEGACOMPACT_MARK_ONLY_L0", false),
     MARK_ONLY_L1: envBool("MEGACOMPACT_MARK_ONLY_L1", false),