pi-mega-compact 0.21.8 → 0.21.9

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

@@ -0,0 +1,42 @@
+/**
+ * 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.
+ */
+const boolDirect = (key, label, description, def) => ({
+    key,
+    label,
+    description,
+    type: "boolean",
+    default: def,
+    disabledConvention: false,
+    requiresLlm: false,
+});
+const num = (key, label, description, def, min, max, unit) => ({
+    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 = {
+    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/dist/extensions/dashboard-server/routes-rag-settings-helpers.js

@@ -1,4 +1,5 @@
 import { VECTOR_CORTEX_SETTINGS } from "./routes-rag-settings-vector-cortex.js";
+import { COMPACTION_SETTINGS } from "./routes-rag-settings-compaction.js";
 // Shorthand builders to keep the inventory terse and unambiguous.
 const boolFlag = (key, label, description, def, requiresLlm = false) => ({
     key,
@@ -127,14 +128,10 @@ 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),
-            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/dist/extensions/mega-config.js

@@ -210,6 +210,18 @@ export function loadConfig() {
         // 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/dist/extensions/mega-events/context-handler/gateCheck.js

@@ -1,6 +1,7 @@
 import { resolveModelThreshold, DEFAULT_SAFETY_MARGIN_PCT, DEFAULT_FIRE_POINT_PCT, } from "../../../src/store/sqlite.js";
 import { autoCompactCheck } from "../../../src/compact.js";
 import { isThrashBlockedFor } from "./thrashGuard.js";
+import { resolveOutputReserve } from "./headroom.js";
 /**
  * 3WF-2 ThrashGuard consult — refuse to fire a NEW compaction while the guard
  * is armed. After an ineffective compaction (the live window did not shrink),
@@ -20,11 +21,18 @@ import { isThrashBlockedFor } from "./thrashGuard.js";
  * Umbrella OFF ⇒ always false (byte-identical to v0.20.83). Non-fatal: a store
  * read error returns false — never refuse compaction on a store fault.
  */
-export function thrashGuardBlocks(runtime, config, currentTokens) {
+export function thrashGuardBlocks(runtime, config, currentTokens, headroomExceeded) {
     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);
 }
 /**
@@ -67,6 +75,48 @@ export function evaluateGate(runtime, config, opts) {
         runtime.diagCtxOutputErrorTrip++;
         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/dist/extensions/mega-events/context-handler/headroom.js

@@ -0,0 +1,128 @@
+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, maxTokens, outputReservePct) {
+    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) {
+    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].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) {
+    return applyTailCap({
+        recentRaw: opts.recentRaw,
+        summaryTokens: estimateBlockTokens(messageContentText(opts.summaryAgentMsg)),
+        ctxWindow: opts.ctxWindow,
+        maxOutputTokens: opts.maxOutputTokens,
+        outputReservePct: opts.outputReservePct,
+        safetyMarginPct: opts.safetyMarginPct,
+    });
+}

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

@@ -1,6 +1,6 @@
-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";
 /**
  * Reconstruct the live-trim window (summary + recent anchor) for this LLM
  * call. Returns the tailed view, or undefined when no trim is safe this call.
@@ -79,56 +79,33 @@ export function buildLiveTrimView(runtime, config, ctx, opts) {
         // 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
         // replay it verbatim (stabilizing the KV-cache prefix) instead of
@@ -152,6 +129,11 @@ export function buildLiveTrimView(runtime, config, ctx, opts) {
             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/dist/extensions/mega-events/context-handler/pipelineRun.js

@@ -2,6 +2,7 @@ import { runCompact } from "../../mega-pipeline.js";
 import { pressureFromPct, pressureRatio } from "../../mega-config.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 } from "../../../src/vector-cortex/rollout/gate.js";
 import { VC5C_ENABLED } from "../../../src/config/vector-cortex.js";
 /**
@@ -72,7 +73,19 @@ export function invokePipeline(pi, runtime, config, ctx, opts) {
         if (runtime.trimCache &&
             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/dist/extensions/mega-events/context-handler.js

@@ -9,6 +9,7 @@ import { evaluateGate, thrashGuardBlocks } from "./context-handler/gateCheck.js"
 import { markCompactionFired, evaluatePendingReduction, } 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(pi, runtime, config) {
     // ---- Auto-trigger: live trim (compact and continue) + native durable ----
@@ -139,7 +140,23 @@ export function registerContextHandler(pi, runtime, config) {
                 : 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);
@@ -159,7 +176,7 @@ export function registerContextHandler(pi, runtime, config) {
         // 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/dist/extensions/mega-runtime/dashboard-snapshot.js

@@ -128,6 +128,7 @@ export function buildDashboardSnapshot(ctx) {
             ctxFastGate: ctx.diagCtxFastGate,
             liveTrimFires: ctx.diagLiveTrimFires,
             liveTrimReplays: ctx.diagLiveTrimReplays,
+            headroomTrips: ctx.diagCtxHeadroomTrip,
         },
         retries: {
             errorRetryCount: ctx.errorRetryCount,

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

@@ -23,6 +23,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.
     recentTurnEmbeddings = [];

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

@@ -94,6 +94,7 @@ export function snapshotImpl(self, ctx) {
         diagCtxFastGate: self.diagCtxFastGate,
         diagLiveTrimFires: self.diagLiveTrimFires,
         diagLiveTrimReplays: self.diagLiveTrimReplays,
+        diagCtxHeadroomTrip: self.diagCtxHeadroomTrip,
         errorRetryCount: self.rt.errorRetryCount,
         consecutiveErrors: self.rt.consecutiveErrors,
         ERROR_RETRY_MAX_CONSECUTIVE: self.config.maxConsecutiveErrors,

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-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";
 
@@ -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(
@@ -173,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);
@@ -194,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).

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

@@ -84,6 +84,7 @@ export interface RuntimeSnapshotContext extends RuntimeHelpersContext {
 	diagCtxFastGate: number;
 	diagLiveTrimFires: number;
 	diagLiveTrimReplays: number;
+	diagCtxHeadroomTrip: number;
 
 	// ── public methods the orchestration calls ──
 	bindRepo(cwd: string | undefined): string;
@@ -177,6 +178,7 @@ export function snapshotImpl(
 			diagCtxFastGate: self.diagCtxFastGate,
 			diagLiveTrimFires: self.diagLiveTrimFires,
 			diagLiveTrimReplays: self.diagLiveTrimReplays,
+			diagCtxHeadroomTrip: self.diagCtxHeadroomTrip,
 			errorRetryCount: self.rt.errorRetryCount,
 			consecutiveErrors: self.rt.consecutiveErrors,
 			ERROR_RETRY_MAX_CONSECUTIVE: self.config.maxConsecutiveErrors,

package/package.json

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