fix(pi): exclude external m[1] delta from pressure refold (cache parity)

Author: Tehan

packages/pi-plugin/src/inject-compartments-pi.test.ts

@@ -1491,3 +1491,90 @@ describe("mustMaterializePi — SOFT/HARD taxonomy (parity with OpenCode)", () =
 		}
 	});
 });
+
+describe("Pi external m[1] delta pressure-refold exclusion (cache parity)", () => {
+	// RED-GREEN regression for Finding #1: a large external-recall delta in m[1]
+	// must NEVER trigger the pressure-refold backstop. The fix subtracts
+	// externalDeltaTokens + wrapper overhead from the pressure comparison so
+	// late recall "must NEVER cause a fold" (parity with OpenCode injectM0M1).
+	//
+	// Setup: materialize m[0] with a small compartment (m[0] tokens ≈ small).
+	// Then seed a large external recall snapshot whose token count exceeds
+	// 15% of m[0] tokens. On a cache-busting pass the pressure math must
+	// exclude the external delta and NOT call materializeM0PiWithRetry.
+	//
+	// RED (without fix): m1PressureTokens = m1Tokens (no subtraction) →
+	//   large delta crosses the 15% ratio → materializeM0PiWithRetry called →
+	//   m[0] bytes change → test FAILS.
+	// GREEN (with fix): m1PressureTokens = m1Tokens - externalDeltaTokens -
+	//   wrapper → ratio not crossed → no refold → m[0] bytes unchanged → PASSES.
+
+	it("large external m[1] delta does NOT trigger pressure refold (m[0] bytes stable)", () => {
+		const db = createTestDb();
+		const cwd = mkdtempSync(join(tmpdir(), "pi-ext-pressure-"));
+		try {
+			const state = piState("ses-pi-ext-pressure", cwd);
+
+			// Materialize m[0] with a compartment large enough to clear the
+			// M0_DRIFT_RATIO_FLOOR_TOKENS=500 gate (so the ratio test can fire).
+			// ~600 tokens of body content ensures m[0] > 500 tokens.
+			const m0Body = "word ".repeat(600); // ~600 tokens
+			appendCompartments(db, state.sessionId, [
+				{
+					sequence: 0,
+					startMessage: 1,
+					endMessage: 1,
+					startMessageId: "entry-0",
+					endMessageId: "entry-0",
+					title: "Large",
+					content: `U: large turn\n${m0Body}`,
+					p1: `U: large turn\n${m0Body}`,
+				},
+			]);
+			const firstPass = [userMessage("hello", 10)];
+			const r0 = injectM0M1Pi(state, db, firstPass as never, ["entry-0"], true);
+			expect(r0.m0Materialized).toBe(true);
+			const baselineM0 = textOf(firstPass[0] as never);
+			const baselineM0Bytes = baselineM0.length;
+
+			// Seed a large external recall snapshot AFTER m[0] was materialized.
+			// The snapshot hash differs from the m[0] baseline hash (which is "")
+			// so the delta will be rendered into m[1]. Make it large enough to
+			// exceed 15% of m[0] tokens (m[0] is small, so even a moderate delta
+			// crosses the ratio without the fix).
+			// ~200 tokens of content — well above 15% of m[0] (~600 tokens).
+			// Without the fix, this delta alone would cross the ratio and trigger
+			// a refold. With the fix, it is subtracted from m1PressureTokens.
+			const largeContent = "word ".repeat(200); // ~200 tokens
+			db.prepare(
+				"UPDATE session_meta SET external_recall_state = ?, external_recall_json = ?, external_recall_at = ? WHERE session_id = ?",
+			).run(
+				"done",
+				JSON.stringify({
+					project: [{ content: largeContent }],
+					profile: [],
+					global: [],
+				}),
+				Date.now(),
+				state.sessionId,
+			);
+
+			// Cache-busting pass: recomputeM1ThisPass=true. The external delta
+			// will be rendered into m[1]. The pressure backstop must NOT fire.
+			const secondPass = [userMessage("hello", 11)];
+			const r1 = injectM0M1Pi(state, db, secondPass as never, ["entry-0"], true);
+
+			// (a) m[0] NOT re-materialized — external delta must not trigger refold.
+			expect(r1.m0Materialized).toBe(false);
+			// (b) m[0] bytes byte-identical to the baseline (cache-stable).
+			const m0After = textOf(secondPass[0] as never);
+			expect(m0After.length).toBe(baselineM0Bytes);
+			expect(m0After).toBe(baselineM0);
+			// (c) m[1] contains the external delta.
+			expect(textOf(secondPass[1] as never)).toContain(largeContent);
+		} finally {
+			rmSync(cwd, { recursive: true, force: true });
+			closeQuietly(db);
+		}
+	});
+});

packages/pi-plugin/src/inject-compartments-pi.ts

@@ -78,6 +78,7 @@ import {
 	type PreparedCompartmentInjection,
 	prepareCompartmentInjection,
 	renderExternalMemoryBlock,
+	renderExternalMemoryDelta,
 	renderMemoryBlockV2,
 	trimMemoriesToBudgetV2,
 	trimUserMemoriesToBudget,
@@ -1645,6 +1646,14 @@ function renderMemoryUpdatesBlockPi(args: {
 interface RenderM1PiResult {
 	text: string;
 	memoryUpdateCount: number;
+	/** The <external-memory> delta block (late-arrival snapshot) when present,
+	 *  "" otherwise. Excluded from the injectM0M1Pi pressure-refold token math
+	 *  so a large recall can NEVER cause an m[0] refold (parity with OpenCode). */
+	externalDeltaText: string;
+	/** True when freshly rendered from current DB state. False when replayed
+	 *  from a sibling-adoption row. The pressure-refold backstop must only fire
+	 *  on recomputed bytes (parity with OpenCode RenderM1Result.recomputed). */
+	recomputed: boolean;
 }
 
 function renderM1PiWithMetadata(
@@ -1767,28 +1776,42 @@ function renderM1PiWithMetadata(
 
 	// External memory delta: when the live recall hash differs from the m[0]
 	// baseline hash, surface the current recall snapshot as a delta. Mirrors
-	// OpenCode renderM1's renderExternalMemoryDelta path. The delta carries ALL
-	// slices (profile lines reconcile into <user-profile> at the next HARD fold).
-	const liveExternalRecallHash = readExternalRecallHash(db, state.sessionId);
-	if (liveExternalRecallHash !== markers.externalRecallHash) {
-		const recallRead = readExternalRecallSnapshot(db, state.sessionId);
-		if (recallRead.state === "done" && recallRead.snapshot) {
-			const externalBlock = renderExternalMemoryBlock(recallRead.snapshot);
-			if (externalBlock) sections.push(externalBlock);
+	// OpenCode renderM1WithMetadata's renderExternalMemoryDelta path. The delta
+	// carries ALL slices including profile (profile lines reconcile into
+	// <user-profile> at the next HARD fold). Captured separately so the caller
+	// can subtract its tokens from the pressure-refold math — recall is NOT a
+	// bust trigger (parity with OpenCode RenderM1Result.externalDeltaText).
+	let externalDeltaText = "";
+	const recallRead = readExternalRecallSnapshot(db, state.sessionId);
+	if (recallRead.state === "done" && recallRead.snapshot) {
+		const currentRecallHash = computeRecallSnapshotHash(recallRead.snapshot);
+		if (
+			currentRecallHash !== "" &&
+			currentRecallHash !== markers.externalRecallHash
+		) {
+			const delta = renderExternalMemoryDelta(recallRead.snapshot);
+			if (delta) {
+				externalDeltaText = delta;
+				sections.push(delta);
+			}
 		}
 	}
 
 	if (sections.length === 0) {
 		return {
 			text: PI_M1_PLACEHOLDER,
 			memoryUpdateCount: memoryUpdates.count,
+			externalDeltaText: "",
+			recomputed: true,
 		};
 	}
 	// Join with "\n" (single newline) to match OpenCode renderM1 exactly — the
 	// m[1] delta bytes must be identical across harnesses.
 	return {
 		text: `<session-history-since>\n${sections.join("\n")}\n</session-history-since>`,
 		memoryUpdateCount: memoryUpdates.count,
+		externalDeltaText,
+		recomputed: true,
 	};
 }
 
@@ -2015,6 +2038,7 @@ function softRefreshCachedM1Pi(args: {
 	markers: PiM0SnapshotMarkers;
 	memoryUpdateCount: number;
 	recomputed: boolean;
+	externalDeltaText: string;
 } {
 	const preRenderedKeyFilesBlock = preRenderKeyFilesBlockPi(
 		args.state,
@@ -2043,15 +2067,20 @@ function softRefreshCachedM1Pi(args: {
 				args.db,
 				args.state.sessionId,
 			);
-			return {
-				...applyCachedPiRow({
-					row: sibling,
-					state: args.state,
-					compartmentsForNormalization: siblingCompartments,
-				}),
-				memoryUpdateCount: 0,
-				recomputed: false,
-			};
+		return {
+			...applyCachedPiRow({
+				row: sibling,
+				state: args.state,
+				compartmentsForNormalization: siblingCompartments,
+			}),
+			memoryUpdateCount: 0,
+			recomputed: false,
+			// Sibling-adoption replay: the bytes are persisted, not freshly
+			// rendered. The external delta is unknown from the persisted row;
+			// use "" so the pressure backstop (which only fires on recomputed
+			// bytes) is never triggered by a replayed sibling m[1].
+			externalDeltaText: "",
+		};
 		}
 
 		const markers = markersFromCachedPiRow(
@@ -2103,6 +2132,7 @@ function softRefreshCachedM1Pi(args: {
 			markers: { ...markers, lastBaselineEndMessageId: advancedBoundary },
 			memoryUpdateCount: rendered.memoryUpdateCount,
 			recomputed: true,
+			externalDeltaText: rendered.externalDeltaText,
 		};
 	} catch (error) {
 		try {
@@ -2164,6 +2194,10 @@ export function injectM0M1Pi(
 	let memoryUpdateCount = 0;
 	let m1Recomputed = false;
 	let freshFallbackRenderedMemoryIds: number[] | null = null;
+	// Tracks the external-recall delta text from the freshly rendered m[1] so
+	// the pressure backstop can subtract its tokens — recall must NEVER cause a
+	// fold (parity with OpenCode injectM0M1 externalDeltaText subtraction).
+	let m1ExternalDeltaText = "";
 
 	if (decision.value) {
 		// On contention exhaustion, reuse the cached m[0]/m[1] pair rather than
@@ -2259,6 +2293,7 @@ export function injectM0M1Pi(
 		m1 = freshM1.text;
 		memoryUpdateCount = freshM1.memoryUpdateCount;
 		m1Recomputed = true;
+		m1ExternalDeltaText = freshM1.externalDeltaText;
 	} else if (contentionExhausted) {
 		// m[1] was replayed with the cached m[0] pair above.
 	} else if (recomputeM1ThisPass) {
@@ -2274,6 +2309,7 @@ export function injectM0M1Pi(
 		markers = refreshed.markers;
 		memoryUpdateCount = refreshed.memoryUpdateCount;
 		m1Recomputed = refreshed.recomputed;
+		m1ExternalDeltaText = refreshed.externalDeltaText;
 	} else {
 		const replayed = replayCachedM1Pi(db, state, currentCompartments);
 		m0 = replayed.m0;
@@ -2294,6 +2330,15 @@ export function injectM0M1Pi(
 	// Token counts (NOT char lengths) on both sides of the ratio — parity with
 	// OpenCode. The documented intent is "m[1] exceeds ~15% of m[0] tokens";
 	// char length diverges from token count on XML-heavy / non-Latin content.
+	//
+	// External recall content must NEVER CAUSE a fold (spec: not a bust trigger);
+	// it rides along when a fold fires for other reasons. Two layers of
+	// subtraction from m1Tokens: the delta itself (late recall) AND a small
+	// wrapper overhead (every m[1] carries the wrapper, empty or not — not a
+	// drift signal). The wrapper tokens are also subtracted from the absolute
+	// cap budget for symmetry, so a tiny m[0] baseline (where the wrapper
+	// alone would exceed the cap) does not falsely fire a refold when the
+	// only m[1] content is the recall delta. (Parity with OpenCode injectM0M1.)
 	const M0_DRIFT_RATIO_FLOOR_TOKENS = 500;
 	const M1_DRIFT_RATIO = 0.15;
 	const M1_ABSOLUTE_CAP_RATIO = 0.2;
@@ -2302,8 +2347,21 @@ export function injectM0M1Pi(
 		M1_ABSOLUTE_CAP_RATIO;
 	const m1HasContent = m1 !== PI_M1_PLACEHOLDER;
 	const m1Tokens = m1HasContent ? estimateTokens(m1) : 0;
+	const M1_PRESSURE_WRAPPER_TOKENS = 20;
+	const externalDeltaTokens = m1ExternalDeltaText
+		? estimateTokens(m1ExternalDeltaText)
+		: 0;
+	const m1PressureTokens = Math.max(
+		0,
+		m1Tokens - externalDeltaTokens - M1_PRESSURE_WRAPPER_TOKENS,
+	);
+	const m1AbsoluteContentBudget = Math.max(
+		0,
+		m1AbsoluteBudget - M1_PRESSURE_WRAPPER_TOKENS,
+	);
 	const m0Tokens = estimateTokens(m0);
-	const m1OverAbsoluteCap = m1HasContent && m1Tokens > m1AbsoluteBudget;
+	const m1OverAbsoluteCap =
+		m1HasContent && m1PressureTokens > m1AbsoluteContentBudget;
 	if (
 		!materialized &&
 		!contentionExhausted &&
@@ -2313,7 +2371,7 @@ export function injectM0M1Pi(
 			m1OverAbsoluteCap ||
 			(m1HasContent &&
 				m0Tokens >= M0_DRIFT_RATIO_FLOOR_TOKENS &&
-				m1Tokens > m0Tokens * M1_DRIFT_RATIO))
+				m1PressureTokens > m0Tokens * M1_DRIFT_RATIO))
 	) {
 		decision = { value: true, reason: "drift" };
 		try {

packages/plugin/src/hooks/magic-context/inject-compartments.ts

@@ -1460,7 +1460,7 @@ export function renderExternalMemoryBlock(snapshot: ExternalRecallSnapshot): str
 
 /** m[1] delta when recall settles after the last m[0] fold — carries ALL
  *  slices (profile lines reconcile into <user-profile> at the next HARD fold). */
-function renderExternalMemoryDelta(snapshot: ExternalRecallSnapshot): string {
+export function renderExternalMemoryDelta(snapshot: ExternalRecallSnapshot): string {
     const body = renderExternalDeltaLines(snapshot);
     if (body.length === 0) return "";
     return [