pi-mega-compact 0.8.5 → 0.8.7

package/dist/extensions/mega-cache-replay.test.js

@@ -0,0 +1,189 @@
+/**
+ * mega-cache-replay.test.ts — locks the v0.8.7 cache-stability fix.
+ *
+ * Two tests (reuses the mega-teamrun.test.ts harness shape: mock pi + the REAL
+ * compiled extension at extensions/mega-compact.js):
+ *  a. REPLAY: drive >=2 gated context events past the debounce within ONE epoch
+ *     (same lastCheckpointId) and assert diagLiveTrimReplays > 0 AND the returned
+ *     messages array is byte-identical (deepEqual) across replays (stable prefix).
+ *  b. DEDUP-ON-DIFFERENT-CHECKPOINT: after a fresh trim, simulate a re-compact
+ *     (context grew on the token basis) that DEDUPS onto a DIFFERENT existing
+ *     checkpoint id (L0 contentHash match against an OLDER checkpoint, so
+ *     result.checkpointId != rt.lastCheckpointId), then assert the NEXT gated
+ *     event STILL replays (diagLiveTrimReplays increments) — i.e. the cache key
+ *     trimCache.checkpointId === rt.lastCheckpointId holds. This is the P2 gap the
+ *     v0.8.6 audit found: keying on the dedup-volatile result.checkpointId
+ *     disabled replay for the rest of the epoch after such a dedup fire.
+ *
+ * MEGACOMPACT_PGLITE_DISABLED keeps the run fast (no WASM index init).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createRequire } from "node:module";
+import { closeVectorIndex } from "../src/store/vectorIndex.js";
+const require = createRequire(import.meta.url);
+const baseTmp = mkdtempSync(join(tmpdir(), "mc-cache-"));
+process.env.MEGACOMPACT_INDEX_DIR = join(baseTmp, "index");
+process.env.MEGACOMPACT_PGLITE_DISABLED = "true"; // fast: skip WASM index
+let counter = 0;
+function harness() {
+    const stateDir = join(baseTmp, `run-${counter++}`);
+    process.env.MEGACOMPACT_STATE_DIR = stateDir;
+    process.env.MEGACOMPACT_DEBUG = "true";
+    process.env.MEGACOMPACT_THRESHOLD_TOKENS = "50";
+    process.env.MEGACOMPACT_FAST_GATE_PCT = "1";
+    process.env.MEGACOMPACT_ANCHOR_USER_MESSAGES = "1";
+    process.env.MEGACOMPACT_DURABLE_TRIM_FLOOR = "0";
+    process.env.MEGACOMPACT_MEMORY_AUTO_REVIEW = "false";
+    process.env.MEGACOMPACT_RAPTOR_ENABLED = "false";
+    // Disable the FUZZY dedup tiers (L1 MinHash/LSH + L2 cosine) so the DEDUP test
+    // is controlled by L0 contentHash only: setB (different vocabulary) then
+    // creates a genuinely NEW checkpoint instead of fuzzy-matching setA's, and
+    // setA-re-again still L0-contentHash-dedups onto the first setA checkpoint.
+    // The TrigramEmbedder otherwise matches on shared structural trigrams
+    // ("— step N" / "Edit"), collapsing setB onto setA. Harmless for the REPLAY
+    // test (pure replay, no dedup reliance).
+    process.env.MEGACOMPACT_L1_ENABLED = "false";
+    process.env.MEGACOMPACT_L2_ENABLED = "false";
+    delete process.env.MEGACOMPACT_LEGACY_DURABLE_TRIM;
+    // Mutable context-usage so tests can drive re-compact on the TOKEN basis by
+    // raising `tokens` while keeping `percent` null (→ token gate + token
+    // grewEnough path in context-handler.ts). The REPLAY test keeps percent=100 so
+    // the percent-basis grewEnough (>=10) never trips (no re-compact → pure replay).
+    const usage = { tokens: 200000, contextWindow: 200000, percent: 100 };
+    const handlers = {};
+    const compactCalls = [];
+    function msg(role, text, toolName) {
+        if (role === "assistant" && toolName) {
+            return { role: "assistant", content: [{ type: "toolCall", name: toolName, id: "c1", arguments: {} }], api: "anthropic-messages", provider: "anthropic", model: "m", usage: { inputTokens: 1, outputTokens: 1, cacheReadTokens: 0, cacheWriteTokens: 0 }, stopReason: "tool_use", timestamp: 0 };
+        }
+        if (role === "toolResult" && toolName) {
+            return { role: "toolResult", content: [{ type: "text", text }], toolCallId: "c1", toolName, isError: false, timestamp: 0 };
+        }
+        return { role: "user", content: text, timestamp: 0 };
+    }
+    // Build a session of `n` tool-call triples tagged `tag`. Set A and B differ in
+    // content (so B never dedups against A) but A === A reproduces the same
+    // regionText → same L0 contentHash → dedup onto the first A checkpoint.
+    function buildSession(tag, n) {
+        const s = [];
+        for (let i = 0; i < n; i++) {
+            s.push(msg("user", `[${tag}] we decided to use approach ${i} for module ${i}`));
+            s.push(msg("assistant", `[${tag}] edited module ${i}`, "Edit"));
+            s.push(msg("toolResult", `[${tag}] edited module ${i}`, "Edit"));
+        }
+        return s;
+    }
+    const toEntry = (m, i) => ({ type: "message", id: `e${i}`, parentId: null, timestamp: String(i), message: m });
+    const sessionManager = {
+        getSessionId: () => "sess_cache_001",
+        getEntries: () => buildSession("A", 14).map(toEntry),
+        getBranch: () => buildSession("A", 14).map(toEntry),
+    };
+    function makeCtx(over = {}) {
+        return {
+            ui: { setStatus: () => { }, notify: () => { }, select: () => { }, confirm: async () => true, input: async () => "", setWidget: () => { } },
+            mode: "tui", hasUI: true, cwd: stateDir, sessionManager,
+            modelRegistry: {}, model: undefined, isIdle: () => true, isProjectTrusted: () => true,
+            signal: undefined, abort: () => { }, hasPendingMessages: () => false, shutdown: () => { },
+            getContextUsage: () => ({ ...usage }),
+            compact: (opts) => { compactCalls.push(opts); return undefined; },
+            getSystemPrompt: () => "system base",
+            ...over,
+        };
+    }
+    const pi = {
+        on: (ev, h) => { handlers[ev] = h; },
+        registerCommand: () => { }, registerTool: () => { }, registerShortcut: () => { },
+        registerFlag: () => { }, getFlag: () => undefined, registerMessageRenderer: () => { },
+        registerEntryRenderer: () => { }, sendMessage: () => { }, sendUserMessage: () => { },
+        appendEntry: () => { }, setSessionName: () => { }, getSessionName: () => undefined,
+        setLabel: () => { }, exec: async () => ({ stdout: "", stderr: "", code: 0 }),
+        getActiveTools: () => [], getAllTools: () => [], setActiveTools: () => { },
+        getCommands: () => [], setModel: async () => false, getThinkingLevel: () => "off",
+        setThinkingLevel: () => { },
+    };
+    const mod = require("./mega-compact.js");
+    mod.default(pi);
+    const { lastRuntime } = require("./mega-events.js");
+    const fire = (ev, event, ctx) => handlers[ev](event, ctx);
+    return {
+        stateDir, handlers, compactCalls, fire, ctx: makeCtx, usage, buildSession,
+        runtime: lastRuntime, // MegaRuntime with diag* counters + rt + trimCache
+        // Bypass the 2s debounce so each fire proceeds without real waiting.
+        clearDebounce: () => { if (lastRuntime)
+            lastRuntime.debounceUntil = 0; },
+    };
+}
+test("REPLAY: >=2 gated context events within one epoch replay verbatim (byte-identical)", async () => {
+    const h = harness();
+    const ctx = h.ctx();
+    const session = h.buildSession("A", 14);
+    // Fire 3 gated context events; clearDebounce between so each passes the gate.
+    // percent stays 100 → percent-basis grewEnough (>=10) never trips → pure replay.
+    h.clearDebounce();
+    const r1 = await h.fire("context", { type: "context", messages: session }, ctx);
+    h.clearDebounce();
+    const r2 = await h.fire("context", { type: "context", messages: session }, ctx);
+    h.clearDebounce();
+    const r3 = await h.fire("context", { type: "context", messages: session }, ctx);
+    const rt = h.runtime;
+    assert.ok(rt.diagLiveTrimFires >= 1, "fresh trim fired on first event");
+    assert.ok(rt.diagLiveTrimReplays >= 2, `replay fired >=2 (got ${rt.diagLiveTrimReplays})`);
+    // byte-identical (stable KV-cache prefix) across replays
+    assert.deepEqual(r2?.messages, r3?.messages, "replay messages byte-identical across replays");
+    // replay matches the fresh-trim view (shallow-copy preserves content)
+    assert.deepEqual(r1?.messages, r2?.messages, "replay matches fresh-trim view (stable prefix)");
+});
+test("DEDUP: re-compact that dedups onto a DIFFERENT checkpoint still replays next (P2 fix)", async () => {
+    const h = harness();
+    // Token-basis growth path: percent null → token gate + token grewEnough
+    // (currentTokens - trimCache.ctxTokens >= effectiveThreshold * 0.5 = 25).
+    h.usage.percent = null;
+    h.usage.tokens = 200000;
+    const ctx = h.ctx();
+    const setA = h.buildSession("A", 14);
+    const setB = h.buildSession("B", 14); // different content, same length
+    const rt = h.runtime;
+    // 1) Fresh trim on setA → genuinely new checkpoint cp_A. lastCheckpointId = cp_A.
+    h.clearDebounce();
+    await h.fire("context", { type: "context", messages: setA }, ctx);
+    const cpA = rt.rt.lastCheckpointId;
+    assert.ok(cpA, "cp_A created on fresh trim");
+    assert.equal(rt.diagLiveTrimFires, 1, "first fire was a fresh trim");
+    // 2) Re-compact on setB (grew tokens) → genuinely new checkpoint cp_B (not deduped).
+    h.usage.tokens = 200100; // grew 100 >= 25
+    h.clearDebounce();
+    await h.fire("context", { type: "context", messages: setB }, ctx);
+    const cpB = rt.rt.lastCheckpointId;
+    assert.notEqual(cpB, cpA, "cp_B is a different, genuinely new checkpoint");
+    assert.equal(rt.rt.dedupSkips, 0, "setB did not dedup (different vocabulary, fuzzy tiers off)");
+    // 3) Re-compact on setA AGAIN (grew tokens) → L0 contentHash dedup onto cp_A.
+    //    result.checkpointId = cp_A (!= lastCheckpointId cp_B); lastCheckpointId is
+    //    NOT updated on a dedup (compact.ts:100-104), so it stays cp_B. With the
+    //    fix, trimCache.checkpointId is keyed on lastCheckpointId (cp_B), NOT the
+    //    dedup-volatile result.checkpointId (cp_A).
+    h.usage.tokens = 200200; // grew 100 >= 25
+    h.clearDebounce();
+    await h.fire("context", { type: "context", messages: setA }, ctx);
+    assert.equal(rt.rt.lastCheckpointId, cpB, "dedup did NOT bump lastCheckpointId (still cp_B)");
+    assert.ok(rt.rt.dedupSkips >= 1, "setA re-compact deduped onto an existing checkpoint");
+    // The P2 invariant: the cache key must equal the stable epoch signal.
+    assert.equal(rt.trimCache?.checkpointId, rt.rt.lastCheckpointId, "trimCache.checkpointId keyed on lastCheckpointId (P2 fix), not dedup-volatile result.checkpointId");
+    // 4) Next gated event (no growth) MUST replay instead of re-running runCompact.
+    //    Without the fix, trimCache.checkpointId (cp_A) != lastCheckpointId (cp_B)
+    //    → the replay condition is false → runCompact re-runs every fire → the
+    //    thrash silently persists in that path (the audit's finding).
+    const replaysBefore = rt.diagLiveTrimReplays;
+    h.usage.tokens = 200200; // no growth → replay
+    h.clearDebounce();
+    await h.fire("context", { type: "context", messages: setA }, ctx);
+    assert.ok(rt.diagLiveTrimReplays > replaysBefore, `replay fired after dedup-onto-different-checkpoint (got ${rt.diagLiveTrimReplays}, was ${replaysBefore})`);
+});
+test("cleanup", async () => {
+    await closeVectorIndex();
+    rmSync(baseTmp, { recursive: true, force: true });
+});

package/dist/extensions/mega-events/compact-handlers.js

@@ -128,6 +128,7 @@ export function registerCompactHandlers(pi, runtime, config) {
     pi.on("session_compact", async (_event, _ctx) => {
         runtime.rt.lastNativeCompactAt = Date.now();
         runtime.rt.lastCompactAt = Date.now();
+        runtime.trimCache = null; // v0.8.6: durable truncation changes the transcript — never replay the stale cached cut (PREVENT-PI-001/002)
         runtime.logger.info("session-compacted", {
             sessionId: runtime.rt.sessionId,
             at: runtime.rt.lastCompactAt,

package/dist/extensions/mega-events/context-handler.js

@@ -122,6 +122,36 @@ export function registerContextHandler(pi, runtime, config) {
             return;
         }
         runtime.debounceUntil = now + 2000;
+        // v0.8.6 cache-stability: replay the cached trim view when still in the
+        // same compaction epoch AND context hasn't grown enough to warrant a
+        // re-compact. This stabilizes the provider KV-cache prefix (the summary +
+        // cut are reused verbatim) instead of regenerating a fresh summary +
+        // sentinel every fire, which invalidated the prefix on every other turn
+        // (the alternating cache-miss regression). Re-compact only when context
+        // grew >=10% of the window (percent basis) or >=50% of the effective
+        // threshold (token basis, when percent is unavailable). The cached `cut`
+        // is only valid while the transcript grows within the epoch — it is
+        // cleared on session_compact (durable truncation) + resetRuntime, so we
+        // never replay a stale cut into a truncated transcript (PREVENT-PI-001/002).
+        const RECOMPACT_PCT_DELTA = 10;
+        if (runtime.trimCache &&
+            runtime.trimCache.checkpointId === runtime.rt.lastCheckpointId &&
+            runtime.trimCache.cut <= messages.length) {
+            const grewEnough = pct != null && runtime.trimCache.ctxPct != null
+                ? pct - runtime.trimCache.ctxPct >= RECOMPACT_PCT_DELTA
+                : currentTokens - (runtime.trimCache.ctxTokens ?? 0) >=
+                    runtime.effectiveThreshold * 0.5;
+            if (!grewEnough) {
+                const recent = messages.slice(runtime.trimCache.cut); // guardrails-allow PREVENT-PI-002: cached `cut` was sanitized once by computeLiveTrimCut (src/boundary.ts) and replayed verbatim; the transcript only grows within an epoch (cache is cleared on durable truncation), so the preserved run still starts on a toolPair-safe index.
+                runtime.diagLiveTrimFires++; // trim view returned this call (replay counts as a fire)
+                runtime.diagLiveTrimReplays++;
+                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] };
+            }
+            // else: context grew enough → fall through to re-compact (cache is stale)
+        }
         // Adaptive compression (Fix E): scale compression strength + keepFrom depth
         // with how close we are to the model context limit. Null-safe: when the
         // token-fallback path ran (pct unavailable) use the token-basis pressure
@@ -224,9 +254,35 @@ export function registerContextHandler(pi, runtime, config) {
             const summaryAgentMsg = {
                 role: "user",
                 content: summaryMsg.text,
-                timestamp: Date.now(),
+                // v0.8.6: stable timestamp across the epoch (NOT Date.now()) so the
+                // summary message bytes — and thus the KV-cache prefix — don't drift
+                // on every replay within the same compaction epoch.
+                timestamp: runtime.rt.lastCompactAt ?? Date.now(),
             };
             const recent = messages.slice(cut); // guardrails-allow PREVENT-PI-002: `cut` is the pre-sanitized `compactedFrom` produced by src/boundary.ts computeDropRange, so the preserved run begins on a toolPair-safe index.
+            // v0.8.6: cache the trim view so subsequent gated calls in this epoch
+            // replay it verbatim (stabilizing the KV-cache prefix) instead of
+            // regenerating a fresh summary + sentinel every fire.
+            runtime.trimCache = {
+                // v0.8.7: key the replay cache on the STABLE epoch signal
+                // (rt.lastCheckpointId) instead of ran.result.checkpointId, which is
+                // dedup-volatile: on a re-compact that dedups onto a DIFFERENT existing
+                // checkpoint, result.checkpointId is the matched id (engine.ts:188) while
+                // lastCheckpointId is only updated on a genuinely new checkpoint
+                // (compact.ts:100-104). Keying on result.checkpointId would make
+                // trimCache.checkpointId != rt.lastCheckpointId forever after that
+                // dedup fire, disabling replay for the rest of the epoch (the
+                // alternating cache-miss that 0.8.6 meant to fix). Prefer the stable
+                // signal; fall back to result.checkpointId then the epoch timestamp
+                // only for the no-checkpoint edge case.
+                checkpointId: runtime.rt.lastCheckpointId ??
+                    ran.result.checkpointId ??
+                    `epoch-${runtime.rt.lastCompactAt ?? Date.now()}`,
+                cut,
+                summaryAgentMsg,
+                ctxPct: pct ?? null,
+                ctxTokens: currentTokens,
+            };
             runtime.snapshot(ctx);
             // DIAG (team-run relief): confirm the live trim actually fires + how big
             // the window still is. The return is non-durable (per-LLM-call only), so

package/dist/extensions/mega-pipeline/compact.js

@@ -152,12 +152,19 @@ function doCompact(view, keepFrom, opts, sid, config, pi, ctx, runtime) {
     }
     // Sentinel marker: a non-LLM bookkeeping entry so subsequent triggers can
     // skip re-vectorizing an already-compacted region (zero token cost).
-    pi.appendEntry(MARKER_TYPE, {
-        checkpointId: result.checkpointId,
-        regionHash: result.regionHash,
-        tokenEstimate: result.tokenEstimate,
-        deduped: result.deduped,
-    });
+    // v0.8.6: gate on !result.deduped so the marker ONLY lands when a genuinely
+    // new checkpoint was created. Without this, every dedup re-fire appended a
+    // fresh sentinel to the real transcript, bloating it and perturbing the
+    // provider KV-cache prefix (the alternating cache-miss regression). Matches
+    // the RAPTOR + vector-index blocks above, which are already !deduped-gated.
+    if (!result.deduped) {
+        pi.appendEntry(MARKER_TYPE, {
+            checkpointId: result.checkpointId,
+            regionHash: result.regionHash,
+            tokenEstimate: result.tokenEstimate,
+            deduped: result.deduped,
+        });
+    }
     // Fix D: refresh the RAPTOR tree for this session so live recall (search) can
     // serve high-level summaries. Best-effort + non-fatal: never block compaction.
     // Budget-guarded (RAPTOR_BUDGET_MS) so it can't hang a large session.

package/dist/extensions/mega-runtime/state.js

@@ -50,6 +50,14 @@ export class MegaRuntime {
         cacheHitTokens: 0,
         lengthStopPending: false,
     };
+    // v0.8.6 cache-stability: the cached live-trim view for the current
+    // compaction epoch. Set after a fresh runCompact + computeLiveTrimCut, and
+    // replayed verbatim on subsequent gated context events in the SAME epoch
+    // (same checkpointId) so the provider KV-cache prefix stays stable instead
+    // of being invalidated by a freshly regenerated summary + sentinel every
+    // fire. Invalidated on session restart (resetRuntime) and on any native
+    // durable compaction (session_compact) that truncates the transcript.
+    trimCache = null;
     debounceUntil = 0;
     // S16: debounce for the agent_end resume nudge (avoid busy-loops).
     resumeNudgeUntil = 0;
@@ -159,6 +167,7 @@ export class MegaRuntime {
      * updated and cost nothing).
      */
     diagLiveTrimFires = 0; // context handler returned a trimmed view
+    diagLiveTrimReplays = 0; // v0.8.6: trim view returned via cached replay (skipped re-compact)
     diagBeforeCompactFires = 0; // session_before_compact handler entered
     diagBeforeCompactSupplied = 0; // session_before_compact supplied our trim
     diagAgentEndIdle = 0; // agent_end with activeAgents===0
@@ -714,6 +723,7 @@ export class MegaRuntime {
             cacheHitTokens: 0,
             lengthStopPending: false,
         };
+        this.trimCache = null; // v0.8.6: never replay a stale trim into a new session
         this.statusKey = undefined;
         this.activeAgents = 0;
         this.currentTurn = 0;

package/extensions/mega-cache-replay.test.ts

@@ -0,0 +1,211 @@
+/**
+ * mega-cache-replay.test.ts — locks the v0.8.7 cache-stability fix.
+ *
+ * Two tests (reuses the mega-teamrun.test.ts harness shape: mock pi + the REAL
+ * compiled extension at extensions/mega-compact.js):
+ *  a. REPLAY: drive >=2 gated context events past the debounce within ONE epoch
+ *     (same lastCheckpointId) and assert diagLiveTrimReplays > 0 AND the returned
+ *     messages array is byte-identical (deepEqual) across replays (stable prefix).
+ *  b. DEDUP-ON-DIFFERENT-CHECKPOINT: after a fresh trim, simulate a re-compact
+ *     (context grew on the token basis) that DEDUPS onto a DIFFERENT existing
+ *     checkpoint id (L0 contentHash match against an OLDER checkpoint, so
+ *     result.checkpointId != rt.lastCheckpointId), then assert the NEXT gated
+ *     event STILL replays (diagLiveTrimReplays increments) — i.e. the cache key
+ *     trimCache.checkpointId === rt.lastCheckpointId holds. This is the P2 gap the
+ *     v0.8.6 audit found: keying on the dedup-volatile result.checkpointId
+ *     disabled replay for the rest of the epoch after such a dedup fire.
+ *
+ * MEGACOMPACT_PGLITE_DISABLED keeps the run fast (no WASM index init).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createRequire } from "node:module";
+import { closeVectorIndex } from "../src/store/vectorIndex.js";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+
+const require = createRequire(import.meta.url);
+const baseTmp = mkdtempSync(join(tmpdir(), "mc-cache-"));
+process.env.MEGACOMPACT_INDEX_DIR = join(baseTmp, "index");
+process.env.MEGACOMPACT_PGLITE_DISABLED = "true"; // fast: skip WASM index
+let counter = 0;
+
+function harness() {
+  const stateDir = join(baseTmp, `run-${counter++}`);
+  process.env.MEGACOMPACT_STATE_DIR = stateDir;
+  process.env.MEGACOMPACT_DEBUG = "true";
+  process.env.MEGACOMPACT_THRESHOLD_TOKENS = "50";
+  process.env.MEGACOMPACT_FAST_GATE_PCT = "1";
+  process.env.MEGACOMPACT_ANCHOR_USER_MESSAGES = "1";
+  process.env.MEGACOMPACT_DURABLE_TRIM_FLOOR = "0";
+  process.env.MEGACOMPACT_MEMORY_AUTO_REVIEW = "false";
+  process.env.MEGACOMPACT_RAPTOR_ENABLED = "false";
+  // Disable the FUZZY dedup tiers (L1 MinHash/LSH + L2 cosine) so the DEDUP test
+  // is controlled by L0 contentHash only: setB (different vocabulary) then
+  // creates a genuinely NEW checkpoint instead of fuzzy-matching setA's, and
+  // setA-re-again still L0-contentHash-dedups onto the first setA checkpoint.
+  // The TrigramEmbedder otherwise matches on shared structural trigrams
+  // ("— step N" / "Edit"), collapsing setB onto setA. Harmless for the REPLAY
+  // test (pure replay, no dedup reliance).
+  process.env.MEGACOMPACT_L1_ENABLED = "false";
+  process.env.MEGACOMPACT_L2_ENABLED = "false";
+  delete process.env.MEGACOMPACT_LEGACY_DURABLE_TRIM;
+
+  // Mutable context-usage so tests can drive re-compact on the TOKEN basis by
+  // raising `tokens` while keeping `percent` null (→ token gate + token
+  // grewEnough path in context-handler.ts). The REPLAY test keeps percent=100 so
+  // the percent-basis grewEnough (>=10) never trips (no re-compact → pure replay).
+  const usage = { tokens: 200000, contextWindow: 200000, percent: 100 as number | null };
+
+  const handlers: Record<string, Function> = {};
+  const compactCalls: any[] = [];
+
+  function msg(role: string, text: string, toolName?: string): AgentMessage {
+    if (role === "assistant" && toolName) {
+      return { role: "assistant", content: [{ type: "toolCall", name: toolName, id: "c1", arguments: {} }], api: "anthropic-messages", provider: "anthropic", model: "m", usage: { inputTokens: 1, outputTokens: 1, cacheReadTokens: 0, cacheWriteTokens: 0 }, stopReason: "tool_use", timestamp: 0 } as unknown as AgentMessage;
+    }
+    if (role === "toolResult" && toolName) {
+      return { role: "toolResult", content: [{ type: "text", text }], toolCallId: "c1", toolName, isError: false, timestamp: 0 } as unknown as AgentMessage;
+    }
+    return { role: "user", content: text, timestamp: 0 } as unknown as AgentMessage;
+  }
+
+  // Build a session of `n` tool-call triples tagged `tag`. Set A and B differ in
+  // content (so B never dedups against A) but A === A reproduces the same
+  // regionText → same L0 contentHash → dedup onto the first A checkpoint.
+  function buildSession(tag: string, n: number): AgentMessage[] {
+    const s: AgentMessage[] = [];
+    for (let i = 0; i < n; i++) {
+      s.push(msg("user", `[${tag}] we decided to use approach ${i} for module ${i}`));
+      s.push(msg("assistant", `[${tag}] edited module ${i}`, "Edit"));
+      s.push(msg("toolResult", `[${tag}] edited module ${i}`, "Edit"));
+    }
+    return s;
+  }
+
+  const toEntry = (m: AgentMessage, i: number): any => ({ type: "message", id: `e${i}`, parentId: null, timestamp: String(i), message: m });
+  const sessionManager = {
+    getSessionId: () => "sess_cache_001",
+    getEntries: () => buildSession("A", 14).map(toEntry),
+    getBranch: () => buildSession("A", 14).map(toEntry),
+  };
+
+  function makeCtx(over: Partial<any> = {}) {
+    return {
+      ui: { setStatus: () => {}, notify: () => {}, select: () => {}, confirm: async () => true, input: async () => "", setWidget: () => {} },
+      mode: "tui" as any, hasUI: true, cwd: stateDir, sessionManager,
+      modelRegistry: {} as any, model: undefined, isIdle: () => true, isProjectTrusted: () => true,
+      signal: undefined, abort: () => {}, hasPendingMessages: () => false, shutdown: () => {},
+      getContextUsage: () => ({ ...usage }),
+      compact: (opts?: any) => { compactCalls.push(opts); return undefined; },
+      getSystemPrompt: () => "system base",
+      ...over,
+    } as any;
+  }
+
+  const pi = {
+    on: (ev: string, h: Function) => { handlers[ev] = h; },
+    registerCommand: () => {}, registerTool: () => {}, registerShortcut: () => {},
+    registerFlag: () => {}, getFlag: () => undefined, registerMessageRenderer: () => {},
+    registerEntryRenderer: () => {}, sendMessage: () => {}, sendUserMessage: () => {},
+    appendEntry: () => {}, setSessionName: () => {}, getSessionName: () => undefined,
+    setLabel: () => {}, exec: async () => ({ stdout: "", stderr: "", code: 0 }),
+    getActiveTools: () => [], getAllTools: () => [], setActiveTools: () => {},
+    getCommands: () => [], setModel: async () => false, getThinkingLevel: () => "off" as any,
+    setThinkingLevel: () => {},
+  } as any;
+
+  const mod = require("./mega-compact.js") as { default: (p: any) => void };
+  mod.default(pi);
+  const { lastRuntime } = require("./mega-events.js") as { lastRuntime: any };
+
+  const fire = (ev: string, event: any, ctx: any) => handlers[ev](event, ctx);
+  return {
+    stateDir, handlers, compactCalls, fire, ctx: makeCtx, usage, buildSession,
+    runtime: lastRuntime, // MegaRuntime with diag* counters + rt + trimCache
+    // Bypass the 2s debounce so each fire proceeds without real waiting.
+    clearDebounce: () => { if (lastRuntime) lastRuntime.debounceUntil = 0; },
+  };
+}
+
+test("REPLAY: >=2 gated context events within one epoch replay verbatim (byte-identical)", async () => {
+  const h = harness();
+  const ctx = h.ctx();
+  const session = h.buildSession("A", 14);
+
+  // Fire 3 gated context events; clearDebounce between so each passes the gate.
+  // percent stays 100 → percent-basis grewEnough (>=10) never trips → pure replay.
+  h.clearDebounce();
+  const r1 = await h.fire("context", { type: "context", messages: session }, ctx);
+  h.clearDebounce();
+  const r2 = await h.fire("context", { type: "context", messages: session }, ctx);
+  h.clearDebounce();
+  const r3 = await h.fire("context", { type: "context", messages: session }, ctx);
+
+  const rt = h.runtime;
+  assert.ok(rt.diagLiveTrimFires >= 1, "fresh trim fired on first event");
+  assert.ok(rt.diagLiveTrimReplays >= 2, `replay fired >=2 (got ${rt.diagLiveTrimReplays})`);
+  // byte-identical (stable KV-cache prefix) across replays
+  assert.deepEqual(r2?.messages, r3?.messages, "replay messages byte-identical across replays");
+  // replay matches the fresh-trim view (shallow-copy preserves content)
+  assert.deepEqual(r1?.messages, r2?.messages, "replay matches fresh-trim view (stable prefix)");
+});
+
+test("DEDUP: re-compact that dedups onto a DIFFERENT checkpoint still replays next (P2 fix)", async () => {
+  const h = harness();
+  // Token-basis growth path: percent null → token gate + token grewEnough
+  // (currentTokens - trimCache.ctxTokens >= effectiveThreshold * 0.5 = 25).
+  h.usage.percent = null;
+  h.usage.tokens = 200000;
+  const ctx = h.ctx();
+  const setA = h.buildSession("A", 14);
+  const setB = h.buildSession("B", 14); // different content, same length
+  const rt = h.runtime;
+
+  // 1) Fresh trim on setA → genuinely new checkpoint cp_A. lastCheckpointId = cp_A.
+  h.clearDebounce();
+  await h.fire("context", { type: "context", messages: setA }, ctx);
+  const cpA = rt.rt.lastCheckpointId;
+  assert.ok(cpA, "cp_A created on fresh trim");
+  assert.equal(rt.diagLiveTrimFires, 1, "first fire was a fresh trim");
+
+  // 2) Re-compact on setB (grew tokens) → genuinely new checkpoint cp_B (not deduped).
+  h.usage.tokens = 200100; // grew 100 >= 25
+  h.clearDebounce();
+  await h.fire("context", { type: "context", messages: setB }, ctx);
+  const cpB = rt.rt.lastCheckpointId;
+  assert.notEqual(cpB, cpA, "cp_B is a different, genuinely new checkpoint");
+  assert.equal(rt.rt.dedupSkips, 0, "setB did not dedup (different vocabulary, fuzzy tiers off)");
+
+  // 3) Re-compact on setA AGAIN (grew tokens) → L0 contentHash dedup onto cp_A.
+  //    result.checkpointId = cp_A (!= lastCheckpointId cp_B); lastCheckpointId is
+  //    NOT updated on a dedup (compact.ts:100-104), so it stays cp_B. With the
+  //    fix, trimCache.checkpointId is keyed on lastCheckpointId (cp_B), NOT the
+  //    dedup-volatile result.checkpointId (cp_A).
+  h.usage.tokens = 200200; // grew 100 >= 25
+  h.clearDebounce();
+  await h.fire("context", { type: "context", messages: setA }, ctx);
+  assert.equal(rt.rt.lastCheckpointId, cpB, "dedup did NOT bump lastCheckpointId (still cp_B)");
+  assert.ok(rt.rt.dedupSkips >= 1, "setA re-compact deduped onto an existing checkpoint");
+  // The P2 invariant: the cache key must equal the stable epoch signal.
+  assert.equal(rt.trimCache?.checkpointId, rt.rt.lastCheckpointId,
+    "trimCache.checkpointId keyed on lastCheckpointId (P2 fix), not dedup-volatile result.checkpointId");
+
+  // 4) Next gated event (no growth) MUST replay instead of re-running runCompact.
+  //    Without the fix, trimCache.checkpointId (cp_A) != lastCheckpointId (cp_B)
+  //    → the replay condition is false → runCompact re-runs every fire → the
+  //    thrash silently persists in that path (the audit's finding).
+  const replaysBefore = rt.diagLiveTrimReplays;
+  h.usage.tokens = 200200; // no growth → replay
+  h.clearDebounce();
+  await h.fire("context", { type: "context", messages: setA }, ctx);
+  assert.ok(rt.diagLiveTrimReplays > replaysBefore,
+    `replay fired after dedup-onto-different-checkpoint (got ${rt.diagLiveTrimReplays}, was ${replaysBefore})`);
+});
+
+test("cleanup", async () => {
+  await closeVectorIndex();
+  rmSync(baseTmp, { recursive: true, force: true });
+});

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

@@ -159,6 +159,7 @@ export function registerCompactHandlers(
 		pi.on("session_compact", async (_event: SessionCompactEvent, _ctx: ExtensionContext) => {
 			runtime.rt.lastNativeCompactAt = Date.now();
 			runtime.rt.lastCompactAt = Date.now();
+			runtime.trimCache = null; // v0.8.6: durable truncation changes the transcript — never replay the stale cached cut (PREVENT-PI-001/002)
 			runtime.logger.info("session-compacted", {
 				sessionId: runtime.rt.sessionId,
 				at: runtime.rt.lastCompactAt,

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

@@ -157,6 +157,40 @@ export function registerContextHandler(
 		}
 		runtime.debounceUntil = now + 2000;
 
+		// v0.8.6 cache-stability: replay the cached trim view when still in the
+		// same compaction epoch AND context hasn't grown enough to warrant a
+		// re-compact. This stabilizes the provider KV-cache prefix (the summary +
+		// cut are reused verbatim) instead of regenerating a fresh summary +
+		// sentinel every fire, which invalidated the prefix on every other turn
+		// (the alternating cache-miss regression). Re-compact only when context
+		// grew >=10% of the window (percent basis) or >=50% of the effective
+		// threshold (token basis, when percent is unavailable). The cached `cut`
+		// is only valid while the transcript grows within the epoch — it is
+		// cleared on session_compact (durable truncation) + resetRuntime, so we
+		// never replay a stale cut into a truncated transcript (PREVENT-PI-001/002).
+		const RECOMPACT_PCT_DELTA = 10;
+		if (
+			runtime.trimCache &&
+			runtime.trimCache.checkpointId === runtime.rt.lastCheckpointId &&
+			runtime.trimCache.cut <= messages.length
+		) {
+			const grewEnough =
+				pct != null && runtime.trimCache.ctxPct != null
+					? pct - runtime.trimCache.ctxPct >= RECOMPACT_PCT_DELTA
+					: currentTokens - (runtime.trimCache.ctxTokens ?? 0) >=
+							runtime.effectiveThreshold * 0.5;
+			if (!grewEnough) {
+				const recent = messages.slice(runtime.trimCache.cut); // guardrails-allow PREVENT-PI-002: cached `cut` was sanitized once by computeLiveTrimCut (src/boundary.ts) and replayed verbatim; the transcript only grows within an epoch (cache is cleared on durable truncation), so the preserved run still starts on a toolPair-safe index.
+				runtime.diagLiveTrimFires++; // trim view returned this call (replay counts as a fire)
+				runtime.diagLiveTrimReplays++;
+				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] };
+			}
+			// else: context grew enough → fall through to re-compact (cache is stale)
+		}
+
 		// Adaptive compression (Fix E): scale compression strength + keepFrom depth
 		// with how close we are to the model context limit. Null-safe: when the
 		// token-fallback path ran (pct unavailable) use the token-basis pressure
@@ -266,9 +300,36 @@ export function registerContextHandler(
 			const summaryAgentMsg = {
 				role: "user" as const,
 				content: summaryMsg.text,
-				timestamp: Date.now(),
+				// v0.8.6: stable timestamp across the epoch (NOT Date.now()) so the
+				// summary message bytes — and thus the KV-cache prefix — don't drift
+				// on every replay within the same compaction epoch.
+				timestamp: runtime.rt.lastCompactAt ?? Date.now(),
 			} as unknown as AgentMessage;
 			const recent = messages.slice(cut); // guardrails-allow PREVENT-PI-002: `cut` is the pre-sanitized `compactedFrom` produced by src/boundary.ts computeDropRange, so the preserved run begins on a toolPair-safe index.
+			// v0.8.6: cache the trim view so subsequent gated calls in this epoch
+			// replay it verbatim (stabilizing the KV-cache prefix) instead of
+			// regenerating a fresh summary + sentinel every fire.
+			runtime.trimCache = {
+				// v0.8.7: key the replay cache on the STABLE epoch signal
+				// (rt.lastCheckpointId) instead of ran.result.checkpointId, which is
+				// dedup-volatile: on a re-compact that dedups onto a DIFFERENT existing
+				// checkpoint, result.checkpointId is the matched id (engine.ts:188) while
+				// lastCheckpointId is only updated on a genuinely new checkpoint
+				// (compact.ts:100-104). Keying on result.checkpointId would make
+				// trimCache.checkpointId != rt.lastCheckpointId forever after that
+				// dedup fire, disabling replay for the rest of the epoch (the
+				// alternating cache-miss that 0.8.6 meant to fix). Prefer the stable
+				// signal; fall back to result.checkpointId then the epoch timestamp
+				// only for the no-checkpoint edge case.
+				checkpointId:
+					runtime.rt.lastCheckpointId ??
+					ran.result.checkpointId ??
+					`epoch-${runtime.rt.lastCompactAt ?? Date.now()}`,
+				cut,
+				summaryAgentMsg,
+				ctxPct: pct ?? null,
+				ctxTokens: currentTokens,
+			};
 			runtime.snapshot(ctx);
 			// DIAG (team-run relief): confirm the live trim actually fires + how big
 			// the window still is. The return is non-durable (per-LLM-call only), so

package/extensions/mega-pipeline/compact.ts

@@ -192,12 +192,19 @@ function doCompact(
 
   // Sentinel marker: a non-LLM bookkeeping entry so subsequent triggers can
   // skip re-vectorizing an already-compacted region (zero token cost).
-  pi.appendEntry(MARKER_TYPE, {
-    checkpointId: result.checkpointId,
-    regionHash: result.regionHash,
-    tokenEstimate: result.tokenEstimate,
-    deduped: result.deduped,
-  });
+  // v0.8.6: gate on !result.deduped so the marker ONLY lands when a genuinely
+  // new checkpoint was created. Without this, every dedup re-fire appended a
+  // fresh sentinel to the real transcript, bloating it and perturbing the
+  // provider KV-cache prefix (the alternating cache-miss regression). Matches
+  // the RAPTOR + vector-index blocks above, which are already !deduped-gated.
+  if (!result.deduped) {
+    pi.appendEntry(MARKER_TYPE, {
+      checkpointId: result.checkpointId,
+      regionHash: result.regionHash,
+      tokenEstimate: result.tokenEstimate,
+      deduped: result.deduped,
+    });
+  }
 
   // Fix D: refresh the RAPTOR tree for this session so live recall (search) can
   // serve high-level summaries. Best-effort + non-fatal: never block compaction.

package/extensions/mega-runtime/state.ts

@@ -87,6 +87,20 @@ export class MegaRuntime {
 		cacheHitTokens: 0,
 		lengthStopPending: false,
 	};
+	// v0.8.6 cache-stability: the cached live-trim view for the current
+	// compaction epoch. Set after a fresh runCompact + computeLiveTrimCut, and
+	// replayed verbatim on subsequent gated context events in the SAME epoch
+	// (same checkpointId) so the provider KV-cache prefix stays stable instead
+	// of being invalidated by a freshly regenerated summary + sentinel every
+	// fire. Invalidated on session restart (resetRuntime) and on any native
+	// durable compaction (session_compact) that truncates the transcript.
+	trimCache: {
+		checkpointId: string;
+		cut: number;
+		summaryAgentMsg: AgentMessage;
+		ctxPct: number | null;
+		ctxTokens: number | null;
+	} | null = null;
 	debounceUntil = 0;
 	// S16: debounce for the agent_end resume nudge (avoid busy-loops).
 	resumeNudgeUntil = 0;
@@ -199,6 +213,7 @@ export class MegaRuntime {
 	 * updated and cost nothing).
 	 */
 	diagLiveTrimFires = 0; // context handler returned a trimmed view
+	diagLiveTrimReplays = 0; // v0.8.6: trim view returned via cached replay (skipped re-compact)
 	diagBeforeCompactFires = 0; // session_before_compact handler entered
 	diagBeforeCompactSupplied = 0; // session_before_compact supplied our trim
 	diagAgentEndIdle = 0; // agent_end with activeAgents===0
@@ -795,6 +810,7 @@ export class MegaRuntime {
 			cacheHitTokens: 0,
 			lengthStopPending: false,
 	};
+		this.trimCache = null; // v0.8.6: never replay a stale trim into a new session
 		this.statusKey = undefined;
 		this.activeAgents = 0;
 		this.currentTurn = 0;

package/package.json

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