pi-mega-compact 0.11.7 → 0.11.9

package/extensions/dashboard-server/gather-debug.ts

@@ -0,0 +1,136 @@
+/**
+ * gather-debug.ts — assemble a diagnostic bundle for bug reports.
+ *
+ * POST /api/maintenance/gather-debug → DebugBundleResponse. Reads local
+ * SQLite + FS only (PREVENT-PI-004: zero network). Each section is non-fatal:
+ * a read failure records `{ error }` for that section and continues, so the
+ * bundle always returns 200 with whatever could be gathered.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import type { ServerResponse } from "node:http";
+import type { RouteContext } from "./routes-core.js";
+import type { DebugBundleResponse } from "./api-contracts/maintenance.js";
+import { defaultMetricsPath, defaultEventsPath } from "../../src/monitoring.js";
+import { ownVersion } from "../mega-runtime/helpers.js";
+import { MEGACOMPACT_ENV_KEYS } from "./gather-debug-keys.js";
+
+/** Event-name patterns that indicate a critical/compaction class of error. */
+const CRITICAL_PATTERN =
+	/critical|overflow|already[.\s-]?compacted|compaction[.\s-]?failed|stream[.\s-]?death|poisoned|prefix_stability/i;
+
+const require = createRequire(import.meta.url);
+
+/** Lazy store opener (mirrors routes-maintenance.ts's lazyStoreUtils). */
+function openStoreDb(ctx: RouteContext) {
+	const mod = require("../../src/store/sqlite/utils.js") as typeof import("../../src/store/sqlite/utils.js");
+	return mod.openStore(ctx.stateDir);
+}
+
+/** Lazy maintenance loaders (mirrors routes-maintenance.ts's lazyMaintenance). */
+function loadMaintenance() {
+	return require("../../src/store/sqlite/maintenance.js") as typeof import("../../src/store/sqlite/maintenance.js");
+}
+
+/** Send the debug bundle as JSON. Always 200 (partial on read failure). */
+export function sendGatherDebug(res: ServerResponse, ctx: RouteContext): void {
+	const result: DebugBundleResponse = {
+		builtAt: Date.now(),
+		version: ownVersion(),
+		stateDir: ctx.stateDir,
+		config: {},
+		schemaHealth: { error: "not fetched" },
+		storeStats: { error: "not fetched" },
+		dashboardSnapshot: { error: "not fetched" },
+		recentEvents: [],
+		criticalEvents: [],
+	};
+
+	// 1. Config flags (no secrets — MEGACOMPACT_* only)
+	for (const key of MEGACOMPACT_ENV_KEYS) {
+		result.config[key] = process.env[key] ?? "<default>";
+	}
+
+	// 2. Schema health
+	try {
+		const maint = loadMaintenance();
+		const integrity = maint.integrityCheck(ctx.stateDir);
+		const db = openStoreDb(ctx);
+		const metaRow = db
+			.prepare("SELECT value FROM meta WHERE key = ?")
+			.get("schema_version") as { value: string } | undefined;
+		const schemaVersion = metaRow ? Number(metaRow.value) : 0;
+		const fkRows = db.prepare("PRAGMA foreign_key_check").all() as Array<Record<string, unknown>>;
+		result.schemaHealth = {
+			type: "schema-health" as const,
+			schemaVersion,
+			integrity,
+			fkCheck: fkRows.map((r) => JSON.stringify(r)),
+			columns: [],
+			healthy: true,
+		};
+	} catch (e) {
+		result.schemaHealth = { error: e instanceof Error ? e.message : String(e) };
+	}
+
+	// 3. Store stats
+	try {
+		const maint = loadMaintenance();
+		const raw = maint.getDbStats(ctx.stateDir);
+		result.storeStats = {
+			type: "db-stats" as const,
+			tables: Object.entries(raw.tableCounts).map(([table, rowCount]) => ({ table, rowCount })),
+			storage: {
+				files: { dbBytes: raw.dbBytes, walBytes: raw.walBytes, shmBytes: raw.shmBytes },
+				pageSize: raw.pageSize,
+				pageCount: raw.pageCount,
+				freelistPages: raw.freelistPages,
+			},
+		};
+	} catch (e) {
+		result.storeStats = { error: e instanceof Error ? e.message : String(e) };
+	}
+
+	// 4. Dashboard snapshot
+	try {
+		const path = defaultMetricsPath(ctx.stateDir);
+		if (existsSync(path)) {
+			const raw = readFileSync(path, "utf-8");
+			result.dashboardSnapshot = JSON.parse(raw) as unknown;
+		} else {
+			result.dashboardSnapshot = { error: "no snapshot" };
+		}
+	} catch (e) {
+		result.dashboardSnapshot = { error: e instanceof Error ? e.message : String(e) };
+	}
+
+	// 5. Recent + critical events (tail ~200 lines of events.log)
+	try {
+		const path = defaultEventsPath(ctx.stateDir);
+		if (existsSync(path)) {
+			const lines = readFileSync(path, "utf-8").split("\n").filter(Boolean);
+			for (const line of lines.slice(-200)) {
+				try {
+					const ev = JSON.parse(line) as unknown;
+					result.recentEvents.push(ev);
+					if (CRITICAL_PATTERN.test(line)) result.criticalEvents.push(ev);
+				} catch {
+					continue; // skip unparseable line (PREVENT-001)
+				}
+			}
+		}
+	} catch (e) {
+		result.recentEvents = [{ error: e instanceof Error ? e.message : String(e) }];
+	}
+
+	// Send (local helper to avoid importing sendJson from a non-exporting module)
+	try {
+		const body = JSON.stringify(result);
+		res.writeHead(200, { "Content-Type": "application/json" }); // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+		res.end(body);
+	} catch {
+		// last resort — never leave the response hanging
+		res.writeHead(500, { "Content-Type": "application/json" }); // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+		res.end('{"error":"failed to serialize debug bundle"}');
+	}
+}

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

@@ -13,6 +13,7 @@
 
 import { createRequire } from "node:module";
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { sendGatherDebug } from "./gather-debug.js";
 
 import type { RouteContext } from "./routes-core.js";
 
@@ -77,6 +78,12 @@ export function handleMaintenance(
 		return true;
 	}
 
+	// ── POST /api/maintenance/gather-debug ──────────────────────────
+	if (method === "POST" && url === "/api/maintenance/gather-debug") {
+		sendGatherDebug(res, ctx);
+		return true;
+	}
+
 	// ── GET /api/maintenance ──────────────────────────────────────────
 	if (method === "GET" && url === "/api/maintenance") {
 		sendDbStats(res, ctx);

package/extensions/dashboard-server/routes-memory-map.ts

@@ -1,7 +1,8 @@
 /**
- * routes-memory-map.ts — GET /api/memory-map route handler (S46).
+ * routes-memory-map.ts — GET /api/memory-map route handler (S46/D3).
  *
  * Builds a memory graph from the local SQLite store and returns it as JSON.
+ * D3: surfaces nodeType on each node and the GraphValidationReport.
  * Uses an inline require to the pi-agnostic src/memoryGraph.ts builder.
  */
 import { createRequire } from "node:module";
@@ -25,14 +26,7 @@ export function handleMemoryMap(
 
 	// guardrails-allow PREVENT-PI-004: local loopback-only dashboard server — reads the local SQLite store for graph data.
 	const { buildMemoryGraph } = _req("../../src/memoryGraph.js") as {
-		buildMemoryGraph: (opts?: {
-			sessionId?: string;
-			similarityThreshold?: number;
-			maxEdgesPerNode?: number;
-			stateDir?: string;
-			includeRaptorEdges?: boolean;
-			includeTemporalEdges?: boolean;
-		}) => MemoryGraphReturn;
+		buildMemoryGraph: (sessionId: string, stateDir: string) => MemoryGraphReturn;
 	};
 
 	type MemoryGraphReturn = {
@@ -48,6 +42,7 @@ export function handleMemoryMap(
 			topicSummary: string | undefined;
 			decisionCount: number;
 			textSnippet: string;
+			nodeType: "checkpoint" | "turn" | "turn-content" | "memory";
 		}>;
 		edges: Array<{
 			source: string;
@@ -56,31 +51,25 @@ export function handleMemoryMap(
 			type: "temporal" | "semantic" | "raptor_parent";
 		}>;
 		metadata: {
-			sessionCount: number;
-			totalCheckpoints: number;
+			totalNodes: number;
 			totalEdges: number;
-			semanticEdgeCount: number;
-			temporalEdgeCount: number;
-			raptorEdgeCount: number;
-			similarityThresholdUsed: number;
+			avgWeight: number;
+			nodeTypeBreakdown: Record<string, number>;
+			edgeTypeBreakdown: Record<string, number>;
+		};
+		validation: {
+			gatesRun: number;
+			gatesPassed: number;
+			dropped: { nodes: number; edges: number };
+			warnings: Array<{ gate: string; code: string; count: number }>;
+			sources: { checkpoint: number; turn: number; turnContent: number; memory: number };
 			builtAt: number;
 		};
 	};
 
-	const sessionId = typeof parsed.query.sessionId === "string" ? parsed.query.sessionId : undefined;
-	const threshold = typeof parsed.query.threshold === "string" ? Number.parseFloat(parsed.query.threshold) : undefined;
-	const maxEdges = typeof parsed.query.maxEdgesPerNode === "string" ? Number.parseInt(parsed.query.maxEdgesPerNode, 10) : undefined;
-	const raptorEdges = parsed.query.includeRaptorEdges === "false" ? false : true;
-	const temporalEdges = parsed.query.includeTemporalEdges === "false" ? false : true;
+	const sessionId = typeof parsed.query.sessionId === "string" ? parsed.query.sessionId : "";
 
-	const graph = buildMemoryGraph({
-		sessionId,
-		similarityThreshold: threshold,
-		maxEdgesPerNode: maxEdges,
-		stateDir: ctx.stateDir,
-		includeRaptorEdges: raptorEdges,
-		includeTemporalEdges: temporalEdges,
-	});
+	const graph = buildMemoryGraph(sessionId, ctx.stateDir);
 
 	const nodes: MemoryMapNode[] = graph.nodes.map((n) => ({
 		id: n.id,
@@ -94,10 +83,13 @@ export function handleMemoryMap(
 		topicSummary: n.topicSummary,
 		decisionCount: n.decisionCount,
 		textSnippet: n.textSnippet,
+		// D3: pass through nodeType for UI node-shape encoding
+		nodeType: n.nodeType,
 	}));
 
 	const edges: MemoryMapEdgeEntry[] = graph.edges as MemoryMapEdgeEntry[];
-	const response: MemoryMapResponse = { nodes, edges, metadata: graph.metadata };
+	// D3: surface the validation report (optional in the response type for backward compat)
+	const response: MemoryMapResponse = { nodes, edges, metadata: graph.metadata, validation: graph.validation };
 
 	res.writeHead(200, { "Content-Type": "application/json" });
 	res.end(JSON.stringify(response));

package/extensions/mega-commands.ts

@@ -11,13 +11,13 @@ import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
 import { normalizeSessionId } from "../src/store.js";
 import { listCheckpoints, latestModelSnapshot, countInjectedGlobal, listRepoRegistry } from "../src/store/sqlite.js";
 import { decompressSmart } from "../src/store/compression.js";
-import { loadMetrics, fpRate, p95, defaultMetricsPath } from "../src/monitoring.js";
+import { loadMetrics, fpRate, p95, defaultMetricsPath, defaultEventsPath } from "../src/monitoring.js";
 import { type MegaRuntime, C, recentUserQuery } from "./mega-runtime.js";
 import { runCompact, doRecall, doRecallAsync } from "./mega-pipeline.js";
 import { vectorStats, vectorRepoStats, vectorDataInvariant } from "../src/vectorStore.js";
 import type { MegaConfig } from "./mega-config.js";
 import { spawnSync } from "node:child_process"; // guardrails-allow PREVENT-PI-004: local subprocess detection only (no network)
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { createRequire } from "node:module";
@@ -280,6 +280,52 @@ export function registerCommands(pi: ExtensionAPI, runtime: MegaRuntime, config:
     },
   });
 
+  /**
+   * Try to peek at recent events.log and mega-compact.log for low recall quality signals.
+   * Best-effort, non-fatal — returns true if a low-quality signal was found.
+   */
+  /**
+   * Try to peek at recent events.log and mega-compact.log for low recall quality signals.
+   * Best-effort, non-fatal — returns true if a low-quality signal was found.
+   */
+  function checkRecallQuality(stateDir: string): boolean {
+    const eventPaths = [
+      defaultEventsPath(stateDir),
+      path.join(stateDir, "mega-compact.log"),
+    ];
+    for (const fp of eventPaths) {
+      try {
+        if (!existsSync(fp)) continue;
+        const buf = readFileSync(fp, { encoding: "utf-8" });
+        // Only scan last 64 KiB of the file
+        const tail = buf.length > 65536 ? buf.slice(buf.length - 65536) : buf;
+        const lines = tail.split("\n").filter(Boolean);
+        for (const line of lines) {
+          try {
+            // guardrails-allow PREVENT-001: JSON.parse with null check
+            const parsed = JSON.parse(line);
+            if (typeof parsed !== "object" || parsed === null) continue;
+            // Check for recall_metrics_low_quality event (latest format)
+            if (parsed.event === "recall_metrics_low_quality" && parsed.score !== undefined) {
+              if (typeof parsed.score === "number" && parsed.score < 0.4) return true;
+            }
+            // Check for recall_metrics with low relevanceScore
+            if (parsed.event === "recall_metrics" && parsed.relevanceScore !== undefined) {
+              if (typeof parsed.relevanceScore === "number" && parsed.relevanceScore < 0.4) return true;
+            }
+            // Check for RecallQualityEvent format from monitoring.ts
+            if (parsed.score !== undefined && typeof parsed.score === "number" && parsed.score < 0.4) return true;
+          } catch {
+            // skip unparseable lines
+          }
+        }
+      } catch {
+        // non-fatal: skip if can't read
+      }
+    }
+    return false;
+  }
+
   pi.registerCommand("mega-setup", {
     description:
       "Local embedding setup wizard — detect available embedders and configure mega-compact.",
@@ -355,6 +401,11 @@ export function registerCommands(pi: ExtensionAPI, runtime: MegaRuntime, config:
         // require error
       }
 
+      // --- 2.5 Quality check ---
+      // Scan recent events for low recall quality (best-effort, non-fatal)
+      const stateDir = process.env["MEGACOMPACT_STATE_DIR"] ?? path.join(os.homedir(), ".pi", "mega-compact");
+      const lowRecallQuality = checkRecallQuality(stateDir);
+
       // --- 3. Build choices ---
       interface Choice {
         label: string;
@@ -402,6 +453,11 @@ export function registerCommands(pi: ExtensionAPI, runtime: MegaRuntime, config:
 
       // --- 4. Prompt user ---
       log(`Current embedder: ${currentEmbedder}`);
+      if (lowRecallQuality) {
+        log(
+          "Tap: recent recall quality is low. Consider switching to Ollama or llama.cpp for better results.",
+        );
+      }
       let selected = "trigram";
       if (choices.length > 1) {
         try {
@@ -435,7 +491,6 @@ export function registerCommands(pi: ExtensionAPI, runtime: MegaRuntime, config:
         const envContent = lines.join("\n") + "\n";
 
         // Write .mega-compact.env to state dir
-        const stateDir = process.env["MEGACOMPACT_STATE_DIR"] ?? path.join(os.homedir(), ".pi", "mega-compact");
         try {
           mkdirSync(stateDir, { recursive: true });
           writeFileSync(path.join(stateDir, ".mega-compact.env"), envContent, "utf-8");
@@ -457,8 +512,6 @@ export function registerCommands(pi: ExtensionAPI, runtime: MegaRuntime, config:
           `export MEGACOMPACT_EMBEDDING_URL="${url}"`,
         ];
         const envContent = lines.join("\n") + "\n";
-
-        const stateDir = process.env["MEGACOMPACT_STATE_DIR"] ?? path.join(os.homedir(), ".pi", "mega-compact");
         try {
           mkdirSync(stateDir, { recursive: true });
           writeFileSync(path.join(stateDir, ".mega-compact.env"), envContent, "utf-8");
@@ -477,7 +530,11 @@ export function registerCommands(pi: ExtensionAPI, runtime: MegaRuntime, config:
           "ONNX Runtime configuration is experimental.\n\nSet MEGACOMPACT_EMBEDDING_URL to your local ONNX server URL, or see docs for manual setup.\nKeeping TrigramEmbedder for now.",
         );
       } else {
-        log("Keeping TrigramEmbedder (default). No configuration needed.");
+        const qualityTip =
+          lowRecallQuality
+            ? " Recent recall quality is low — consider running /mega-setup again to switch to Ollama or llama.cpp for better results."
+            : "";
+        log(`Keeping TrigramEmbedder (default). No configuration needed.${qualityTip}`);
       }
      } catch (e) {
        ctx.ui.notify(`[mega-compact] /mega-setup failed: ${String(e)}`);

package/extensions/mega-config.ts

@@ -172,6 +172,9 @@ export interface MegaConfig {
 	 *  from volatile tool results so the prompt-cache prefix stays stable.
 	 *  Default OFF (flag-OFF = byte-identical pre-sprint). */
 	messageSeparation: boolean;
+	/** P3: Cache-aware striping (PLAN_V2 Phase 3). Inserts stability-ordered
+	 *  cache stripes between summaries and thread. Default OFF. */
+	cacheStriping: boolean;
 	debug: boolean;
 	/** Master reconciliation: TUI shutdown widget (MEGACOMPACT_TUI_WIDGET=0 to disable). */
 	tuiWidget: boolean;
@@ -183,6 +186,18 @@ export interface MegaConfig {
 	ragRecallMetrics: boolean;
 	/** S57 B4: Memory graph traversal (dashboard-oriented). */
 	ragMemoryGraph: boolean;
+	/** D1: Seed initial wiki topic model from live turns when no context_chunks exist yet. */
+	wikiSeedFromTurns: boolean;
+	/** D3 Source A: Include structural turn nodes in the memory graph (metadata only, no content). */
+	memoryGraphSeedTurns: boolean;
+	/** D3 Source B: Include raw_transcript content nodes in the memory graph (requires dbMirror). */
+	memoryGraphSeedTurnContent: boolean;
+	/** D3 Source C: Include memory review nodes in the memory graph. */
+	memoryGraphSeedMemories: boolean;
+	/** D3 edges: Stricter cosine floor for cross-type edges (e.g. turn↔checkpoint). */
+	memoryGraphCrossTypeThreshold: number;
+	/** D3 edges: Cosine floor for within-type semantic edges. */
+	memoryGraphWithinTypeThreshold: number;
 }
 
 function envFlag(name: string, fallback: number): number {
@@ -345,11 +360,18 @@ export function loadConfig(): MegaConfig {
 		windowDedupe: envBool("MEGACOMPACT_WINDOW_DEDUPE", true),
 		recallTailInject: envBool("MEGACOMPACT_RECALL_TAIL_INJECT", true),
 		messageSeparation: envBool("MEGACOMPACT_MESSAGE_SEPARATION", false),
+			cacheStriping: envBool("MEGACOMPACT_CACHE_STRIPING", false),
 		tuiWidget: envBool("MEGACOMPACT_TUI_WIDGET", true),
 		ragQueryReformulation: envBool("MEGACOMPACT_QUERY_REFORMULATION", false),
 		ragTieredRouter: envBool("MEGACOMPACT_TIERED_ROUTER", false),
 		ragRecallMetrics: envBool("MEGACOMPACT_RECALL_METRICS", false),
 		ragMemoryGraph: envBool("MEGACOMPACT_MEMORY_GRAPH", false),
+		wikiSeedFromTurns: envBool("MEGACOMPACT_WIKI_SEED_FROM_TURNS", true),
+		memoryGraphSeedTurns: envBool("MEGACOMPACT_MEMORY_GRAPH_SEED_TURNS", true),
+		memoryGraphSeedTurnContent: envBool("MEGACOMPACT_MEMORY_GRAPH_SEED_TURN_CONTENT", true),
+		memoryGraphSeedMemories: envBool("MEGACOMPACT_MEMORY_GRAPH_SEED_MEMORIES", true),
+		memoryGraphCrossTypeThreshold: envFlag("MEGACOMPACT_MEMORY_GRAPH_CROSS_TYPE_THRESHOLD", 0.85),
+		memoryGraphWithinTypeThreshold: envFlag("MEGACOMPACT_MEMORY_GRAPH_WITHIN_TYPE_THRESHOLD", 0.7),
 		// D.1: env-overridable recompact delta (minimum context growth % before
 		// re-compacting instead of replaying the cached live trim). Default 50.
 		recompactPctDelta: envFlag("MEGACOMPACT_RECOMPACT_PCT_DELTA", 50),

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

@@ -26,6 +26,15 @@ import {
 import { safeSendUserMessage } from "./send-safe.js";
 import { maybeSendProviderOutageAdvisory } from "./outage-advisor.js";
 import { vectorStats } from "../../src/vectorStore.js";
+import { defaultEmbedder } from "../../src/embedder.js";
+import {
+	storeTopicEmbedding,
+	loadTopicEmbedding,
+	detectTopicShift,
+} from "./separated-prompt.js";
+import {
+	refreshStripeAssignments as writeStripeAssignments,
+} from "../../src/cache-stripe-impl.js";
 
 /** Register agent/turn tracking event handlers. */
 export function registerAgentHandlers(
@@ -167,9 +176,20 @@ export function registerAgentHandlers(
 					// context-handler.ts:258-287 so both call sites stay in sync.
 					const cooldownMs = config.raceGuardStrict ? 30_000 : 10_000;
 					const sinceCompact = now - (runtime.rt.lastNativeCompactAt ?? 0);
+					// CRITICAL-OVER ESCAPE HATCH: when context is critically over the
+					// window (>= 90%), force the durable ctx.compact() even if
+					// piCompactWouldNoop says it would no-op ("Already compacted").
+					// Without this, the on-disk transcript never truncates and the
+					// session stays overflowed on every resume — the "Already
+					// compacted" + overflow death-spiral (2026-08-01 incident). The
+					// cooldown still applies (we don't spam compact), but the no-op
+					// gate is bypassed when critical. pi's ctx.compact() may throw
+					// "Already compacted" in the truly-no-op case — wrapped in
+					// try/catch so the throw is non-fatal.
+					const criticalOver = (runtime.lastCtxPercent ?? 0) >= 90;
 					if (sinceCompact < cooldownMs) {
 						runtime.diagAgentEndDurableSkipRecent++;
-					} else if (!piCompactWouldNoop(ctx)) {
+					} else if (criticalOver || !piCompactWouldNoop(ctx)) {
 						runtime.debounceUntil = now + 2000;
 						runtime.diagAgentEndDurable++;
 						runtime.logger.info("agent-end-durable-trigger", {
@@ -186,6 +206,7 @@ export function registerAgentHandlers(
 							// would re-check before it lands.
 							const stamp = runtime.rt.lastNativeCompactAt;
 							const liveSid = runtime.rt.sessionId;
+							const liveCritical = criticalOver;
 							setTimeout(() => {
 								try {
 									if (runtime.rt.sessionId !== liveSid) return; // session reset
@@ -198,16 +219,22 @@ export function registerAgentHandlers(
 										since2 < cooldownMs
 									)
 										return;
-									if (piCompactWouldNoop(ctx)) return;
+									// CRITICAL-OVER ESCAPE HATCH: bypass the no-op gate when
+									// critical (captured at handler time) so the durable trim fires.
+									if (!liveCritical && piCompactWouldNoop(ctx)) return;
 									ctx.compact({
 										customInstructions: undefined,
-									}); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; deferred + re-validated.
+									}); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; deferred + re-validated. May throw "Already compacted" when the escape hatch forces it — caught below.
 								} catch {
-									/* non-fatal */
+									/* non-fatal: "Already compacted" throws are expected when the critical-over hatch forces a no-op compact */
 								}
 							}, 500);
 						} else {
-							ctx.compact({ customInstructions: undefined }); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; agent settled so no in-flight abort. Race-guarded by lastNativeCompactAt cooldown above (ctx.compact returns void → throw is surfaced by pi as compaction_end; the cooldown prevents the call entirely).
+							try {
+								ctx.compact({ customInstructions: undefined }); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; agent settled so no in-flight abort. May throw "Already compacted" when the critical-over escape hatch forces it — caught.
+							} catch {
+								/* non-fatal */
+							}
 						}
 						didDurableTrim = true;
 					}
@@ -777,5 +804,61 @@ export function registerAgentHandlers(
 		} catch {
 			/* non-fatal: a classifier/retry failure never breaks the agent loop */
 		}
+
+		// P3.5: topic-shift stripe refresh. When MEGACOMPACT_CACHE_STRIPING is ON,
+		// embed the current turn, detect topic shift vs. the previous turn, and
+		// refresh cache stripe assignments when shifted (or first turn). Best-effort:
+		// failures log + continue, never break the agent loop.
+		if (config.cacheStriping) {
+			try {
+				const stateDir = runtime.currentStateDir;
+				const sessionId = runtime.rt.sessionId;
+				const currentTurn = event.turnIndex;
+				const embedder = defaultEmbedder();
+
+				// (a) Extract text from the assistant's response for topic embedding.
+				let textToEmbed = "";
+				const msg = event.message;
+				if (msg.role === "assistant" && Array.isArray(msg.content)) {
+					for (const part of msg.content) {
+						if ("text" in part && typeof part.text === "string") {
+							textToEmbed += part.text + " ";
+						}
+					}
+				}
+				textToEmbed = textToEmbed.trim() || `turn-${currentTurn}`;
+				const embedding = new Float32Array(embedder.embed(textToEmbed));
+				storeTopicEmbedding(stateDir, sessionId, currentTurn, embedding);
+
+				// (b) Load previous turn's embedding and detect topic shift.
+				const prevEmb = currentTurn > 0
+					? loadTopicEmbedding(stateDir, sessionId, currentTurn - 1)
+					: null;
+				const shifted = currentTurn === 0 || detectTopicShift(embedding, prevEmb);
+
+				// (c) If shifted (or first turn), refresh stripe assignments (WRITE path).
+				let chunkCount = 0;
+				if (shifted) {
+					chunkCount = writeStripeAssignments(
+						stateDir,
+						undefined,
+						embedder,
+						(detail) => runtime.logger.info("stripe_refresh_detail", {
+							detail,
+							turnIndex: currentTurn,
+						}),
+					);
+				}
+
+				// (d) Log the refresh outcome.
+				runtime.logger.info("stripe_refresh", {
+					turnIndex: currentTurn,
+					shifted,
+					chunkCount,
+				});
+			} catch {
+				/* non-fatal: stripe refresh never breaks the agent loop */
+			}
+		}
 	});
 }