pi-mega-compact 0.20.85 → 0.20.86

package/extensions/mega-events/context-handler/thrashGuard.ts

@@ -0,0 +1,228 @@
+/**
+ * context-handler/thrashGuard.ts — 3WF-2 ReductionValidator + ThrashGuard.
+ *
+ * Production bug fixed here: compaction fired 496× freeing 0.0% of the live
+ * window. Root cause — correctness was judged by the STORED `saved` metric
+ * (a cumulative SQLite total that the dedup made look healthy every fire)
+ * while the LIVE context window (`currentTokens`) never shrank. This module
+ * judges correctness by the LIVE-WINDOW delta across consecutive `context`
+ * events, and after an ineffective compaction persists a meta-backed refusal
+ * so the guard will not re-fire until the window has grown meaningfully again.
+ *
+ * Everything is gated on the umbrella `config.threeWayFailback`
+ * (MEGACOMPACT_THREE_WAY_FAILBACK, default ON). Flag OFF ⇒ every entry point
+ * is an immediate no-op, so gateCheck + compactSession behave byte-identically
+ * to v0.20.83.
+ *
+ * Non-fatal EVERYWHERE: every store read/write is best-effort, swallowed on
+ * failure. Structured JSON logging only (runtime.logger.info with ts + event).
+ * No console.*, no network, no mocks.
+ */
+import type { MegaRuntime } from "../../mega-runtime.js";
+import type { MegaConfig } from "../../mega-config.js";
+import { getMetaNumber, setMetaNumber } from "../../../src/store/sqlite.js";
+import type { ReductionVerdict } from "../../../src/failback/types.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: number, liveAfter: number): ReductionVerdict {
+		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: number,
+	rearmPct: number,
+	effectiveThreshold: number,
+	stateDir: string,
+	logger?: { info(event: string, fields?: Record<string, unknown>): void },
+): void {
+	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: number, stateDir: string): boolean {
+	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<MegaRuntime, { liveBefore: number }>();
+
+/**
+ * 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<MegaRuntime, number>();
+
+/**
+ * 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: MegaRuntime,
+	currentTokens: number,
+	stateDir: string,
+): boolean {
+	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: MegaRuntime, liveBefore: number): void {
+	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: MegaRuntime,
+	currentTokens: number,
+	config: MegaConfig,
+): void {
+	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/extensions/mega-events/context-handler.ts

@@ -26,7 +26,11 @@ 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";
 
@@ -88,6 +92,14 @@ export function registerContextHandler(
 				: 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);
@@ -147,6 +159,18 @@ export function registerContextHandler(
 			// 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();
@@ -171,6 +195,17 @@ export function registerContextHandler(
 		// 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/extensions/mega-pipeline/compact/noop.ts

@@ -0,0 +1,96 @@
+/**
+ * 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 type { ExtensionContext } 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: ExtensionContext): boolean {
+	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 as { role?: string }).role !== "toolResult") isCut = true;
+				const c = (m as { content?: unknown }).content;
+				const text =
+					typeof c === "string" ? c
+						: Array.isArray(c)
+							? (c as { text?: string }[]).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(): number {
+	const raw = process.env.MEGACOMPACT_DURABLE_TRIM_FLOOR;
+	if (raw !== undefined && Number.isFinite(Number(raw))) return Number(raw);
+	return 20_000;
+}