pi-mega-compact 0.20.84 → 0.20.86

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

@@ -1,345 +1,14 @@
 /**
- * compact.ts — full compaction pipeline (Trident) + pi no-op prediction.
- *
- * `runCompact` runs the full Trident pipeline (fast-gate aside) and persists a
- * checkpoint. `piCompactWouldNoop` predicts whether pi's `ctx.compact()` would
- * throw a no-op error. Both mutate the shared MegaRuntime (token accounting,
- * ticker, status, events) and are driven by the event + command handlers in
- * mega-events.ts / mega-commands.ts.
- */
-import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
-import { compactSession } from "../../src/engine.js";
-import { normalizeSessionId } from "../../src/store.js";
-import { repoKey } from "../../src/store/repoKey.js";
-import { estimateBlockTokens } from "../../src/tokens.js";
-import { touchSession, logDaily, incCompactCount, incCacheHitTokens } from "../../src/store/sqlite.js";
-import { consolidateMemories } from "../../src/memory.js";
-import { C, MARKER_TYPE, } from "../mega-runtime.js";
-import { resolveRepoRoot, preserveRecentForPressure } from "../mega-config.js";
-import { runRaptor } from "../../src/dedup/raptor/index.js";
-import { isRaptorTreeFresh } from "../../src/dedup/raptor/buildHistory.js";
-import { loadDedupConfig } from "../../src/config/dedup.js";
-import { upsertEmbedding as indexUpsertEmbedding } from "../../src/store/vectorIndex.js";
-import { runMemoryReview } from "./memory-review.js";
-import { vectorList } from "../../src/vectorStore.js";
-/** Run the full compaction pipeline and persist a checkpoint. Returns the result. */
-export function runCompact(pi, runtime, config, ctx, messages, opts = {}) {
-    runtime.bindRepo(ctx.cwd);
-    const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
-    runtime.resetRuntime(sid);
-    runtime.rt.sessionId = sid;
-    const view = runtime.engineView(messages);
-    // keepFrom deepens with context pressure (Fix E): under high pressure we
-    // compact more of the session, down to the preserveRecentMin floor.
-    const preserve = preserveRecentForPressure(opts.compressionPressure ?? 0, config.preserveRecent, config.preserveRecentMin);
-    const keepFrom = opts.keepFrom ?? Math.max(0, view.length - preserve);
-    // For very small sessions (fewer messages than preserveRecent), allow
-    // compacting everything except the last message — the user explicitly
-    // requested compaction, so don't refuse it just because the session is short.
-    if (keepFrom <= 0) {
-        if (view.length <= 1)
-            return { skipped: true };
-        // Use the fallback: compact everything except the last message
-        const fallbackKeepFrom = view.length - 1;
-        return doCompact(view, fallbackKeepFrom, opts, sid, config, pi, ctx, runtime);
-    }
-    return doCompact(view, keepFrom, opts, sid, config, pi, ctx, runtime);
-}
-function doCompact(view, keepFrom, opts, sid, config, pi, ctx, runtime) {
-    runtime.pulsing = true; // animate the status line while the (sync) pipeline runs
-    runtime.setEffect?.("pulse", "accent", 1500); // v0.8.3: ambient border pulse during compaction
-    // S21.2: reset the per-compaction memory-op counter so the post-compact
-    // consolidate pass only fires when memory rows actually changed during the
-    // compaction window (turn_end → auto-review may have written some).
-    runtime.memoriesTouchedThisCompaction = 0;
-    const result = compactSession({
-        sessionId: sid,
-        messages: view,
-        keepFrom,
-        summary: opts.summary,
-        timestamp: Date.now(),
-        onTier: runtime.makeTierCallback(ctx),
-        compressionPressure: opts.compressionPressure,
-    }, runtime.store);
-    runtime.pulsing = false;
-    if (result.skipped)
-        return { skipped: true };
-    if (!result.deduped) {
-        runtime.rt.persistedThisSession = true;
-        runtime.rt.lastCheckpointId = result.checkpointId;
-    }
-    runtime.rt.lastCompactedFrom = result.compactedFrom;
-    runtime.rt.lastCompactedTokens = result.tokenEstimate;
-    runtime.rt.dedupAttempts++;
-    // Honest "tokens saved" for this session-instance only:
-    //   new checkpoint      → original − stored
-    //   deduped onto existing → whole original region (nothing new stored)
-    // Resets to 0 on session_start (rt is rebuilt) — so a fresh session shows 0
-    // while the repo's cumulative saved (SQLite meta) keeps the running total.
-    const saved = result.deduped
-        ? result.originalTokenEstimate
-        : Math.max(0, result.originalTokenEstimate - result.tokenEstimate);
-    runtime.rt.tokensSaved += saved;
-    runtime.rt.compactCount += 1;
-    incCompactCount(runtime.currentStateDir);
-    if (result.deduped) {
-        runtime.rt.cacheHitTokens += saved;
-        incCacheHitTokens(saved, runtime.currentStateDir);
-    }
-    runtime.rt.lastCompactAt = Date.now();
-    if (result.deduped)
-        runtime.rt.dedupSkips++;
-    // Grow the rolling "saved" goal so the progress bar always has a fresh
-    // denominator (we don't want it pinned at 100% once we pass an old target).
-    if (runtime.rt.tokensSaved > runtime.savedGoal)
-        runtime.savedGoal = Math.ceil((runtime.rt.tokensSaved * 1.25) / 10_000) * 10_000;
-    // Live toolbar activity: what file/region just got compacted or deduped.
-    // Rendered via the rotating ticker line (see snapshot); the ring buffer is
-    // cycled one-per-repaint so the single line scrolls through recent files.
-    const files = result.filesModified ?? [];
-    const fileLabel = files.length
-        ? files.map((f) => f.split("/").pop() ?? f).slice(0, 2).join(", ")
-        : result.regionHash.slice(0, 8);
-    runtime.lastActivityAt = Date.now();
-    // Explain-why line: surfaced while fresh. Pulls the dedup reason (which for
-    // L2 includes the cosine sim) so the user sees WHY a region was kept/dropped.
-    runtime.lastWhy = result.deduped
-        ? `why: deduped@${result.dedupReason ?? "tier"}`
-        : `why: compacted → ${result.checkpointId}`;
-    // Recall/activity ticker: record this event in the ring buffer.
-    const savedK = (saved / 1000).toFixed(1);
-    runtime.pushTicker(result.deduped
-        ? `${C.green}♻${C.reset} deduped ${fileLabel} · ${savedK}k saved`
-        : `${C.cyan}🗜${C.reset} ${result.checkpointId} · +${savedK}k · ${fileLabel}`);
-    // The per-tier trace has settled into the final outcome — fold it back into
-    // the activity line and stop showing the live trace.
-    runtime.tierTrace = undefined;
-    // Record session activity + a daily-log entry in the per-repo SQLite store
-    // (foundation for resume-sessions / daily-log features). Best-effort — never
-    // block a compaction on bookkeeping.
-    try {
-        const root = resolveRepoRoot(ctx.cwd);
-        touchSession(sid, root, runtime.currentStateDir);
-        logDaily(sid, "compact", result.checkpointId, saved, runtime.currentStateDir);
-    }
-    catch {
-        /* non-fatal: stats bookkeeping only */
-    }
-    // S21.2: best-effort consolidation of near-duplicate memories for this repo.
-    // Runs after the per-repo stats touch so `consolidateMemories` can use the
-    // same stateDir. Non-fatal — a failed consolidate never blocks a compaction.
-    // Only runs when new memory ops landed in this pass (otherwise the prior
-    // compaction's consolidate already had its shot — re-running would just
-    // touch every row again with no merges).
-    if (!result.deduped && runtime.memoriesTouchedThisCompaction > 0) {
-        try {
-            const root = resolveRepoRoot(ctx.cwd);
-            void consolidateMemories(runtime.currentStateDir, root).then((n) => {
-                if (n > 0)
-                    runtime.pushTicker(`${C.green}∫${C.reset} consolidated ${n} memory dup${n === 1 ? "" : "s"}`);
-            }, () => {
-                /* swallow: consolidate failures must never surface to the user */
-            });
-        }
-        catch {
-            /* non-fatal */
-        }
-    }
-    // S24 review-on-compact: when pressure is high, the just-compacted region is
-    // exactly the context worth remembering, so review it immediately rather than
-    // waiting for the next turn-cadence tick. Uses the shared runMemoryReview
-    // helper (fire-and-forget; doCompact is sync). Best-effort + non-fatal. Only
-    // fires above the `high` band so low-pressure compactions don't pay the cost.
-    if (!result.deduped && config.memoryAutoReview && runtime.pressureBand !== "low" && runtime.pressureBand !== "medium") {
-        void runMemoryReview(runtime, view, "pressure");
-    }
-    // Sentinel marker: a non-LLM bookkeeping entry so subsequent triggers can
-    // skip re-vectorizing an already-compacted region (zero token cost).
-    // v0.8.6: gate on !result.deduped so the marker ONLY lands when a genuinely
-    // new checkpoint was created. Without this, every dedup re-fire appended a
-    // fresh sentinel to the real transcript, bloating it and perturbing the
-    // provider KV-cache prefix (the alternating cache-miss regression). Matches
-    // the RAPTOR + vector-index blocks above, which are already !deduped-gated.
-    if (!result.deduped) {
-        pi.appendEntry(MARKER_TYPE, {
-            checkpointId: result.checkpointId,
-            regionHash: result.regionHash,
-            tokenEstimate: result.tokenEstimate,
-            deduped: result.deduped,
-        });
-    }
-    // Fix D: refresh the RAPTOR tree for this session so live recall (search) can
-    // serve high-level summaries. Best-effort + non-fatal: never block compaction.
-    // Budget-guarded (RAPTOR_BUDGET_MS) so it can't hang a large session.
-    if (config.raptorEnabled && !result.deduped) {
-        try {
-            const dd = loadDedupConfig();
-            const all = vectorList(runtime.store, sid);
-            const leaves = all.map((cp) => ({
-                id: cp.checkpointId,
-                messages: [],
-                sourceText: cp.normalizedText ?? cp.summary ?? cp.regionHash,
-                embedding: cp.embedding,
-            }));
-            if (leaves.length >= 2) {
-                // S42D: skip the rebuild when the last build is fresh (within
-                // RAPTOR_FRESHNESS_HOURS) and the checkpoint count hasn't drifted by
-                // more than 20%. avoids re-clustering on every compaction when the
-                // tree is still representative. 0 disables (always rebuild).
-                if (dd.RAPTOR_FRESHNESS_HOURS > 0 &&
-                    isRaptorTreeFresh(sid, runtime.currentStateDir, dd.RAPTOR_FRESHNESS_HOURS, all.length)) {
-                    runtime.logger?.info("raptor_skip_fresh", { sessionId: sid });
-                }
-                else {
-                    // S25: stamp the tree with the newest checkpoint epoch so the
-                    // freshness guard in raptorSearchHits can reject stale trees after a
-                    // later compaction adds newer checkpoints.
-                    const builtAt = all.length > 0 ? Math.max(...all.map((c) => c.timestamp)) : Date.now();
-                    runRaptor(leaves, {
-                        stateDir: runtime.currentStateDir,
-                        sessionId: sid,
-                        budgetMs: dd.RAPTOR_BUDGET_MS,
-                        clustersPerLevel: dd.RAPTOR_CLUSTERS_PER_LEVEL,
-                        consistencyThreshold: dd.RAPTOR_CONSISTENCY,
-                        logger: runtime.logger,
-                        builtAt: Number.isFinite(builtAt) ? builtAt : Date.now(),
-                    });
-                }
-            }
-        }
-        catch {
-            /* non-fatal: tree refresh never blocks a compaction */
-        }
-    }
-    // Slice 2: best-effort mirror of the new checkpoint into the async global
-    // PGlite/HNSW vector index. Fires once per compaction (not per-add), so the
-    // shared global dir is never hammered by concurrent test workers.
-    // Non-fatal: a WASM init failure degrades to the sync scan silently.
-    if (!result.deduped) {
-        try {
-            const all = vectorList(runtime.store, sid);
-            const latest = all.find((cp) => cp.checkpointId === result.checkpointId);
-            if (latest?.embedding) {
-                void indexUpsertEmbedding(repoKey(runtime.currentStateDir), sid, latest.checkpointId, latest.embedding).catch(() => {
-                    /* non-fatal: index refresh never blocks a compaction */
-                });
-            }
-        }
-        catch {
-            /* non-fatal: index refresh never blocks a compaction */
-        }
-    }
-    runtime.setStatus(ctx, runtime.rt.persistedThisSession
-        ? `mega-compact: ${result.checkpointId} · ${saved} tok saved`
-        : `mega-compact: ready`);
-    runtime.logger.info("compact", {
-        sessionId: sid,
-        checkpointId: result.checkpointId ?? "(deduped)",
-        deduped: result.deduped,
-        tokenEstimate: saved,
-        compactedFrom: result.compactedFrom,
-    });
-    runtime.dashboard.event("compact", {
-        sessionId: sid,
-        checkpointId: result.checkpointId ?? "(deduped)",
-        deduped: result.deduped,
-        tokenEstimate: saved,
-        compactedFrom: result.compactedFrom,
-    });
-    runtime.snapshot(ctx);
-    return { skipped: false, result, keepFrom, saved };
-}
-/**
- * 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.
+ * compact.ts — delegate-shell for the compaction pipeline (3WF-2 split).
+ *
+ * This file is now a thin barrel: the real bodies live in `./compact/` so the
+ * module stays well under the extensions/ 400-line soft cap. The public API is
+ * UNCHANGED — every existing importer (via `../mega-pipeline.js`, which does
+ * `export * from "./mega-pipeline/compact.js"`) keeps working with ZERO changes
+ * at their call sites. Exports preserved exactly:
+ *   - `RunCompactResult` (type)
+ *   - `runCompact`
+ *   - `piCompactWouldNoop`
  */
-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;
-            }
-        }
-        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;
-}
+export { runCompact } from "./compact/run.js";
+export { piCompactWouldNoop } from "./compact/noop.js";

package/dist/extensions/mega-runtime/pressure-getters.js

@@ -51,6 +51,18 @@ export function pressureImpl(self) {
  * always below pi's native auto-compaction (~80% of window).
  */
 export function effectiveThresholdImpl(self) {
+    // 3WF-2 threshold invariant: under the umbrella, a tiered config with an
+    // UNKNOWN window (lastCtxWindow <= 0) DEFERS — auto-compaction must never
+    // substitute a guessed window. Returning +Infinity keeps every downstream
+    // `tokens >= threshold` comparison false (gateCheck token path,
+    // agent_end durable trigger, live-trim re-compact), so no compaction fires
+    // until the provider reports a real window. custom (tierPct null) and
+    // umbrella-OFF fall through to the legacy helper (byte-identical).
+    if (self.config.threeWayFailback &&
+        self.config.tierPct != null &&
+        self.lastCtxWindow <= 0) {
+        return Number.POSITIVE_INFINITY;
+    }
     return effectiveThresholdTokens({
         tierPct: self.config.tierPct,
         fallbackThreshold: self.config.thresholdTokens,

package/dist/src/failback/compact.js

@@ -0,0 +1,109 @@
+/**
+ * src/failback/compact.ts — 3WF-2 candidate-veto + vote module (pure, advisory).
+ *
+ * The production bug this fixes: compaction "succeeded" (a checkpoint was
+ * persisted, `saved` grew) while the LIVE WINDOW (`currentTokens`) never
+ * shrank — because `saved` is a cumulative SQLite total, not the working-set
+ * delta. This module builds competing summary candidates (extractive vs
+ * cluster/raptor) and VOTES which one, if any, is worth replacing the
+ * supersede-only result. It is purely advisory/observational: it never mutates
+ * a checkpoint, never overwrites `result.summary`, and returning `null` means
+ * "keep the supersede-only result" — the caller must NOT substitute a summary.
+ *
+ * Pure: no store mutation, no I/O, no network, no console.*. pi-agnostic
+ * (imports only from src/). Designed for the 3WF umbrella flag gate at the
+ * extension layer (see extensions/mega-pipeline/compact/vote.ts).
+ */
+import { collectRecentUserRequests, summarizeMessages } from "../compact.js";
+import { summarizeCluster } from "../dedup/raptor/summarizer.js";
+import { estimateBlockTokens } from "../tokens.js";
+/**
+ * Default floor (tokens of net reduction) below which a candidate vote is
+ * REJECTED, returning `null` (keep the supersede-only result).
+ *
+ * Rationale: a candidate that reduces the region by fewer than 1 token is not
+ * meaningfully smaller than the compacted region it would replace — swapping
+ * the supersede-only result for it buys nothing and only adds a (possibly
+ * less faithful) summary. The floor therefore requires the voted summary to be
+ * STRICTLY smaller than the compacted region. Set to 1 (minimally defensible:
+ * the summary must actually be smaller). Overridable via `opts.floor`.
+ */
+export const DEFAULT_VOTE_FLOOR_TOKENS = 1;
+/** Strip a trailing ellipsis/truncation marker from a needle before containment. */
+function stripEllipsis(s) {
+    // collectRecentUserRequests truncates to 160 chars via compact.ts's truncate,
+    // which appends the U+2026 ellipsis when it cuts. Drop it for a fair test.
+    return s.replace(/…\s*$/u, "").trim();
+}
+/** Normalize for containment: collapse whitespace, lowercase. */
+function normalize(s) {
+    return s.replace(/\s+/g, " ").trim().toLowerCase();
+}
+/** True when `summary` contains the content of EVERY recent user request. */
+export function signalPreserved(summary, messages) {
+    const requests = collectRecentUserRequests(messages, 3);
+    if (requests.length === 0)
+        return true; // nothing to preserve
+    const haystack = normalize(summary);
+    return requests.every((r) => haystack.includes(normalize(stripEllipsis(r))));
+}
+/**
+ * Build the two competing candidates (extractive + cluster/raptor) for a
+ * compacted message region. Degenerate (empty/whitespace-only) summaries are
+ * VETOED — never returned. Both candidates use estimateBlockTokens(summary) for
+ * a single consistent token basis so the vote compares like with like (the
+ * cluster path's own tokenEstimate is intentionally ignored for fairness).
+ */
+export function buildCandidates(messages) {
+    const out = [];
+    const extractive = summarizeMessages(messages);
+    if (extractive.trim().length > 0) {
+        out.push({
+            source: "extractive",
+            summary: extractive,
+            tokenEstimate: estimateBlockTokens(extractive),
+            signalPreserved: signalPreserved(extractive, messages),
+        });
+    }
+    // summarizeCluster returns deterministic extractive when MEGACOMPACT_RAPTOR_MODEL
+    // is unset and the local-only Ollama variant when set — so using it makes the
+    // Ollama path an insertion that adds NO new LLM call site for the on-by-default
+    // extraction. No behavior change for the default config.
+    const cluster = summarizeCluster(messages).summary;
+    if (cluster.trim().length > 0) {
+        out.push({
+            source: "cluster",
+            summary: cluster,
+            tokenEstimate: estimateBlockTokens(cluster),
+            signalPreserved: signalPreserved(cluster, messages),
+        });
+    }
+    return out;
+}
+/**
+ * Vote the best candidate. `score = reduction * (signalPreserved ? 1 : 0.5)`
+ * where `reduction = tokensBefore - candidate.tokenEstimate`. Ties resolve to
+ * the EARLIER (extractive) candidate for determinism. Returns `null` when the
+ * winner's score is below `opts.floor` (default DEFAULT_VOTE_FLOOR_TOKENS) —
+ * caller MUST keep the supersede-only result and must NOT substitute a summary.
+ */
+export function voteCandidate(messages, tokensBefore, opts = {}) {
+    const floor = opts.floor ?? DEFAULT_VOTE_FLOOR_TOKENS;
+    const candidates = buildCandidates(messages);
+    let best = null;
+    let bestScore = -Infinity;
+    for (const c of candidates) {
+        const reduction = tokensBefore - c.tokenEstimate;
+        const score = reduction * (c.signalPreserved ? 1 : 0.5);
+        // Earlier candidate wins ties (strict > keeps insertion order = extractive first).
+        if (score > bestScore) {
+            bestScore = score;
+            best = c;
+        }
+    }
+    if (best === null)
+        return null;
+    if (bestScore < floor)
+        return null;
+    return best;
+}

package/dist/src/store/sqlite/meta.js

@@ -36,6 +36,38 @@ export function getMetaNumber(key, stateDir = getStateDir()) {
     const n = raw == null ? 0 : Number(raw);
     return Number.isFinite(n) ? n : 0;
 }
+/**
+ * Upsert a single numeric meta key to an absolute value (NOT a cumulative
+ * counter). Follows the `addTokensSaved` INSERT-ON-CONFLICT pattern with a
+ * fully parameterized query (PREVENT-002: no SQL string concat — `key` and
+ * `value` are both bound, never interpolated). The only write is the standard
+ * ON CONFLICT upsert of THIS key's own value; no other key is touched, no
+ * DELETE is issued.
+ *
+ * Used by the 3WF-2 ThrashGuard to persist exactly two keys:
+ *  - `thrasguard.baseline_tokens` — the live-window token count at the moment
+ *    an ineffective compaction was observed (the baseline the guard re-arms from).
+ *  - `thrasguard.blocked_until` — the live-window token count below which
+ *    re-firing is refused (guard active).
+ *
+ * Non-finite input (NaN / ±Infinity) is rejected: the extension must never
+ * persist a non-number into the meta table (getMetaNumber would read it back as
+ * 0), so we return early, non-fatal. Best-effort: any store failure is swallowed.
+ */
+export function setMetaNumber(key, value, stateDir = getStateDir()) {
+    if (key.length === 0)
+        return;
+    if (!Number.isFinite(value))
+        return;
+    try {
+        const db = openStore(stateDir);
+        db.prepare(`INSERT INTO meta(key, value) VALUES(?, ?)
+       ON CONFLICT(key) DO UPDATE SET value = ?`).run(key, String(value), String(value));
+    }
+    catch {
+        /* non-fatal: meta writes never break the agent loop */
+    }
+}
 /** Atomically add `delta` to an integer meta counter. */
 function incMeta(key, delta, stateDir = getStateDir()) {
     if (!(delta > 0))

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

@@ -274,6 +274,27 @@ export const SETTINGS: ReadonlyArray<SettingGroup> = [
 			num("MEGACOMPACT_EMBEDDING_CHARS_PER_TOKEN", "Embedding Chars per Token", "Estimated characters per token used for embedder chunking size", 4, 1, 32),
 		],
 	},
+	{
+		name: "Compaction",
+		settings: [
+			num(
+				"MEGACOMPACT_THRESHOLD_PCT",
+				"Compaction Threshold",
+				"Fraction of the actual model context window at which compaction fires — 0.80 fires at 80% used (leaves 20% free). Applies to any model size; a per-model Model Thresholds row overrides it",
+				0.8,
+				0.1,
+				0.95,
+			),
+			num(
+				"MEGACOMPACT_THRASH_REARM_PCT",
+				"Thrash Re-arm %",
+				"After an ineffective compaction (live window did not shrink), refuse to re-fire until the live window grows by this fraction of the effective threshold. Default 0.10 (10%)",
+				0.1,
+				0.01,
+				0.5,
+			),
+		],
+	},
 	VECTOR_CORTEX_SETTINGS,
 	{
 		name: "Cost API",

package/extensions/mega-config-types.ts

@@ -140,6 +140,14 @@ export interface MegaConfig {
 	 *  session_start never fired, so every session has a staged block (recall hits,
 	 *  else a provenance floor). Default ON; OFF = byte-identical pre-sprint. */
 	threeWayFailback: boolean;
+	/** 3WF-2: ThrashGuard re-arm budget as a FRACTION of `effectiveThreshold`.
+	 *  After an ineffective compaction (live window did not shrink), the guard
+	 *  refuses to re-fire until the live window has grown by at least
+	 *  `rearmPct × effectiveThreshold` tokens past the observed baseline. Default
+	 *  0.10 (10% of the effective threshold). Env-overridable via
+	 *  MEGACOMPACT_THRASH_REARM_PCT. When the effective threshold is unknown
+	 *  (+Infinity), the guard skips arming (cannot compute N) and logs instead. */
+	thrashRearmPct: number;
 	/** A1 PLAN_V2 Phase 2: Message Separation — isolate user/assistant turns
 	 *  from volatile tool results so the prompt-cache prefix stays stable.
 	 *  PC-A: positive sprint flag, now default ON; flag-OFF (=0) is byte-identical

package/extensions/mega-config.ts

@@ -78,12 +78,31 @@ function resolveThreshold(): {
 	}
 	const raw = (process.env.MEGACOMPACT_TIER ?? "low").toLowerCase();
 	const tier = (raw in COMPACT_TIERS ? raw : "low") as CompactTier;
-	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: number, lo: number, hi: number): number {
+	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.
  *
@@ -206,6 +225,12 @@ export function loadConfig(): MegaConfig {
 		// 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),