pi-mega-compact 0.20.84 → 0.20.86

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

@@ -126,6 +126,13 @@ 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),
+        ],
+    },
     VECTOR_CORTEX_SETTINGS,
     {
         name: "Cost API",

package/dist/extensions/mega-config.js

@@ -66,11 +66,30 @@ function resolveThreshold() {
     }
     const raw = (process.env.MEGACOMPACT_TIER ?? "low").toLowerCase();
     const tier = (raw in COMPACT_TIERS ? raw : "low");
-    const tierPct = TIER_PCT[tier];
+    let tierPct = TIER_PCT[tier];
+    // 3WF-2 threshold invariant: under the umbrella, when no named tier is set
+    // the fire point is the configurable % of the ACTUAL model window (default
+    // 0.80 — "20% free remaining"). Tiered (named preset) keeps its preset pct;
+    // both paths still compute the legacy 200k boot fallback below as a display
+    // placeholder + the custom-tier absolute companion. Umbrella OFF stays
+    // byte-identical to v0.20.83 (default tier=low 0.5).
+    const umbrella = envBool("MEGACOMPACT_THREE_WAY_FAILBACK", true);
+    if (umbrella && !(process.env.MEGACOMPACT_TIER && process.env.MEGACOMPACT_TIER !== "")) {
+        tierPct = clamp(envFlag("MEGACOMPACT_THRESHOLD_PCT", 0.8), 0.1, 0.95);
+    }
     // Boot fallback: sane gate before the first context event provides a window.
+    // (NO hardcoded window in the firing path — effectiveThresholdImpl defers
+    // when window unknown; this remains only a display placeholder + custom
+    // companion under the umbrella.)
     const thresholdTokens = Math.round(tierPct * 200_000);
     return { tier, tierPct, thresholdTokens };
 }
+/** Clamp `n` into [lo, hi]; non-finite → fallback. */
+function clamp(n, lo, hi) {
+    if (!Number.isFinite(n))
+        return lo;
+    return Math.min(hi, Math.max(lo, n));
+}
 /**
  * Pure helper: the real compaction fire point, given the model context window.
  *
@@ -170,6 +189,12 @@ export function loadConfig() {
         // 3WF-1: TriggerGuard — guarantee a staged recall block on every context
         // event even when session_start never fires. Default ON; OFF = byte-identical.
         threeWayFailback: envBool("MEGACOMPACT_THREE_WAY_FAILBACK", true),
+        // 3WF-2: ThrashGuard re-arm budget as a fraction of effectiveThreshold.
+        // 0.10 default (10% of the effective threshold) — see mega-config-types.
+        // Clamped to [0.01, 0.5]: below 1% the guard is almost never armed (any
+        // growth re-fires, defeating the anti-thrash purpose); above 50% it would
+        // suppress legitimate re-fires for half the window. Env-overridable.
+        thrashRearmPct: clamp(envFlag("MEGACOMPACT_THRASH_REARM_PCT", 0.1), 0.01, 0.5),
         // PC-A: positive sprint flag, default ON. =0 byte-identical to the
         // pre-change OFF state (single gate lives at the call site in tailResult.ts).
         messageSeparation: envBool("MEGACOMPACT_MESSAGE_SEPARATION", true),

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

@@ -1,5 +1,32 @@
 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";
+/**
+ * 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),
+ * `thrasguard.blocked_until` holds the live-token count the window must exceed
+ * before re-firing is allowed.
+ *
+ * WHY THIS IS NOT INSIDE `evaluateGate`: the fast gate runs BEFORE the cached
+ * replay path in context-handler.ts, and REPLAY MUST STAY EXEMPT. A replay is
+ * free (no compute, no new checkpoint) and re-stabilises the provider KV-cache
+ * prefix — suppressing it would cause the very cache invalidation the D.2/D.3
+ * replay design exists to prevent. The guard's job is to stop wasted NEW
+ * compaction work, not to withhold an already-computed view. So the consult is
+ * called from the handler AFTER the replay block and BEFORE the debounce +
+ * `invokePipeline` (the actual fire point), covering the percent branch and the
+ * token branch alike since both converge there.
+ *
+ * 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) {
+    if (!config.threeWayFailback)
+        return false;
+    if (currentTokens == null)
+        return false;
+    return isThrashBlockedFor(runtime, currentTokens, runtime.currentStateDir);
+}
 /**
  * Evaluate whether the current context warrants compaction. Returns a tailed
  * view ("return") when the gate does not pass, or "proceed" with the resolved
@@ -40,11 +67,23 @@ export function evaluateGate(runtime, config, opts) {
     }
     else {
         // custom tier OR tiered-but-pct-unavailable → token gate (S27 fallback).
-        if (currentTokens < runtime.effectiveThreshold) {
+        // 3WF-2: under the umbrella, when the window is known AND the config is
+        // tiered, honor the per-model Dashboard override exactly like the percent
+        // branch (firePointPct % of the actual window) instead of the bare boot
+        // fallback. custom / window-unknown / umbrella-OFF keep the bare
+        // runtime.effectiveThreshold (window-unknown defers via +Infinity from
+        // effectiveThresholdImpl; custom is the explicit absolute).
+        let gateThreshold = runtime.effectiveThreshold;
+        if (config.threeWayFailback &&
+            config.tierPct != null &&
+            runtime.lastCtxWindow > 0) {
+            gateThreshold = Math.round((perModelThreshold.firePointPct / 100) * runtime.lastCtxWindow);
+        }
+        if (currentTokens < gateThreshold) {
             runtime.diagCtxFastGate++;
             return { kind: "return", view: tailResult() ?? undefined };
         }
-        const check = autoCompactCheck(currentTokens, runtime.effectiveThreshold); // SERVER-STYLE CONFIRM (local)
+        const check = autoCompactCheck(currentTokens, gateThreshold); // SERVER-STYLE CONFIRM (local)
         if (!check.shouldCompact) {
             runtime.diagCtxNoCompact++;
             return { kind: "return", view: tailResult() ?? undefined };

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

@@ -0,0 +1,186 @@
+import { getMetaNumber, setMetaNumber } from "../../../src/store/sqlite.js";
+/** Meta key holding the live-window baseline (tokens) at the ineffective fire. */
+export const THRASH_BASELINE_KEY = "thrasguard.baseline_tokens";
+/** Meta key holding the live-window token count below which re-firing is blocked. */
+export const THRASH_BLOCKED_KEY = "thrasguard.blocked_until";
+/**
+ * "Meaningful reduction" floor as a FRACTION of `liveBefore`. A compaction is
+ * only credited with freeing space when the live window shrank by at least this
+ * fraction of its pre-compaction size.
+ *
+ * Rationale (invented constant, calibrated + configurable-by-design): the model
+ * re-reports token counts on every context event with noise on the order of a
+ * percent or two, so a sub-1% wobble is not a real reduction — crediting it
+ * would suppress the guard on a genuine no-op fire (the exact bug we are
+ * fixing). 2% is a defensible "real shrink" threshold: it is well above typical
+ * re-estimation noise but low enough that a compaction that freed even a few
+ * percent of the window is not punished. A reduction of ≤0 tokens is
+ * unconditionally ineffective regardless of this floor.
+ */
+const MEANINGFUL_REDUCTION_PCT = 0.02;
+/** Pure reduction verdict for a live-window bracketing pair. */
+export const ReductionValidator = {
+    /**
+     * Judge whether the LIVE window actually shrank between two consecutive
+     * context events bracketing a compaction.
+     *  - a reduction of ≤0 tokens ⇒ definitively ineffective.
+     *  - otherwise effective only when the reduction is ≥ the small positive
+     *    floor (MEANINGFUL_REDUCTION_PCT of liveBefore), so estimation noise on
+     *    the model's re-reported token count is not mistaken for a real shrink.
+     */
+    validateReduction(liveBefore, liveAfter) {
+        const reduction = liveBefore - liveAfter;
+        const floor = Math.max(1, Math.round(MEANINGFUL_REDUCTION_PCT * liveBefore));
+        const effective = Number.isFinite(reduction) && reduction > 0 && reduction >= floor;
+        return { effective, liveBefore, liveAfter };
+    },
+};
+/**
+ * Arm the ThrashGuard after an ineffective compaction. Persists:
+ *  - `thrasguard.baseline_tokens` = the live currentTokens at this (post-fire)
+ *    context event, so re-arm is measured from the window that failed to shrink.
+ *  - `thrasguard.blocked_until` = baseline + N, where N = `rearmPct ×
+ *    effectiveThreshold`. Re-firing is refused until the live window grows past
+ *    `blocked_until`.
+ *
+ * If `effectiveThreshold` is non-finite (+Infinity — the 3WF-2 invariant when
+ * the model window is unknown), N cannot be computed; we MUST NOT persist
+ * Infinity/NaN into meta (getMetaNumber would read it back as 0). Skip arming
+ * + log instead; the next over-threshold event simply re-fires (pre-sprint
+ * behavior) rather than corrupting the guard.
+ */
+export function armThrashGuard(currentTokens, rearmPct, effectiveThreshold, stateDir, logger) {
+    if (!Number.isFinite(currentTokens) || currentTokens <= 0)
+        return;
+    if (!Number.isFinite(rearmPct) || rearmPct <= 0)
+        return;
+    if (!Number.isFinite(effectiveThreshold)) {
+        logger?.info("thrasguard_skip_arm", {
+            reason: "nonfinite_effective_threshold",
+            currentTokens,
+        });
+        return;
+    }
+    try {
+        const n = Math.round(rearmPct * effectiveThreshold);
+        setMetaNumber(THRASH_BASELINE_KEY, Math.round(currentTokens), stateDir);
+        setMetaNumber(THRASH_BLOCKED_KEY, Math.round(currentTokens + n), stateDir);
+        logger?.info("thrasguard_armed", {
+            baselineTokens: Math.round(currentTokens),
+            blockedUntilTokens: Math.round(currentTokens + n),
+            rearmTokens: n,
+        });
+    }
+    catch {
+        /* non-fatal: best-effort meta write */
+    }
+}
+/**
+ * Consult the ThrashGuard for the current live-window token count. Returns true
+ * when compaction must be refused (the window is still below the armed
+ * `blocked_until`). A `blocked_until` of 0/absent ⇒ never blocked. When the
+ * live tokens have grown past `blocked_until`, the guard no longer blocks
+ * (caller re-fires normally). Pure read, best-effort — on any failure returns
+ * false (do not refuse compaction on a store error).
+ */
+export function isThrashBlocked(currentTokens, stateDir) {
+    try {
+        const blockedUntil = getMetaNumber(THRASH_BLOCKED_KEY, stateDir);
+        if (blockedUntil <= 0)
+            return false;
+        return Number.isFinite(currentTokens) && currentTokens < blockedUntil;
+    }
+    catch {
+        return false; // non-fatal: never refuse compaction on a read error
+    }
+}
+/**
+ * Per-runtime one-shot session state for the live-window delta correlation.
+ * Like triggerGuard.ts, keyed by runtime in a WeakMap so it dies with the
+ * runtime and a test can pass a thin stub. Holds the live token count observed
+ * at the event that FIRED a compaction; consumed on the following context event
+ * to judge whether the window actually shrank.
+ */
+const sessionBefore = new WeakMap();
+/**
+ * The live-token count of the event that most recently ARMED the guard, per
+ * runtime. The arming happens early in a context event (the live-delta consume
+ * point), but the guard consult runs LATER IN THAT SAME EVENT — and since
+ * `blocked_until = currentTokens + N`, a naive consult would always find
+ * `currentTokens < blocked_until` and swallow the very event that armed it.
+ * That is an off-by-one-event error: the guard's contract is to refuse
+ * SUBSEQUENT re-fires, not to cancel the compaction that revealed the problem.
+ * Recording the arming event's token count lets the consult skip exactly that
+ * one event. Cleared once the window grows past it.
+ */
+const armedOnEvent = new WeakMap();
+/**
+ * Runtime-aware ThrashGuard consult: true when a NEW compaction must be refused.
+ *
+ * Reads the persisted `thrasguard.blocked_until` (see `isThrashBlocked`) but
+ * EXEMPTS the single event that armed the guard — otherwise, because arming sets
+ * `blocked_until = currentTokens + N` earlier in the very same context event, the
+ * consult would always fire and cancel the compaction that exposed the thrash.
+ * The guard exists to refuse SUBSEQUENT re-fires. Once the live window grows past
+ * the armed count the exemption is dropped, and normal blocking resumes until the
+ * window clears `blocked_until`.
+ *
+ * Best-effort: any failure returns false (never refuse on a store fault).
+ */
+export function isThrashBlockedFor(runtime, currentTokens, stateDir) {
+    try {
+        if (!isThrashBlocked(currentTokens, stateDir))
+            return false;
+        const armedAt = armedOnEvent.get(runtime);
+        if (armedAt !== undefined && currentTokens === armedAt) {
+            // EXACTLY the event that armed the guard (same live-token reading): let it
+            // through once, then block normally from the next event onward. An exact
+            // match (not <=) is required so a genuinely lower or different live reading
+            // on a later event is still blocked.
+            armedOnEvent.delete(runtime);
+            return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Record that a compaction fired at `liveBefore` tokens (call on the firing event). */
+export function markCompactionFired(runtime, liveBefore) {
+    try {
+        if (Number.isFinite(liveBefore) && liveBefore > 0) {
+            sessionBefore.set(runtime, { liveBefore });
+        }
+    }
+    catch {
+        /* non-fatal */
+    }
+}
+/**
+ * Consume a pending live-window delta on a subsequent context event. If a
+ * compaction fired on a prior event, compare THIS event's live tokens against
+ * that pre-fire baseline; an ineffective reduction arms the guard. The pending
+ * marker is consumed exactly once (cleared before any re-arm). No-op when no
+ * compaction is pending, when the umbrella flag is OFF, or on any error.
+ */
+export function evaluatePendingReduction(runtime, currentTokens, config) {
+    if (!config.threeWayFailback)
+        return;
+    const pending = sessionBefore.get(runtime);
+    if (pending == null)
+        return;
+    try {
+        sessionBefore.delete(runtime); // consume once, regardless of verdict
+        const verdict = ReductionValidator.validateReduction(pending.liveBefore, currentTokens);
+        if (!verdict.effective) {
+            // Remember which event armed us so the consult later in THIS SAME event
+            // does not swallow it (see armedOnEvent).
+            armedOnEvent.set(runtime, currentTokens);
+            armThrashGuard(currentTokens, config.thrashRearmPct, runtime.effectiveThreshold, runtime.currentStateDir, runtime.logger);
+        }
+    }
+    catch {
+        /* non-fatal */
+    }
+}

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

@@ -4,7 +4,8 @@ import { buildTailResult } from "./context-handler/tailResult.js";
 import { runTriggerGuard } from "./context-handler/triggerGuard.js";
 import { persistEpochAndMaintain } from "./context-handler/afterCompact.js";
 import { appendMirrorAndLedger } from "./context-handler/dbMirrorAppend.js";
-import { evaluateGate } from "./context-handler/gateCheck.js";
+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";
 /** Register the context event handler (live-trim auto-trigger). */
@@ -60,6 +61,15 @@ export function registerContextHandler(pi, runtime, config) {
                 : null) ??
             Math.round(((pct ?? 0) / 100) * (usage?.contextWindow ?? 0));
         runtime.lastCtxTokens = currentTokens ?? null;
+        // 3WF-2: consume a pending live-window delta from a prior compaction. If a
+        // compaction fired on the previous context event and the live window did
+        // not shrink, this arms the ThrashGuard (meta). No-op when none pending.
+        try {
+            evaluatePendingReduction(runtime, currentTokens ?? 0, config);
+        }
+        catch {
+            /* non-fatal */
+        }
         runtime.lastCtxPercent = pct ?? null;
         runtime.lastCtxWindow = usage?.contextWindow ?? 0;
         runtime.snapshot(ctx);
@@ -113,6 +123,17 @@ export function registerContextHandler(pi, runtime, config) {
             }
             // else: context grew enough → fall through to re-compact (cache is stale)
         }
+        // 3WF-2 ThrashGuard: refuse a NEW compaction while armed (an ineffective
+        // prior compaction left the live window unshrunk). Sits AFTER the replay
+        // block — replay is free and must stay exempt — and BEFORE debounce +
+        // 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)) {
+            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.)
         const now = Date.now();
@@ -135,6 +156,17 @@ export function registerContextHandler(pi, runtime, config) {
         // S27 DB-mirror: write checkpoint_epoch + stamp turn epochs + auto-wiki +
         // topic seed + fire-and-forget dedup. Best-effort + non-fatal.
         await persistEpochAndMaintain(runtime, config, pipeline.ran);
+        // 3WF-2: record the live-window baseline at the moment a compaction actually
+        // fired, so the NEXT context event can judge whether the window shrank. We
+        // use the LIVE currentTokens here (not ran.saved — that is the false
+        // stored-checkpoint metric the thrash bug used), matching the spec's
+        // "value observed just BEFORE that compaction fired" seam.
+        try {
+            markCompactionFired(runtime, currentTokens ?? 0);
+        }
+        catch {
+            /* non-fatal */
+        }
         // LEGACY path (rollback): v0.4.28 ctx.compact() + the no-op gate. The
         // manual compact path aborts the in-flight turn — only used behind the flag.
         // Read live from env (in addition to the load-time config) so the flag can be

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

@@ -0,0 +1,104 @@
+/**
+ * noop.ts — pi durable-compact no-op prediction (moved from compact.ts as part
+ * of the delegate-shell split; the shell re-exports the public API unchanged).
+ *
+ * See piCompactWouldNoop's JSDoc for the full rationale (predicting pi's
+ * `ctx.compact()` no-op throw before it surfaces a user-facing error).
+ */
+import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
+import { estimateBlockTokens } from "../../../src/tokens.js";
+/**
+ * Predict whether pi's `ctx.compact()` would throw a no-op error — "Already
+ * compacted" or "Nothing to compact (session too small)" — so the auto-trigger
+ * can SKIP the call instead of surfacing a hard, user-facing error.
+ *
+ * Why we can't intercept or suppress it: pi's public `compact()` computes
+ * `prepareCompaction()` and throws *before* it emits `session_before_compact`,
+ * so our handler there never runs on the no-op path. And `ctx.compact()`'s
+ * `onError` callback fires only AFTER pi has already emitted a `compaction_end`
+ * event carrying the error message (which the interactive UI renders) — so
+ * `onError` cannot mute it either. The only robust fix is to not call
+ * `ctx.compact()` when pi would no-op. (pi's own `_runAutoCompaction` path is
+ * silent on this same condition; the public path we're forced through is the
+ * one that throws.)
+ *
+ * Skipping is correct, not a compromise: by the time this runs, `runCompact()`
+ * has already persisted the recall checkpoint (Path A). The durable on-disk
+ * trim is only useful when pi can actually summarize a region; a transcript
+ * under pi's `keepRecentTokens` budget is small enough that reloading it on
+ * resume isn't a token-growth problem, so the durable trim is unnecessary
+ * there anyway.
+ *
+ * Mirrors pi's `prepareCompaction()` return-undefined conditions (compaction.js):
+ *  (1) last entry is a compaction      → "Already compacted"
+ *  (2) <2 cut-point messages since the last compaction → nothing to summarize
+ *      (a cut point = any non-toolResult message — user/assistant/bash/custom/
+ *       branchSummary/compactionSummary — matching pi's isCutPointMessage)
+ *  (3) transcript tokens since the last compaction < keepRecentTokens → pi
+ *      keeps everything → nothing to summarize
+ * `keepRecentTokens` isn't readable from the extension API, so (3) uses the pi
+ * default (20000) as a conservative floor; raise it via
+ * `MEGACOMPACT_DURABLE_TRIM_FLOOR` if you raise pi's `compact.keepRecentTokens`.
+ *
+ * Best-effort: on any read error returns true (skip) — skipping a durable trim
+ * is always safe; calling `ctx.compact()` on a no-op throws to the user.
+ */
+export function piCompactWouldNoop(ctx) {
+    try {
+        const branch = ctx.sessionManager.getBranch();
+        if (branch.length === 0)
+            return true;
+        // (1) already compacted — pi throws "Already compacted"
+        if (branch[branch.length - 1].type === "compaction")
+            return true;
+        // boundaryStart = index just after the most recent compaction entry (or 0)
+        let boundaryStart = 0;
+        for (let i = branch.length - 1; i >= 0; i--) {
+            if (branch[i].type === "compaction") {
+                boundaryStart = i + 1;
+                break;
+            }
+        }
+        void boundaryStart;
+        let cutPoints = 0;
+        let tokens = 0;
+        for (let i = boundaryStart; i < branch.length; i++) {
+            const e = branch[i];
+            if (e.type === "compaction")
+                continue;
+            let isCut = false;
+            for (const m of sessionEntryToContextMessages(e)) {
+                // pi's isCutPointMessage: every role except toolResult
+                if (m.role !== "toolResult")
+                    isCut = true;
+                const c = m.content;
+                const text = typeof c === "string" ? c
+                    : Array.isArray(c)
+                        ? c.map((b) => b?.text ?? "").join(" ")
+                        : "";
+                if (text)
+                    tokens += estimateBlockTokens(text);
+            }
+            if (isCut)
+                cutPoints++;
+        }
+        // (2) need >=2 cut points so the kept cut isn't the first message
+        if (cutPoints < 2)
+            return true;
+        // (3) transcript under pi's keepRecentTokens budget → pi keeps everything
+        if (tokens < durableTrimFloorTokens())
+            return true;
+        return false;
+    }
+    catch {
+        return true; // safe: skip the durable trim rather than risk a user-facing throw
+    }
+}
+/** pi's default keepRecentTokens (compaction settings). Override with
+ *  MEGACOMPACT_DURABLE_TRIM_FLOOR if you raise pi's compact.keepRecentTokens. */
+function durableTrimFloorTokens() {
+    const raw = process.env.MEGACOMPACT_DURABLE_TRIM_FLOOR;
+    if (raw !== undefined && Number.isFinite(Number(raw)))
+        return Number(raw);
+    return 20_000;
+}