pi-mega-compact 0.21.8 → 0.21.10

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

@@ -13,12 +13,9 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { EngineMessage } from "../../../src/types.js";
-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";
 import type { MegaRuntime } from "../../mega-runtime.js";
 import type { MegaConfig } from "../../mega-config.js";
 import type { TailResultFn } from "./gateCheck.js";
@@ -136,59 +133,33 @@ export function buildLiveTrimView(
 		// 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
@@ -199,8 +170,12 @@ export function buildLiveTrimView(
 			// (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
@@ -214,6 +189,11 @@ export function buildLiveTrimView(
 			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/extensions/mega-events/context-handler/pipelineRun.ts

@@ -21,6 +21,7 @@ import type { MegaConfig } from "../../mega-config.js";
 import type { TailResultFn } from "./gateCheck.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, type RolloutEvidence } from "../../../src/vector-cortex/rollout/gate.js";
 import { VC5C_ENABLED } from "../../../src/config/vector-cortex.js";
 
@@ -120,7 +121,19 @@ export function invokePipeline(
 			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/extensions/mega-events/context-handler.ts

@@ -34,6 +34,7 @@ import {
 } 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(
@@ -173,7 +174,23 @@ export function registerContextHandler(
 					: 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);
@@ -194,7 +211,7 @@ export function registerContextHandler(
 		// 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;
@@ -202,8 +219,14 @@ export function registerContextHandler(
 
 		// 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/extensions/mega-pipeline/compact/run.ts

@@ -109,10 +109,20 @@ function doCompact(
 	runtime.pulsing = false;
 
 	if (result.skipped) return { skipped: true };
-	if (!result.deduped) {
-		runtime.rt.persistedThisSession = true;
-		runtime.rt.lastCheckpointId = result.checkpointId;
-	}
+	// 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.lastCompactedFrom = result.compactedFrom;
 	runtime.rt.lastCompactedTokens = result.tokenEstimate;
 	runtime.rt.dedupAttempts++;

package/extensions/mega-runtime/dashboard-snapshot.ts

@@ -49,6 +49,8 @@ export interface SnapshotBuildContext {
 	readonly diagCtxFastGate: number;
 	readonly diagLiveTrimFires: number;
 	readonly diagLiveTrimReplays: number;
+	/** v0.21.9: output-headroom gate trips (pre-overflow compaction fires). */
+	readonly diagCtxHeadroomTrip: number;
 	readonly errorRetryCount: number;
 	readonly consecutiveErrors: number;
 	readonly ERROR_RETRY_MAX_CONSECUTIVE: number;
@@ -190,6 +192,7 @@ export function buildDashboardSnapshot(ctx: SnapshotBuildContext): DashboardSnap
 			ctxFastGate: ctx.diagCtxFastGate,
 			liveTrimFires: ctx.diagLiveTrimFires,
 			liveTrimReplays: ctx.diagLiveTrimReplays,
+			headroomTrips: ctx.diagCtxHeadroomTrip,
 		},
 		retries: {
 			errorRetryCount: ctx.errorRetryCount,

package/extensions/mega-runtime/runtime-instrumentation.ts

@@ -39,6 +39,7 @@ export class RuntimeInstrumentation {
 	diagCtxCutNull = 0; // computeLiveTrimCut returned null (anchor/boundary)
 	diagCtxThrown = 0; // live-trim try threw (caught)
 	diagCtxOutputErrorTrip = 0; // Phase H: output-error catch tripped a forced compaction
+	diagCtxHeadroomTrip = 0; // v0.21.9: output-headroom gate tripped a pre-overflow compaction
 
 	// Context health instrumentation (v0.12): rolling ring buffers for
 	// drift detection + cache poison Layer 1 hash baseline.
@@ -79,6 +80,9 @@ export class RuntimeInstrumentation {
 		summaryAgentMsg: AgentMessage;
 		ctxPct: number | null;
 		ctxTokens: number | null;
+		/** v0.21.9: safety margin % recorded at fire time so the D.2/D.3 replay
+		 *  paths can re-cap the replayed tail with the same reserve math. */
+		safetyMarginPct: number;
 	} | null = null;
 	debounceUntil = 0;
 	// S16: debounce for the agent_end resume nudge (avoid busy-loops).

package/extensions/mega-runtime/runtime-snapshot.ts

@@ -84,6 +84,7 @@ export interface RuntimeSnapshotContext extends RuntimeHelpersContext {
 	diagCtxFastGate: number;
 	diagLiveTrimFires: number;
 	diagLiveTrimReplays: number;
+	diagCtxHeadroomTrip: number;
 
 	// ── public methods the orchestration calls ──
 	bindRepo(cwd: string | undefined): string;
@@ -177,6 +178,7 @@ export function snapshotImpl(
 			diagCtxFastGate: self.diagCtxFastGate,
 			diagLiveTrimFires: self.diagLiveTrimFires,
 			diagLiveTrimReplays: self.diagLiveTrimReplays,
+			diagCtxHeadroomTrip: self.diagCtxHeadroomTrip,
 			errorRetryCount: self.rt.errorRetryCount,
 			consecutiveErrors: self.rt.consecutiveErrors,
 			ERROR_RETRY_MAX_CONSECUTIVE: self.config.maxConsecutiveErrors,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.21.8",
+  "version": "0.21.10",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",

package/src/config/dedup.ts

@@ -66,6 +66,18 @@ export interface DedupConfigShape {
   L2_COSINE_CODE: number | null;
   L2_COSINE_PROSE: number | null;
   L1_JACCARD: number; // MinHash/LSH near-dup verification
+  /**
+   * Degenerate-match guard (incident 2026-08-19). ON declines an L1/L2 collapse
+   * when the MATCHED stored checkpoint is a content-free skeleton and the
+   * incoming candidate is richer, so a degenerate checkpoint can no longer
+   * absorb every future compaction forever. OFF is byte-identical to the
+   * pre-guard cascade. See src/dedup/degenerate.ts.
+   */
+  DEDUP_DEGENERATE_GUARD: boolean;
+  /** Absolute token floor under which a stored summary counts as degenerate. */
+  DEDUP_DEGEN_MIN_TOKENS: number;
+  /** Relative floor as a fraction of the summary's original region size. */
+  DEDUP_DEGEN_MIN_PCT: number;
   DEDUP_SIM: number; // legacy content-similarity fallback
   MMR_LAMBDA: number; // retrieval diversity
   SEMDEDUP_COSINE: number; // offline SemDeDup pair threshold
@@ -123,6 +135,9 @@ export function loadDedupConfig(): DedupConfigShape {
     L2_COSINE_CODE: envNumOrNull("MEGACOMPACT_L2_THRESHOLD_CODE"),
     L2_COSINE_PROSE: envNumOrNull("MEGACOMPACT_L2_THRESHOLD_PROSE"),
     L1_JACCARD: envNum("MEGACOMPACT_L1_JACCARD", 0.8),
+    DEDUP_DEGENERATE_GUARD: envBool("MEGACOMPACT_DEDUP_DEGENERATE_GUARD", true),
+    DEDUP_DEGEN_MIN_TOKENS: envNum("MEGACOMPACT_DEDUP_DEGEN_MIN_TOKENS", 48),
+    DEDUP_DEGEN_MIN_PCT: envNum("MEGACOMPACT_DEDUP_DEGEN_MIN_PCT", 0.005),
     DEDUP_SIM: envNum("MEGACOMPACT_DEDUP_SIM", 0.9),
     MMR_LAMBDA: envNum("MEGACOMPACT_MMR_LAMBDA", 0.5),
     SEMDEDUP_COSINE: envNum("MEGACOMPACT_SEMDEDUP_COSINE", 0.95),

package/src/dedup/degenerate.ts

@@ -0,0 +1,125 @@
+/**
+ * degenerate.ts — the degenerate-checkpoint predicate + the L1/L2 collapse guard.
+ *
+ * WHY THIS EXISTS (incident 2026-08-19). A defect in the summarizer could emit a
+ * DEGENERATE summary: a ~30-40 token structural skeleton with no informational
+ * content, e.g.
+ *
+ *   "Conversation: 64 messages (5 user, 29 assistant, 27 tool). Tools: bash, edit, read."
+ *
+ * Once such a checkpoint landed in the store it became an absorbing state. Every
+ * later compaction produced a structurally identical skeleton, so L1 MinHash and
+ * L2 cosine (0.872 against a 0.85 threshold) matched it EVERY time — each add()
+ * returned `deduped: true`, discarded the incoming content, and only bumped the
+ * stored skeleton's timestamp. The store could never heal, even after the
+ * summarizer was fixed, because a rich new summary that happened to match the
+ * skeleton would still be swallowed by it.
+ *
+ * THE GUARD. When L1 or L2 finds a match, we ask whether the MATCHED (stored)
+ * checkpoint is degenerate and the incoming candidate is RICHER. If both hold, we
+ * decline the collapse and let the cascade continue as if nothing matched — so a
+ * fresh, informative checkpoint is written and the skeleton stops absorbing.
+ *
+ * Direction matters: only "poor stored ← rich incoming" is unblocked. Two equal
+ * skeletons still collapse (dedup is doing its job), and a rich stored
+ * checkpoint absorbing a poor incoming one is left alone — that is ordinary
+ * dedup, not the pathology.
+ *
+ * PREVENT-PI-004: pure arithmetic over already-loaded fields. No IO, no network.
+ */
+import type { StoredCheckpoint } from "../store.js";
+
+/** The tunables the guard reads (thread from DedupConfigShape). */
+export interface DegenerateGuardTunables {
+	/** Umbrella flag. OFF ⇒ the guard never fires (byte-identical predecessor). */
+	readonly DEDUP_DEGENERATE_GUARD: boolean;
+	/** Absolute token floor below which a stored summary is structural, not informational. */
+	readonly DEDUP_DEGEN_MIN_TOKENS: number;
+	/** Relative floor as a fraction of the ORIGINAL region the summary stands in for. */
+	readonly DEDUP_DEGEN_MIN_PCT: number;
+}
+
+/** The two fields the predicate scores. Kept structural so tests need no full row. */
+export interface DegenerateSubject {
+	tokenEstimate?: number;
+	originalTokenEstimate?: number;
+}
+
+/**
+ * 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: DegenerateSubject,
+	tunables: DegenerateGuardTunables,
+): number {
+	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: DegenerateSubject,
+	tunables: DegenerateGuardTunables,
+): boolean {
+	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: StoredCheckpoint,
+	candidate: DegenerateSubject & { contentHash?: string },
+	tunables: DegenerateGuardTunables,
+): boolean {
+	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);
+}