pi-mega-compact 0.21.4 → 0.21.6

package/README.md

@@ -1,5 +1,9 @@
 # pi-mega-compact
 
+> **⚠️ LTS — patches only (2026-08-13).** This extension is maintained for bug fixes only. New feature development has moved to **[radcode](https://github.com/TheArchitectit/radcode)**, a Rust pi.dev replacement that has ported mega-compact's compaction/recall/dedup/RAPTOR stack. See [`docs/LTS.md`](docs/LTS.md) and [`docs/SUCCESSION.md`](docs/SUCCESSION.md).
+> 
+Pending public release
+> 
 A local-first context compressor for the [pi coding agent](https://github.com/earendil-works/pi). Keeps long sessions running without overflowing the context window. Local by default — no cloud, no API calls, no telemetry. Bring your own localhost embedder (Ollama, ONNX, TEI) for better semantic matches, or opt in to a remote endpoint if you need to.
 
 ## Features

package/dist/extensions/mega-config.js

@@ -10,31 +10,41 @@ import { STATE_DIR_DEFAULT } from "../src/config.js";
 import { join } from "node:path";
 import { execSync } from "node:child_process"; // guardrails-allow PREVENT-PI-004: read-only `git rev-parse` to scope the store per-repo
 /**
- * Named compaction tiers. A tier sets the token threshold at which the
- * auto-trigger persists a checkpoint; pick by how aggressively you want the
- * session trimmed. Explicit MEGACOMPACT_THRESHOLD_TOKENS always wins.
+ * Named compaction tiers — each tier sets the compaction fire point as a
+ * FRACTION of the model's context window (NOT a static token amount): the live
+ * + durable trim fire at `tier × window`, so they always fire BELOW pi's native
+ * auto-compaction (~80% of window) for any model size (200k or 1M). Pick by how
+ * aggressively you want the session trimmed. Explicit
+ * MEGACOMPACT_THRESHOLD_TOKENS always wins (`custom`, tierPct null — absolute,
+ * never percent-scaled). This is the SINGLE source of truth for tier fractions;
+ * `keyof typeof COMPACT_TIERS` is the `CompactTier` type and
+ * `raw in COMPACT_TIERS` validates a named preset name.
  */
 export const COMPACT_TIERS = {
-    low: 50_000,
-    medium: 100_000,
-    high: 200_000,
-    ultra: 1_000_000,
-    mega: 10_000_000,
-};
-/**
- * Compaction thresholds as a FRACTION of the model's context window (NOT a
- * static token amount). The live + durable trim fire at tier% of the window,
- * so they always fire BELOW pi's native auto-compaction (~80% of window) for
- * any model size (200k or 1M). `custom` (explicit MEGACOMPACT_THRESHOLD_TOKENS)
- * is NOT scaled by this map — it stays an absolute token count.
- */
-export const TIER_PCT = {
     low: 0.5,
     medium: 0.6,
     high: 0.7,
     ultra: 0.7,
     mega: 0.75,
 };
+/**
+ * Boot-fallback context window (env-overridable). Used ONLY as a display/seed
+ * placeholder before the first real context event supplies the provider's
+ * window — the live fire point (`effectiveThresholdImpl`) DEFERS (returns
+ * `+Infinity`) when the window is unknown, so this value is never a guessed
+ * gate. Default 200k keeps the display seed stable; set
+ * `MEGACOMPACT_DEFAULT_CONTEXT_WINDOW=<tokens>` to repoint it (e.g. for a
+ * 32k-model fleet the seed should reflect that).
+ */
+export const DEFAULT_CONTEXT_WINDOW = envFlag("MEGACOMPACT_DEFAULT_CONTEXT_WINDOW", 200_000);
+/**
+ * Display seed for the progress-bar "saved tokens goal" denominator. The live
+ * value grows dynamically (`run.ts`: `savedGoal = ceil(tokensSaved × 1.25)` once
+ * exceeded), so this is only the initial target before the first compaction.
+ * Derived from the low-tier fire point at the default window (no bare magic):
+ * `COMPACT_TIERS.low × DEFAULT_CONTEXT_WINDOW`. Display-only.
+ */
+export const DEFAULT_SAVED_GOAL = Math.round(COMPACT_TIERS.low * DEFAULT_CONTEXT_WINDOW);
 function envFlag(name, fallback) {
     const v = process.env[name];
     if (v == null || v === "")
@@ -52,8 +62,8 @@ function envBool(name, fallback) {
  * Resolve the effective token threshold from TIER (or explicit) env vars.
  *
  * For a named tier the returned `thresholdTokens` is a BOOT FALLBACK
- * (`round(tierPct * 200_000)`) — sane before any context event reaches the
- * runtime. The true fire point is computed per-window at runtime via
+ * (`round(tierPct * DEFAULT_CONTEXT_WINDOW)`) — sane before any context event
+ * reaches the runtime. The true fire point is computed per-window at runtime via
  * `effectiveThresholdTokens(...)`. `custom` (explicit MEGACOMPACT_THRESHOLD_TOKENS)
  * keeps `tierPct: null` and an ABSOLUTE `thresholdTokens` (never percent-scaled).
  */
@@ -66,7 +76,7 @@ function resolveThreshold() {
     }
     const raw = (process.env.MEGACOMPACT_TIER ?? "low").toLowerCase();
     const tier = (raw in COMPACT_TIERS ? raw : "low");
-    let tierPct = TIER_PCT[tier];
+    let tierPct = COMPACT_TIERS[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;
@@ -80,8 +90,9 @@ function resolveThreshold() {
     // 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);
+    // companion under the umbrella.) Env-overridable via
+    // MEGACOMPACT_DEFAULT_CONTEXT_WINDOW (see DEFAULT_CONTEXT_WINDOW).
+    const thresholdTokens = Math.round(tierPct * DEFAULT_CONTEXT_WINDOW);
     return { tier, tierPct, thresholdTokens };
 }
 /** Clamp `n` into [lo, hi]; non-finite → fallback. */
@@ -115,8 +126,11 @@ export function effectiveThresholdTokens(opts) {
  * Resolve the optional manual arming-floor override (MEGACOMPACT_FAST_GATE_PCT).
  * Kept for backward-compat: when unset, the default arming floor equals the
  * tier's percent threshold (tierPct*100) so the dashboard stays consistent;
- * `custom` (tierPct null) falls back to the legacy 70% default.
+ * `custom` (tierPct null — an explicit absolute opt-out of percent scaling by
+ * design) has no tier fraction to derive from, so it falls back to the named
+ * DEFAULT_FAST_GATE_PCT_CUSTOM. Env-overridable like every other default here.
  */
+export const DEFAULT_FAST_GATE_PCT_CUSTOM = 70;
 function resolveFastGatePct(tierPct) {
     const raw = process.env.MEGACOMPACT_FAST_GATE_PCT;
     if (raw != null && raw !== "") {
@@ -124,7 +138,7 @@ function resolveFastGatePct(tierPct) {
         if (Number.isFinite(n))
             return n;
     }
-    return tierPct != null ? Math.round(tierPct * 100) : 70;
+    return tierPct != null ? Math.round(tierPct * 100) : DEFAULT_FAST_GATE_PCT_CUSTOM;
 }
 /**
  * Pressure helpers for adaptive compression live in src/config.ts (pi-agnostic)
@@ -193,6 +207,9 @@ export function loadConfig() {
         memoryAutoReview: envBool("MEGACOMPACT_MEMORY_AUTO_REVIEW", true),
         memoryReviewInterval: envFlag("MEGACOMPACT_MEMORY_REVIEW_INTERVAL", 10),
         recallMaxTokens: envFlag("MEGACOMPACT_RECALL_MAX_TOKENS", 1500),
+        // Phase H: output-error catch — trip compaction on a truncated model output
+        // (S28 stopReason==='length'). Default ON; OFF byte-identical pre-H.
+        outputErrorCompact: envBool("MEGACOMPACT_OUTPUT_ERROR_COMPACT", true),
         windowDedupe: envBool("MEGACOMPACT_WINDOW_DEDUPE", true),
         recallTailInject: envBool("MEGACOMPACT_RECALL_TAIL_INJECT", true),
         // 3WF-1: TriggerGuard — guarantee a staged recall block on every context

package/dist/extensions/mega-events/agent-handlers/turnEndHandler/lengthStop.js

@@ -7,6 +7,13 @@ export function lengthStop(event, runtime, config) {
         event.message.role === "assistant" &&
         event.message.stopReason === "length") {
         runtime.rt.lengthStopPending = true;
+        // Phase H: output-error catch — ALSO arm the one-shot force-compact flag so
+        // the next compaction gate trips immediately, freeing input headroom for
+        // the model's next response. Gated by config.outputErrorCompact (default
+        // ON; OFF = byte-identical pre-H — only the S28 auto-continue nudge fires).
+        if (config.outputErrorCompact) {
+            runtime.rt.forceCompactNextGate = true;
+        }
         runtime.dashboard.event("length_stop", { turnIndex: event.turnIndex });
     }
 }

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

@@ -50,6 +50,23 @@ export function evaluateGate(runtime, config, opts) {
             : DEFAULT_FIRE_POINT_PCT,
         stateDir: runtime.currentStateDir,
     });
+    // Phase H: output-error catch. A truncated model output (S28
+    // stopReason==='length' — "Response was truncated before completion") trips
+    // a one-shot force-compact so the next compaction runs IMMEDIATELY, freeing
+    // input headroom for the model's next response. This closes the
+    // small-context-model deadlock: the model truncates MID-OUTPUT below the
+    // 80% INPUT threshold (so the gate never fires) → "compact never" → every
+    // subsequent response also truncates. lengthStop.ts sets this flag
+    // alongside its auto-continue nudge; gated by config.outputErrorCompact
+    // (default ON; OFF = byte-identical pre-H). One-shot: cleared on consumption.
+    // thrashGuardBlocks is consulted separately by the handler; in the reported
+    // "compact never" case compactCount===0 so the guard is never armed and will
+    // not block this trip.
+    if (config.outputErrorCompact && runtime.rt?.forceCompactNextGate) {
+        runtime.rt.forceCompactNextGate = false;
+        runtime.diagCtxOutputErrorTrip++;
+        return { kind: "proceed", perModelThreshold };
+    }
     // S29 FAST GATE: `custom` (absolute MEGACOMPACT_THRESHOLD_TOKENS,
     // tierPct null) is an explicit opt-out of percent scaling — it keeps the
     // token gate. When pct is unavailable (window unknown / a model that

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

@@ -99,6 +99,23 @@ export function registerContextHandler(pi, runtime, config) {
         // S27 DB-mirror + VC1B ledger append. Runs BEFORE the fast-gate so every
         // message is captured, even if we don't compact this turn. Non-fatal.
         appendMirrorAndLedger(runtime, config, messages);
+        // Phase H.1: output-error catch noop guard. When forceCompactNextGate is
+        // armed (Phase H: model truncated its output → lengthStop.ts set the flag
+        // at turn_end), check piCompactWouldNoop BEFORE evaluateGate consumes the
+        // flag. If pi would noop (session too small to summarize — the transcript
+        // is under pi's keepRecentTokens floor), clear the flag + return the tail
+        // result silently instead of forcing a proceed that will throw "Nothing
+        // to compact (session too small)" to the user. The session is genuinely
+        // too small to compact — skipping is correct (the model retries on the
+        // next turn regardless). Gated by config.outputErrorCompact (default ON;
+        // OFF = byte-identical pre-H.1).
+        if (config.outputErrorCompact &&
+            runtime.rt.forceCompactNextGate &&
+            piCompactWouldNoop(ctx)) {
+            runtime.rt.forceCompactNextGate = false;
+            runtime.diagCtxOutputErrorTrip++;
+            return tailResult() ?? undefined;
+        }
         // S29 FAST GATE: drive the auto-trigger off the context percent (see
         // gateCheck.ts). Returns a tailed view when the gate does not pass.
         const gate = evaluateGate(runtime, config, { pct, currentTokens, tailResult });

package/dist/extensions/mega-runtime/helpers.js

@@ -67,6 +67,7 @@ export function createSessionRuntime() {
         recallInjections: 0,
         cacheHitTokens: 0,
         lengthStopPending: false,
+        forceCompactNextGate: false,
         errorRetryCount: 0,
         errorRetryUntil: 0,
         consecutiveErrors: 0,

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

@@ -51,16 +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) {
+    // 3WF-2 threshold invariant (LTS-correctness fix, Phase C): a tiered config
+    // (tierPct != null) with an UNKNOWN window (lastCtxWindow <= 0) DEFERS —
+    // auto-compaction must never substitute a guessed window, under ANY umbrella
+    // state. 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. This closes the small-context-model deadlock: umbrella-OFF
+    // previously fell through to the legacy 200k helper (round(tierPct × 200k)),
+    // which is unreachable on a 32k window → the model truncates before the gate
+    // ever fires → "compact never". custom (tierPct null) always falls through
+    // to the explicit absolute.
+    if (self.config.tierPct != null && self.lastCtxWindow <= 0) {
         return Number.POSITIVE_INFINITY;
     }
     return effectiveThresholdTokens({

package/dist/extensions/mega-runtime/reset-runtime.js

@@ -9,6 +9,7 @@
  * runtime-helpers.ts.
  */
 import { normalizeSessionId } from "../../src/store.js";
+import { DEFAULT_SAVED_GOAL } from "../mega-config.js";
 // --------------------------------------------------------------- resetRuntime
 export function resetRuntimeImpl(self, sessionId) {
     // Only call normalizeSessionId when a real sessionId string is passed.
@@ -37,6 +38,7 @@ export function resetRuntimeImpl(self, sessionId) {
         recallInjections: 0,
         cacheHitTokens: 0,
         lengthStopPending: false,
+        forceCompactNextGate: false,
         errorRetryCount: 0,
         errorRetryUntil: 0,
         consecutiveErrors: 0,
@@ -60,7 +62,7 @@ export function resetRuntimeImpl(self, sessionId) {
     self.tierTrace = undefined;
     self.ticker.length = 0;
     self.pulsing = false;
-    self.savedGoal = 50_000;
+    self.savedGoal = DEFAULT_SAVED_GOAL;
     self.lastWhy = undefined;
     // S31 audit P2: symmetry with bindRepo — a reset can coincide with a context
     // that re-binds the repo, so drop the memo too. Cheap; the next

package/dist/extensions/mega-runtime/runtime-instrumentation.js

@@ -1,3 +1,4 @@
+import { DEFAULT_SAVED_GOAL } from "../mega-config.js";
 /**
  * DIAG counters for the "team run doesn't relieve context" investigation.
  * Plain integers, incremented at the three compaction decision points. They
@@ -21,6 +22,7 @@ export class RuntimeInstrumentation {
     diagCtxRunSkipped = 0; // runCompact() returned skipped
     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
     // Context health instrumentation (v0.12): rolling ring buffers for
     // drift detection + cache poison Layer 1 hash baseline.
     recentTurnEmbeddings = [];
@@ -110,7 +112,10 @@ export class RuntimeInstrumentation {
     memoriesTouchedThisCompaction = 0;
     // Rolling "saved" goal for the progress bar — grows as we save more, so the
     // bar always has a meaningful denominator (never sits at 100% forever).
-    savedGoal = 50_000;
+    // Seeded from the %-derived DEFAULT_SAVED_GOAL (low-tier fire point at the
+    // default context window); resetRuntime re-seeds from the live
+    // effectiveThreshold when the window is known. Display-only.
+    savedGoal = DEFAULT_SAVED_GOAL;
     // Last explain-why line (dedup reason / anchor-kept / superseded), surfaced
     // while fresh.
     lastWhy = undefined;

package/dist/src/compact-summary.js

@@ -0,0 +1,99 @@
+function truncate(s, max) {
+    return s.length <= max ? s : `${s.slice(0, max)}…`;
+}
+function summarizeBlock(m) {
+    if (m.role === "tool")
+        return `tool_result ${m.toolName ?? "?"}: ${truncate(m.output ?? m.text, 160)}`;
+    if (m.toolName)
+        return `tool_use ${m.toolName}(${truncate(m.input ?? "", 160)})`;
+    return truncate(m.text, 160);
+}
+function stripTag(block, tag) {
+    const start = `<${tag}>`;
+    const end = `</${tag}>`;
+    const s = block.indexOf(start);
+    const e = block.indexOf(end);
+    if (s === -1 || e === -1)
+        return block;
+    return block.slice(0, s) + block.slice(e + end.length);
+}
+function extractTag(block, tag) {
+    const s = block.indexOf(`<${tag}>`);
+    const e = block.indexOf(`</${tag}>`);
+    if (s === -1 || e === -1)
+        return undefined;
+    return block.slice(s + `<${tag}>`.length, e);
+}
+/** Normalize a raw summary into user-facing "Summary: ..." text. */
+export function formatCompactSummary(summary) {
+    const withoutAnalysis = stripTag(summary, "analysis");
+    let formatted = withoutAnalysis;
+    const content = extractTag(withoutAnalysis, "summary");
+    if (content !== undefined) {
+        formatted = withoutAnalysis.replace(`<summary>${content}</summary>`, `Summary:\n${content.trim()}`);
+    }
+    return formatted.replace(/\n{3,}/g, "\n\n").trim();
+}
+/** Extract the prior "highlights" + "timeline" sections from an existing summary. */
+export function extractSummaryHighlights(summary) {
+    const lines = formatCompactSummary(summary).split("\n");
+    const out = [];
+    let inTimeline = false;
+    for (const line of lines) {
+        const t = line.trimEnd();
+        if (!t || t === "Summary:" || t === "Conversation summary:")
+            continue;
+        if (t === "- Key timeline:") {
+            inTimeline = true;
+            continue;
+        }
+        if (inTimeline)
+            continue;
+        out.push(t);
+    }
+    return out;
+}
+export function extractSummaryTimeline(summary) {
+    const lines = formatCompactSummary(summary).split("\n");
+    const out = [];
+    let inTimeline = false;
+    for (const line of lines) {
+        const t = line.trimEnd();
+        if (t === "- Key timeline:") {
+            inTimeline = true;
+            continue;
+        }
+        if (!inTimeline)
+            continue;
+        if (!t)
+            break;
+        out.push(t);
+    }
+    return out;
+}
+/** Merge an existing compact summary with a new one (accumulate, don't overwrite). */
+export function mergeCompactSummaries(existing, newSummary) {
+    if (!existing)
+        return newSummary;
+    const prevHighlights = extractSummaryHighlights(existing);
+    const newHighlights = extractSummaryHighlights(formatCompactSummary(newSummary));
+    const newTimeline = extractSummaryTimeline(formatCompactSummary(newSummary));
+    const lines = ["<summary>", "Conversation summary:"];
+    if (prevHighlights.length) {
+        lines.push("- Previously compacted context:");
+        prevHighlights.forEach((l) => lines.push(`  ${l}`));
+    }
+    if (newHighlights.length) {
+        lines.push("- Newly compacted context:");
+        newHighlights.forEach((l) => lines.push(`  ${l}`));
+    }
+    if (newTimeline.length) {
+        lines.push("- Key timeline:");
+        newTimeline.forEach((l) => lines.push(`  ${l}`));
+    }
+    lines.push("</summary>");
+    return lines.join("\n");
+}
+// Private helpers re-exported for the shell's summarizeMessages (which stays
+// in compact.ts because it depends on the inference helpers there).
+export { truncate, summarizeBlock };

package/dist/src/compact.js

@@ -7,14 +7,19 @@
  * Pure, pi-agnostic, deterministic, no LLM required.
  */
 import { estimateSessionTokens } from "./tokens.js";
+// Summary tag/format/merge helpers live in the compact-summary sibling (delegate-
+// shell split, Phase D follow-up) so this file stays under the 300-line soft
+// limit. truncate + summarizeBlock are re-imported here because summarizeMessages
+// (kept below) depends on them alongside the inference helpers that stay here.
+import { truncate, summarizeBlock, formatCompactSummary, } from "./compact-summary.js";
+// Re-export the public summary API so external consumers importing from
+// `../compact.js` are unchanged by the split.
+export { formatCompactSummary, mergeCompactSummaries } from "./compact-summary.js";
 const INTERESTING_EXT = new Set(["rs", "ts", "tsx", "js", "json", "md"]);
 const PENDING_WORDS = ["todo", "next", "pending", "follow up", "remaining"];
 const COMPACT_PREAMBLE = "This session is being continued from a previous conversation that ran out of context. The summary below covers the earlier portion of the conversation.\n\n";
 const RECENT_NOTE = "Recent messages are preserved verbatim.";
 const DIRECT_RESUME = "Continue the conversation from where it left off without asking the user any further questions. Resume directly — do not acknowledge the summary, do not recap what was happening, and do not preface with continuation text.";
-function truncate(s, max) {
-    return s.length <= max ? s : `${s.slice(0, max)}…`;
-}
 function firstText(m) {
     // PREVENT crash: pi can hand us a message with text: undefined (pure
     // tool-call/tool-result). Guard the trim so the legacy summarizeMessages
@@ -99,40 +104,6 @@ export function collectRecentUserRequests(messages, limit) {
         .map((t) => truncate(t, 160));
     return reqs.slice(-limit);
 }
-/** Summarize a block to a one-line description. */
-function summarizeBlock(m) {
-    if (m.role === "tool")
-        return `tool_result ${m.toolName ?? "?"}: ${truncate(m.output ?? m.text, 160)}`;
-    if (m.toolName)
-        return `tool_use ${m.toolName}(${truncate(m.input ?? "", 160)})`;
-    return truncate(m.text, 160);
-}
-function stripTag(block, tag) {
-    const start = `<${tag}>`;
-    const end = `</${tag}>`;
-    const s = block.indexOf(start);
-    const e = block.indexOf(end);
-    if (s === -1 || e === -1)
-        return block;
-    return block.slice(0, s) + block.slice(e + end.length);
-}
-function extractTag(block, tag) {
-    const s = block.indexOf(`<${tag}>`);
-    const e = block.indexOf(`</${tag}>`);
-    if (s === -1 || e === -1)
-        return undefined;
-    return block.slice(s + `<${tag}>`.length, e);
-}
-/** Normalize a raw summary into user-facing "Summary: ..." text. */
-export function formatCompactSummary(summary) {
-    const withoutAnalysis = stripTag(summary, "analysis");
-    let formatted = withoutAnalysis;
-    const content = extractTag(withoutAnalysis, "summary");
-    if (content !== undefined) {
-        formatted = withoutAnalysis.replace(`<summary>${content}</summary>`, `Summary:\n${content.trim()}`);
-    }
-    return formatted.replace(/\n{3,}/g, "\n\n").trim();
-}
 /**
  * Build a <summary> block from a slice of messages (the COLLAPSE output).
  * Mirrors claw-code summarize_messages.
@@ -175,66 +146,6 @@ export function summarizeMessages(messages) {
     lines.push("</summary>");
     return lines.join("\n");
 }
-/** Extract the prior "highlights" + "timeline" sections from an existing summary. */
-function extractSummaryHighlights(summary) {
-    const lines = formatCompactSummary(summary).split("\n");
-    const out = [];
-    let inTimeline = false;
-    for (const line of lines) {
-        const t = line.trimEnd();
-        if (!t || t === "Summary:" || t === "Conversation summary:")
-            continue;
-        if (t === "- Key timeline:") {
-            inTimeline = true;
-            continue;
-        }
-        if (inTimeline)
-            continue;
-        out.push(t);
-    }
-    return out;
-}
-function extractSummaryTimeline(summary) {
-    const lines = formatCompactSummary(summary).split("\n");
-    const out = [];
-    let inTimeline = false;
-    for (const line of lines) {
-        const t = line.trimEnd();
-        if (t === "- Key timeline:") {
-            inTimeline = true;
-            continue;
-        }
-        if (!inTimeline)
-            continue;
-        if (!t)
-            break;
-        out.push(t);
-    }
-    return out;
-}
-/** Merge an existing compact summary with a new one (accumulate, don't overwrite). */
-export function mergeCompactSummaries(existing, newSummary) {
-    if (!existing)
-        return newSummary;
-    const prevHighlights = extractSummaryHighlights(existing);
-    const newHighlights = extractSummaryHighlights(formatCompactSummary(newSummary));
-    const newTimeline = extractSummaryTimeline(formatCompactSummary(newSummary));
-    const lines = ["<summary>", "Conversation summary:"];
-    if (prevHighlights.length) {
-        lines.push("- Previously compacted context:");
-        prevHighlights.forEach((l) => lines.push(`  ${l}`));
-    }
-    if (newHighlights.length) {
-        lines.push("- Newly compacted context:");
-        newHighlights.forEach((l) => lines.push(`  ${l}`));
-    }
-    if (newTimeline.length) {
-        lines.push("- Key timeline:");
-        newTimeline.forEach((l) => lines.push(`  ${l}`));
-    }
-    lines.push("</summary>");
-    return lines.join("\n");
-}
 /** True when the compactable portion exceeds the budget. */
 export function shouldCompact(messages, maxEstimatedTokens, preserveRecent) {
     if (messages.length <= preserveRecent)
@@ -242,8 +153,13 @@ export function shouldCompact(messages, maxEstimatedTokens, preserveRecent) {
     const compactable = messages.slice(0, messages.length - preserveRecent);
     return estimateSessionTokens(compactable) >= maxEstimatedTokens;
 }
-/** Local reimplementation of memory-mcp auto_compact_check. */
-export function autoCompactCheck(currentTokens, threshold = 50000) {
+/** Local reimplementation of memory-mcp auto_compact_check.
+ *
+ * `threshold` is REQUIRED (no default) — every caller (gateCheck.ts) passes the
+ * resolved `gateThreshold` (effectiveThresholdImpl: `tierPct × window`, or the
+ * custom absolute). A bare default here would silently re-introduce a hardcoded
+ * magic-number gate that bypasses the percent-based fire point. */
+export function autoCompactCheck(currentTokens, threshold) {
     return {
         shouldCompact: currentTokens >= threshold,
         currentTokens,

package/extensions/mega-config-types.ts

@@ -133,6 +133,14 @@ export interface MegaConfig {
 	 *  adding checkpoints once the block would exceed this — bounds read-path
 	 *  token cost so it can never net-inflate the window. */
 	recallMaxTokens: number;
+	/** Phase H: output-error catch. When a model response is truncated mid-OUTPUT
+	 *  (S28 stopReason==='length' — "Response was truncated before completion"),
+	 *  trip a one-shot forced compaction on the next gate so the model's NEXT
+	 *  response has freed input headroom. This closes the small-context-model
+	 *  deadlock where the model truncates BELOW the 80% INPUT threshold (so the
+	 *  gate never fires → "compact never" → every subsequent response truncates
+	 *  too). Default ON; OFF (=0/`=false`) = byte-identical pre-H. */
+	outputErrorCompact: boolean;
 	/** Inline-dedupe recalled checkpoints against the live window (Fix C): drop
 	 *  a hit whose summary is ≥ dedupSim similar to a live message — "dedupe on
 	 *  inline/read" so we never re-inject context already resident. */

package/extensions/mega-config.ts

@@ -13,33 +13,49 @@ import { execSync } from "node:child_process"; // guardrails-allow PREVENT-PI-00
 import type { MegaConfig } from "./mega-config-types.js";
 
 /**
- * Named compaction tiers. A tier sets the token threshold at which the
- * auto-trigger persists a checkpoint; pick by how aggressively you want the
- * session trimmed. Explicit MEGACOMPACT_THRESHOLD_TOKENS always wins.
+ * Named compaction tiers — each tier sets the compaction fire point as a
+ * FRACTION of the model's context window (NOT a static token amount): the live
+ * + durable trim fire at `tier × window`, so they always fire BELOW pi's native
+ * auto-compaction (~80% of window) for any model size (200k or 1M). Pick by how
+ * aggressively you want the session trimmed. Explicit
+ * MEGACOMPACT_THRESHOLD_TOKENS always wins (`custom`, tierPct null — absolute,
+ * never percent-scaled). This is the SINGLE source of truth for tier fractions;
+ * `keyof typeof COMPACT_TIERS` is the `CompactTier` type and
+ * `raw in COMPACT_TIERS` validates a named preset name.
  */
 export const COMPACT_TIERS = {
-	low: 50_000,
-	medium: 100_000,
-	high: 200_000,
-	ultra: 1_000_000,
-	mega: 10_000_000,
-} as const;
-export type CompactTier = keyof typeof COMPACT_TIERS;
-
-/**
- * Compaction thresholds as a FRACTION of the model's context window (NOT a
- * static token amount). The live + durable trim fire at tier% of the window,
- * so they always fire BELOW pi's native auto-compaction (~80% of window) for
- * any model size (200k or 1M). `custom` (explicit MEGACOMPACT_THRESHOLD_TOKENS)
- * is NOT scaled by this map — it stays an absolute token count.
- */
-export const TIER_PCT: Record<CompactTier, number> = {
 	low: 0.5,
 	medium: 0.6,
 	high: 0.7,
 	ultra: 0.7,
 	mega: 0.75,
-};
+} as const;
+export type CompactTier = keyof typeof COMPACT_TIERS;
+
+/**
+ * Boot-fallback context window (env-overridable). Used ONLY as a display/seed
+ * placeholder before the first real context event supplies the provider's
+ * window — the live fire point (`effectiveThresholdImpl`) DEFERS (returns
+ * `+Infinity`) when the window is unknown, so this value is never a guessed
+ * gate. Default 200k keeps the display seed stable; set
+ * `MEGACOMPACT_DEFAULT_CONTEXT_WINDOW=<tokens>` to repoint it (e.g. for a
+ * 32k-model fleet the seed should reflect that).
+ */
+export const DEFAULT_CONTEXT_WINDOW = envFlag(
+	"MEGACOMPACT_DEFAULT_CONTEXT_WINDOW",
+	200_000,
+);
+
+/**
+ * Display seed for the progress-bar "saved tokens goal" denominator. The live
+ * value grows dynamically (`run.ts`: `savedGoal = ceil(tokensSaved × 1.25)` once
+ * exceeded), so this is only the initial target before the first compaction.
+ * Derived from the low-tier fire point at the default window (no bare magic):
+ * `COMPACT_TIERS.low × DEFAULT_CONTEXT_WINDOW`. Display-only.
+ */
+export const DEFAULT_SAVED_GOAL = Math.round(
+	COMPACT_TIERS.low * DEFAULT_CONTEXT_WINDOW,
+);
 
 // MegaConfig type moved to mega-config-types.ts (delegate-shell split, PC-A)
 // so this runtime config barrel stays under the 400-line soft limit.
@@ -60,8 +76,8 @@ function envBool(name: string, fallback: boolean): boolean {
  * Resolve the effective token threshold from TIER (or explicit) env vars.
  *
  * For a named tier the returned `thresholdTokens` is a BOOT FALLBACK
- * (`round(tierPct * 200_000)`) — sane before any context event reaches the
- * runtime. The true fire point is computed per-window at runtime via
+ * (`round(tierPct * DEFAULT_CONTEXT_WINDOW)`) — sane before any context event
+ * reaches the runtime. The true fire point is computed per-window at runtime via
  * `effectiveThresholdTokens(...)`. `custom` (explicit MEGACOMPACT_THRESHOLD_TOKENS)
  * keeps `tierPct: null` and an ABSOLUTE `thresholdTokens` (never percent-scaled).
  */
@@ -78,7 +94,7 @@ function resolveThreshold(): {
 	}
 	const raw = (process.env.MEGACOMPACT_TIER ?? "low").toLowerCase();
 	const tier = (raw in COMPACT_TIERS ? raw : "low") as CompactTier;
-	let tierPct = TIER_PCT[tier];
+	let tierPct: number = COMPACT_TIERS[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;
@@ -92,8 +108,9 @@ function resolveThreshold(): {
 	// 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);
+	// companion under the umbrella.) Env-overridable via
+	// MEGACOMPACT_DEFAULT_CONTEXT_WINDOW (see DEFAULT_CONTEXT_WINDOW).
+	const thresholdTokens = Math.round(tierPct * DEFAULT_CONTEXT_WINDOW);
 	return { tier, tierPct, thresholdTokens };
 }
 
@@ -133,15 +150,19 @@ export function effectiveThresholdTokens(opts: {
  * Resolve the optional manual arming-floor override (MEGACOMPACT_FAST_GATE_PCT).
  * Kept for backward-compat: when unset, the default arming floor equals the
  * tier's percent threshold (tierPct*100) so the dashboard stays consistent;
- * `custom` (tierPct null) falls back to the legacy 70% default.
+ * `custom` (tierPct null — an explicit absolute opt-out of percent scaling by
+ * design) has no tier fraction to derive from, so it falls back to the named
+ * DEFAULT_FAST_GATE_PCT_CUSTOM. Env-overridable like every other default here.
  */
+export const DEFAULT_FAST_GATE_PCT_CUSTOM = 70;
+
 function resolveFastGatePct(tierPct: number | null): number {
 	const raw = process.env.MEGACOMPACT_FAST_GATE_PCT;
 	if (raw != null && raw !== "") {
 		const n = Number(raw);
 		if (Number.isFinite(n)) return n;
 	}
-	return tierPct != null ? Math.round(tierPct * 100) : 70;
+	return tierPct != null ? Math.round(tierPct * 100) : DEFAULT_FAST_GATE_PCT_CUSTOM;
 }
 
 /**
@@ -229,6 +250,9 @@ export function loadConfig(): MegaConfig {
 		memoryAutoReview: envBool("MEGACOMPACT_MEMORY_AUTO_REVIEW", true),
 		memoryReviewInterval: envFlag("MEGACOMPACT_MEMORY_REVIEW_INTERVAL", 10),
 		recallMaxTokens: envFlag("MEGACOMPACT_RECALL_MAX_TOKENS", 1500),
+		// Phase H: output-error catch — trip compaction on a truncated model output
+		// (S28 stopReason==='length'). Default ON; OFF byte-identical pre-H.
+		outputErrorCompact: envBool("MEGACOMPACT_OUTPUT_ERROR_COMPACT", true),
 		windowDedupe: envBool("MEGACOMPACT_WINDOW_DEDUPE", true),
 		recallTailInject: envBool("MEGACOMPACT_RECALL_TAIL_INJECT", true),
 		// 3WF-1: TriggerGuard — guarantee a staged recall block on every context

package/extensions/mega-events/agent-handlers/turnEndHandler/lengthStop.ts

@@ -24,6 +24,13 @@ export function lengthStop(
 		event.message.stopReason === "length"
 	) {
 		runtime.rt.lengthStopPending = true;
+		// Phase H: output-error catch — ALSO arm the one-shot force-compact flag so
+		// the next compaction gate trips immediately, freeing input headroom for
+		// the model's next response. Gated by config.outputErrorCompact (default
+		// ON; OFF = byte-identical pre-H — only the S28 auto-continue nudge fires).
+		if (config.outputErrorCompact) {
+			runtime.rt.forceCompactNextGate = true;
+		}
 		runtime.dashboard.event("length_stop", { turnIndex: event.turnIndex });
 	}
 }

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

@@ -95,6 +95,24 @@ export function evaluateGate(
 		stateDir: runtime.currentStateDir,
 	});
 
+	// Phase H: output-error catch. A truncated model output (S28
+	// stopReason==='length' — "Response was truncated before completion") trips
+	// a one-shot force-compact so the next compaction runs IMMEDIATELY, freeing
+	// input headroom for the model's next response. This closes the
+	// small-context-model deadlock: the model truncates MID-OUTPUT below the
+	// 80% INPUT threshold (so the gate never fires) → "compact never" → every
+	// subsequent response also truncates. lengthStop.ts sets this flag
+	// alongside its auto-continue nudge; gated by config.outputErrorCompact
+	// (default ON; OFF = byte-identical pre-H). One-shot: cleared on consumption.
+	// thrashGuardBlocks is consulted separately by the handler; in the reported
+	// "compact never" case compactCount===0 so the guard is never armed and will
+	// not block this trip.
+	if (config.outputErrorCompact && runtime.rt?.forceCompactNextGate) {
+		runtime.rt.forceCompactNextGate = false;
+		runtime.diagCtxOutputErrorTrip++;
+		return { kind: "proceed", perModelThreshold };
+	}
+
 	// S29 FAST GATE: `custom` (absolute MEGACOMPACT_THRESHOLD_TOKENS,
 	// tierPct null) is an explicit opt-out of percent scaling — it keeps the
 	// token gate. When pct is unavailable (window unknown / a model that

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

@@ -130,6 +130,26 @@ export function registerContextHandler(
 		// message is captured, even if we don't compact this turn. Non-fatal.
 		appendMirrorAndLedger(runtime, config, messages);
 
+		// Phase H.1: output-error catch noop guard. When forceCompactNextGate is
+		// armed (Phase H: model truncated its output → lengthStop.ts set the flag
+		// at turn_end), check piCompactWouldNoop BEFORE evaluateGate consumes the
+		// flag. If pi would noop (session too small to summarize — the transcript
+		// is under pi's keepRecentTokens floor), clear the flag + return the tail
+		// result silently instead of forcing a proceed that will throw "Nothing
+		// to compact (session too small)" to the user. The session is genuinely
+		// too small to compact — skipping is correct (the model retries on the
+		// next turn regardless). Gated by config.outputErrorCompact (default ON;
+		// OFF = byte-identical pre-H.1).
+		if (
+			config.outputErrorCompact &&
+			runtime.rt.forceCompactNextGate &&
+			piCompactWouldNoop(ctx)
+		) {
+			runtime.rt.forceCompactNextGate = false;
+			runtime.diagCtxOutputErrorTrip++;
+			return tailResult() ?? undefined;
+		}
+
 		// S29 FAST GATE: drive the auto-trigger off the context percent (see
 		// gateCheck.ts). Returns a tailed view when the gate does not pass.
 		const gate = evaluateGate(runtime, config, { pct, currentTokens, tailResult });

package/extensions/mega-runtime/helpers.ts

@@ -51,6 +51,10 @@ export interface SessionRuntime {
 	recallInjections: number; // recall blocks injected this session-instance
 	cacheHitTokens: number; // tokens saved via cache hits (dedup + recall) this session
 	lengthStopPending: boolean; // S28: set on turn_end when stopReason==='length'
+	/** Phase H: one-shot flag set alongside lengthStopPending (S28) so the next
+	 *  compaction gate trips immediately regardless of input-pressure. Cleared on
+	 *  consumption by evaluateGate (gateCheck.ts). See config.outputErrorCompact. */
+	forceCompactNextGate: boolean;
 	errorRetryCount: number; // S38: consecutive error turns, reset on success/turn_start
 	errorRetryUntil: number; // S38: wall-clock ms before which the next nudge is suppressed (R1: now gating)
 	// S38.6: circuit-breaker state — consecutive error turns across the session.
@@ -141,6 +145,7 @@ export function createSessionRuntime(): SessionRuntime {
 		recallInjections: 0,
 		cacheHitTokens: 0,
 		lengthStopPending: false,
+		forceCompactNextGate: false,
 		errorRetryCount: 0,
 		errorRetryUntil: 0,
 		consecutiveErrors: 0,

package/extensions/mega-runtime/pressure-getters.ts

@@ -81,18 +81,18 @@ export function pressureImpl(self: PressureContext): number {
  * always below pi's native auto-compaction (~80% of window).
  */
 export function effectiveThresholdImpl(self: PressureContext): number {
-	// 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
-	) {
+	// 3WF-2 threshold invariant (LTS-correctness fix, Phase C): a tiered config
+	// (tierPct != null) with an UNKNOWN window (lastCtxWindow <= 0) DEFERS —
+	// auto-compaction must never substitute a guessed window, under ANY umbrella
+	// state. 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. This closes the small-context-model deadlock: umbrella-OFF
+	// previously fell through to the legacy 200k helper (round(tierPct × 200k)),
+	// which is unreachable on a 32k window → the model truncates before the gate
+	// ever fires → "compact never". custom (tierPct null) always falls through
+	// to the explicit absolute.
+	if (self.config.tierPct != null && self.lastCtxWindow <= 0) {
 		return Number.POSITIVE_INFINITY;
 	}
 	return effectiveThresholdTokens({

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

@@ -13,6 +13,7 @@ import { normalizeSessionId } from "../../src/store.js";
 import type { TickerEntry } from "./widget.js";
 import type { GameState } from "../../src/store/sqlite.js";
 import type { SessionRuntime } from "./helpers.js";
+import { DEFAULT_SAVED_GOAL } from "../mega-config.js";
 
 // ---------------------------------------------------------------------- types
 
@@ -67,6 +68,7 @@ export function resetRuntimeImpl(
 		recallInjections: 0,
 		cacheHitTokens: 0,
 		lengthStopPending: false,
+		forceCompactNextGate: false,
 		errorRetryCount: 0,
 		errorRetryUntil: 0,
 		consecutiveErrors: 0,
@@ -90,7 +92,7 @@ export function resetRuntimeImpl(
 	self.tierTrace = undefined;
 	self.ticker.length = 0;
 	self.pulsing = false;
-	self.savedGoal = 50_000;
+	self.savedGoal = DEFAULT_SAVED_GOAL;
 	self.lastWhy = undefined;
 	// S31 audit P2: symmetry with bindRepo — a reset can coincide with a context
 	// that re-binds the repo, so drop the memo too. Cheap; the next

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

@@ -13,6 +13,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { ModelSnapshot, GameState } from "../../src/store/sqlite.js";
 import type { TickerEntry, WidgetData } from "./widget.js";
 import type { FSWatcher } from "node:fs";
+import { DEFAULT_SAVED_GOAL } from "../mega-config.js";
 
 /**
  * DIAG counters for the "team run doesn't relieve context" investigation.
@@ -37,6 +38,7 @@ export class RuntimeInstrumentation {
 	diagCtxRunSkipped = 0; // runCompact() returned skipped
 	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
 
 	// Context health instrumentation (v0.12): rolling ring buffers for
 	// drift detection + cache poison Layer 1 hash baseline.
@@ -137,7 +139,10 @@ export class RuntimeInstrumentation {
 	memoriesTouchedThisCompaction = 0;
 	// Rolling "saved" goal for the progress bar — grows as we save more, so the
 	// bar always has a meaningful denominator (never sits at 100% forever).
-	savedGoal = 50_000;
+	// Seeded from the %-derived DEFAULT_SAVED_GOAL (low-tier fire point at the
+	// default context window); resetRuntime re-seeds from the live
+	// effectiveThreshold when the window is known. Display-only.
+	savedGoal = DEFAULT_SAVED_GOAL;
 	// Last explain-why line (dedup reason / anchor-kept / superseded), surfaced
 	// while fresh.
 	lastWhy: string | undefined = undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.21.4",
+  "version": "0.21.6",
   "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/compact-summary.ts

@@ -0,0 +1,120 @@
+/**
+ * compact-summary.ts — summary tag helpers, formatting, and merging (Layer 2).
+ *
+ * Extracted from compact.ts (delegate-shell split, Phase D follow-up) so
+ * compact.ts stays under the 300-line soft limit without squeezing. These
+ * functions form a cohesive unit: they all operate on the `<summary>…</summary>`
+ * tag block produced by the COLLAPSE output and consumed by the continuation
+ * message builder. Kept pi-agnostic (only `EngineMessage` type imported).
+ */
+import type { EngineMessage } from "./types.js";
+
+function truncate(s: string, max: number): string {
+	return s.length <= max ? s : `${s.slice(0, max)}…`;
+}
+
+function summarizeBlock(m: EngineMessage): string {
+	if (m.role === "tool")
+		return `tool_result ${m.toolName ?? "?"}: ${truncate(m.output ?? m.text, 160)}`;
+	if (m.toolName)
+		return `tool_use ${m.toolName}(${truncate(m.input ?? "", 160)})`;
+	return truncate(m.text, 160);
+}
+
+function stripTag(block: string, tag: string): string {
+	const start = `<${tag}>`;
+	const end = `</${tag}>`;
+	const s = block.indexOf(start);
+	const e = block.indexOf(end);
+	if (s === -1 || e === -1) return block;
+	return block.slice(0, s) + block.slice(e + end.length);
+}
+
+function extractTag(block: string, tag: string): string | undefined {
+	const s = block.indexOf(`<${tag}>`);
+	const e = block.indexOf(`</${tag}>`);
+	if (s === -1 || e === -1) return undefined;
+	return block.slice(s + `<${tag}>`.length, e);
+}
+
+/** Normalize a raw summary into user-facing "Summary: ..." text. */
+export function formatCompactSummary(summary: string): string {
+	const withoutAnalysis = stripTag(summary, "analysis");
+	let formatted = withoutAnalysis;
+	const content = extractTag(withoutAnalysis, "summary");
+	if (content !== undefined) {
+		formatted = withoutAnalysis.replace(
+			`<summary>${content}</summary>`,
+			`Summary:\n${content.trim()}`,
+		);
+	}
+	return formatted.replace(/\n{3,}/g, "\n\n").trim();
+}
+
+/** Extract the prior "highlights" + "timeline" sections from an existing summary. */
+export function extractSummaryHighlights(summary: string): string[] {
+	const lines = formatCompactSummary(summary).split("\n");
+	const out: string[] = [];
+	let inTimeline = false;
+	for (const line of lines) {
+		const t = line.trimEnd();
+		if (!t || t === "Summary:" || t === "Conversation summary:") continue;
+		if (t === "- Key timeline:") {
+			inTimeline = true;
+			continue;
+		}
+		if (inTimeline) continue;
+		out.push(t);
+	}
+	return out;
+}
+
+export function extractSummaryTimeline(summary: string): string[] {
+	const lines = formatCompactSummary(summary).split("\n");
+	const out: string[] = [];
+	let inTimeline = false;
+	for (const line of lines) {
+		const t = line.trimEnd();
+		if (t === "- Key timeline:") {
+			inTimeline = true;
+			continue;
+		}
+		if (!inTimeline) continue;
+		if (!t) break;
+		out.push(t);
+	}
+	return out;
+}
+
+/** Merge an existing compact summary with a new one (accumulate, don't overwrite). */
+export function mergeCompactSummaries(
+	existing: string | undefined,
+	newSummary: string,
+): string {
+	if (!existing) return newSummary;
+	const prevHighlights = extractSummaryHighlights(existing);
+	const newHighlights = extractSummaryHighlights(
+		formatCompactSummary(newSummary),
+	);
+	const newTimeline = extractSummaryTimeline(formatCompactSummary(newSummary));
+
+	const lines = ["<summary>", "Conversation summary:"];
+	if (prevHighlights.length) {
+		lines.push("- Previously compacted context:");
+		prevHighlights.forEach((l) => lines.push(`  ${l}`));
+	}
+	if (newHighlights.length) {
+		lines.push("- Newly compacted context:");
+		newHighlights.forEach((l) => lines.push(`  ${l}`));
+	}
+	if (newTimeline.length) {
+		lines.push("- Key timeline:");
+		newTimeline.forEach((l) => lines.push(`  ${l}`));
+	}
+	lines.push("</summary>");
+	return lines.join("\n");
+}
+
+// Private helpers re-exported for the shell's summarizeMessages (which stays
+// in compact.ts because it depends on the inference helpers there).
+export { truncate, summarizeBlock };

package/src/compact.ts

@@ -9,6 +9,18 @@
 
 import type { EngineMessage } from "./types.js";
 import { estimateSessionTokens } from "./tokens.js";
+// Summary tag/format/merge helpers live in the compact-summary sibling (delegate-
+// shell split, Phase D follow-up) so this file stays under the 300-line soft
+// limit. truncate + summarizeBlock are re-imported here because summarizeMessages
+// (kept below) depends on them alongside the inference helpers that stay here.
+import {
+	truncate,
+	summarizeBlock,
+	formatCompactSummary,
+} from "./compact-summary.js";
+// Re-export the public summary API so external consumers importing from
+// `../compact.js` are unchanged by the split.
+export { formatCompactSummary, mergeCompactSummaries } from "./compact-summary.js";
 
 const INTERESTING_EXT = new Set(["rs", "ts", "tsx", "js", "json", "md"]);
 const PENDING_WORDS = ["todo", "next", "pending", "follow up", "remaining"];
@@ -19,10 +31,6 @@ const RECENT_NOTE = "Recent messages are preserved verbatim.";
 const DIRECT_RESUME =
 	"Continue the conversation from where it left off without asking the user any further questions. Resume directly — do not acknowledge the summary, do not recap what was happening, and do not preface with continuation text.";
 
-function truncate(s: string, max: number): string {
-	return s.length <= max ? s : `${s.slice(0, max)}…`;
-}
-
 function firstText(m: EngineMessage): string | undefined {
 	// PREVENT crash: pi can hand us a message with text: undefined (pure
 	// tool-call/tool-result). Guard the trim so the legacy summarizeMessages
@@ -113,45 +121,6 @@ export function collectRecentUserRequests(
 	return reqs.slice(-limit);
 }
 
-/** Summarize a block to a one-line description. */
-function summarizeBlock(m: EngineMessage): string {
-	if (m.role === "tool")
-		return `tool_result ${m.toolName ?? "?"}: ${truncate(m.output ?? m.text, 160)}`;
-	if (m.toolName)
-		return `tool_use ${m.toolName}(${truncate(m.input ?? "", 160)})`;
-	return truncate(m.text, 160);
-}
-
-function stripTag(block: string, tag: string): string {
-	const start = `<${tag}>`;
-	const end = `</${tag}>`;
-	const s = block.indexOf(start);
-	const e = block.indexOf(end);
-	if (s === -1 || e === -1) return block;
-	return block.slice(0, s) + block.slice(e + end.length);
-}
-
-function extractTag(block: string, tag: string): string | undefined {
-	const s = block.indexOf(`<${tag}>`);
-	const e = block.indexOf(`</${tag}>`);
-	if (s === -1 || e === -1) return undefined;
-	return block.slice(s + `<${tag}>`.length, e);
-}
-
-/** Normalize a raw summary into user-facing "Summary: ..." text. */
-export function formatCompactSummary(summary: string): string {
-	const withoutAnalysis = stripTag(summary, "analysis");
-	let formatted = withoutAnalysis;
-	const content = extractTag(withoutAnalysis, "summary");
-	if (content !== undefined) {
-		formatted = withoutAnalysis.replace(
-			`<summary>${content}</summary>`,
-			`Summary:\n${content.trim()}`,
-		);
-	}
-	return formatted.replace(/\n{3,}/g, "\n\n").trim();
-}
-
 /**
  * Build a <summary> block from a slice of messages (the COLLAPSE output).
  * Mirrors claw-code summarize_messages.
@@ -200,70 +169,6 @@ export function summarizeMessages(messages: EngineMessage[]): string {
 	return lines.join("\n");
 }
 
-/** Extract the prior "highlights" + "timeline" sections from an existing summary. */
-function extractSummaryHighlights(summary: string): string[] {
-	const lines = formatCompactSummary(summary).split("\n");
-	const out: string[] = [];
-	let inTimeline = false;
-	for (const line of lines) {
-		const t = line.trimEnd();
-		if (!t || t === "Summary:" || t === "Conversation summary:") continue;
-		if (t === "- Key timeline:") {
-			inTimeline = true;
-			continue;
-		}
-		if (inTimeline) continue;
-		out.push(t);
-	}
-	return out;
-}
-
-function extractSummaryTimeline(summary: string): string[] {
-	const lines = formatCompactSummary(summary).split("\n");
-	const out: string[] = [];
-	let inTimeline = false;
-	for (const line of lines) {
-		const t = line.trimEnd();
-		if (t === "- Key timeline:") {
-			inTimeline = true;
-			continue;
-		}
-		if (!inTimeline) continue;
-		if (!t) break;
-		out.push(t);
-	}
-	return out;
-}
-
-/** Merge an existing compact summary with a new one (accumulate, don't overwrite). */
-export function mergeCompactSummaries(
-	existing: string | undefined,
-	newSummary: string,
-): string {
-	if (!existing) return newSummary;
-	const prevHighlights = extractSummaryHighlights(existing);
-	const newHighlights = extractSummaryHighlights(
-		formatCompactSummary(newSummary),
-	);
-	const newTimeline = extractSummaryTimeline(formatCompactSummary(newSummary));
-
-	const lines = ["<summary>", "Conversation summary:"];
-	if (prevHighlights.length) {
-		lines.push("- Previously compacted context:");
-		prevHighlights.forEach((l) => lines.push(`  ${l}`));
-	}
-	if (newHighlights.length) {
-		lines.push("- Newly compacted context:");
-		newHighlights.forEach((l) => lines.push(`  ${l}`));
-	}
-	if (newTimeline.length) {
-		lines.push("- Key timeline:");
-		newTimeline.forEach((l) => lines.push(`  ${l}`));
-	}
-	lines.push("</summary>");
-	return lines.join("\n");
-}
-
 /** True when the compactable portion exceeds the budget. */
 export function shouldCompact(
 	messages: EngineMessage[],
@@ -275,10 +180,15 @@ export function shouldCompact(
 	return estimateSessionTokens(compactable) >= maxEstimatedTokens;
 }
 
-/** Local reimplementation of memory-mcp auto_compact_check. */
+/** Local reimplementation of memory-mcp auto_compact_check.
+ *
+ * `threshold` is REQUIRED (no default) — every caller (gateCheck.ts) passes the
+ * resolved `gateThreshold` (effectiveThresholdImpl: `tierPct × window`, or the
+ * custom absolute). A bare default here would silently re-introduce a hardcoded
+ * magic-number gate that bypasses the percent-based fire point. */
 export function autoCompactCheck(
 	currentTokens: number,
-	threshold = 50000,
+	threshold: number,
 ): {
 	shouldCompact: boolean;
 	currentTokens: number;