pi-mega-compact 0.11.4 → 0.11.6

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.
@@ -12,7 +15,11 @@
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { type MegaRuntime } from "../mega-runtime.js";
-import { recordPerfSample } from "../../src/store/sqlite.js";
+import {
+	recordPerfSample,
+	readPerfSamples,
+} 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 +37,158 @@ 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.
+ *
+ * Also evaluates rolling cache health and emits a degradation event when the
+ * composite score falls below 0.6 (A3, PLAN_V2 Phase 4).
+ *
+ * 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)
+
+		// A3: compute rolling cache health score and emit alert on degradation.
+		tryComputeCacheHealth(stateDir, currHitPct, runtime);
+	} catch {
+		/* non-fatal: prefix-break detection never blocks the agent loop */
+	}
+}
+
+/**
+ * Compute a rolling cache health score and emit a dashboard event when it
+ * falls below the degradation threshold (0.6 / "yellow").
+ *
+ * The score is a weighted composite of:
+ *   - hitRateScore (0-1): recent cache_hit_pct sample average / 100
+ *   - stabilityScore (0-1): 1 - recent prefix_break count / maxExpectedBreaks
+ *   - churnScore (0-1): 1 - stripe re-assignment rate (derived from prefix_break classifications)
+ *
+ * Weights: hit rate 50%, prefix stability 30%, churn 20%.
+ *
+ * PREVENT-PI-004: guardrails-allow PREVENT-PI-004: local SQLite read, no network.
+ * PREVENT-001: readPerfSamples returns empty array when no data; handled.
+ * PREVENT-011: no `any` — all arrays are typed PerfSampleRow[].
+ */
+function tryComputeCacheHealth(
+	stateDir: string,
+	currHitPct: number,
+	runtime: MegaRuntime,
+): void {
+	try {
+		const now = Date.now();
+		const windowMs = 300_000; // 5-minute lookback
+		const sinceTs = now - windowMs;
+
+		// Read recent cache_hit_pct and prefix_break samples.
+		const hitSamples = readPerfSamples(stateDir, sinceTs, "cache_hit_pct");
+		const breakSamples = readPerfSamples(stateDir, sinceTs, "prefix_break");
+
+		// hitRateScore: average of recent cache hit percentages / 100.
+		let hitRateAvg = currHitPct;
+		if (hitSamples.length > 0) {
+			const sum = hitSamples.reduce((a, r) => a + r.value, 0);
+			hitRateAvg = sum / hitSamples.length;
+		}
+		const hitRateScore = Math.max(0, Math.min(1, hitRateAvg / 100));
+
+		// stabilityScore: penalize for frequent prefix breaks.
+		// Assume at most 2 breaks in 5min is tolerable.
+		const maxExpectedBreaks = 2;
+		const stabilityScore = Math.max(
+			0,
+			1 - breakSamples.length / maxExpectedBreaks,
+		);
+
+		// churnScore: if recent breaks have varied causes, penalize.
+		const causeVariety = new Set(
+			breakSamples.map((r) => {
+				const m = typeof r.meta === "string" ? (JSON.parse(r.meta) as Record<string, unknown>) : null;
+				return typeof m?.cause === "string" ? m.cause : "other";
+			}),
+		);
+		const churnPenalty = Math.min(1, causeVariety.size / 4); // 4 possible causes
+		const churnScore = 1 - churnPenalty;
+
+		// Composite: hitRate dominates.
+		const composite =
+			hitRateScore * 0.5 + stabilityScore * 0.3 + churnScore * 0.2;
+
+		// Emit degradation event when score < 0.6.
+		if (composite < 0.6) {
+			const prevScore = runtime.rt._lastCacheHealthScore ?? 1;
+			runtime.rt._lastCacheHealthScore = composite;
+
+			recordPerfSample(
+				stateDir,
+				"cache_health",
+				composite,
+				{
+					hitRateScore: Math.round(hitRateScore * 1000) / 1000,
+					stabilityScore: Math.round(stabilityScore * 1000) / 1000,
+					churnScore: Math.round(churnScore * 1000) / 1000,
+					breakCount: breakSamples.length,
+					hitSampleCount: hitSamples.length,
+					currHitPct,
+					trend: composite < prevScore ? "falling" : "stable",
+				},
+			); // guardrails-allow PREVENT-PI-004: local SQLite write (loopback dashboard event)
+
+			// Structured log line for the host to pick up.
+			const level = composite < 0.4 ? "error" : "warn";
+			// eslint-disable-next-line no-console
+			console.log(
+				JSON.stringify({
+					ts: now,
+					event: `cache_health_${level}`,
+					composite: Math.round(composite * 1000) / 1000,
+					hitRateAvg: Math.round(hitRateAvg * 10) / 10,
+					breakCount: breakSamples.length,
+					trend: composite < prevScore ? "falling" : "stable",
+				}),
+			);
+		} else {
+			// Still healthy — just update the stored score.
+			runtime.rt._lastCacheHealthScore = composite;
+		}
+	} catch {
+		/* non-fatal: cache health computation never blocks */
+	}
+}
+
 /** Register perf instrumentation handlers + start the 5s cpu/mem interval. */
 export function registerPerfHandler(
 	pi: ExtensionAPI,
@@ -51,6 +210,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 +233,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 +294,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();
-}
+}

package/extensions/mega-events/recall-tail.ts

@@ -0,0 +1,88 @@
+/**
+ * recall-tail.ts — S53 Recall Tail Injection: append staged recall/memory blocks
+ * as a single user-role message at the very tail of the context view, instead
+ * of prepending them as part of systemPrompt (the pre-S53 behavior).
+ *
+ * Key invariants (enforced / tested):
+ *  - PREVENT-PI-001/002: append-only at the very tail; never splits a
+ *    toolCall/toolResult pair.
+ *  - PREVENT-PI-003: user-role message, never system role.
+ *  - Turn-scoped pin: staged blocks inject on EVERY context event of the turn
+ *    (tool loops); consumed at turn_end ONLY if actually injected.
+ *  - Non-fatal: any failure returns the unmodified messages array.
+ *  - Flag OFF: no-op (returns messages unchanged — byte-identical pre-sprint;
+ *    session-handlers.ts keeps the legacy systemPrompt prepend path).
+ */
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { MegaRuntime } from "../mega-runtime.js";
+import type { MegaConfig } from "../mega-config.js";
+
+/**
+ * True when recall blocks are staged AND the feature flag is ON. Called by the
+ * context handler to decide whether to call withRecallTail.
+ */
+export function stagedForTail(
+	runtime: MegaRuntime,
+	config: MegaConfig,
+): boolean {
+	if (!config.recallTailInject) return false;
+	return (
+		runtime.pendingRecallBlock != null ||
+		runtime.pendingMemoryRecallBlock != null
+	);
+}
+
+/**
+ * Append staged recall/memory blocks as a single user-role message at the very
+ * tail of the messages array. Returns a NEW array (does not mutate input).
+ *
+ * Sets `runtime.recallInjectedThisTurn = true` when it actually appends, so the
+ * turn_end handler (agent-handlers.ts) consumes the staged blocks only if they
+ * reached a view this turn. If a turn ends with no context event, the flag
+ * stays false and the blocks remain staged for the next turn.
+ *
+ * Stable timestamp (runtime.perfTurnStart ?? Date.now()) so replays within the
+ * turn are byte-identical (mirrors the v0.8.6 summaryAgentMsg rationale).
+ *
+ * Non-fatal: on any failure, returns messages unmodified and does NOT set the
+ * injected flag. PREVENT-PI-003: the injected message has role "user", never
+ * "system".
+ */
+export function withRecallTail(
+	messages: readonly AgentMessage[],
+	runtime: MegaRuntime,
+	config: MegaConfig,
+): AgentMessage[] {
+	if (!config.recallTailInject) return messages as AgentMessage[];
+	try {
+		const blocks: string[] = [];
+		if (runtime.pendingRecallBlock != null) {
+			blocks.push(runtime.pendingRecallBlock);
+		}
+		if (runtime.pendingMemoryRecallBlock != null) {
+			blocks.push(runtime.pendingMemoryRecallBlock);
+		}
+		if (blocks.length === 0) return messages as AgentMessage[];
+
+		const tailText = blocks.join("\n\n");
+		const timestamp =
+			runtime.perfTurnStart ?? // stable within a turn
+			Date.now();
+
+		const tailMsg = {
+			role: "user" as const,
+			content: tailText,
+			timestamp,
+		} as unknown as AgentMessage;
+
+		runtime.rt.recallInjectedThisTurn = true;
+		// Append at the very tail — never splits toolCall/toolResult.
+		// PREVENT-PI-001/002: a single message appended after a complete
+		// transcript prefix cannot split a toolCall/toolResult pair.
+		return [...messages, tailMsg];
+	} catch {
+		// Non-fatal: leave blocks staged (flag stays unset) and return the
+		// unmodified view. The context event still proceeds normally.
+		return messages as AgentMessage[];
+	}
+}