pi-mega-compact 0.21.8 → 0.21.10

package/extensions/dashboard-server/api-contracts/endpoints/types.ts

@@ -303,6 +303,8 @@ export interface PerfDiag {
 	readonly liveTrimFires: number;
 	/** Number of live trim replays. */
 	readonly liveTrimReplays: number;
+	/** v0.21.9: output-headroom gate trips (pre-overflow compaction fires). */
+	readonly headroomTrips: number;
 }
 
 /**

package/extensions/dashboard-server/routes-dedup-attribution.ts

@@ -59,7 +59,17 @@ function parseAuditLine(line: string): DedupAuditEvent | null {
   const tier = obj.tier;
   const status = obj.status;
   if (tier !== "L0" && tier !== "L1" && tier !== "L2" && tier !== "new") return null;
-  if (status !== "deduped" && status !== "passed" && status !== "stored") return null;
+  // "skipped" = a tier matched but the degenerate-match guard declined to
+  // collapse. Accepted so the line is not silently dropped from the tail; the
+  // rollup below counts only deduped/passed, so tier catch-share math is
+  // unchanged by its presence.
+  if (
+    status !== "deduped" &&
+    status !== "passed" &&
+    status !== "stored" &&
+    status !== "skipped"
+  )
+    return null;
   // sessionId is never read by the rollup; a parsed line may omit richer fields.
   return { type: "dedup_audit", ts: obj.ts, tier, status, sessionId: "" };
 }

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

@@ -0,0 +1,91 @@
+/**
+ * dashboard-server/routes-rag-settings-compaction.ts — Compaction SETTINGS.
+ *
+ * The compaction-group flag inventory, split out of routes-rag-settings-helpers.ts
+ * (delegate-shell split per the extensions/ 400-line soft limit) when the
+ * v0.21.9 output-headroom flags landed. regression_check.py globs every
+ * routes-rag-settings*.ts sibling, so no scanner update is needed on split.
+ *
+ * PREVENT-011: no `any` type.
+ */
+
+import type { SettingSpec, SettingGroup } from "./routes-rag-settings-types.js";
+
+const boolDirect = (
+	key: string,
+	label: string,
+	description: string,
+	def: boolean,
+): SettingSpec => ({
+	key,
+	label,
+	description,
+	type: "boolean",
+	default: def,
+	disabledConvention: false,
+	requiresLlm: false,
+});
+
+const num = (
+	key: string,
+	label: string,
+	description: string,
+	def: number,
+	min: number,
+	max: number,
+	unit?: string,
+): SettingSpec => ({
+	key,
+	label,
+	description,
+	type: "number",
+	default: def,
+	disabledConvention: false,
+	requiresLlm: false,
+	min,
+	max,
+	...(unit ? { unit } : {}),
+});
+
+/** The compaction flags, as one SETTINGS category. */
+export const COMPACTION_SETTINGS: SettingGroup = {
+	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,
+		),
+		boolDirect(
+			"MEGACOMPACT_OVERFLOW_HEADROOM",
+			"Overflow Headroom Gate",
+			"Fire compaction BEFORE the request overflows the model window — when input tokens + the output reserve + safety margin would exceed the context window — instead of waiting for the percent fire point (which judges only INPUT and never trips on small-window models whose output budget is a large fraction of the window). Percent-based: the reserve scales with the model's own window, so the math holds at every window size (32k…5M). OFF disables this pre-fire check (the gate reverts to input-only judgment); the pair-safe tail-cap hardenings are unconditional safety fixes and remain active.",
+			true,
+		),
+		num(
+			"MEGACOMPACT_OUTPUT_RESERVE_PCT",
+			"Output Reserve %",
+			"FALLBACK output reserve as a fraction of the context window, used only when the model's declared maxTokens is absent or implausible (0, or a models.json sentinel like 1e9/1e38, or >= the window). When maxTokens IS plausible the declared value wins — vLLM-style backends reserve the FULL declared maxTokens. Default 0.30 (30%), clamped 0.10–0.95.",
+			0.3,
+			0.1,
+			0.95,
+		),
+	],
+};

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";
 
@@ -227,6 +228,12 @@ export const SETTINGS: ReadonlyArray<SettingGroup> = [
 			boolDirect("MEGACOMPACT_MARK_ONLY_L1", "Mark Only L1", "L1 runs but does not collapse", false),
 			boolDirect("MEGACOMPACT_MARK_ONLY_L2", "Mark Only L2", "L2 runs but does not collapse", false),
 			boolDirect("MEGACOMPACT_MINILM", "MiniLM Embedder", "Use MiniLM instead of trigram", false),
+			boolDirect(
+				"MEGACOMPACT_DEDUP_DEGENERATE_GUARD",
+				"Degenerate Match Guard",
+				"Decline an L1/L2 collapse when the MATCHED stored checkpoint is a content-free skeleton (a ~30-40 token structural summary) and the incoming region is richer. Without this, one degenerate checkpoint absorbs every later compaction forever and the store can never heal. OFF = byte-identical pre-guard cascade. Calibrated by the two Degenerate floors under Dedup Thresholds.",
+				true,
+			),
 			boolDirect(
 				"MEGACOMPACT_DEDUP_AUDIT",
 				"Dedup Audit Trail",
@@ -241,6 +248,8 @@ export const SETTINGS: ReadonlyArray<SettingGroup> = [
 			num("MEGACOMPACT_L2_THRESHOLD", "L2 Cosine Threshold", "L2 semantic dedup firing point", 0.85, 0, 1),
 			num("MEGACOMPACT_L1_JACCARD", "L1 Jaccard Threshold", "L1 MinHash near-dup threshold", 0.8, 0, 1),
 			num("MEGACOMPACT_DEDUP_SIM", "Dedup Similarity", "Legacy content-similarity fallback", 0.9, 0, 1),
+			num("MEGACOMPACT_DEDUP_DEGEN_MIN_TOKENS", "Degenerate Min Tokens", "Absolute token floor below which a stored summary counts as a degenerate skeleton (Degenerate Match Guard)", 48, 0, 10000, "tokens"),
+			num("MEGACOMPACT_DEDUP_DEGEN_MIN_PCT", "Degenerate Min Percent", "Relative floor as a fraction of the summary's original region size; a summary under max(min-tokens, pct x original) is degenerate", 0.005, 0, 1),
 			num("MEGACOMPACT_RECALL_MIN_COSINE", "Recall Min Cosine (same-repo)", "3WF-3 same-repo floor the 3-source validator applies to the top winner (cross-repo 0.90 stays separate)", 0.12, 0, 1),
 			num("MEGACOMPACT_MMR_LAMBDA", "MMR Lambda", "Maximal Marginal Relevance diversity", 0.5, 0, 1),
 			num("MEGACOMPACT_SEMDEDUP_COSINE", "SemDeDup Cosine", "Offline SemDeDup pair threshold", 0.95, 0, 1),
@@ -275,33 +284,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,
+	});
+}