pi-mega-compact 0.8.24 → 0.8.26

package/extensions/mega-pipeline/compact.ts

@@ -24,6 +24,7 @@ import {
 } from "../mega-runtime.js";
 import { resolveRepoRoot, preserveRecentForPressure, type MegaConfig } from "../mega-config.js";
 import { runRaptor } from "../../src/dedup/raptor/index.js";
+import { isRaptorTreeFresh } from "../../src/dedup/raptor/buildHistory.js";
 import { loadDedupConfig } from "../../src/config/dedup.js";
 import { upsertEmbedding as indexUpsertEmbedding } from "../../src/store/vectorIndex.js";
 import { runMemoryReview } from "./memory-review.js";
@@ -221,22 +222,33 @@ function doCompact(
         embedding: cp.embedding,
       }));
       if (leaves.length >= 2) {
-        // S25: stamp the tree with the newest checkpoint epoch so the
-        // freshness guard in raptorSearchHits can reject stale trees after a
-        // later compaction adds newer checkpoints.
-        const builtAt = all.length > 0 ? Math.max(...all.map((c) => c.timestamp)) : Date.now();
-        runRaptor(
-          leaves,
-          {
-            stateDir: runtime.currentStateDir,
-            sessionId: sid,
-            budgetMs: dd.RAPTOR_BUDGET_MS,
-            clustersPerLevel: dd.RAPTOR_CLUSTERS_PER_LEVEL,
-            consistencyThreshold: dd.RAPTOR_CONSISTENCY,
-            logger: runtime.logger,
-            builtAt: Number.isFinite(builtAt) ? builtAt : Date.now(),
-          },
-        );
+        // S42D: skip the rebuild when the last build is fresh (within
+        // RAPTOR_FRESHNESS_HOURS) and the checkpoint count hasn't drifted by
+        // more than 20%. avoids re-clustering on every compaction when the
+        // tree is still representative. 0 disables (always rebuild).
+        if (
+          dd.RAPTOR_FRESHNESS_HOURS > 0 &&
+          isRaptorTreeFresh(sid, runtime.currentStateDir, dd.RAPTOR_FRESHNESS_HOURS, all.length)
+        ) {
+          runtime.logger?.info("raptor_skip_fresh", { sessionId: sid });
+        } else {
+          // S25: stamp the tree with the newest checkpoint epoch so the
+          // freshness guard in raptorSearchHits can reject stale trees after a
+          // later compaction adds newer checkpoints.
+          const builtAt = all.length > 0 ? Math.max(...all.map((c) => c.timestamp)) : Date.now();
+          runRaptor(
+            leaves,
+            {
+              stateDir: runtime.currentStateDir,
+              sessionId: sid,
+              budgetMs: dd.RAPTOR_BUDGET_MS,
+              clustersPerLevel: dd.RAPTOR_CLUSTERS_PER_LEVEL,
+              consistencyThreshold: dd.RAPTOR_CONSISTENCY,
+              logger: runtime.logger,
+              builtAt: Number.isFinite(builtAt) ? builtAt : Date.now(),
+            },
+          );
+        }
       }
     } catch {
       /* non-fatal: tree refresh never blocks a compaction */

package/extensions/mega-pipeline/recall.ts

@@ -10,7 +10,8 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
 import { recallAndInline, recallAndInlineAsync, formatRecallBlock, type RecallInjectResult } from "../../src/recall.js";
 import { normalizeSessionId } from "../../src/store.js";
-import { incRecallInjected, incCacheHitTokens } from "../../src/store/sqlite.js";
+import { incRecallInjected, incCacheHitTokens, getIndexDir } from "../../src/store/sqlite.js";
+import { ensureConversationId, recordTurn, recordTurnRecall, type RecallSource } from "../../src/store/sqlite/turns.js";
 import {
   type MegaRuntime,
   C,
@@ -64,6 +65,30 @@ export function doRecall(
     runtime.rt.cacheHitTokens += sumTokens;
     incRecallInjected(result.toInject.length, runtime.currentStateDir);
     incCacheHitTokens(sumTokens, runtime.currentStateDir);
+    // S43: record recall provenance — which checkpoints/summaries served this
+    // turn, their score + source path. Linked to the turn row written at
+    // turn_end via the conversation+turnIndex. Best-effort + non-fatal.
+    try {
+      const convId = ensureConversationId(sid, runtime.currentStateDir);
+      const turnId = recordTurn({
+        conversationId: convId,
+        sessionId: sid,
+        turnIndex: runtime.currentTurn,
+        startedAt: Date.now(),
+      }, runtime.currentStateDir);
+      recordTurnRecall(
+        turnId,
+        result.toInject.map((h) => ({
+          checkpointId: h.checkpoint.checkpointId,
+          score: h.score,
+          source: (h.raptorLevel !== undefined ? "raptor" : h.repoId ? "cross-repo" : "flat") as RecallSource,
+          raptorLevel: h.raptorLevel,
+        })),
+        runtime.currentStateDir,
+      );
+    } catch {
+      /* non-fatal: recall provenance never breaks the recall path */
+    }
   }
   return result;
 }
@@ -108,7 +133,14 @@ export async function doRecallAsync(
         sessionId: sid, query, limit: config.autoInlineK, source, skipInjected: true,
         recallMaxTokens: config.recallMaxTokens, windowDedupe: config.windowDedupe,
         liveWindow, dedupSim: config.crossRepoCosine, crossRepo: true,
-        globalIndexDir: process.env.MEGACOMPACT_INDEX_DIR,
+        // F2: resolve the machine-wide index dir via the shared resolver so the
+        // cross-repo injected-set dedup works even when MEGACOMPACT_INDEX_DIR is
+        // unset. The env var still wins when set (getIndexDir checks it first);
+        // the default (~/.mega-compact-index) is the same DB mega-commands and the
+        // dashboard read, so injection counts stay consistent. Without this, a
+        // bare `process.env` read returns undefined → cross-repo hits re-inject in
+        // every new session (the global injected-set is never consulted).
+        globalIndexDir: getIndexDir(),
       },
       runtime.store,
     );

package/extensions/mega-runtime/dashboard-snapshot.ts

@@ -50,6 +50,10 @@ export interface SnapshotBuildContext {
 	readonly consecutiveErrors: number;
 	readonly ERROR_RETRY_MAX_CONSECUTIVE: number;
 	readonly errorRetryHardStop: boolean;
+	// R7 (retry redesign): session-global cap + poisoned-context counters.
+	readonly sessionRetryCount: number;
+	readonly sessionRetryMax: number;
+	readonly poisonedCount: number;
 	readonly activeAgents: number;
 	readonly currentTurn: number;
 	readonly currentModel: { providerName: string | null; modelId: string; provider: string; inputRate: number; outputRate: number } | null | undefined;
@@ -168,6 +172,10 @@ export function buildDashboardSnapshot(ctx: SnapshotBuildContext): DashboardSnap
 			consecutiveErrors: ctx.consecutiveErrors,
 			maxConsecutiveErrors: ctx.ERROR_RETRY_MAX_CONSECUTIVE,
 			errorRetryHardStop: ctx.errorRetryHardStop,
+			// R7 (retry redesign): additive session-cap + poisoned-context counters.
+			sessionRetryCount: ctx.sessionRetryCount,
+			sessionMax: ctx.sessionRetryMax,
+			poisonedCount: ctx.poisonedCount,
 		},
 	};
 }

package/extensions/mega-runtime/helpers.ts

@@ -44,10 +44,34 @@ export interface SessionRuntime {
 	cacheHitTokens: number; // tokens saved via cache hits (dedup + recall) this session
 	lengthStopPending: boolean; // S28: set on turn_end when stopReason==='length'
 	errorRetryCount: number; // S38: consecutive error turns, reset on success/turn_start
-	errorRetryUntil: number; // S38: wall-clock ms debounce for error-retry nudge
+	errorRetryUntil: number; // S38: wall-clock ms before which the next nudge is suppressed (R1: now gating)
 	// S38.6: circuit-breaker state — consecutive error turns across the session.
 	// When this exceeds maxConsecutiveErrors, the extension stops retrying.
 	consecutiveErrors: number; // reset to 0 on successful turn_end
+	// R1 (retry redesign): in-flight nudge dedup. A nudge queued via
+	// deliverAs:'followUp' must not be re-sent until it has been consumed by an
+	// actual new agent turn (turn_start) or superseded by a successful turn.
+	// Without this, a fast-erroring provider + a per-turn nudge → N nudges queue
+	// up and pi dispatches N retry turns, each re-submitting the same failing
+	// prompt (the 2026-07-28 incident: ~60-message spam storm).
+	lastErrorRetryAt: number; // wall-clock ms of the last fired nudge (diagnostics)
+	retryNudgePending: boolean; // true while a queued nudge awaits consumption
+	// R2: session-global cap. Total S38 nudges per session across ALL bursts;
+	// independent of the per-burst max and the circuit breaker. Hitting it is
+	// terminal for the session — the extension stops nudging entirely.
+	errorRetrySessionCount: number; // nudges fired this session (across all bursts)
+	// R3: poisoned-context detection state. The classifier is stateless; the
+	// stateful "repeated identical error text" signal is tracked here and upgrades
+	// a 'transient' classification to 'poisoned-context' after the threshold.
+	lastErrorText: string | undefined; // normalized error signature from the last error turn
+	errorTextRepeatCount: number; // consecutive count of identical error signatures
+	// R3b: one-per-session /clear advise message throttle.
+	poisonedAdviseSent: boolean; // true after the advise message fires once
+	// R3c: one guarded compact per error signature (avoids re-compacting the
+	// same poisoned region repeatedly).
+	poisonedCompactSignatures: Set<string>; // signatures already attempted a compact for
+	// R7: poisoned-context event counter for the dashboard.
+	poisonedCount: number;
 }
 
 // ── ownVersion ─────────────────────────────────────────────────────────────

package/extensions/mega-runtime/runtime-snapshot.ts

@@ -158,6 +158,10 @@ export function snapshotImpl(self: RuntimeSnapshotContext, ctx?: ExtensionContex
 			consecutiveErrors: self.rt.consecutiveErrors,
 			ERROR_RETRY_MAX_CONSECUTIVE: self.config.maxConsecutiveErrors,
 			errorRetryHardStop: self.config.errorRetryHardStop,
+			// R7 (retry redesign): session-cap + poisoned-context counters.
+			sessionRetryCount: self.rt.errorRetrySessionCount,
+			sessionRetryMax: self.config.errorRetrySessionMax,
+			poisonedCount: self.rt.poisonedCount,
 			activeAgents: self.activeAgents,
 			currentTurn: self.currentTurn,
 			currentModel: self.currentModel,

package/extensions/mega-runtime/runtime.ts

@@ -5,7 +5,7 @@
  * Phase 2d (maximal split): the class body is field declarations, the
  * constructor, and 1-line delegates only. Every method body lives in its own
  * module following the context-interface + free-function + thin-delegate
- * pattern: pressure-getters.ts / reset-runtime.ts / append-event.ts /
+ * pattern: pressure-getters.ts / append-event.ts /
  * get-state-dir.ts / render-widget.ts / status.ts / engine-view.ts /
  * runtime-snapshot.ts / runtime-helpers.ts / effects.ts / game-state.ts /
  * capture-model.ts / bind-repo.ts / perf.ts. state.ts re-exports the class for
@@ -15,27 +15,16 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import { join } from "node:path";
-import { type FSWatcher } from "node:fs";
+import type { FSWatcher } from "node:fs";
 import { VectorStore } from "../../src/vectorStore.js";
-import { toEngineMessages } from "../../src/adapt.js";
+import type { toEngineMessages } from "../../src/adapt.js";
 import { normalizeSessionId } from "../../src/store.js";
 import { Logger } from "../../src/log.js";
-import {
-	type ModelSnapshot,
-	type GameState,
-} from "../../src/store/sqlite.js";
-import {
-	type MegaConfig,
-	type PressureBand,
-} from "../mega-config.js";
+import type { ModelSnapshot, GameState } from "../../src/store/sqlite.js";
+import type { MegaConfig, PressureBand } from "../mega-config.js";
 import { Dashboard } from "../mega-dashboard.js";
-import {
-	type SessionRuntime,
-} from "./helpers.js";
-import {
-	type TickerEntry,
-	type WidgetData,
-} from "./widget.js";
+import type { SessionRuntime } from "./helpers.js";
+import type { TickerEntry, WidgetData } from "./widget.js";
 import {
 	ensureGameStateWatcherImpl,
 	getCachedGameStateImpl,
@@ -59,7 +48,6 @@ import {
 	effectiveThresholdImpl,
 	pressureBandImpl,
 } from "./pressure-getters.js";
-import { resetRuntimeImpl } from "./reset-runtime.js";
 import { appendEventImpl } from "./append-event.js";
 import { getStateDirImpl } from "./get-state-dir.js";
 import { renderWidgetImpl } from "./render-widget.js";
@@ -95,6 +83,15 @@ export class MegaRuntime {
 		errorRetryCount: 0,
 		errorRetryUntil: 0,
 		consecutiveErrors: 0,
+		// R1-R3 (retry redesign): in-flight dedup, session cap, poisoned-context state.
+		lastErrorRetryAt: 0,
+		retryNudgePending: false,
+		errorRetrySessionCount: 0,
+		lastErrorText: undefined,
+		errorTextRepeatCount: 0,
+		poisonedAdviseSent: false,
+		poisonedCompactSignatures: new Set(),
+		poisonedCount: 0,
 	};
 	// v0.8.6 cache-stability: the cached live-trim view for the current
 	// compaction epoch. Set after a fresh runCompact + computeLiveTrimCut, and
@@ -125,7 +122,12 @@ export class MegaRuntime {
 	 *  compaction start). Threaded into widgetData as `activeEffect`; the widget
 	 *  computes the per-frame phase from startedAt vs Date.now() (non-expired).
 	 *  Null when idle/expired. */
-	activeEffect: { type: "pulse" | "flash"; role: "accent" | "mega" | "red"; startedAt: number; durationMs: number } | null = null;
+	activeEffect: {
+		type: "pulse" | "flash";
+		role: "accent" | "mega" | "red";
+		startedAt: number;
+		durationMs: number;
+	} | null = null;
 	megaCacheFlarePct = 0;
 	levelUpFlare = false;
 	lastLevel = 0;
@@ -316,10 +318,54 @@ export class MegaRuntime {
 		setStatusImpl(this, ctx, text);
 	}
 
-	/** Per-session state reset (session_start / session_tree) — thin delegate to
-	 *  `resetRuntimeImpl` (reset-runtime.ts). */
+	/** Per-session state reset (session_start / session_tree) — inlined by the
+	 *  raptor-promotion merge (R1–R3 retry-redesign fields); reset-runtime.ts was
+	 *  retired by that branch. */
 	resetRuntime(sessionId: string | undefined): void {
-		resetRuntimeImpl(this, sessionId);
+		const sid = normalizeSessionId(sessionId);
+		if (this.rt.sessionId === sid && this.rt.persistedThisSession) return; // same session, keep checkpoint memory
+		this.rt = {
+			sessionId: sid,
+			persistedThisSession: false,
+			lastCheckpointId: undefined,
+			lastCompactedFrom: 0,
+			lastCompactedTokens: 0,
+			dedupSkips: 0,
+			dedupAttempts: 0,
+			tokensSaved: 0,
+			lastCompactAt: null,
+			lastNativeCompactAt: null,
+			compactCount: 0,
+			recallInjections: 0,
+			cacheHitTokens: 0,
+			lengthStopPending: false,
+			errorRetryCount: 0,
+			errorRetryUntil: 0,
+			consecutiveErrors: 0,
+			// R1-R3 (retry redesign): in-flight dedup, session cap, poisoned-context state.
+			lastErrorRetryAt: 0,
+			retryNudgePending: false,
+			errorRetrySessionCount: 0,
+			lastErrorText: undefined,
+			errorTextRepeatCount: 0,
+			poisonedAdviseSent: false,
+			poisonedCompactSignatures: new Set(),
+			poisonedCount: 0,
+		};
+		this.trimCache = null; // v0.8.6: never replay a stale trim into a new session
+		this.statusKey = undefined;
+		this.activeAgents = 0;
+		this.currentTurn = 0;
+		this.lastActivityAt = 0;
+		this.tierTrace = undefined;
+		this.ticker.length = 0;
+		this.pulsing = false;
+		this.savedGoal = 50_000;
+		this.lastWhy = undefined;
+		// S31 audit P2: symmetry with bindRepo — a reset can coincide with a context
+		// that re-binds the repo, so drop the memo too. Cheap; the next
+		// getCachedGameState() re-queries lazily.
+		this.cachedGameState = undefined;
 	}
 
 	captureModel(ctx: ExtensionContext): void {

package/package.json

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

package/src/boundary.test.ts

@@ -7,6 +7,7 @@ function user(t: string): EngineMessage { return { role: "user", text: t }; }
 function assistant(t: string): EngineMessage { return { role: "assistant", text: t }; }
 function toolUse(n: string, i = "{}"): EngineMessage { return { role: "assistant", text: "", toolName: n, input: i }; }
 function toolResult(n: string, o = "ok"): EngineMessage { return { role: "tool", text: "", toolName: n, output: o }; }
+function custom(t: string): EngineMessage { return { role: "custom", text: t }; }
 
 test("walks back so first preserved message is not an orphaned tool result", () => {
   const messages = [
@@ -25,9 +26,14 @@ test("walks back so first preserved message is not an orphaned tool result", ()
   assert.equal(kept[0].toolName, "search"); // assistant tool-call preserved
 });
 
-test("isBoundarySafe: tool result at boundary with preceding tool use is safe", () => {
+test("isBoundarySafe: cut that drops a toolCall but keeps its toolResult is unsafe (PREVENT-PI-002)", () => {
   const messages = [user("a"), toolUse("search"), toolResult("search")];
-  assert.equal(isBoundarySafe(messages, 2), true);
+  // keepFrom=2 drops the toolUse at index 1 but keeps the toolResult at index 2 →
+  // the preserved run starts on an orphaned tool result. This is the shape the old
+  // check mis-validated (it only compared messages[keepFrom] to messages[keepFrom-1]).
+  assert.equal(isBoundarySafe(messages, 2), false);
+  // keepFrom=1 keeps the toolCall together with its toolResult → safe.
+  assert.equal(isBoundarySafe(messages, 1), true);
 });
 
 test("isBoundarySafe: orphaned tool result without preceding tool use is unsafe", () => {
@@ -59,3 +65,123 @@ test("dropBefore returns original when range is empty", () => {
   const messages = [user("a"), assistant("b")];
   assert.equal(dropBefore(messages, 0, 1), messages);
 });
+
+// --- PREVENT-PI-002 regression cases for arbitrary interleavings ---
+
+test("interleaved custom message between toolCall and toolResult: walk-back keeps the call", () => {
+  // [user, assistant(tc=read), custom/bashExecution, tool(read-result)] with
+  // desired keepFrom=3. The old walk-back saw messages[2] was not a toolUse and
+  // broke at k=2, dropping the assistant toolCall at index 1 while KEEPING its
+  // tool result at index 3 → orphaned tool result → provider 400.
+  const messages = [
+    user("Search for files"),
+    toolUse("read"),
+    custom("bash: ls -la"),
+    toolResult("read", "file contents"),
+    assistant("Done."),
+  ];
+  const [start, end] = computeDropRange(messages, 3, 0);
+  assert.equal(start, 0);
+  assert.equal(end, 1); // keep the assistant toolCall at index 1 with its result
+  const kept = messages.slice(end);
+  assert.equal(kept[0].toolName, "read"); // assistant tool-call preserved
+  assert.ok(kept.some((m) => m.role === "tool" && m.toolName === "read"));
+  // The toolCall and its toolResult are both in the kept run.
+  const callIdx = kept.findIndex((m) => m.role === "assistant" && m.toolName === "read");
+  const resultIdx = kept.findIndex((m) => m.role === "tool" && m.toolName === "read");
+  assert.ok(callIdx !== -1 && resultIdx !== -1 && callIdx < resultIdx);
+});
+
+test("consecutive tool results sharing one call: no-op when the call cannot be kept", () => {
+  // [assistant(tc), T1, T2] with keepFrom=1: dropping the call orphans BOTH T1
+  // and T2. No pair-safe positive cut exists below keepFrom → no-op compaction
+  // (the [start,end) contract preserves a non-zero result only when one exists).
+  const messages = [toolUse("multi"), toolResult("multi", "r1"), toolResult("multi", "r2")];
+  const [start, end] = computeDropRange(messages, 1, 0);
+  assert.equal(start, 0);
+  assert.equal(end, 0); // no-op — pair rule outranks dropping
+  assert.equal(dropBefore(messages, 1, 0), messages);
+});
+
+test("consecutive tool results sharing one call: safe cut keeps the call with both results", () => {
+  // [user, assistant(tc), T1, T2, user2] — keepFrom=3 would orphan T2; the guard
+  // walks back to keep the call (dropEnd=1, only the first user is dropped).
+  const messages = [
+    user("u1"),
+    toolUse("multi"),
+    toolResult("multi", "r1"),
+    toolResult("multi", "r2"),
+    user("u2"),
+  ];
+  const [start, end] = computeDropRange(messages, 3, 0);
+  assert.equal(start, 0);
+  assert.equal(end, 1); // keep [assistant(tc), T1, T2, user2]
+  const kept = messages.slice(end);
+  const callIdx = kept.findIndex((m) => m.role === "assistant" && m.toolName === "multi");
+  const r1Idx = kept.findIndex((m) => m.role === "tool" && m.output === "r1");
+  const r2Idx = kept.findIndex((m) => m.role === "tool" && m.output === "r2");
+  assert.ok(callIdx < r1Idx && r1Idx < r2Idx);
+});
+
+test("consecutive shared-call results: dropping call + all results together is safe", () => {
+  // keepFrom=4 preserves only the trailing user — the call and BOTH results are
+  // dropped together, so nothing is orphaned.
+  const messages = [
+    user("u1"),
+    toolUse("multi"),
+    toolResult("multi", "r1"),
+    toolResult("multi", "r2"),
+    user("u2"),
+  ];
+  const [start, end] = computeDropRange(messages, 4, 0);
+  assert.equal(start, 0);
+  assert.equal(end, 4);
+  assert.deepEqual(messages.slice(end), [user("u2")]);
+});
+
+test("keepFrom landing on a call whose results follow is safe", () => {
+  // [user, assistant(tc1), T1, assistant(tc2), T2, user2] keepFrom=3 → preserved
+  // run starts on assistant(tc2) at index 3, whose result T2 follows. Safe.
+  const messages = [
+    user("u1"),
+    toolUse("read"),
+    toolResult("read", "r1"),
+    toolUse("write"),
+    toolResult("write", "r2"),
+    user("u2"),
+  ];
+  const [start, end] = computeDropRange(messages, 3, 0);
+  assert.equal(start, 0);
+  assert.equal(end, 3);
+  const kept = messages.slice(end);
+  assert.equal(kept[0].role, "assistant");
+  assert.equal(kept[0].toolName, "write");
+  assert.ok(kept.some((m) => m.role === "tool" && m.toolName === "write"));
+});
+
+test("anchor floor + pair-rule conflict: pair rule wins, drop less", () => {
+  // [assistant(tc), user, T] with anchor=1: the anchor floor wants dropEnd<=1
+  // (keep the user at index 1), but keeping from index 1 orphans T (its owner at
+  // index 0 would be dropped). The pair rule outranks the floor — we drop LESS,
+  // keeping everything (no-op) rather than cross a pair.
+  const messages = [toolUse("read"), user("keep me"), toolResult("read", "r")];
+  const out = dropBefore(messages, 2, 1);
+  assert.equal(out, messages, "anchor floor would orphan the tool result → no-op");
+});
+
+test("isBoundarySafe: interleaved custom between call and result is detected unsafe", () => {
+  const messages = [user("a"), toolUse("read"), custom("bash"), toolResult("read", "r")];
+  // keepFrom=3 drops the call at index 1, keeps the result at index 3 → unsafe.
+  assert.equal(isBoundarySafe(messages, 3), false);
+  // keepFrom=2 ALSO drops the call at index 1 (drop [0,2) = [user, toolUse]) and
+  // keeps the result at index 3 → still orphaned → unsafe.
+  assert.equal(isBoundarySafe(messages, 2), false);
+  // keepFrom=1 keeps the call (index 1) together with its result at index 3 → safe.
+  assert.equal(isBoundarySafe(messages, 1), true);
+});
+
+test("isBoundarySafe: cut before any tool result is safe", () => {
+  const messages = [user("a"), toolUse("read"), toolResult("read", "r"), assistant("done")];
+  assert.equal(isBoundarySafe(messages, 0), true); // out of range → safe
+  assert.equal(isBoundarySafe(messages, messages.length), true); // out of range → safe
+});

package/src/boundary.ts

@@ -5,10 +5,19 @@
  *  1. ANCHOR FLOOR: never drop the most recent N user messages.
  *  2. TOOL-PAIR: never split an assistant(toolCall) from its following
  *     tool-result message — an orphaned `tool` role with no preceding
- *     assistant tool call causes a 400 on the OpenAI-compat path.
+ *     assistant tool call causes a 400 on the OpenAI-compat path. The pair
+ *     invariant outranks the anchor floor: on conflict we drop LESS (lower the
+ *     drop end), never cross a pair.
  *
  * The engine reasons over EngineMessage; the pi adapter maps role "tool" +
- * toolName to the tool-result shape.
+ * toolName to the tool-result shape. EngineMessage carries no tool-call id, so
+ * ownership is positional: a tool result's owner is its nearest preceding
+ * assistant tool-call (the last assistant message with a `toolName` before it).
+ * A preserved tool result is orphaned by a cut when its owner is dropped; the
+ * guard rejects any cut that drops an owner while preserving its result, for
+ * ARBITRARY interleavings (custom/non-tool messages between call and result,
+ * consecutive results sharing one call, a cut landing directly on a call whose
+ * results follow).
  */
 
 import type { EngineMessage } from "./types.js";
@@ -23,16 +32,53 @@ function hasToolUse(m: EngineMessage): boolean {
   return Boolean(m.toolName) && m.role !== "tool";
 }
 
+/**
+ * Is the drop boundary at `dropEnd` pair-safe? The preserved run is
+ * [dropEnd, messages.length). The cut is pair-safe iff NO preserved tool result
+ * is orphaned: for every tool result at index >= dropEnd, its nearest preceding
+ * assistant tool-call must EXIST and be PRESERVED (index >= dropEnd). A tool
+ * result with no preceding assistant tool-call is already orphaned in the
+ * input — we treat that as unsafe too, so the guard never endorses shipping an
+ * orphaned result to the provider.
+ *
+ * O(messages.length) single forward pass; early-exits on the first orphan. The
+ * owner of each result is the most recent `hasToolUse` message seen so far
+ * (tracked across the whole stream, including dropped messages, because a
+ * dropped assistant tool-call is exactly the owner we must reject).
+ */
+export function isPairSafe(messages: EngineMessage[], dropEnd: number): boolean {
+  if (dropEnd <= 0 || dropEnd >= messages.length) return true;
+  let lastToolCall = -1;
+  for (let i = 0; i < messages.length; i++) {
+    if (hasToolUse(messages[i])) lastToolCall = i;
+    if (i >= dropEnd && isToolResult(messages[i])) {
+      if (lastToolCall === -1) return false; // no preceding call → orphaned
+      if (lastToolCall < dropEnd) return false; // owner dropped → orphaned
+    }
+  }
+  return true;
+}
+
 /**
  * Compute the safe drop range [dropStart, dropEnd) within `messages`.
- * `keepFrom` is the caller's desired first-preserved index. We then:
- *  1. Walk it back (lower dropEnd = keep more) so the first preserved message
- *     is never an orphaned tool result (tool-pair invariant).
- *  2. Raise it (lower dropEnd) to the anchor floor so the last N user messages
- *     are never dropped, when enough user messages exist.
  *
- * dropEnd is the first index KEPT. Returns [dropStart, dropEnd]; empty range
- * if nothing should be dropped.
+ * Contract:
+ *  - `keepFrom` is the caller's desired first-preserved index (drop [0, keepFrom)).
+ *  - `dropEnd` is the first index KEPT; we may LOWER it (keep more) to satisfy the
+ *    guards, never raise it above keepFrom.
+ *  - The anchor floor (PREVENT-PI-001) caps dropEnd at the index of the
+ *    Nth-from-last user message so the last N user messages are never dropped.
+ *  - The tool-pair invariant (PREVENT-PI-002) rejects any dropEnd that orphans a
+ *    preserved tool result; on conflict with the anchor floor the pair rule wins
+ *    (we drop less, never cross a pair).
+ *  - We return the LARGEST pair-safe dropEnd <= min(keepFrom, anchorStart) so the
+ *    caller drops as much as is safe. When no pair-safe positive cut exists at
+ *    or below keepFrom, we return [0, 0] (no-op) — the pair rule outranks
+ *    dropping. dropStart is always 0 today (we drop a prefix); reserved for
+ *    future two-sided trimming.
+ *
+ * Returns [0, 0] (empty range, drop nothing) when keepFrom is out of range or no
+ * pair-safe positive cut exists.
  */
 export function computeDropRange(
   messages: EngineMessage[],
@@ -44,48 +90,38 @@ export function computeDropRange(
   const userIndexes: number[] = [];
   messages.forEach((m, i) => { if (m.role === "user") userIndexes.push(i); });
   const anchorActive = anchorUserMessages > 0 && userIndexes.length >= anchorUserMessages;
-  const anchorStart = anchorActive ? userIndexes[userIndexes.length - anchorUserMessages] : 0;
-  const floor = anchorActive ? anchorStart : 0;
+  const anchorStart = anchorActive ? userIndexes[userIndexes.length - anchorUserMessages] : keepFrom;
+  // Upper bound on dropEnd: never keep less than the caller asked (dropEnd <= keepFrom)
+  // and never drop a must-keep user message (dropEnd <= anchorStart).
+  const upperBound = Math.min(keepFrom, anchorActive ? anchorStart : keepFrom);
 
-  // Walk back for the tool-pair invariant (keep more when needed).
-  let k = keepFrom;
-  while (k > floor) {
-    const firstPreserved = messages[k];
-    if (!firstPreserved || !isToolResult(firstPreserved)) break;
-    const preceding = messages[k - 1];
-    if (preceding && hasToolUse(preceding)) {
-      k -= 1; // pair intact across boundary — include the assistant turn
-      break;
-    }
-    k -= 1;
+  // Walk down from the upper bound to find the largest pair-safe cut. dropEnd=0
+  // (drop nothing) is always pair-safe; the loop finds the largest positive cut,
+  // and falls back to [0, 0] when none exists — the pair rule outranks dropping.
+  for (let dropEnd = upperBound; dropEnd > 0; dropEnd--) {
+    if (isPairSafe(messages, dropEnd)) return [0, dropEnd];
   }
-  if (k < floor) k = floor;
-
-  // Anchor floor: never drop a must-keep user message. Raise dropEnd so we keep
-  // from anchorStart onward when the walk didn't already.
-  if (anchorActive && k > anchorStart) k = anchorStart;
-
-  if (k <= 0) return [0, 0];
-  return [0, k];
+  return [0, 0];
 }
 
 /**
  * Validate that the intended split at `keepFrom` (drop [0, keepFrom), keep the
- * rest) does not start the preserved run on an orphaned tool result. Checks
- * messages[keepFrom] against messages[keepFrom-1] directly — independent of the
- * walk-back that computeDropRange may apply.
+ * rest) does not orphan any preserved tool result. Checks the FULL preserved
+ * run, not just the first message, so it holds for arbitrary interleavings
+ * (custom messages between call and result, consecutive shared-call results, a
+ * cut landing on a call whose results follow). Used on the every-LLM-call
+ * live-trim hot path (extensions/mega-trim.ts) and by dropCompactedRange
+ * (src/adapt.ts).
  */
 export function isBoundarySafe(messages: EngineMessage[], keepFrom: number): boolean {
-  if (keepFrom <= 0 || keepFrom >= messages.length) return true;
-  const firstPreserved = messages[keepFrom];
-  if (!isToolResult(firstPreserved)) return true;
-  const preceding = messages[keepFrom - 1];
-  return Boolean(preceding && hasToolUse(preceding));
+  return isPairSafe(messages, keepFrom);
 }
 
 /**
  * Drop everything before the safe keep-index, honoring both guards, returning
- * the filtered message list.
+ * the filtered message list. Returns the original array reference (unchanged)
+ * when the safe range is empty so callers can short-circuit on reference
+ * equality.
  */
 export function dropBefore(messages: EngineMessage[], keepFrom: number, anchorUserMessages: number): EngineMessage[] {
   const [dropStart, dropEnd] = computeDropRange(messages, keepFrom, anchorUserMessages);

package/src/canary.ts

@@ -8,6 +8,16 @@
  * The controller owns a MUTABLE working copy of the dedup config; callers read
  * `controller.config` after each step. Tiers disabled via MARK_ONLY degrade
  * gracefully rather than fully off.
+ *
+ * Persistence design: disabled state is IN-MEMORY ONLY by design. The dedup
+ * config loads from MEGACOMPACT_* env vars (config/dedup.ts) with no durable
+ * save mechanism. `setEnabled` DOES mutate `this.config.L1_ENABLED` etc. so
+ * callers reading `controller.config` see the disabled state for the current
+ * session. On restart, env defaults re-apply and the canary sequences again
+ * from L0 — this is intentional: a tier disabled due to a cold cache or
+ * transient load gets a fresh evaluation each run rather than being locked
+ * out forever. To permanently disable a tier, set the corresponding
+ * MEGACOMPACT_*_ENABLED env var to false.
  */
 
 import type { DedupConfigShape, DedupTier } from "./config/dedup.js";