pi-mega-compact 0.21.7 → 0.21.9

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

@@ -9,6 +9,7 @@
  */
 import type { SettingSpec, SettingGroup } from "./routes-rag-settings-types.js";
 import { VECTOR_CORTEX_SETTINGS } from "./routes-rag-settings-vector-cortex.js";
+import { COMPACTION_SETTINGS } from "./routes-rag-settings-compaction.js";
 
 export type { SettingSpec } from "./routes-rag-settings-types.js";
 
@@ -275,33 +276,10 @@ 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,
-			),
-			num(
-				"MEGACOMPACT_THRASH_REARM_PCT",
-				"Thrash Re-arm %",
-				"After an ineffective compaction (live window did not shrink), refuse to re-fire until the live window grows by this fraction of the effective threshold. Default 0.10 (10%)",
-				0.1,
-				0.01,
-				0.5,
-			),
-			boolDirect(
-				"MEGACOMPACT_OUTPUT_ERROR_COMPACT",
-				"Output-Error Compact",
-				"When a model response is truncated mid-output (stopReason: 'length'), trip a one-shot forced compaction to free input headroom. Closes the small-context deadlock where the model truncates below the input threshold.",
-				true,
-			),
-		],
-	},
+	// v0.21.9: compaction group extracted to keep this file under the
+	// extensions/ soft limit (delegate-shell split); carries the overflow-
+	// headroom + output-reserve flags alongside the pre-existing trio.
+	COMPACTION_SETTINGS,
 	{
 		name: "Three-Way Failback",
 		settings: [

package/extensions/mega-config-types.ts

@@ -141,6 +141,31 @@ export interface MegaConfig {
 	 *  gate never fires → "compact never" → every subsequent response truncates
 	 *  too). Default ON; OFF (=0/`=false`) = byte-identical pre-H. */
 	outputErrorCompact: boolean;
+	/** v0.21.9: output-headroom gate. Fire compaction BEFORE the request
+	 *  overflows the model window — when
+	 *  `currentTokens + outputReserve + safetyMargin >= contextWindow` —
+	 *  instead of waiting for the percent/token fire point (which judges only
+	 *  INPUT and never trips on small-window models whose output reserve is a
+	 *  large fraction of the window: a 32k window with a 20k maxTokens
+	 *  overflows at ~37% INPUT). Percent-based by construction: the reserve is
+	 *  a fraction of the model's own window, so the math is identical at every
+	 *  window size (32k, 64k, 200k, 1M, 5M). Default ON; OFF (=0/`=false`)
+	 *  disables ONLY the pre-fire gate check (the gate reverts to the
+	 *  input-only pre-v0.21.9 judgment). NOTE: the shared tail-cap hardenings
+	 *  this fix introduced — pair-safe front-drop (the pre-v0.21.9 cap could
+	 *  split a toolCall/toolResult pair, PREVENT-PI-002) and the budget floor
+	 *  (the old cap silently disabled itself when the reserve exceeded the
+	 *  window) — are UNCONDITIONAL guardrail fixes and apply regardless of
+	 *  this flag. Headroom-triggered fires are EXEMPT from the ThrashGuard
+	 *  (an overflowed session is unrecoverable). */
+	overflowHeadroom: boolean;
+	/** v0.21.9: fallback output reserve as a fraction of the context window
+	 *  when the model's declared maxTokens is absent or implausible (0, or the
+	 *  models.json sentinels 1e9/1e38, or >= the window). Clamped [0.1, 0.95];
+	 *  default 0.30 (30% of the window). When maxTokens is plausible the
+	 *  declared value wins — vLLM-style backends reserve the FULL declared
+	 *  maxTokens against the context window, so the reserve must match it. */
+	outputReservePct: number;
 	/** Inline-dedupe recalled checkpoints against the live window (Fix C): drop
 	 *  a hit whose summary is ≥ dedupSim similar to a live message — "dedupe on
 	 *  inline/read" so we never re-inject context already resident. */

package/extensions/mega-config.ts

@@ -253,6 +253,18 @@ export function loadConfig(): MegaConfig {
 		// Phase H: output-error catch — trip compaction on a truncated model output
 		// (S28 stopReason==='length'). Default ON; OFF byte-identical pre-H.
 		outputErrorCompact: envBool("MEGACOMPACT_OUTPUT_ERROR_COMPACT", true),
+		// v0.21.9 OUTPUT-HEADROOM GATE: fire compaction BEFORE the request
+		// overflows the model window (input + output reserve + margin >= window),
+		// not after. Percent-based: the reserve scales with the model's own window
+		// so the math holds at every window size (32k…5M). Default ON;
+		// OFF = byte-identical pre-v0.21.9 (2026-08-19 32k incident fix).
+		overflowHeadroom: envBool("MEGACOMPACT_OVERFLOW_HEADROOM", true),
+		// v0.21.9: fallback OUTPUT reserve as a FRACTION of the context window,
+		// used when the model's declared maxTokens is absent or implausible
+		// (0 / sentinel 1e9/1e38 / >= window). Clamped [0.1, 0.95]; default 0.30.
+		// When maxTokens IS plausible the declared value wins (vLLM reserves the
+		// full maxTokens) — this fraction is only the fallback.
+		outputReservePct: clamp(envFlag("MEGACOMPACT_OUTPUT_RESERVE_PCT", 0.3), 0.1, 0.95),
 		windowDedupe: envBool("MEGACOMPACT_WINDOW_DEDUPE", true),
 		recallTailInject: envBool("MEGACOMPACT_RECALL_TAIL_INJECT", true),
 		// 3WF-1: TriggerGuard — guarantee a staged recall block on every context

package/extensions/mega-dashboard.ts

@@ -142,11 +142,14 @@ export interface DashboardSnapshot {
     outputRate: number;    // USD per output token (Model.cost)
   };
   /** v0.8.8 Perf dashboard: live diag counters (skip vs recompute vs replay)
-   *  for the Perf tab's "TUI lag proxy" cards. Optional for back-compat. */
+   *  for the Perf tab's "TUI lag proxy" cards. Optional for back-compat.
+   *  v0.21.9: headroomTrips added (output-headroom gate trips); readers that
+   *  don't know it stay backward-compatible. */
   diag?: {
     ctxFastGate: number;
     liveTrimFires: number;
     liveTrimReplays: number;
+    headroomTrips?: number;
   };
   /** S38.8: error-retry state for dashboard "retries" tile.
    *  R7 (retry redesign): sessionRetryCount / sessionMax / poisonedCount are

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

@@ -18,6 +18,7 @@ import { autoCompactCheck } from "../../../src/compact.js";
 import type { MegaRuntime } from "../../mega-runtime.js";
 import type { MegaConfig } from "../../mega-config.js";
 import { isThrashBlockedFor } from "./thrashGuard.js";
+import { resolveOutputReserve } from "./headroom.js";
 
 /** Tail-injection closure shape produced by buildTailResult (tailResult.ts). */
 export type TailResultFn = (
@@ -30,6 +31,14 @@ export type GateOutcome =
 	| {
 			kind: "proceed";
 			perModelThreshold: { safetyMarginPct: number; firePointPct: number };
+			/**
+			 * v0.21.9: true when the proceed was forced by the output-headroom
+			 * check (the request would overflow the model window before reaching
+			 * the percent/token fire point). Consumed by thrashGuardBlocks so an
+			 * overflow-bound fire is never refused by the thrash guard — an
+			 * overflowed session is unrecoverable (2026-08-19 32k incident).
+			 */
+			headroomExceeded?: boolean;
 	  };
 
 /**
@@ -55,9 +64,16 @@ export function thrashGuardBlocks(
 	runtime: MegaRuntime,
 	config: MegaConfig,
 	currentTokens: number | null | undefined,
+	headroomExceeded?: boolean,
 ): boolean {
 	if (!config.threeWayFailback) return false;
 	if (currentTokens == null) return false;
+	// v0.21.9: an overflow-bound fire (headroomExceeded) is EXEMPT from the
+	// thrash guard. The guard exists to stop wasted re-compaction when the
+	// window refuses to shrink; but an overflowed request is not "wasted work"
+	// — it is the model about to 400. Blocking that fire reproduces the
+	// 2026-08-19 32k deadlock (compact never → request > window → error loop).
+	if (headroomExceeded) return false;
 	return isThrashBlockedFor(runtime, currentTokens, runtime.currentStateDir);
 }
 
@@ -113,6 +129,57 @@ export function evaluateGate(
 		return { kind: "proceed", perModelThreshold };
 	}
 
+	// v0.21.9 OUTPUT-HEADROOM GATE (the root-cause fix for the 32k truncation
+	// loop). The percent/token fire points above judge only INPUT utilization
+	// (tier% of the window), but a request's budget is
+	//   input tokens + the model's output budget + safety margin.
+	// On a small-window model with a large maxTokens (the user's 32k/20k
+	// GLM-4.7), the request overflows at ~32% INPUT (21.4k + 20k > 32.768k) —
+	// long before any percent gate fires → provider 400 "request exceeds the
+	// available context size" every turn → the poisoned-error loop. Phase H only
+	// reacts to stopReason 'length' (mid-output truncation); a pre-output 400
+	// never arms it, so "compact never". This check fires the compaction
+	// BEFORE the overflow instead of after.
+	//
+	// PERCENT-BASED (LTS invariant — must work at every window size: 32k, 64k,
+	// 200k, 1M, 5M): the reserve is a FRACTION of the model's own window via
+	// resolveOutputReserve (plausible declared maxTokens wins, else
+	// clamp(MEGACOMPACT_OUTPUT_RESERVE_PCT, 10–95%) × window). Same math, any
+	// size. window <= 0 (unknown) ⇒ deferred (never guess a window), matching
+	// the effectiveThresholdImpl Phase-C invariant. Gated on
+	// config.overflowHeadroom (default ON; OFF = byte-identical pre-v0.21.9).
+	// Thrash-guard exemption: headroomExceeded rides along on the proceed so the
+	// handler's thrash consult never refuses an overflow-bound fire (see
+	// thrashGuardBlocks above) — an overflowed session is unrecoverable, so a
+	// wasted re-fire is always the better outcome (2026-08-19 incident).
+	if (
+		config.overflowHeadroom &&
+		runtime.lastCtxWindow > 0 &&
+		Number.isFinite(currentTokens) &&
+		currentTokens > 0
+	) {
+		const { reserveTokens, fallbackUsed } = resolveOutputReserve(
+			runtime.lastCtxWindow,
+			runtime.currentModel?.maxTokens ?? 0,
+			config.outputReservePct,
+		);
+		const headroomMargin = Math.ceil(
+			runtime.lastCtxWindow * (perModelThreshold.safetyMarginPct / 100),
+		);
+		if (currentTokens + reserveTokens + headroomMargin >= runtime.lastCtxWindow) {
+			runtime.diagCtxHeadroomTrip++;
+			runtime.logger.info("gate-headroom-trip", {
+				sessionId: runtime.rt.sessionId,
+				currentTokens,
+				ctxWindow: runtime.lastCtxWindow,
+				reserveTokens,
+				fallbackUsed,
+				marginPct: perModelThreshold.safetyMarginPct,
+			});
+			return { kind: "proceed", perModelThreshold, headroomExceeded: true };
+		}
+	}
+
 	// S29 FAST GATE: `custom` (absolute MEGACOMPACT_THRESHOLD_TOKENS,
 	// tierPct null) is an explicit opt-out of percent scaling — it keeps the
 	// token gate. When pct is unavailable (window unknown / a model that

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

@@ -0,0 +1,190 @@
+/**
+ * context-handler/headroom.ts — output-headroom reserve math + pair-safe tail cap.
+ *
+ * v0.21.9. Single source of truth for the output reserve used by BOTH the
+ * gate's pre-fire overflow check (gateCheck.ts) and the live-trim tail cap
+ * (liveTrim.ts + the D.2/D.3 replay paths). The pre-v0.21.9 code computed the
+ * reserve inline in liveTrim only and never in the gate — the two halves could
+ * drift, and the gate had no output awareness at all.
+ *
+ * PERCENT-BASED BY DESIGN (per the LTS invariant): every quantity is expressed
+ * as a fraction of the MODEL'S OWN context window, so the math is identical at
+ * any window size — 32k, 64k, 200k, 1M, 5M. The reserve is the model's
+ * declared max output tokens when plausible, else a clamped fraction of the
+ * window (MEGACOMPACT_OUTPUT_RESERVE_PCT, default 30%, clamped 10–95%).
+ *
+ * Pure functions, no runtime dependency — trivially unit-testable headlessly.
+ */
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { estimateBlockTokens, estimateMessageTokens } from "../../../src/tokens.js";
+import { messageContentText } from "./messageText.js";
+
+/**
+ * The model's declared maxTokens is only trusted as the output budget when it
+ * is plausible. models.json carries sentinel junk for some entries (1e9,
+ * 1e38, "unlimited"), and some providers report 0/absent. A declared budget
+ * above this FRACTION of the window is implausible — fall back to the
+ * configured fraction so a 200k/1e9 model doesn't compute a negative budget
+ * and silently disable the cap (the pre-v0.21.9 bug). Percent-based: holds at
+ * every window size.
+ *
+ * WHY 0.95 AND NOT LOWER: vLLM-style backends reject a request when
+ * `input + max_tokens > context window` — they reserve the model's FULL
+ * declared maxTokens, not a fraction of it. The user's own GLM-4.7 entry is
+ * 32000/20000 (62.5%); a 0.6 cutoff rejected that REAL config as
+ * "implausible" and fell back to a 30% reserve (9600) while the backend
+ * reserved the full 20000 — the gate would keep firing late and the
+ * post-compact tail would still overflow (2026-08-19 incident, attempt #6).
+ * A declared budget is plausible up to just below the WHOLE window; anything
+ * at/above the window (or the 1e9/1e38 sentinels) is junk.
+ */
+export const MAX_OUTPUT_PLAUSIBLE_FRACTION = 0.95;
+
+/** Bounds for the fallback reserve fraction (MEGACOMPACT_OUTPUT_RESERVE_PCT). */
+export const OUTPUT_RESERVE_PCT_MIN = 0.1;
+export const OUTPUT_RESERVE_PCT_MAX = 0.95;
+
+/**
+ * Resolve the output reserve (tokens) for a model window.
+ *
+ *  - window <= 0 (unknown) → { reserveTokens: 0, fallbackUsed: false }; every
+ *    consumer is guarded on window > 0 and defers (never guesses a window).
+ *  - maxTokens plausible (0 < maxTokens <= 95% of the window) → maxTokens —
+ *    vLLM-style backends reserve the FULL declared maxTokens, so the reserve
+ *    must equal it, not a fraction of it.
+ *  - otherwise → clamp(outputReservePct, 0.1, 0.95) × window.
+ *
+ * `outputReservePct` is config.outputReservePct (already env-clamped at load,
+ * re-clamped here for defense against direct callers).
+ */
+export function resolveOutputReserve(
+	ctxWindow: number,
+	maxTokens: number,
+	outputReservePct: number,
+): { reserveTokens: number; fallbackUsed: boolean } {
+	if (!Number.isFinite(ctxWindow) || ctxWindow <= 0) {
+		return { reserveTokens: 0, fallbackUsed: false };
+	}
+	const plausible =
+		Number.isFinite(maxTokens) &&
+		maxTokens > 0 &&
+		maxTokens <= ctxWindow * MAX_OUTPUT_PLAUSIBLE_FRACTION;
+	if (plausible) return { reserveTokens: Math.round(maxTokens), fallbackUsed: false };
+	const pct = Math.min(
+		OUTPUT_RESERVE_PCT_MAX,
+		Math.max(OUTPUT_RESERVE_PCT_MIN, Number.isFinite(outputReservePct) ? outputReservePct : 0.3),
+	);
+	return { reserveTokens: Math.ceil(ctxWindow * pct), fallbackUsed: true };
+}
+
+/**
+ * Pair-safe front-drop for the live-trim tail cap. Drops OLDEST messages from
+ * the front of `recentRaw` until the remaining tail fits
+ * `ctxWindow − outputReserve − safetyMargin − summaryTokens`, then advances
+ * the start index past any leading toolResult messages so the preserved tail
+ * never begins on an orphaned toolResult (PREVENT-PI-002: a toolCall/toolResult
+ * pair must not be split). Never returns an empty tail — the final message is
+ * always kept so the agent can respond.
+ *
+ * v0.21.9 hardenings over the pre-v0.21.9 inline cap in liveTrim.ts:
+ *  1. BUDGET FLOOR — when the reserve exceeds the window (implausible maxTokens
+ *     made budget <= 0) the old block silently skipped the cap entirely and an
+ *     oversized tail sailed past the window. Now the reserve is clamped (via
+ *     resolveOutputReserve) to a fraction of the window, so a floor budget
+ *     always exists. If even ONE message exceeds the floor budget we keep only
+ *     the final message — the agent's last turn is the one thing the model
+ *     must always see.
+ *  2. TOOL-PAIR SAFETY — the old front-drop could land between a toolCall and
+ *     its toolResult, splitting the pair.
+ *
+ * Pure: returns { recent, dropped } without touching the input array.
+ */
+export function applyTailCap(opts: {
+	recentRaw: readonly AgentMessage[];
+	summaryTokens: number;
+	ctxWindow: number;
+	maxOutputTokens: number;
+	outputReservePct: number;
+	safetyMarginPct: number;
+	/**
+	 * Optional token-count override for the tail messages. When present, the
+	 * token sum is counted from this array (index-aligned with `recentRaw`);
+	 * otherwise each message's tokens are estimated from its text content.
+	 */
+	messageTokens?: readonly number[];
+}): { recent: AgentMessage[]; dropped: number } {
+	const { recentRaw, summaryTokens, ctxWindow, outputReservePct } = opts;
+	if (ctxWindow <= 0 || recentRaw.length <= 1) {
+		return { recent: [...recentRaw], dropped: 0 };
+	}
+	const msgTokens =
+		opts.messageTokens && opts.messageTokens.length === recentRaw.length
+			? opts.messageTokens
+			: null;
+	const { reserveTokens } = resolveOutputReserve(
+		ctxWindow,
+		opts.maxOutputTokens,
+		outputReservePct,
+	);
+	const safetyMargin = Math.ceil(
+		ctxWindow * (Math.max(0, opts.safetyMarginPct) / 100),
+	);
+	// Budget floor: never negative. An implausible reserve (clamped above to
+	// <= 95% of the window) plus margin + summary can still exceed the window
+	// on tiny summaries-free edges; the floor keeps the cap alive with a small
+	// positive budget instead of disabling it (pre-v0.21.9 behavior).
+	const budget = Math.max(
+		1,
+		ctxWindow - reserveTokens - safetyMargin - Math.max(0, summaryTokens),
+	);
+	let start = 0;
+	let tailTokens = 0;
+	for (let i = recentRaw.length - 1; i >= 0; i--) {
+		tailTokens +=
+			msgTokens != null
+				? Math.max(0, msgTokens[i])
+				: estimateMessageTokens({ text: messageContentText(recentRaw[i]) });
+		if (tailTokens > budget) {
+			// Keep from i+1 onward; never drop below the FINAL message.
+			start = Math.min(i + 1, recentRaw.length - 1);
+			break;
+		}
+	}
+	// PREVENT-PI-002: never begin the preserved tail on an orphaned toolResult —
+	// its toolCall was dropped by the front-cut above. Advance past consecutive
+	// toolResults; the pair stays intact or drops whole.
+	while (
+		start < recentRaw.length - 1 &&
+		(recentRaw[start] as { role?: string }).role === "toolResult"
+	) {
+		start++;
+	}
+	return { recent: recentRaw.slice(start), dropped: start };
+}
+
+/**
+ * v0.21.9: re-cap a REPLAYED trim tail (D.2 in context-handler.ts, D.3 in
+ * pipelineRun.ts). The replay paths return the cached trim view verbatim —
+ * which bypasses the fire-time tail cap. A model switch mid-epoch can shrink
+ * the window, leaving a replayed tail that fit the OLD window overflowing the
+ * NEW one. Re-runs applyTailCap against the CURRENT window with the margin
+ * stored at fire time (trimCache.safetyMarginPct), so the replayed view never
+ * exceeds what the gate would allow. Pure — no runtime dependency.
+ */
+export function recapReplayedTail(opts: {
+	recentRaw: readonly AgentMessage[];
+	summaryAgentMsg: AgentMessage;
+	ctxWindow: number;
+	maxOutputTokens: number;
+	outputReservePct: number;
+	safetyMarginPct: number;
+}): { recent: AgentMessage[]; dropped: number } {
+	return applyTailCap({
+		recentRaw: opts.recentRaw,
+		summaryTokens: estimateBlockTokens(messageContentText(opts.summaryAgentMsg)),
+		ctxWindow: opts.ctxWindow,
+		maxOutputTokens: opts.maxOutputTokens,
+		outputReservePct: opts.outputReservePct,
+		safetyMarginPct: opts.safetyMarginPct,
+	});
+}

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

@@ -13,12 +13,9 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { EngineMessage } from "../../../src/types.js";
-import {
-	estimateBlockTokens,
-	estimateMessageTokens,
-} from "../../../src/tokens.js";
+import { estimateBlockTokens } from "../../../src/tokens.js";
 import { computeLiveTrimCut, liveTrimSummaryMessage } from "../../mega-trim.js";
-import { messageContentText } from "./messageText.js";
+import { applyTailCap } from "./headroom.js";
 import type { MegaRuntime } from "../../mega-runtime.js";
 import type { MegaConfig } from "../../mega-config.js";
 import type { TailResultFn } from "./gateCheck.js";
@@ -136,59 +133,33 @@ export function buildLiveTrimView(
 		// but has NO token cap, so a 2-message tail of two 80K bash outputs sails
 		// right past the window.
 		//
-		// Cap: when the model context window is known, reserve room for the
-		// summary + the model's max output tokens + a 10% safety margin, then
-		// drop oldest preserved messages from the front of `recentRaw` until the
-		// tail fits. Never drops below the FINAL message (always keep the latest
-		// turn so the agent can respond). This is a last-resort HARD cap — it
-		// only fires when the preserved tail alone is oversized, which is rare.
+		// v0.21.9: the reserve + front-drop now lives in headroom.ts (single
+		// source shared with the gate's pre-fire headroom check and the D.2/D.3
+		// replay paths): (a) percent-based reserve — plausible declared maxTokens
+		// wins, else clamp(MEGACOMPACT_OUTPUT_RESERVE_PCT, 10–95%) × window — so
+		// the math is identical at any window size and a sentinel maxTokens
+		// (1e9/1e38) can no longer drive the budget negative and silently
+		// disable the cap; (b) budget floor (max(1, …)) so the cap stays active
+		// on every window; (c) pair-safe front-drop — the preserved tail never
+		// begins on an orphaned toolResult (PREVENT-PI-002).
 		const ctxWindow = runtime.lastCtxWindow;
 		// Reuse the per-model threshold resolved at the gate (single lookup).
 		const modelThreshold = perModelThreshold;
-		// Reserve room for output tokens. Use the model's reported max output
-		// when known; fall back to 10% of the window (scales with any model —
-		// 20K for a 200K window, 100K for a 1M window) so we never let the
-		// preserved tail eat the model's output budget when maxTokens is unknown.
-		const maxOutput =
-			runtime.currentModel?.maxTokens && runtime.currentModel.maxTokens > 0
-				? runtime.currentModel.maxTokens
-				: Math.ceil(ctxWindow * 0.1);
-		let recent = recentRaw;
-		if (ctxWindow > 0 && recentRaw.length > 1) {
-			const summaryTokens = estimateBlockTokens(summaryMsg.text);
-			// Reserve: summary + max output + per-model safety margin (0-20%).
-			const safetyMargin = Math.ceil(
-				ctxWindow * (modelThreshold.safetyMarginPct / 100),
-			);
-			const budget = ctxWindow - maxOutput - safetyMargin - summaryTokens;
-			if (budget > 0) {
-				// Walk recent from the front, dropping oldest first until the
-				// remaining tail fits. Use the AgentMessage→engine-text estimate via
-				// messageContentText (already imported) + estimateMessageTokens.
-				let tailTokens = 0;
-				for (let i = recentRaw.length - 1; i >= 0; i--) {
-					const m = recentRaw[i];
-					tailTokens += estimateMessageTokens({
-						text: messageContentText(m),
-					});
-					if (tailTokens > budget) {
-						// Keep from i+1 onward; but never fewer than the final message.
-						const startIdx = Math.min(i + 1, recentRaw.length - 1);
-						if (startIdx > 0) {
-							recent = recentRaw.slice(startIdx);
-							runtime.logger.warn("live-trim-tail-cap", {
-								sessionId: runtime.rt.sessionId,
-								dropped: startIdx,
-								tailTokens,
-								safetyMarginPct: modelThreshold.safetyMarginPct,
-								budget,
-								ctxWindow,
-							});
-						}
-						break;
-					}
-				}
-			}
+		const { recent, dropped } = applyTailCap({
+			recentRaw,
+			summaryTokens: estimateBlockTokens(summaryMsg.text),
+			ctxWindow,
+			maxOutputTokens: runtime.currentModel?.maxTokens ?? 0,
+			outputReservePct: config.outputReservePct,
+			safetyMarginPct: modelThreshold.safetyMarginPct,
+		});
+		if (dropped > 0) {
+			runtime.logger.warn("live-trim-tail-cap", {
+				sessionId: runtime.rt.sessionId,
+				dropped,
+				safetyMarginPct: modelThreshold.safetyMarginPct,
+				ctxWindow,
+			});
 		}
 
 		// v0.8.6: cache the trim view so subsequent gated calls in this epoch
@@ -214,6 +185,11 @@ export function buildLiveTrimView(
 			summaryAgentMsg,
 			ctxPct: pct ?? null,
 			ctxTokens: currentTokens,
+			// v0.21.9: the D.2/D.3 replay paths re-cap the replayed tail against
+			// the CURRENT window (a model switch can change it mid-epoch). The
+			// margin % used at fire time is stored alongside so the replay uses
+			// the same reserve math as the fire that built the view.
+			safetyMarginPct: modelThreshold.safetyMarginPct,
 		};
 		runtime.snapshot(ctx);
 		// DIAG (team-run relief): confirm the live trim actually fires + how big

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

@@ -21,6 +21,7 @@ import type { MegaConfig } from "../../mega-config.js";
 import type { TailResultFn } from "./gateCheck.js";
 import { recordCompactLatency } from "../../mega-runtime/vc-observer.js";
 import { decideLivePath } from "../../mega-runtime/vector-cortex-live.js";
+import { recapReplayedTail } from "./headroom.js";
 import { defaultClock, type RolloutEvidence } from "../../../src/vector-cortex/rollout/gate.js";
 import { VC5C_ENABLED } from "../../../src/config/vector-cortex.js";
 
@@ -120,7 +121,19 @@ export function invokePipeline(
 			runtime.trimCache.checkpointId === runtime.rt.lastCheckpointId &&
 			runtime.trimCache.cut <= opts.messages.length
 		) {
-			const recent = opts.messages.slice(runtime.trimCache.cut); // guardrails-allow PREVENT-PI-002: cached `cut` was sanitized by computeLiveTrimCut (src/boundary.ts); replayed verbatim, transcript only grows within an epoch.
+			const recentRaw = opts.messages.slice(runtime.trimCache.cut); // guardrails-allow PREVENT-PI-002: cached `cut` was sanitized by computeLiveTrimCut (src/boundary.ts); replayed verbatim, transcript only grows within an epoch.
+			// v0.21.9: RE-CAP the replayed tail against the CURRENT window —
+			// the D.3 skip-replay bypasses the fire-time tail cap exactly like
+			// D.2; a model switch mid-epoch can shrink the window below what
+			// the cached view was built for. No-op when the tail already fits.
+			const { recent } = recapReplayedTail({
+				recentRaw,
+				summaryAgentMsg: runtime.trimCache.summaryAgentMsg,
+				ctxWindow: runtime.lastCtxWindow,
+				maxOutputTokens: runtime.currentModel?.maxTokens ?? 0,
+				outputReservePct: config.outputReservePct,
+				safetyMarginPct: runtime.trimCache.safetyMarginPct,
+			});
 			runtime.diagLiveTrimFires++;
 			runtime.diagLiveTrimReplays++;
 			runtime.snapshot(ctx);

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

@@ -34,6 +34,7 @@ import {
 } from "./context-handler/thrashGuard.js";
 import { invokePipeline } from "./context-handler/pipelineRun.js";
 import { buildLiveTrimView } from "./context-handler/liveTrim.js";
+import { recapReplayedTail } from "./context-handler/headroom.js";
 
 /** Register the context event handler (live-trim auto-trigger). */
 export function registerContextHandler(
@@ -116,7 +117,21 @@ export function registerContextHandler(
 			/* non-fatal */
 		}
 		runtime.lastCtxPercent = pct ?? null;
-		runtime.lastCtxWindow = usage?.contextWindow ?? 0;
+		// Resolve the model window used by the token gate + live-trim tail-cap.
+		// Prefer the provider-reported usage window (authoritative when present);
+		// fall back to the captured model snapshot's contextWindow (populated from
+		// models.json / pi's model registry) when the provider does not report it
+		// via getContextUsage(). plexus (OpenAI-compatible) omits contextWindow in
+		// usage, so without this fallback lastCtxWindow is 0 for those providers —
+		// which silently disables the live-trim tail-cap (guarded on ctxWindow>0)
+		// and the token-gate window math, so mega-compact never reserves output
+		// headroom and a 32k model's own output overflows the window each turn.
+		// Mirrors the gate's existing pct fallback (gateCheck.ts S27).
+		const reportedWindow = usage?.contextWindow ?? 0;
+		runtime.lastCtxWindow =
+			reportedWindow > 0
+				? reportedWindow
+				: (runtime.currentModel?.contextWindow ?? 0);
 		runtime.snapshot(ctx);
 		if (!config.auto) {
 			const tailed = tailResult();
@@ -159,7 +174,23 @@ export function registerContextHandler(
 					: 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.
+				const recentRaw = 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.
+				// v0.21.9: RE-CAP the replayed tail against the CURRENT window.
+				// Replay returns the cached view verbatim, which bypasses the
+				// fire-time tail cap — a model switch mid-epoch can shrink the
+				// window and leave a replayed tail that fit the OLD window
+				// overflowing the NEW one. Same reserve math as the fire
+				// (margin % stored in the cache at fire time); no-op when the
+				// tail already fits. Pair-safe (applyTailCap advances past any
+				// leading toolResult its front-drop exposes).
+				const { recent } = recapReplayedTail({
+					recentRaw,
+					summaryAgentMsg: runtime.trimCache.summaryAgentMsg,
+					ctxWindow: runtime.lastCtxWindow,
+					maxOutputTokens: runtime.currentModel?.maxTokens ?? 0,
+					outputReservePct: config.outputReservePct,
+					safetyMarginPct: runtime.trimCache.safetyMarginPct,
+				});
 				runtime.diagLiveTrimFires++; // trim view returned this call (replay counts as a fire)
 				runtime.diagLiveTrimReplays++;
 				runtime.snapshot(ctx);
@@ -180,7 +211,7 @@ export function registerContextHandler(
 		// invokePipeline (the real fire point), so it covers the percent + token
 		// gate paths alike. Umbrella OFF ⇒ never blocks (byte-identical). Returns
 		// the tailed view so a staged recall block still rides along.
-		if (thrashGuardBlocks(runtime, config, currentTokens)) {
+		if (thrashGuardBlocks(runtime, config, currentTokens, gate.headroomExceeded)) {
 			runtime.diagCtxFastGate++;
 			runtime.snapshot(ctx);
 			return tailResult() ?? undefined;

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

@@ -49,6 +49,8 @@ export interface SnapshotBuildContext {
 	readonly diagCtxFastGate: number;
 	readonly diagLiveTrimFires: number;
 	readonly diagLiveTrimReplays: number;
+	/** v0.21.9: output-headroom gate trips (pre-overflow compaction fires). */
+	readonly diagCtxHeadroomTrip: number;
 	readonly errorRetryCount: number;
 	readonly consecutiveErrors: number;
 	readonly ERROR_RETRY_MAX_CONSECUTIVE: number;
@@ -190,6 +192,7 @@ export function buildDashboardSnapshot(ctx: SnapshotBuildContext): DashboardSnap
 			ctxFastGate: ctx.diagCtxFastGate,
 			liveTrimFires: ctx.diagLiveTrimFires,
 			liveTrimReplays: ctx.diagLiveTrimReplays,
+			headroomTrips: ctx.diagCtxHeadroomTrip,
 		},
 		retries: {
 			errorRetryCount: ctx.errorRetryCount,

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

@@ -39,6 +39,7 @@ export class RuntimeInstrumentation {
 	diagCtxCutNull = 0; // computeLiveTrimCut returned null (anchor/boundary)
 	diagCtxThrown = 0; // live-trim try threw (caught)
 	diagCtxOutputErrorTrip = 0; // Phase H: output-error catch tripped a forced compaction
+	diagCtxHeadroomTrip = 0; // v0.21.9: output-headroom gate tripped a pre-overflow compaction
 
 	// Context health instrumentation (v0.12): rolling ring buffers for
 	// drift detection + cache poison Layer 1 hash baseline.
@@ -79,6 +80,9 @@ export class RuntimeInstrumentation {
 		summaryAgentMsg: AgentMessage;
 		ctxPct: number | null;
 		ctxTokens: number | null;
+		/** v0.21.9: safety margin % recorded at fire time so the D.2/D.3 replay
+		 *  paths can re-cap the replayed tail with the same reserve math. */
+		safetyMarginPct: number;
 	} | null = null;
 	debounceUntil = 0;
 	// S16: debounce for the agent_end resume nudge (avoid busy-loops).