pi-mega-compact 0.21.8 → 0.21.10

package/dist/dedup/degenerate.js

@@ -0,0 +1,68 @@
+/**
+ * The effective token floor for a checkpoint: the larger of the absolute floor
+ * and `MIN_PCT × originalTokenEstimate`.
+ *
+ * A missing / zero / non-finite `originalTokenEstimate` contributes nothing, so
+ * the absolute floor applies alone — direct add() callers and pre-v0.4 rows that
+ * never recorded the original region size are judged on absolute size only,
+ * never accidentally deemed degenerate by a 0-valued percentage term.
+ */
+export function degenerateFloor(subject, tunables) {
+    const orig = subject.originalTokenEstimate;
+    const relative = typeof orig === "number" && Number.isFinite(orig) && orig > 0
+        ? orig * tunables.DEDUP_DEGEN_MIN_PCT
+        : 0;
+    return Math.max(tunables.DEDUP_DEGEN_MIN_TOKENS, relative);
+}
+/**
+ * Is this stored checkpoint a degenerate (content-free) summary?
+ *
+ * Calibration against the incident data:
+ *  - skeleton: tokenEstimate 34, original ≈19166 → 34 < max(48, 95.8) → TRUE
+ *  - normal:   tokenEstimate 2000, original 70000 → 2000 > max(48, 350) → FALSE
+ *
+ * The relative term is what makes this scale: a 34-token summary of a 900-token
+ * region is a legitimate 26× compression, while the same 34 tokens standing in
+ * for 19k is a skeleton.
+ */
+export function isDegenerateCheckpoint(subject, tunables) {
+    const tokens = subject.tokenEstimate ?? 0;
+    return tokens < degenerateFloor(subject, tunables);
+}
+/**
+ * Should an L1/L2 match be DECLINED because it would collapse richer incoming
+ * content onto a degenerate stored checkpoint?
+ *
+ * Returns true only when all four hold:
+ *   1. the umbrella flag is ON,
+ *   2. the matched (stored) checkpoint is degenerate,
+ *   3. the candidate is strictly richer than the match,
+ *   4. the candidate's content is not byte-identical to the match's.
+ *
+ * Condition 3 uses a strict `>`: equal-size skeletons collapsing is harmless and
+ * keeps the store from growing one row per compaction while the summarizer is
+ * broken. Only a genuine improvement is worth declining a collapse for.
+ *
+ * Condition 4 is a CORRECTNESS requirement, not a refinement. `context_chunks`
+ * carries a partial UNIQUE index on (session_id, content_hash) (schema/core.ts
+ * QA #1), so declining a match whose content hash already exists would fall
+ * through to an INSERT that throws — inside add(), which sits on the agent loop.
+ * It is also the semantically right call: identical bytes are the SAME region,
+ * so re-storing them adds no information and heals nothing. Only L0 may own the
+ * exact-match case; the guard exists for fuzzy matches on genuinely different
+ * text, which is exactly the incident's shape (each compaction produced a
+ * *similar but distinct* skeleton).
+ */
+export function shouldSkipDegenerateMatch(matched, candidate, tunables) {
+    if (!tunables.DEDUP_DEGENERATE_GUARD)
+        return false;
+    if (!isDegenerateCheckpoint(matched, tunables))
+        return false;
+    if ((candidate.tokenEstimate ?? 0) <= (matched.tokenEstimate ?? 0))
+        return false;
+    // Byte-identical content → not a healing opportunity (and would violate the
+    // UNIQUE index). Compared only when both hashes are known.
+    const a = candidate.contentHash;
+    const b = matched.contentHash;
+    return !(a !== undefined && b !== undefined && a === b);
+}

package/dist/extensions/dashboard-server/routes-dedup-attribution.js

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

package/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,
@@ -84,6 +85,7 @@ export const SETTINGS = [
             boolDirect("MEGACOMPACT_MARK_ONLY_L1", "Mark Only L1", "L1 runs but does not collapse", false),
             boolDirect("MEGACOMPACT_MARK_ONLY_L2", "Mark Only L2", "L2 runs but does not collapse", false),
             boolDirect("MEGACOMPACT_MINILM", "MiniLM Embedder", "Use MiniLM instead of trigram", false),
+            boolDirect("MEGACOMPACT_DEDUP_DEGENERATE_GUARD", "Degenerate Match Guard", "Decline an L1/L2 collapse when the MATCHED stored checkpoint is a content-free skeleton (a ~30-40 token structural summary) and the incoming region is richer. Without this, one degenerate checkpoint absorbs every later compaction forever and the store can never heal. OFF = byte-identical pre-guard cascade. Calibrated by the two Degenerate floors under Dedup Thresholds.", true),
             boolDirect("MEGACOMPACT_DEDUP_AUDIT", "Dedup Audit Trail", "Append one events.log line per tier decision (which layer collapsed a region, onto what, at what similarity) to tune the thresholds below. Pure instrumentation — dedup behavior is identical either way.", true),
         ],
     },
@@ -93,6 +95,8 @@ export const SETTINGS = [
             num("MEGACOMPACT_L2_THRESHOLD", "L2 Cosine Threshold", "L2 semantic dedup firing point", 0.85, 0, 1),
             num("MEGACOMPACT_L1_JACCARD", "L1 Jaccard Threshold", "L1 MinHash near-dup threshold", 0.8, 0, 1),
             num("MEGACOMPACT_DEDUP_SIM", "Dedup Similarity", "Legacy content-similarity fallback", 0.9, 0, 1),
+            num("MEGACOMPACT_DEDUP_DEGEN_MIN_TOKENS", "Degenerate Min Tokens", "Absolute token floor below which a stored summary counts as a degenerate skeleton (Degenerate Match Guard)", 48, 0, 10000, "tokens"),
+            num("MEGACOMPACT_DEDUP_DEGEN_MIN_PCT", "Degenerate Min Percent", "Relative floor as a fraction of the summary's original region size; a summary under max(min-tokens, pct x original) is degenerate", 0.005, 0, 1),
             num("MEGACOMPACT_RECALL_MIN_COSINE", "Recall Min Cosine (same-repo)", "3WF-3 same-repo floor the 3-source validator applies to the top winner (cross-repo 0.90 stays separate)", 0.12, 0, 1),
             num("MEGACOMPACT_MMR_LAMBDA", "MMR Lambda", "Maximal Marginal Relevance diversity", 0.5, 0, 1),
             num("MEGACOMPACT_SEMDEDUP_COSINE", "SemDeDup Cosine", "Offline SemDeDup pair threshold", 0.95, 0, 1),
@@ -127,14 +131,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
@@ -138,8 +115,12 @@ export function buildLiveTrimView(runtime, config, ctx, opts) {
             // (rt.lastCheckpointId) instead of ran.result.checkpointId, which is
             // dedup-volatile: on a re-compact that dedups onto a DIFFERENT existing
             // checkpoint, result.checkpointId is the matched id (engine.ts:188) while
-            // lastCheckpointId is only updated on a genuinely new checkpoint
-            // (compact.ts:100-104). Keying on result.checkpointId would make
+            // lastCheckpointId was, pre-C1, only updated on a genuinely new checkpoint.
+            // C1 (v0.21.10) now stamps lastCheckpointId on the dedup path too (see
+            // compact/run.ts) — it means "the checkpoint backing this epoch" — so this
+            // key and the D.2/D.3 comparison agree in both directions and the `??`
+            // fallbacks below are now only for the truly-no-checkpoint edge case.
+            // Keying on result.checkpointId directly would still make
             // trimCache.checkpointId != rt.lastCheckpointId forever after that
             // dedup fire, disabling replay for the rest of the epoch (the
             // alternating cache-miss that 0.8.6 meant to fix). Prefer the stable
@@ -152,6 +133,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,15 +176,21 @@ 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;
         }
         // Debounce so we don't fire on every context event past threshold.
         // (Replay already returned above — only fresh compacts reach this point.)
+        // C2 (v0.21.10): EXEMPT headroom-triggered fires, matching the thrash-guard
+        // exemption above. pi's own overflow recovery (400 → compact → immediate
+        // retry) re-fires a context event <2s after our last fire; debouncing it
+        // returned the RAW untrimmed view, so input + output reserve still blew the
+        // window → 400 → "recovery failed after one compact-and-retry attempt".
+        // An overflowed session is unrecoverable; a re-fire is merely wasteful.
         const now = Date.now();
-        if (now < runtime.debounceUntil) {
+        if (now < runtime.debounceUntil && !gate.headroomExceeded) {
             runtime.diagCtxDebounce++;
             return tailResult() ?? undefined;
         }

package/dist/extensions/mega-pipeline/compact/run.js

@@ -71,10 +71,21 @@ function doCompact(view, keepFrom, opts, sid, config, pi, ctx, runtime) {
     runtime.pulsing = false;
     if (result.skipped)
         return { skipped: true };
-    if (!result.deduped) {
+    // C1 (v0.21.10): lastCheckpointId tracks "the checkpoint backing this epoch",
+    // so it is stamped on BOTH paths — a matched-dedup checkpoint backs this epoch
+    // just as much as a freshly created one. Previously the dedup path left it
+    // undefined, so a runtime session whose every compaction deduped (common after
+    // a process restart, when checkpoints persist but `rt` is rebuilt) never set it
+    // → liveTrim's trimCache fell back to result.checkpointId (the matched id) →
+    // `trimCache.checkpointId === rt.lastCheckpointId` was `"chkpt_001" !== undefined`
+    // → the D.2/D.3 replay NEVER matched and the full pipeline re-ran on every
+    // context event (liveTrimReplays: 0, "comp lag warn"). A later fire matching a
+    // DIFFERENT checkpoint now changes the key once (one cache regeneration), then
+    // replays stabilise. `persistedThisSession` keeps its narrower meaning ("we
+    // wrote NEW state this session") and stays gated on !deduped.
+    if (!result.deduped)
         runtime.rt.persistedThisSession = true;
-        runtime.rt.lastCheckpointId = result.checkpointId;
-    }
+    runtime.rt.lastCheckpointId = result.checkpointId;
     runtime.rt.lastCompactedFrom = result.compactedFrom;
     runtime.rt.lastCompactedTokens = result.tokenEstimate;
     runtime.rt.dedupAttempts++;