pi-mega-compact 0.20.83 → 0.20.85

package/dist/extensions/dashboard-server/routes-rag-settings-helpers.js

@@ -126,6 +126,12 @@ export const SETTINGS = [
             num("MEGACOMPACT_EMBEDDING_CHARS_PER_TOKEN", "Embedding Chars per Token", "Estimated characters per token used for embedder chunking size", 4, 1, 32),
         ],
     },
+    {
+        name: "Compaction",
+        settings: [
+            num("MEGACOMPACT_THRESHOLD_PCT", "Compaction Threshold", "Fraction of the actual model context window at which compaction fires — 0.80 fires at 80% used (leaves 20% free). Applies to any model size; a per-model Model Thresholds row overrides it", 0.8, 0.1, 0.95),
+        ],
+    },
     VECTOR_CORTEX_SETTINGS,
     {
         name: "Cost API",

package/dist/extensions/mega-config.js

@@ -66,11 +66,30 @@ function resolveThreshold() {
     }
     const raw = (process.env.MEGACOMPACT_TIER ?? "low").toLowerCase();
     const tier = (raw in COMPACT_TIERS ? raw : "low");
-    const tierPct = TIER_PCT[tier];
+    let tierPct = TIER_PCT[tier];
+    // 3WF-2 threshold invariant: under the umbrella, when no named tier is set
+    // the fire point is the configurable % of the ACTUAL model window (default
+    // 0.80 — "20% free remaining"). Tiered (named preset) keeps its preset pct;
+    // both paths still compute the legacy 200k boot fallback below as a display
+    // placeholder + the custom-tier absolute companion. Umbrella OFF stays
+    // byte-identical to v0.20.83 (default tier=low 0.5).
+    const umbrella = envBool("MEGACOMPACT_THREE_WAY_FAILBACK", true);
+    if (umbrella && !(process.env.MEGACOMPACT_TIER && process.env.MEGACOMPACT_TIER !== "")) {
+        tierPct = clamp(envFlag("MEGACOMPACT_THRESHOLD_PCT", 0.8), 0.1, 0.95);
+    }
     // Boot fallback: sane gate before the first context event provides a window.
+    // (NO hardcoded window in the firing path — effectiveThresholdImpl defers
+    // when window unknown; this remains only a display placeholder + custom
+    // companion under the umbrella.)
     const thresholdTokens = Math.round(tierPct * 200_000);
     return { tier, tierPct, thresholdTokens };
 }
+/** Clamp `n` into [lo, hi]; non-finite → fallback. */
+function clamp(n, lo, hi) {
+    if (!Number.isFinite(n))
+        return lo;
+    return Math.min(hi, Math.max(lo, n));
+}
 /**
  * Pure helper: the real compaction fire point, given the model context window.
  *
@@ -167,6 +186,9 @@ export function loadConfig() {
         recallMaxTokens: envFlag("MEGACOMPACT_RECALL_MAX_TOKENS", 1500),
         windowDedupe: envBool("MEGACOMPACT_WINDOW_DEDUPE", true),
         recallTailInject: envBool("MEGACOMPACT_RECALL_TAIL_INJECT", true),
+        // 3WF-1: TriggerGuard — guarantee a staged recall block on every context
+        // event even when session_start never fires. Default ON; OFF = byte-identical.
+        threeWayFailback: envBool("MEGACOMPACT_THREE_WAY_FAILBACK", true),
         // PC-A: positive sprint flag, default ON. =0 byte-identical to the
         // pre-change OFF state (single gate lives at the call site in tailResult.ts).
         messageSeparation: envBool("MEGACOMPACT_MESSAGE_SEPARATION", true),

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

@@ -40,11 +40,23 @@ export function evaluateGate(runtime, config, opts) {
     }
     else {
         // custom tier OR tiered-but-pct-unavailable → token gate (S27 fallback).
-        if (currentTokens < runtime.effectiveThreshold) {
+        // 3WF-2: under the umbrella, when the window is known AND the config is
+        // tiered, honor the per-model Dashboard override exactly like the percent
+        // branch (firePointPct % of the actual window) instead of the bare boot
+        // fallback. custom / window-unknown / umbrella-OFF keep the bare
+        // runtime.effectiveThreshold (window-unknown defers via +Infinity from
+        // effectiveThresholdImpl; custom is the explicit absolute).
+        let gateThreshold = runtime.effectiveThreshold;
+        if (config.threeWayFailback &&
+            config.tierPct != null &&
+            runtime.lastCtxWindow > 0) {
+            gateThreshold = Math.round((perModelThreshold.firePointPct / 100) * runtime.lastCtxWindow);
+        }
+        if (currentTokens < gateThreshold) {
             runtime.diagCtxFastGate++;
             return { kind: "return", view: tailResult() ?? undefined };
         }
-        const check = autoCompactCheck(currentTokens, runtime.effectiveThreshold); // SERVER-STYLE CONFIRM (local)
+        const check = autoCompactCheck(currentTokens, gateThreshold); // SERVER-STYLE CONFIRM (local)
         if (!check.shouldCompact) {
             runtime.diagCtxNoCompact++;
             return { kind: "return", view: tailResult() ?? undefined };

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

@@ -0,0 +1,86 @@
+import { normalizeSessionId } from "../../../src/store.js";
+import { recall } from "../../../src/engine.js";
+import { formatRecallBlock } from "../../../src/recall.js";
+import { vectorStats, vectorList } from "../../../src/vectorStore.js";
+import { recentUserQuery } from "../../mega-runtime.js";
+/** One-shot completion marker per MegaRuntime (dies with the runtime). */
+const guardDone = new WeakMap();
+/**
+ * Run the TriggerGuard for this context event. Best-effort: never throws; any
+ * failure degrades to the pre-sprint path (no staged block).
+ */
+export function runTriggerGuard(runtime, config, ctx) {
+    try {
+        // Flag OFF => byte-identical pre-sprint behavior (no touch, no telemetry).
+        if (!config.threeWayFailback)
+            return;
+        // session_start already staged a block => the normal path wins, no-op.
+        if (runtime.pendingRecallBlock != null)
+            return;
+        // One-shot: we've already decided for this runtime.
+        if (guardDone.has(runtime))
+            return;
+        // recentUserQuery only reads sessionManager.getEntries(); the structural
+        // GuardCtx satisfies it at runtime (cast to the full type it expects).
+        const query = recentUserQuery(ctx);
+        if (!query) {
+            guardDone.set(runtime, { done: true });
+            return;
+        }
+        const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
+        const stats = vectorStats(runtime.store, sid);
+        // Empty store => genuinely new session; not a recall failure. Mark done so
+        // we don't re-check forever, stage nothing (no crash, no floor).
+        if (stats.checkpointCount <= 0) {
+            guardDone.set(runtime, { done: true });
+            return;
+        }
+        // Read-only recall: search + rank only; skipInjected:false means we keep
+        // hits already injected this session, but we never call vectorMarkInjected
+        // ourselves (A1) — formatRecallBlock does the same as session_start uses.
+        const hits = recall({ sessionId: sid, query, limit: config.autoInlineK, skipInjected: false }, runtime.store).hits;
+        if (hits.length > 0) {
+            runtime.pendingRecallBlock = formatRecallBlock(hits);
+            guardDone.set(runtime, { done: true });
+            runtime.appendEvent("three_way_guard_fired", {
+                source: "recall",
+                hitCount: hits.length,
+                topScore: hits[0]?.score ?? null,
+            });
+            return;
+        }
+        // Store HAS checkpoints but recall found nothing relevant: stage a
+        // provenance floor built from the newest checkpoint summary rather than
+        // silence (the incident's "recall silently never ran" shape).
+        const floor = buildFloorBlock(runtime, sid);
+        runtime.pendingRecallBlock = floor;
+        guardDone.set(runtime, { done: true });
+        runtime.appendEvent("three_way_floor_used", { basis: "lastCheckpoint" });
+    }
+    catch {
+        /* never throws; best-effort guard */
+    }
+}
+/** Build the provenance floor string from the session's newest checkpoint. */
+function buildFloorBlock(runtime, sid) {
+    try {
+        const cps = vectorList(runtime.store, sid);
+        let newest = cps[0];
+        for (const cp of cps) {
+            if (!newest || (cp.timestamp ?? 0) > (newest.timestamp ?? 0))
+                newest = cp;
+        }
+        const summary = newest?.summary?.trim();
+        if (summary) {
+            return ("The following compacted context is the most recent checkpoint from " +
+                "this session (recall found no query-relevant match):\n\n" + summary);
+        }
+        return ("This session has compacted context but recall could not surface a " +
+            "checkpoint relevant to the current request; the most recent checkpoint " +
+            "summary is unavailable.");
+    }
+    catch {
+        return ("This session has compacted context but recall could not surface a " +
+            "checkpoint relevant to the current request.");
+    }
+}

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

@@ -1,6 +1,7 @@
 import { estimateSessionTokens } from "../../src/tokens.js";
 import { piCompactWouldNoop } from "../mega-pipeline.js";
 import { buildTailResult } from "./context-handler/tailResult.js";
+import { runTriggerGuard } from "./context-handler/triggerGuard.js";
 import { persistEpochAndMaintain } from "./context-handler/afterCompact.js";
 import { appendMirrorAndLedger } from "./context-handler/dbMirrorAppend.js";
 import { evaluateGate } from "./context-handler/gateCheck.js";
@@ -26,6 +27,17 @@ export function registerContextHandler(pi, runtime, config) {
         const usage = ctx.getContextUsage();
         const pct = usage?.percent;
         const messages = event.messages;
+        // 3WF-1 TriggerGuard: guarantee a staged recall block on this event even
+        // when session_start never fired. One-shot per session; a block already
+        // staged by session_start takes precedence (no-op). Run BEFORE building the
+        // tail factory so a freshly staged block is composed into THIS event's view.
+        // Best-effort — a failure falls through to the pre-sprint path.
+        try {
+            runTriggerGuard(runtime, config, ctx);
+        }
+        catch {
+            /* non-fatal */
+        }
         // S53: helper to inject the staged recall/memory block as a user-role
         // tail message at any view-return point. Returns undefined when nothing
         // is staged (or the flag is OFF) so the caller falls through to its

package/dist/extensions/mega-runtime/pressure-getters.js

@@ -51,6 +51,18 @@ export function pressureImpl(self) {
  * always below pi's native auto-compaction (~80% of window).
  */
 export function effectiveThresholdImpl(self) {
+    // 3WF-2 threshold invariant: under the umbrella, a tiered config with an
+    // UNKNOWN window (lastCtxWindow <= 0) DEFERS — auto-compaction must never
+    // substitute a guessed window. Returning +Infinity keeps every downstream
+    // `tokens >= threshold` comparison false (gateCheck token path,
+    // agent_end durable trigger, live-trim re-compact), so no compaction fires
+    // until the provider reports a real window. custom (tierPct null) and
+    // umbrella-OFF fall through to the legacy helper (byte-identical).
+    if (self.config.threeWayFailback &&
+        self.config.tierPct != null &&
+        self.lastCtxWindow <= 0) {
+        return Number.POSITIVE_INFINITY;
+    }
     return effectiveThresholdTokens({
         tierPct: self.config.tierPct,
         fallbackThreshold: self.config.thresholdTokens,

package/dist/src/failback/types.js

@@ -0,0 +1,11 @@
+/**
+ * src/failback/types.ts — 3WF Three-Way Failback contract types (contract-first).
+ *
+ * Pure, pi-agnostic interfaces describing the staged-recall guarantee chain:
+ * every session should have a staged recall block even when `session_start`
+ * never fires. 3WF-1 (TriggerGuard) is the first consumer; 3WF-2/3/4 extend
+ * these shapes for the compaction ladder, the 3-source recall vote, and
+ * InjectionConfirm. No pi runtime imports, no store mutation — these are the
+ * shape contract only.
+ */
+export {};

package/extensions/dashboard-server/routes-rag-settings-helpers.ts

@@ -274,6 +274,19 @@ export const SETTINGS: ReadonlyArray<SettingGroup> = [
 			num("MEGACOMPACT_EMBEDDING_CHARS_PER_TOKEN", "Embedding Chars per Token", "Estimated characters per token used for embedder chunking size", 4, 1, 32),
 		],
 	},
+	{
+		name: "Compaction",
+		settings: [
+			num(
+				"MEGACOMPACT_THRESHOLD_PCT",
+				"Compaction Threshold",
+				"Fraction of the actual model context window at which compaction fires — 0.80 fires at 80% used (leaves 20% free). Applies to any model size; a per-model Model Thresholds row overrides it",
+				0.8,
+				0.1,
+				0.95,
+			),
+		],
+	},
 	VECTOR_CORTEX_SETTINGS,
 	{
 		name: "Cost API",

package/extensions/mega-config-types.ts

@@ -136,6 +136,10 @@ export interface MegaConfig {
 	 *  the tail of the view when auto is OFF AND no trim action is needed. Default ON
 	 *  (true). When false, restores the pre-sprint systemPrompt prepend behavior. */
 	recallTailInject: boolean;
+	/** 3WF-1: TriggerGuard — re-stage a recall block at the context event seam when
+	 *  session_start never fired, so every session has a staged block (recall hits,
+	 *  else a provenance floor). Default ON; OFF = byte-identical pre-sprint. */
+	threeWayFailback: boolean;
 	/** A1 PLAN_V2 Phase 2: Message Separation — isolate user/assistant turns
 	 *  from volatile tool results so the prompt-cache prefix stays stable.
 	 *  PC-A: positive sprint flag, now default ON; flag-OFF (=0) is byte-identical

package/extensions/mega-config.ts

@@ -78,12 +78,31 @@ function resolveThreshold(): {
 	}
 	const raw = (process.env.MEGACOMPACT_TIER ?? "low").toLowerCase();
 	const tier = (raw in COMPACT_TIERS ? raw : "low") as CompactTier;
-	const tierPct = TIER_PCT[tier];
+	let tierPct = TIER_PCT[tier];
+	// 3WF-2 threshold invariant: under the umbrella, when no named tier is set
+	// the fire point is the configurable % of the ACTUAL model window (default
+	// 0.80 — "20% free remaining"). Tiered (named preset) keeps its preset pct;
+	// both paths still compute the legacy 200k boot fallback below as a display
+	// placeholder + the custom-tier absolute companion. Umbrella OFF stays
+	// byte-identical to v0.20.83 (default tier=low 0.5).
+	const umbrella = envBool("MEGACOMPACT_THREE_WAY_FAILBACK", true);
+	if (umbrella && !(process.env.MEGACOMPACT_TIER && process.env.MEGACOMPACT_TIER !== "")) {
+		tierPct = clamp(envFlag("MEGACOMPACT_THRESHOLD_PCT", 0.8), 0.1, 0.95);
+	}
 	// Boot fallback: sane gate before the first context event provides a window.
+	// (NO hardcoded window in the firing path — effectiveThresholdImpl defers
+	// when window unknown; this remains only a display placeholder + custom
+	// companion under the umbrella.)
 	const thresholdTokens = Math.round(tierPct * 200_000);
 	return { tier, tierPct, thresholdTokens };
 }
 
+/** Clamp `n` into [lo, hi]; non-finite → fallback. */
+function clamp(n: number, lo: number, hi: number): number {
+	if (!Number.isFinite(n)) return lo;
+	return Math.min(hi, Math.max(lo, n));
+}
+
 /**
  * Pure helper: the real compaction fire point, given the model context window.
  *
@@ -203,6 +222,9 @@ export function loadConfig(): MegaConfig {
 		recallMaxTokens: envFlag("MEGACOMPACT_RECALL_MAX_TOKENS", 1500),
 		windowDedupe: envBool("MEGACOMPACT_WINDOW_DEDUPE", true),
 		recallTailInject: envBool("MEGACOMPACT_RECALL_TAIL_INJECT", true),
+		// 3WF-1: TriggerGuard — guarantee a staged recall block on every context
+		// event even when session_start never fires. Default ON; OFF = byte-identical.
+		threeWayFailback: envBool("MEGACOMPACT_THREE_WAY_FAILBACK", true),
 		// PC-A: positive sprint flag, default ON. =0 byte-identical to the
 		// pre-change OFF state (single gate lives at the call site in tailResult.ts).
 		messageSeparation: envBool("MEGACOMPACT_MESSAGE_SEPARATION", true),

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

@@ -82,11 +82,27 @@ export function evaluateGate(
 		gatePassed = pct / 100 >= firePct;
 	} else {
 		// custom tier OR tiered-but-pct-unavailable → token gate (S27 fallback).
-		if (currentTokens < runtime.effectiveThreshold) {
+		// 3WF-2: under the umbrella, when the window is known AND the config is
+		// tiered, honor the per-model Dashboard override exactly like the percent
+		// branch (firePointPct % of the actual window) instead of the bare boot
+		// fallback. custom / window-unknown / umbrella-OFF keep the bare
+		// runtime.effectiveThreshold (window-unknown defers via +Infinity from
+		// effectiveThresholdImpl; custom is the explicit absolute).
+		let gateThreshold = runtime.effectiveThreshold;
+		if (
+			config.threeWayFailback &&
+			config.tierPct != null &&
+			runtime.lastCtxWindow > 0
+		) {
+			gateThreshold = Math.round(
+				(perModelThreshold.firePointPct / 100) * runtime.lastCtxWindow,
+			);
+		}
+		if (currentTokens < gateThreshold) {
 			runtime.diagCtxFastGate++;
 			return { kind: "return", view: tailResult() ?? undefined };
 		}
-		const check = autoCompactCheck(currentTokens, runtime.effectiveThreshold); // SERVER-STYLE CONFIRM (local)
+		const check = autoCompactCheck(currentTokens, gateThreshold); // SERVER-STYLE CONFIRM (local)
 		if (!check.shouldCompact) {
 			runtime.diagCtxNoCompact++;
 			return { kind: "return", view: tailResult() ?? undefined };

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

@@ -0,0 +1,137 @@
+/**
+ * extensions/mega-events/context-handler/triggerGuard.ts — 3WF-1 TriggerGuard.
+ *
+ * Production-incident fix: `session_start` can silently never fire (pi host
+ * behavior), so the only recall staging point (session-handlers.ts) is skipped
+ * and a session replays with NO recall block and NO telemetry. TriggerGuard
+ * re-stages at the `context` event seam — the one place that ALWAYS runs and
+ * where the staged block is composed into the model view on this same event.
+ *
+ * Stack position (context-handler.ts): run DIRECTLY BEFORE `buildTailResult` is
+ * built, so a freshly staged block is picked up by the existing tail machinery
+ * (recall-tail.ts) with zero changes to it.
+ *
+ * Contract:
+ *  - one-shot per MegaRuntime (WeakMap) — recall does NOT re-run on every event.
+ *  - if runtime.pendingRecallBlock != null already, no-op (session_start won).
+ *  - read-only recall via engine.recall -> formatRecallBlock; no vectorMarkInjected,
+ *    no S43 telemetry, no turn writes (this is a guard, not an inline).
+ *  - an empty store (checkpointCount == 0) is a genuinely new session: no crash,
+ *    no floor staged, just marked done.
+ *  - a store WITH checkpoints whose recall returns nothing: stage the provenance
+ *    floor (newest checkpoint summary) instead of silence.
+ *  - never throws (whole body guarded), non-fatal, PREVENT-PI-003 (block is plain
+ *    text; role decided downstream by withRecallTail as user).
+ */
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { MegaRuntime } from "../../mega-runtime.js";
+import type { MegaConfig } from "../../mega-config.js";
+import { normalizeSessionId } from "../../../src/store.js";
+import { recall } from "../../../src/engine.js";
+import { formatRecallBlock } from "../../../src/recall.js";
+import { vectorStats, vectorList } from "../../../src/vectorStore.js";
+import { recentUserQuery } from "../../mega-runtime.js";
+
+/** One-shot completion marker per MegaRuntime (dies with the runtime). */
+const guardDone = new WeakMap<MegaRuntime, { done: true }>();
+
+/** The minimal ctx surface the guard reads (query + session id). Accepted instead
+ *  of the full ExtensionContext so tests can pass a thin stub without a full
+ *  pi ctx; structurally satisfied by the real ExtensionContext. */
+interface GuardCtx {
+	sessionManager: { getSessionId(): string };
+}
+
+
+/**
+ * Run the TriggerGuard for this context event. Best-effort: never throws; any
+ * failure degrades to the pre-sprint path (no staged block).
+ */
+export function runTriggerGuard(
+	runtime: MegaRuntime,
+	config: MegaConfig,
+	ctx: GuardCtx,
+): void {
+	try {
+		// Flag OFF => byte-identical pre-sprint behavior (no touch, no telemetry).
+		if (!config.threeWayFailback) return;
+		// session_start already staged a block => the normal path wins, no-op.
+		if (runtime.pendingRecallBlock != null) return;
+		// One-shot: we've already decided for this runtime.
+		if (guardDone.has(runtime)) return;
+
+		// recentUserQuery only reads sessionManager.getEntries(); the structural
+		// GuardCtx satisfies it at runtime (cast to the full type it expects).
+		const query = recentUserQuery(ctx as unknown as ExtensionContext);
+		if (!query) {
+			guardDone.set(runtime, { done: true });
+			return;
+		}
+
+		const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
+		const stats = vectorStats(runtime.store, sid);
+		// Empty store => genuinely new session; not a recall failure. Mark done so
+		// we don't re-check forever, stage nothing (no crash, no floor).
+		if (stats.checkpointCount <= 0) {
+			guardDone.set(runtime, { done: true });
+			return;
+		}
+
+		// Read-only recall: search + rank only; skipInjected:false means we keep
+		// hits already injected this session, but we never call vectorMarkInjected
+		// ourselves (A1) — formatRecallBlock does the same as session_start uses.
+		const hits = recall(
+			{ sessionId: sid, query, limit: config.autoInlineK, skipInjected: false },
+			runtime.store,
+		).hits;
+
+		if (hits.length > 0) {
+			runtime.pendingRecallBlock = formatRecallBlock(hits);
+			guardDone.set(runtime, { done: true });
+			runtime.appendEvent("three_way_guard_fired", {
+				source: "recall",
+				hitCount: hits.length,
+				topScore: hits[0]?.score ?? null,
+			});
+			return;
+		}
+
+		// Store HAS checkpoints but recall found nothing relevant: stage a
+		// provenance floor built from the newest checkpoint summary rather than
+		// silence (the incident's "recall silently never ran" shape).
+		const floor = buildFloorBlock(runtime, sid);
+		runtime.pendingRecallBlock = floor;
+		guardDone.set(runtime, { done: true });
+		runtime.appendEvent("three_way_floor_used", { basis: "lastCheckpoint" });
+	} catch {
+		/* never throws; best-effort guard */
+	}
+}
+
+/** Build the provenance floor string from the session's newest checkpoint. */
+function buildFloorBlock(runtime: MegaRuntime, sid: string): string {
+	try {
+		const cps = vectorList(runtime.store, sid);
+		let newest = cps[0];
+		for (const cp of cps) {
+			if (!newest || (cp.timestamp ?? 0) > (newest.timestamp ?? 0)) newest = cp;
+		}
+		const summary = newest?.summary?.trim();
+		if (summary) {
+			return (
+				"The following compacted context is the most recent checkpoint from " +
+				"this session (recall found no query-relevant match):\n\n" + summary
+			);
+		}
+		return (
+			"This session has compacted context but recall could not surface a " +
+			"checkpoint relevant to the current request; the most recent checkpoint " +
+			"summary is unavailable."
+		);
+	} catch {
+		return (
+			"This session has compacted context but recall could not surface a " +
+			"checkpoint relevant to the current request."
+		);
+	}
+}

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

@@ -23,6 +23,7 @@ import type { MegaRuntime } from "../mega-runtime.js";
 import { piCompactWouldNoop } from "../mega-pipeline.js";
 import type { MegaConfig } from "../mega-config.js";
 import { buildTailResult } from "./context-handler/tailResult.js";
+import { runTriggerGuard } from "./context-handler/triggerGuard.js";
 import { persistEpochAndMaintain } from "./context-handler/afterCompact.js";
 import { appendMirrorAndLedger } from "./context-handler/dbMirrorAppend.js";
 import { evaluateGate } from "./context-handler/gateCheck.js";
@@ -53,6 +54,16 @@ export function registerContextHandler(
 		const usage = ctx.getContextUsage();
 		const pct = usage?.percent;
 		const messages = event.messages;
+		// 3WF-1 TriggerGuard: guarantee a staged recall block on this event even
+		// when session_start never fired. One-shot per session; a block already
+		// staged by session_start takes precedence (no-op). Run BEFORE building the
+		// tail factory so a freshly staged block is composed into THIS event's view.
+		// Best-effort — a failure falls through to the pre-sprint path.
+		try {
+			runTriggerGuard(runtime, config, ctx);
+		} catch {
+			/* non-fatal */
+		}
 		// S53: helper to inject the staged recall/memory block as a user-role
 		// tail message at any view-return point. Returns undefined when nothing
 		// is staged (or the flag is OFF) so the caller falls through to its

package/extensions/mega-runtime/pressure-getters.ts

@@ -81,6 +81,20 @@ export function pressureImpl(self: PressureContext): number {
  * always below pi's native auto-compaction (~80% of window).
  */
 export function effectiveThresholdImpl(self: PressureContext): number {
+	// 3WF-2 threshold invariant: under the umbrella, a tiered config with an
+	// UNKNOWN window (lastCtxWindow <= 0) DEFERS — auto-compaction must never
+	// substitute a guessed window. Returning +Infinity keeps every downstream
+	// `tokens >= threshold` comparison false (gateCheck token path,
+	// agent_end durable trigger, live-trim re-compact), so no compaction fires
+	// until the provider reports a real window. custom (tierPct null) and
+	// umbrella-OFF fall through to the legacy helper (byte-identical).
+	if (
+		self.config.threeWayFailback &&
+		self.config.tierPct != null &&
+		self.lastCtxWindow <= 0
+	) {
+		return Number.POSITIVE_INFINITY;
+	}
 	return effectiveThresholdTokens({
 		tierPct: self.config.tierPct,
 		fallbackThreshold: self.config.thresholdTokens,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.83",
+  "version": "0.20.85",
   "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/failback/types.ts

@@ -0,0 +1,46 @@
+/**
+ * src/failback/types.ts — 3WF Three-Way Failback contract types (contract-first).
+ *
+ * Pure, pi-agnostic interfaces describing the staged-recall guarantee chain:
+ * every session should have a staged recall block even when `session_start`
+ * never fires. 3WF-1 (TriggerGuard) is the first consumer; 3WF-2/3/4 extend
+ * these shapes for the compaction ladder, the 3-source recall vote, and
+ * InjectionConfirm. No pi runtime imports, no store mutation — these are the
+ * shape contract only.
+ */
+
+/** One-shot guard state for a session (observable result of a TriggerGuard run). */
+export interface TriggerGuardState {
+	/** True once a recall/floor attempt has run for this session. */
+	recallRan: boolean;
+	/** The block staged into runtime.pendingRecallBlock (null when nothing staged). */
+	stagedBlock: string | null;
+	/** True when the provenance floor (not a recall hit) was staged. */
+	usedFloor: boolean;
+}
+
+/** A provenance floor string built from the newest checkpoint / session basis. */
+export interface FloorBlock {
+	/** The model-visible floor text. */
+	text: string;
+	/** Why this floor was produced. */
+	basis: "lastCheckpoint" | "sessionProvenance" | "none";
+}
+
+/** Result of a single TriggerGuard evaluation (for tests + telemetry). */
+export interface GuardRunResult {
+	/** How the block (or non-block) was produced. */
+	source: "already-staged" | "recall" | "floor" | "none";
+	/** The staged block text; null when nothing was staged. */
+	block: string | null;
+}
+
+/** Options the TriggerGuard needs to run a staged recall. */
+export interface GuardOpts {
+	/** The latest user message used as the recall query; empty => 'none'. */
+	query: string | null;
+	/** Normalized session id. */
+	sessionId: string;
+	/** Max hits to recall (mirrors autoInlineK). */
+	limit: number;
+}