pi-mega-compact 0.11.4 → 0.11.5

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

@@ -13,10 +13,8 @@ import type {
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import {
 	openStore,
-	appendRawTranscript,
 	writeCheckpointEpoch,
 	type CheckpointEpoch,
-	type RawTranscriptRow,
 } from "../../src/store/sqlite.js";
 import { epochIdFor } from "../../src/mirror/epoch.js";
 import { autoCompactCheck } from "../../src/compact.js";
@@ -37,84 +35,8 @@ import {
 	pressureRatio,
 	type MegaConfig,
 } from "../mega-config.js";
-import { computeContentDigest } from "../../src/dedup/digest.js";
-
-/**
- * Recursively canonicalize a value for deterministic JSON serialization:
- * - Objects: keys sorted alphabetically, values recursively canonicalized
- * - Arrays: elements recursively canonicalized (array ORDER is preserved)
- * - Primitives: returned as-is
- *
- * F5 fix: shallow-sorted JSON.stringify(content, Object.keys(content).sort())
- * omitted nested keys not in the top-level keys array and only sorted one level.
- * This recursively sorts every object at every depth so semantically-equal
- * differently-ordered content hashes identically.
- */
-function canonicalize(value: unknown): unknown {
-	if (value === null || value === undefined) return value;
-	if (typeof value !== "object") return value;
-	if (Array.isArray(value)) return value.map(canonicalize);
-	// Plain object: sort keys, recursively canonicalize values.
-	const sorted = Object.keys(value as Record<string, unknown>).sort();
-	const out: Record<string, unknown> = {};
-	for (const k of sorted) {
-		out[k] = canonicalize((value as Record<string, unknown>)[k]);
-	}
-	return out;
-}
-
-/**
- * Convert a pi AgentMessage to a RawTranscriptRow for the DB mirror.
- * content_bytes is canonical JSON (sorted keys, recursive) for deterministic
- * storage; contentHash is the canonical digest (normalize + hash) that matches
- * what dedupTranscript computes so the two pipelines use the same linkage key.
- *
- * F4 fix: the hash key MUST match on both sides of the append/dedup split.
- * Using computeContentDigest here (normalize → hash) ensures content_ref set
- * by dedupTranscript always resolves to an existing dedup_mirror row even for
- * whitespace/case-variant content. F5 fix: recursive canonicalize replaces the
- * broken shallow-sorted JSON.stringify replacer.
- */
-function toRawTranscriptRow(
-	msg: AgentMessage,
-	sessionId: string,
-	epochId: string,
-	currentTurn?: number,
-): RawTranscriptRow | null {
-	// Narrow to Message union (has content + timestamp).
-	const m = msg as {
-		role?: string;
-		content?: unknown;
-		timestamp?: number;
-		toolName?: string;
-	};
-	const content = m.content;
-	if (content == null || content === "") return null;
-	// Canonical bytes: string content → normalize for consistent byte content;
-	// object content → recursive canonicalize then JSON (no replacer).
-	const contentBytes =
-		typeof content === "string"
-			? content // F5: strings are primitives; their byte content is fixed
-			: JSON.stringify(canonicalize(content));
-	// F4 fix: use the same digest as dedupTranscript so contentHash is consistent
-	// on both sides of the append/dedup split. computeContentDigest normalizes
-	// (strip ANSI, NFC, case-fold, collapse whitespace) then hashes → the same
-	// key is stored in raw_transcript.content_hash AND used as the dedup link.
-	const { contentHash } = computeContentDigest(contentBytes);
-	return {
-		contentHash,
-		sessionId,
-		seq: 0, // assigned by appendRawTranscript (COALESCE(MAX(seq),0)+1)
-		role: m.role ?? "unknown",
-		contentBytes,
-		toolName: m.toolName ?? null,
-		messageTimestamp: m.timestamp ?? null,
-		checkpointEpoch: epochId,
-		// S50: label the row with the turn that produced it (per-turn dedup /
-		// compression-by-turn metrics). Null when the writer omits it (back-compat).
-		turnIndex: currentTurn ?? null,
-	};
-}
+import { appendMirrorMessages } from "./mirror-append.js";
+import { stagedForTail, withRecallTail } from "./recall-tail.js";
 
 /** Register the context event handler (live-trim auto-trigger). */
 export function registerContextHandler(
@@ -140,6 +62,16 @@ export function registerContextHandler(
 		const usage = ctx.getContextUsage();
 		const pct = usage?.percent;
 		const messages = event.messages;
+		// S53: helper to inject the staged recall/memory block as a user-role
+		// tail message at any view-return point. Returns undefined when nothing
+		// is staged (or the flag is OFF) so the caller falls through to its
+		// normal return. The F3 mirror append (above the gates) runs on the
+		// REAL transcript before any view is built, so the injected tail never
+		// reaches raw_transcript (PREVENT-PI: append-only, view-only).
+		const tailResult = (msgs?: readonly AgentMessage[]) => {
+			if (!stagedForTail(runtime, config)) return undefined;
+			return { messages: withRecallTail(msgs ?? messages, runtime, config) };
+		};
 		// Always track context for the dashboard/widget, even when auto is off.
 		// (v0.8 regression: !config.auto gate sat above this, leaving ctx stats
 		// null -> widget '?% / ?/?' when auto disabled. Track first, THEN gate.)
@@ -162,30 +94,35 @@ export function registerContextHandler(
 		runtime.lastCtxPercent = pct ?? null;
 		runtime.lastCtxWindow = usage?.contextWindow ?? 0;
 		runtime.snapshot(ctx);
-		if (!config.auto) return;
+		if (!config.auto) {
+			const tailed = tailResult();
+			if (tailed) return tailed;
+			return;
+		}
 
 		const view = viewForFallback ?? runtime.engineView(messages);
 
-		// S27 DB-mirror: append ALL incoming messages to raw_transcript.
-		// Runs BEFORE fast-gate so every message is captured, even if we
-		// don't compact this turn. Append is idempotent (content_hash PK).
-		if (config.dbMirror) {
-			try {
-				const db = openStore(runtime.currentStateDir);
-				const epochId = epochIdFor(runtime.rt.sessionId);
-				for (const msg of messages) {
-					const raw = toRawTranscriptRow(
-						msg,
+		// S27 DB-mirror: append incoming messages to raw_transcript.
+			// Runs BEFORE fast-gate so every message is captured, even if we
+			// don't compact this turn. Append is idempotent (content_hash PK).
+			// F3: high-water mark (mirror-append.ts) skips already-processed
+			// messages on subsequent events. On fork/rewind (shorter list or
+			// boundary hash mismatch) the mark is dropped, falling back to a
+			// full reprocess.
+			if (config.dbMirror) {
+				try {
+					const db = openStore(runtime.currentStateDir);
+					appendMirrorMessages(
+						db,
+						messages,
 						runtime.rt.sessionId,
-						epochId,
+						epochIdFor(runtime.rt.sessionId),
 						runtime.currentTurn,
 					);
-					if (raw) appendRawTranscript(db, raw);
+				} catch (e) {
+					runtime.logger.warn("db-mirror-append-fail", { error: String(e) });
 				}
-			} catch (e) {
-				runtime.logger.warn("db-mirror-append-fail", { error: String(e) });
 			}
-		}
 
 		// S29 FAST GATE: drive the auto-trigger off the context % (the number the
 		// menu bar shows), NOT the token count — the model under-reports tokens,
@@ -205,18 +142,18 @@ export function registerContextHandler(
 			// custom tier OR tiered-but-pct-unavailable → token gate (S27 fallback).
 			if (currentTokens < runtime.effectiveThreshold) {
 				runtime.diagCtxFastGate++;
-				return;
+				return tailResult() ?? undefined;
 			}
 			const check = autoCompactCheck(currentTokens, runtime.effectiveThreshold); // SERVER-STYLE CONFIRM (local)
 			if (!check.shouldCompact) {
 				runtime.diagCtxNoCompact++;
-				return;
+				return tailResult() ?? undefined;
 			}
 			gatePassed = true;
 		}
 		if (!gatePassed) {
 			runtime.diagCtxFastGate++;
-			return;
+			return tailResult() ?? undefined;
 		}
 
 		// D.2: Replay MUST be exempt from debounce — replay is free (no compute,
@@ -249,9 +186,8 @@ export function registerContextHandler(
 				runtime.snapshot(ctx);
 				// v0.8.7: shallow-copy the cached summary so pi's transformContext can't
 				// mutate the shared reference across replays (audit P3).
-				return {
-					messages: [{ ...runtime.trimCache.summaryAgentMsg }, ...recent],
-				};
+				const replayView = [{ ...runtime.trimCache.summaryAgentMsg }, ...recent];
+				return tailResult(replayView) ?? { messages: replayView };
 			}
 			// else: context grew enough → fall through to re-compact (cache is stale)
 		}
@@ -261,7 +197,7 @@ export function registerContextHandler(
 		const now = Date.now();
 		if (now < runtime.debounceUntil) {
 			runtime.diagCtxDebounce++;
-			return;
+			return tailResult() ?? undefined;
 		}
 		runtime.debounceUntil = now + 2000;
 
@@ -290,11 +226,10 @@ export function registerContextHandler(
 				runtime.diagLiveTrimFires++;
 				runtime.diagLiveTrimReplays++;
 				runtime.snapshot(ctx);
-				return {
-					messages: [{ ...runtime.trimCache.summaryAgentMsg }, ...recent],
-				};
+				const skipView = [{ ...runtime.trimCache.summaryAgentMsg }, ...recent];
+				return tailResult(skipView) ?? { messages: skipView };
 			}
-			return;
+			return tailResult() ?? undefined;
 		}
 
 		// S27 DB-mirror: write checkpoint_epoch with deterministic nonce.
@@ -460,7 +395,7 @@ export function registerContextHandler(
 					viewLen: view.length,
 					anchorUserMessages,
 				});
-				return; // unsafe / below anchor floor — no trim this call
+				return tailResult() ?? undefined; // unsafe / below anchor floor — no trim this call
 			}
 			const summaryMsg = liveTrimSummaryMessage({
 				compactedFrom: ran.result.compactedFrom,
@@ -515,10 +450,10 @@ export function registerContextHandler(
 				ctxPct: pct,
 				ctxTokens: usage?.tokens ?? null,
 			});
-			return { messages: [summaryAgentMsg, ...recent] };
+			return tailResult([summaryAgentMsg, ...recent]) ?? { messages: [summaryAgentMsg, ...recent] };
 		} catch {
 			runtime.diagCtxThrown++;
-			return; // non-fatal: no trim this call; the next context event retries
+			return tailResult() ?? undefined; // non-fatal: no trim this call; the next context event retries
 		}
 	});
 }

package/extensions/mega-events/context-hwm.ts

@@ -0,0 +1,85 @@
+/**
+ * mega-events/context-hwm.ts — high-water mark for DB-mirror raw_transcript
+ * incremental append (F3 sprint).
+ *
+ * Stores the last-processed seq + content_hash per session so the context
+ * event only appends the tail on subsequent events. On fork/rewind (shorter
+ * message list or hash mismatch at the boundary), the mark is dropped so the
+ * next event falls back to a full reprocess.
+ *
+ * Non-fatal: every function logs and swallows errors; the agent loop is never
+ * broken (repo invariant).
+ *
+ * All queries parameterized (PREVENT-002); no `any` (PREVENT-011).
+ */
+import type { DatabaseSync } from "node:sqlite";
+
+export interface ContextHwm {
+  sessionId: string;
+  lastSeq: number;
+  lastContentHash: string;
+}
+
+const TABLE_DDL = `CREATE TABLE IF NOT EXISTS context_hwm (
+  session_id        TEXT PRIMARY KEY,
+  last_seq          INTEGER NOT NULL,
+  last_content_hash TEXT NOT NULL
+)`;
+
+/** Ensure the context_hwm table exists. Idempotent. */
+export function ensureHwmTable(db: DatabaseSync): void {
+  try {
+    db.exec(TABLE_DDL);
+  } catch {
+    // non-fatal
+  }
+}
+
+/** Read the high-water mark for a session. Returns undefined if none. */
+export function readHwm(
+  db: DatabaseSync,
+  sessionId: string,
+): ContextHwm | undefined {
+  try {
+    const row = db
+      .prepare(
+        "SELECT session_id, last_seq, last_content_hash FROM context_hwm WHERE session_id = ?",
+      )
+      .get(sessionId) as
+      | { session_id: string; last_seq: number; last_content_hash: string }
+      | undefined;
+    if (!row) return undefined;
+    return {
+      sessionId: row.session_id,
+      lastSeq: Number(row.last_seq),
+      lastContentHash: row.last_content_hash,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/** Write (INSERT OR REPLACE) the high-water mark for a session. */
+export function writeHwm(
+  db: DatabaseSync,
+  hwm: ContextHwm,
+): void {
+  try {
+    db.prepare(
+      "INSERT OR REPLACE INTO context_hwm (session_id, last_seq, last_content_hash) VALUES (?, ?, ?)",
+    ).run(hwm.sessionId, hwm.lastSeq, hwm.lastContentHash);
+  } catch {
+    // non-fatal
+  }
+}
+
+/** Drop the high-water mark for a session (invalidation). */
+export function dropHwm(db: DatabaseSync, sessionId: string): void {
+  try {
+    db.prepare("DELETE FROM context_hwm WHERE session_id = ?").run(sessionId);
+  } catch {
+    // non-fatal
+  }
+}
+
+export const TEST_ONLY = { TABLE_DDL };

package/extensions/mega-events/error-classifier.ts

@@ -102,7 +102,7 @@ export function classifyErrorDetailed(message: unknown): ClassifyErrorDetail {
 		const sr = typeof m.stopReason === 'string' ? m.stopReason : '';
 		if (sr === 'length') return { category: null, signal: 'length-guard' };
 		if (sr === 'aborted') return { category: 'cancelled', signal: 'cancelled' };
-		if (sr === 'stop' || sr === 'toolUse' || sr === 'tool_use') return { category: null, signal: 'success' };
+		if (/^(stop|tool_?use|end_?turn|max_?tokens|complete|finished|done)$/i.test(sr)) return { category: null, signal: 'success' };
 		const usage = m.usage;
 		usagePresent = usage != null && typeof usage === 'object';
 		if (usagePresent) {
@@ -133,9 +133,20 @@ export function classifyErrorDetailed(message: unknown): ClassifyErrorDetail {
 			}
 		}
 		if (!sr) {
-			const r: ClassifyErrorDetail = { category: 'transient', signal: 'stream-death-no-stopreason' };
-			if (httpStatus !== undefined) r.httpStatus = httpStatus;
-			return r;
+			// A missing stopReason alone is not sufficient evidence of stream death.
+			// Require at least one corroborating signal: an error field, or 0 total tokens
+			// (indicating the stream died before producing anything). A normal completion
+			// from a runtime that omits stopReason has content and tokens — not an error.
+			const hasError = (m.error != null && m.error !== undefined && m.error !== '') ||
+				(typeof (m as { errorMessage?: unknown }).errorMessage === 'string' && (m as { errorMessage?: string }).errorMessage !== '');
+			if (hasError || (usagePresent && totalTokens === 0)) {
+				const r: ClassifyErrorDetail = { category: 'transient', signal: 'stream-death-no-stopreason' };
+				if (httpStatus !== undefined) r.httpStatus = httpStatus;
+				return r;
+			}
+			// No stopReason, no error field, tokens present — likely a normal completion
+			// from a runtime that omits stopReason (pi-crew, etc.). Not an error.
+			return { category: null, signal: 'success' };
 		}
 		text = parts.join(' ');
 	}

package/extensions/mega-events/mirror-append.ts

@@ -0,0 +1,155 @@
+/**
+ * mirror-append.ts — extracted DB-mirror append logic for context-handler.ts
+ * (F3 sprint: high-water mark incremental append).
+ *
+ * Follows the repo's delegate-shell pattern: the context handler shell delegates
+ * to this impl module for the mirror-append concern. Returns `rowsProcessed`
+ * so callers (including tests) can observe how many new rows were written
+ * without adding test-only hooks.
+ */
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { DatabaseSync } from "node:sqlite";
+import { appendRawTranscript, type RawTranscriptRow } from "../../src/store/sqlite.js";
+import { computeContentDigest } from "../../src/dedup/digest.js";
+import {
+	ensureHwmTable,
+	readHwm,
+	writeHwm,
+	dropHwm,
+} from "./context-hwm.js";
+
+export interface MirrorAppendResult {
+	rowsProcessed: number;
+}
+
+/**
+ * Append incoming messages to raw_transcript with HWM incremental support.
+ *
+ * On fork/rewind (shorter message list or boundary hash mismatch), the HWM
+ * is dropped and all messages are reprocessed.
+ */
+export function appendMirrorMessages(
+	db: DatabaseSync,
+	messages: AgentMessage[],
+	sessionId: string,
+	epochId: string,
+	currentTurn: number | undefined,
+): MirrorAppendResult {
+	ensureHwmTable(db);
+	const hwm = readHwm(db, sessionId);
+
+	let tailStart = 0;
+	let needDrop = false;
+
+	if (hwm) {
+		if (messages.length <= hwm.lastSeq) {
+			// Session was shortened (fork/rewind/clear) — full reprocess.
+			needDrop = true;
+		} else {
+			// Verify boundary integrity: hash of message at hwm.lastSeq-1
+			// must match the stored hash.
+			const boundaryMsg = messages[hwm.lastSeq - 1];
+			const boundaryHash = contentHashOf(
+				(boundaryMsg as { content?: unknown }).content,
+			);
+			if (boundaryHash === hwm.lastContentHash) {
+				tailStart = hwm.lastSeq;
+			} else {
+				needDrop = true;
+			}
+		}
+	}
+
+	if (needDrop) {
+		dropHwm(db, sessionId);
+	}
+
+	// Process tail (or all if tailStart === 0).
+	let rowsProcessed = 0;
+	for (let i = tailStart; i < messages.length; i++) {
+		const raw = toRawRow(messages[i], sessionId, epochId, currentTurn);
+		if (raw) {
+			appendRawTranscript(db, raw);
+			rowsProcessed++;
+		}
+	}
+
+	// Write new HWM.
+	if (messages.length > 0) {
+		const lastMsg = messages[messages.length - 1];
+		writeHwm(db, {
+			sessionId,
+			lastSeq: messages.length,
+			lastContentHash: contentHashOf(
+				(lastMsg as { content?: unknown }).content,
+			),
+		});
+	}
+
+	return { rowsProcessed };
+}
+
+/** Single rule for hashing message content on BOTH sides of the HWM
+ *  (write + boundary check) — a mismatch here silently defeats the
+ *  incremental path (every event would full-reprocess). null/undefined → "". */
+function contentHashOf(content: unknown): string {
+	if (content == null) return "";
+	const bytes =
+		typeof content === "string"
+			? content
+			: JSON.stringify(canonicalize(content));
+	return computeContentDigest(bytes).contentHash;
+}
+
+/**
+ * Canonicalize a value for deterministic JSON serialization (keys sorted).
+ * This is the same logic as the inline function in context-handler.ts.
+ */
+function canonicalize(value: unknown): unknown {
+	if (value === null || value === undefined) return value;
+	if (typeof value !== "object") return value;
+	if (Array.isArray(value)) return value.map(canonicalize);
+	const sorted = Object.keys(value as Record<string, unknown>).sort();
+	const out: Record<string, unknown> = {};
+	for (const k of sorted) {
+		(out as Record<string, unknown>)[k] = canonicalize(
+			(value as Record<string, unknown>)[k],
+		);
+	}
+	return out;
+}
+
+/** Convert an AgentMessage to a RawTranscriptRow (same logic as toRawTranscriptRow in context-handler.ts). */
+function toRawRow(
+	msg: AgentMessage,
+	sessionId: string,
+	epochId: string,
+	currentTurn: number | undefined,
+): RawTranscriptRow | null {
+	const m = msg as {
+		role?: string;
+		content?: unknown;
+		timestamp?: number;
+		toolName?: string;
+	};
+	const content = m.content;
+	if (content == null || content === "") return null;
+	const contentBytes =
+		typeof content === "string"
+			? content
+			: JSON.stringify(canonicalize(content));
+	return {
+		contentHash: computeContentDigest(contentBytes).contentHash,
+		sessionId,
+		seq: 0, // assigned by appendRawTranscript
+		role: m.role ?? "unknown",
+		contentBytes,
+		toolName: m.toolName ?? null,
+		messageTimestamp: m.timestamp ?? null,
+		checkpointEpoch: epochId,
+		turnIndex: currentTurn ?? null,
+	};
+}
+
+// Re-export for convenience when the handler only needs the table ensure.
+export { ensureHwmTable, readHwm, writeHwm, dropHwm };

package/extensions/mega-events/outage-advisor.ts

@@ -39,7 +39,7 @@ export async function maybeSendProviderOutageAdvisory(
 	effectiveCategory: string,
 	runtime: MegaRuntime,
 	pi: ExtensionAPI,
-	config: { providerOutageAdviseThreshold: number },
+	config: { providerOutageAdviseThreshold: number; advisoryChannel?: boolean },
 	detail?: OutageDetail,
 ): Promise<void> {
 	if (effectiveCategory !== "transient") return;
@@ -66,8 +66,14 @@ export async function maybeSendProviderOutageAdvisory(
 		...(detail?.rawText !== undefined ? { rawText: detail.rawText } : {}),
 	});
 
-	await safeSendUserMessage(
-		pi,
-		`[mega-compact] the provider is having issues (${runtime.rt.consecutiveErrors} consecutive failures — timeouts/5xx/rate-limits). Retries are bounded and continue automatically; your context is fine — do NOT clear or reset it. Work resumes as soon as the provider recovers.`,
-	);
+	// Advisory is dashboard-only (events tab + log). No user-visible message —
+	// injecting into the conversation scares users and triggers false-positive
+	// re-classification of the resulting turn (2026-07-31 incident).
+	if (!config.advisoryChannel) {
+		// Legacy path (flag OFF): user-role message injection.
+		await safeSendUserMessage(
+			pi,
+			`[mega-compact] the provider is having issues (${runtime.rt.consecutiveErrors} consecutive failures — timeouts/5xx/rate-limits). Retries are bounded and continue automatically; your context is fine — do NOT clear or reset it. Work resumes as soon as the provider recovers.`,
+		);
+	}
 }

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

@@ -3,8 +3,11 @@
  *
  * Captures cheap, local-only telemetry into the `perf_samples` SQLite table for
  * the dashboard's Perf tab: turn + provider latency, TPS, cache hit %, and (via
- * MegaRuntime.ensurePerfInterval) a 5s cpu/mem interval. All capture is wrapped in
- * try/catch — instrumentation NEVER blocks the agent loop (non-fatal).
+ * MegaRuntime.ensurePerfInterval) a 5s cpu/mem interval. All capture is wrapped
+ * in try/catch — instrumentation NEVER blocks the agent loop (non-fatal).
+ *
+ * S53A: detects significant cache_hit_pct drops (delta > 20 pp) between
+ * consecutive turns and records a `prefix_break` sample with a classified cause.
  *
  * PREVENT-PI-004: Date.now / process.cpuUsage / process.memoryUsage + local
  *   SQLite only, zero network.
@@ -13,6 +16,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { type MegaRuntime } from "../mega-runtime.js";
 import { recordPerfSample } from "../../src/store/sqlite.js";
+import { classifyPrefixBreak, type EventTimestamps } from "../../src/prefix-break.js";
 
 /** Structural view of an AssistantMessage usage block (no pi-ai import). */
 interface UsageBlock {
@@ -30,6 +34,51 @@ function usageOf(
 	return msg.usage;
 }
 
+/**
+ * Attempt to record a prefix_break sample when a significant cache_hit_pct
+ * drop is detected between two consecutive turns.
+ *
+ * Drop threshold: 20 percentage points.  When triggered, calls
+ * classifyPrefixBreak with the three candidate event timestamps from the
+ * runtime and records a `prefix_break` sample.  Best-effort + non-fatal.
+ *
+ * PREVENT-PI-004: guardrails-allow PREVENT-PI-004: local SQLite write only.
+ * PREVENT-002: SQL is fully parameterized via recordPerfSample.
+ */
+function tryRecordPrefixBreak(
+	stateDir: string,
+	prevHitPct: number,
+	currHitPct: number,
+	breakAt: number,
+	runtime: MegaRuntime,
+): void {
+	try {
+		if (prevHitPct - currHitPct < 20) return; // no significant drop
+
+		const events: EventTimestamps = {
+			lastRecallAt: runtime.rt.lastInjectAt, // S53: inject fires alongside recall
+			lastCompactAt: runtime.rt.lastCompactAt,
+			lastInjectAt: runtime.rt.lastInjectAt,
+		};
+		const { cause, confidence } = classifyPrefixBreak(breakAt, events);
+
+		recordPerfSample(
+			stateDir,
+			"prefix_break",
+			0,
+			{
+				cause,
+				confidence,
+				prevHitPct,
+				currHitPct,
+				breakAt,
+			},
+		); // guardrails-allow PREVENT-PI-004: local SQLite write (loopback perf instrumentation)
+	} catch {
+		/* non-fatal: prefix-break detection never blocks the agent loop */
+	}
+}
+
 /** Register perf instrumentation handlers + start the 5s cpu/mem interval. */
 export function registerPerfHandler(
 	pi: ExtensionAPI,
@@ -51,6 +100,7 @@ export function registerPerfHandler(
 
 	// turn_end: compute turn latency + TPS + cache hit % from the assistant
 	// message's usage block. One perf_samples row per metric per turn.
+	// S53A: tracks prevHitPct across turns to detect prefix breaks.
 	pi.on("turn_end", async (event) => {
 		try {
 			if (runtime.perfTurnStart > 0) {
@@ -73,10 +123,34 @@ export function registerPerfHandler(
 						runtime.currentStateDir,
 						"cache_hit_pct",
 						hitPct,
-						{ input: u.input, cacheRead: u.cacheRead, cacheWrite: u.cacheWrite },
+						{
+							input: u.input,
+							cacheRead: u.cacheRead,
+							cacheWrite: u.cacheWrite,
+							modelName: runtime.currentModel?.modelName,
+							modelId: runtime.currentModel?.modelId,
+						},
 					);
+
+					// S53A: detect significant cache hit % drop → record prefix_break.
+					// Only trigger when we have a previous value AND the drop is >20pp.
+					if (
+						runtime.rt._prevCacheHitPct != null &&
+						runtime.rt._prevCacheHitPct - hitPct >= 20
+					) {
+						const breakAt = runtime.perfTurnStart;
+						tryRecordPrefixBreak(
+							runtime.currentStateDir,
+							runtime.rt._prevCacheHitPct,
+							hitPct,
+							breakAt,
+							runtime,
+						);
+					}
+					// Stamp for the next turn's comparison (even when no break fires).
+					runtime.rt._prevCacheHitPct = hitPct;
+				}
 			}
-		}
 		} catch {
 			/* non-fatal: instrumentation must never break the agent loop */
 		}
@@ -110,4 +184,4 @@ export function registerPerfHandler(
 	// Start the 5s cpu/mem sampling interval (one per MegaRuntime; cleared in
 	// runtime.dispose()). Idempotent — safe to call again after a dispose().
 	runtime.ensurePerfInterval();
-}
+}