pi-mega-compact 0.21.7 → 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 ----
@@ -87,7 +88,21 @@ export function registerContextHandler(pi, runtime, config) {
             /* non-fatal */
         }
         runtime.lastCtxPercent = pct ?? null;
-        runtime.lastCtxWindow = usage?.contextWindow ?? 0;
+        // Resolve the model window used by the token gate + live-trim tail-cap.
+        // Prefer the provider-reported usage window (authoritative when present);
+        // fall back to the captured model snapshot's contextWindow (populated from
+        // models.json / pi's model registry) when the provider does not report it
+        // via getContextUsage(). plexus (OpenAI-compatible) omits contextWindow in
+        // usage, so without this fallback lastCtxWindow is 0 for those providers —
+        // which silently disables the live-trim tail-cap (guarded on ctxWindow>0)
+        // and the token-gate window math, so mega-compact never reserves output
+        // headroom and a 32k model's own output overflows the window each turn.
+        // Mirrors the gate's existing pct fallback (gateCheck.ts S27).
+        const reportedWindow = usage?.contextWindow ?? 0;
+        runtime.lastCtxWindow =
+            reportedWindow > 0
+                ? reportedWindow
+                : (runtime.currentModel?.contextWindow ?? 0);
         runtime.snapshot(ctx);
         if (!config.auto) {
             const tailed = tailResult();
@@ -125,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);
@@ -145,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,
+		),
+	],
+};