pi-mega-compact 0.7.7 → 0.7.9

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

@@ -0,0 +1,173 @@
+import { piCompactWouldNoop, runMemoryReview, } from "../mega-pipeline.js";
+import { memoryReviewCadence, } from "../mega-config.js";
+/** Register agent/turn tracking event handlers. */
+export function registerAgentHandlers(pi, runtime, config) {
+    // ---- Agent tracking for real-time widget + status-line updates ---------
+    pi.on("agent_start", async (_event, ctx) => {
+        runtime.activeAgents++;
+        runtime.dashboard.event("agent_start", {
+            activeAgents: runtime.activeAgents,
+        });
+        // Surface live agent activity on the status line (toolbar), not just the
+        // above-editor widget — otherwise concurrent agents look frozen.
+        runtime.setStatus(ctx, `mega-compact: ▶ ${runtime.activeAgents} agent${runtime.activeAgents === 1 ? "" : "s"}`);
+        runtime.snapshot(ctx);
+    });
+    pi.on("agent_end", async (_event, ctx) => {
+        runtime.activeAgents = Math.max(0, runtime.activeAgents - 1);
+        runtime.dashboard.event("agent_end", {
+            activeAgents: runtime.activeAgents,
+        });
+        if (runtime.activeAgents > 0) {
+            runtime.setStatus(ctx, `mega-compact: ▶ ${runtime.activeAgents} agent${runtime.activeAgents === 1 ? "" : "s"}`);
+        }
+        else {
+            runtime.setStatus(ctx, config.auto ? "mega-compact: ready" : "mega-compact: manual only");
+        }
+        // S16 continuation fallback: if the turn settled idle right after a live-trim
+        // compaction AND there is queued work AND we haven't nudged recently, nudge
+        // once so the agent continues (the live trim should make this rare). Guarded
+        // to never busy-loop: one nudge per 30s, only when truly idle + queued.
+        if ((config.auto || config.autoContinueLengthStop) && runtime.activeAgents === 0) {
+            try {
+                const idle = ctx.isIdle?.() ?? true;
+                const queued = ctx.hasPendingMessages?.() ?? false;
+                const now = Date.now();
+                // DIAG (team-run relief): surface whether the agent is idle + over
+                // threshold at agent_end so we can see if a mid-run durable-trim trigger
+                // *should* have fired but didn't.
+                const overThreshold = (runtime.lastCtxTokens ?? 0) >= runtime.effectiveThreshold;
+                runtime.diagAgentEndIdle++;
+                runtime.logger.info("agent-end-idle", {
+                    sessionId: runtime.rt.sessionId,
+                    idle,
+                    queued,
+                    overThreshold,
+                    ctxPct: runtime.lastCtxPercent,
+                    ctxTokens: runtime.lastCtxTokens,
+                    thresholdTokens: config.thresholdTokens,
+                    wouldNudge: idle &&
+                        (queued || overThreshold) &&
+                        now >= runtime.resumeNudgeUntil,
+                });
+                // S16+S24: MID-RUN DURABLE TRIM. During a long team run (sub-agents),
+                // pi's native durable compaction only fires from _checkCompaction at
+                // PARENT settle (agent-session.js:760/844), so the on-disk transcript +
+                // context meter balloon to ~150k and never relieve until the very end
+                // ("compacts but doesn't resume"). agent_end with activeAgents===0 is a
+                // SAFE, settled point: calling ctx.compact() here does NOT abort an
+                // in-flight turn (the S16 danger is only mid-turn). ctx.compact() runs
+                // pi's flow, which fires our session_before_compact handler to supply
+                // the durable trim (truncates the transcript from firstKeptEntryId).
+                // Guarded three ways: only when truly idle + over threshold, only when
+                // pi would actually compact (piCompactWouldNoop skips the user-facing
+                // no-op throw), and debounced (one durable trim per 2s) to avoid
+                // thrashing the transcript while sub-agents keep settling.
+                //
+                // FIX "compacts but doesn't resume": the manual ctx.compact() path
+                // STOPS the agent loop (agent-session.js:1345). The old resume-nudge
+                // was gated on `queued`, so when a sub-agent settled with no
+                // *immediately* queued message, the trim fired but the nudge did not,
+                // and the (stopped) session hung. The trim still fires on
+                // `idle && overThreshold` — we intentionally do NOT add a `!queued`
+                // guard, because that would suppress mid-run relief exactly during
+                // team-run waves where queued is usually true and relief is needed
+                // most. Instead we DECOUPLE the nudge from `queued`: after a durable
+                // trim we ALWAYS nudge so the agent reliably restarts. Debounced 30s.
+                let didDurableTrim = false;
+                if (config.auto && idle && overThreshold && now >= runtime.debounceUntil) {
+                    // COMPACT-DEDUP FIX: skip the manual durable-trim trigger when pi's
+                    // NATIVE auto-compaction just fired (or is in-flight). pi emits
+                    // agent_end BEFORE its own _checkCompaction (per its docstring:
+                    // "Called after agent_end and before prompt submission"), so a
+                    // synchronous `piCompactWouldNoop` branch check misses a native
+                    // compaction that hasn't appended its entry yet — calling
+                    // ctx.compact() then races with pi and throws "Already compacted"
+                    // to the user. The `lastCompactAt` cooldown (updated by the
+                    // session_compact listener for EVERY compaction, native or
+                    // extension-supplied) closes that race window.
+                    const sinceCompact = now - (runtime.rt.lastNativeCompactAt ?? 0);
+                    if (sinceCompact < 10_000) {
+                        runtime.diagAgentEndDurableSkipRecent++;
+                    }
+                    else if (!piCompactWouldNoop(ctx)) {
+                        runtime.debounceUntil = now + 2000;
+                        runtime.diagAgentEndDurable++;
+                        runtime.logger.info("agent-end-durable-trigger", {
+                            sessionId: runtime.rt.sessionId,
+                            ctxTokens: runtime.lastCtxTokens,
+                            thresholdTokens: config.thresholdTokens,
+                            queued,
+                        });
+                        ctx.compact({ customInstructions: undefined }); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; agent settled so no in-flight abort. Race-guarded by lastCompactAt cooldown above (ctx.compact returns void → throw is surfaced by pi as compaction_end; the cooldown prevents the call entirely).
+                        didDurableTrim = true;
+                    }
+                }
+                // Restart the agent after a mid-run durable trim (which stopped it), or
+                // when it settled idle with queued work. Decoupled from `queued` for the
+                // durable-trim case — see FIX note above. Debounced 30s; never blocks.
+                const lengthStop = config.autoContinueLengthStop && runtime.rt.lengthStopPending;
+                if (idle &&
+                    now >= runtime.resumeNudgeUntil &&
+                    ((config.auto && (didDurableTrim || queued)) || lengthStop)) {
+                    runtime.resumeNudgeUntil = now + 30_000;
+                    if (runtime.rt.lengthStopPending) {
+                        runtime.rt.lengthStopPending = false; // one-shot: never re-fire for same stop
+                        runtime.dashboard.event("length_stop_continue", { turnIndex: runtime.currentTurn });
+                        runtime.logger.info("length_stop_continue", {
+                            sessionId: runtime.rt.sessionId,
+                            didDurableTrim,
+                            queued,
+                        });
+                    }
+                    // S28: when a length-stop (max-output-token truncation) fired WITHOUT a durable trim, do NOT claim a compaction happened
+                    // (nothing was compacted on the low-pressure length path). Branch the message so the nudge matches reality.
+                    const nudgeMsg = lengthStop && !didDurableTrim
+                        ? "[mega-compact] the last response hit the output-token cap; continue from where it stopped."
+                        : "[mega-compact] continue from the compacted context above.";
+                    pi.sendUserMessage(nudgeMsg);
+                }
+            }
+            catch {
+                /* non-fatal: a failed nudge never blocks */
+            }
+        }
+        runtime.snapshot(ctx);
+    });
+    pi.on("turn_start", async (event, ctx) => {
+        runtime.currentTurn = event.turnIndex;
+        runtime.rt.lengthStopPending = false; // S28: re-arm defensively each user turn
+        runtime.dashboard.event("turn_start", { turnIndex: event.turnIndex });
+        runtime.snapshot(ctx);
+    });
+    pi.on("turn_end", async (event, ctx) => {
+        runtime.dashboard.event("turn_end", { turnIndex: event.turnIndex });
+        runtime.snapshot(ctx);
+        // S20+S24: auto-review the conversation and persist durable memories. The
+        // review cadence scales with pressure (memoryReviewCadence): as context
+        // fills, the conversation is reviewed more often so memories keep pace with
+        // faster churn. Best-effort + non-fatal: a review failure must never break
+        // the agent loop. Debounced by the pressure-adjusted interval.
+        if (config.memoryAutoReview && runtime.currentTurn > 0) {
+            const cadence = memoryReviewCadence(runtime.pressureBand, config.memoryReviewInterval);
+            if (runtime.currentTurn % cadence === 0) {
+                // S20+S24: review the conversation and persist durable memories. The
+                // cadence scales with pressure (memoryReviewCadence): as context fills,
+                // the conversation is reviewed more often so memories keep pace with
+                // faster churn. Shared runMemoryReview body (also used on compact).
+                const entries = ctx.sessionManager.getEntries();
+                const view = runtime.engineView(entries.flatMap((e) => (e.message ? [e.message] : [])));
+                await runMemoryReview(runtime, view, "turn");
+            }
+        }
+        // S28: detect max-output-token truncation. event.message.stopReason is the
+        // pi-ai StopReason union; 'length' == generation hit max_tokens OUTPUT cap
+        // (INPUT-orthogonal to context-window overflow). Arm the agent_end nudge.
+        if (config.autoContinueLengthStop &&
+            event.message.role === "assistant" &&
+            event.message.stopReason === "length") {
+            runtime.rt.lengthStopPending = true;
+            runtime.dashboard.event("length_stop", { turnIndex: event.turnIndex });
+        }
+    });
+}

package/dist/extensions/mega-events/compact-handlers.js

@@ -0,0 +1,133 @@
+import { driveNativeCompaction, } from "../mega-compact-driver.js";
+import { estimateBlockTokens } from "../../src/tokens.js";
+/**
+ * Build a minimal fallback compaction so pi never runs its throwing compact().
+ *
+ * Used when our Trident/RAPTOR summary is empty or there is nothing to
+ * summarize (the anchor floor protects every message). We still record a
+ * resume summary + truncate from prep.firstKeptEntryId so the session always
+ * gets a compact summary and resumes. Returns undefined only if pi handed us
+ * no preparation cut point at all.
+ */
+function fallbackCompaction(event) {
+    const prep = event.preparation;
+    if (!prep?.firstKeptEntryId)
+        return undefined;
+    // When messagesToSummarize is empty the anchor floor protects everything,
+    // so firstKeptEntryId == current first entry and the trim is a no-op — but
+    // we still record a resume summary so the session has context after compaction.
+    const tokensBefore = prep.tokensBefore ?? 0;
+    const summary = `[mega-compact] context compacted at ${tokensBefore.toLocaleString()} tokens ` +
+        `(anchor floor active). Continue from the most recent messages above.`;
+    return {
+        compaction: {
+            summary,
+            firstKeptEntryId: prep.firstKeptEntryId,
+            tokensBefore,
+            estimatedTokensAfter: estimateBlockTokens(summary),
+        },
+    };
+}
+/**
+ * Debounced resume-nudge: restart the agent loop after a compaction (which
+ * may have stopped it). Idempotent — one nudge per 30s, never blocks.
+ */
+function nudgeResume(pi, runtime) {
+    try {
+        const now = Date.now();
+        if (now >= runtime.resumeNudgeUntil) {
+            runtime.resumeNudgeUntil = now + 30_000;
+            pi.sendUserMessage("[mega-compact] continue from the compacted context above.");
+        }
+    }
+    catch {
+        /* non-fatal: a failed nudge never blocks */
+    }
+}
+/** Register native compaction event handlers. */
+export function registerCompactHandlers(pi, runtime, config) {
+    // ---- Supply a DURABLE trim to pi's native compaction (Fix B) ----------
+    // We run the Trident pipeline to produce a compressed summary, then return
+    // it as a CompactionResult. pi writes the summary into a compactionSummary
+    // entry AND truncates the on-disk transcript from firstKeptEntryId. This is
+    // the durable fix for "tokens grow on read": the trim survives resume, so
+    // there is no full-reload + additive recall inflation.
+    pi.on("session_before_compact", async (event, ctx) => {
+        runtime.resetRuntime(ctx.sessionManager.getSessionId());
+        // DIAG (team-run relief): this is the ONLY durable-trim entry point. Log
+        // every fire + whether we supplied a compaction (truncates transcript) or
+        // fell through to {} (pi runs its own). If this is sparse during a team
+        // run, the durable trim is firing too late (only at parent settle).
+        const prep = event.preparation;
+        runtime.diagBeforeCompactFires++;
+        runtime.logger.info("before-compact-entry", {
+            sessionId: runtime.rt.sessionId,
+            reason: event.reason,
+            hasPrep: !!prep,
+            msgsToSummarize: prep?.messagesToSummarize?.length ?? 0,
+            firstKeptEntryId: prep?.firstKeptEntryId ?? null,
+            activeAgents: runtime.activeAgents,
+        });
+        if (!config.auto)
+            return {}; // let pi run its own native compaction
+        try {
+            const result = driveNativeCompaction(event, runtime, config);
+            if (result && result.compaction.summary?.trim()) {
+                runtime.diagBeforeCompactSupplied++;
+                runtime.logger.info("native-compact", {
+                    sessionId: runtime.rt.sessionId,
+                    firstKeptEntryId: result.compaction.firstKeptEntryId,
+                    tokensBefore: result.compaction.tokensBefore,
+                    summaryTokens: result.compaction.estimatedTokensAfter,
+                });
+                nudgeResume(pi, runtime);
+                return { compaction: result.compaction };
+            }
+            // FIX "compacts but doesn't resume" + "Nothing to compact" regression:
+            // when we have nothing to summarize (anchor floor protects everything →
+            // messagesToSummarize empty) or our Trident/RAPTOR summary came back
+            // EMPTY, pi's OWN compact() throws "Nothing to compact (session too
+            // small)" and leaves the session stuck with no resume context. Instead
+            // of returning {} (which makes pi run its throwing compact()), supply a
+            // fallback compaction from prep.firstKeptEntryId with a minimal resume
+            // summary. This ALWAYS injects a compact summary so the session
+            // resumes, and never surfaces the "Nothing to compact" error to the user.
+            const fb = fallbackCompaction(event);
+            if (fb) {
+                runtime.diagBeforeCompactSupplied++;
+                runtime.logger.info("native-compact-fallback", {
+                    sessionId: runtime.rt.sessionId,
+                    firstKeptEntryId: fb.compaction.firstKeptEntryId,
+                    tokensBefore: fb.compaction.tokensBefore,
+                    reason: event.reason,
+                });
+                nudgeResume(pi, runtime);
+                return { compaction: fb.compaction };
+            }
+        }
+        catch (err) {
+            runtime.logger.error("native-compact-failed", {
+                sessionId: runtime.rt.sessionId,
+                error: String(err instanceof Error ? err.message : err),
+            });
+        }
+        // Absolute last resort: let pi run its own (may throw "Nothing to compact").
+        return {};
+    });
+    // COMPACT-DEDUP FIX: track EVERY compaction (native + extension-supplied)
+    // so the agent_end durable-trim guard can skip a redundant ctx.compact()
+    // when pi just compacted. Without this, agent_end fires ctx.compact()
+    // synchronously AFTER pi's native auto-compaction appended a compaction
+    // entry but BEFORE our branch read sees it on the next tick — racing
+    // into a user-facing "Already compacted" throw. `lastCompactAt` is the
+    // race-closing signal: any compaction (manual/threshold/overflow, ours
+    // or pi's own) stamps it, and the agent_end guard skips for 10s.
+    pi.on("session_compact", async (_event, _ctx) => {
+        runtime.rt.lastNativeCompactAt = Date.now();
+        runtime.rt.lastCompactAt = Date.now();
+        runtime.logger.info("session-compacted", {
+            sessionId: runtime.rt.sessionId,
+            at: runtime.rt.lastCompactAt,
+        });
+    });
+}

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

@@ -0,0 +1,249 @@
+import { openStore, appendRawTranscript, writeCheckpointEpoch, } from "../../src/store/sqlite.js";
+import { epochIdFor } from "../../src/mirror/epoch.js";
+import { autoCompactCheck } from "../../src/compact.js";
+import { estimateSessionTokens } from "../../src/tokens.js";
+import { runCompact, piCompactWouldNoop } from "../mega-pipeline.js";
+import { computeLiveTrimCut, liveTrimSummaryMessage } from "../mega-trim.js";
+import { pressureFromPct, pressureRatio, } from "../mega-config.js";
+import { createHash } from "node:crypto";
+/**
+ * Convert a pi AgentMessage to a RawTranscriptRow for the DB mirror.
+ * content_bytes is canonical JSON (sorted keys) for deterministic hashing.
+ * Returns null if the message has no usable content.
+ */
+function toRawTranscriptRow(msg, sessionId, epochId) {
+    // Narrow to Message union (has content + timestamp).
+    const m = msg;
+    const content = m.content;
+    if (content == null || content === "")
+        return null;
+    // Canonical form: sort object keys for deterministic hashing.
+    const contentBytes = typeof content === "string"
+        ? content
+        : JSON.stringify(content, Object.keys(content).sort());
+    const contentHash = createHash("sha256").update(contentBytes).digest("hex");
+    return {
+        contentHash,
+        sessionId,
+        seq: 0, // assigned by appendRawTranscript (COALESCE(MAX(seq),0)+1)
+        role: m.role ?? "unknown",
+        contentBytes,
+        toolName: m.toolName ?? null,
+        messageTimestamp: m.timestamp ?? null,
+        checkpointEpoch: epochId,
+    };
+}
+/** Register the context event handler (live-trim auto-trigger). */
+export function registerContextHandler(pi, runtime, config) {
+    // ---- Auto-trigger: live trim (compact and continue) + native durable ----
+    // S16 redesign: we NO LONGER call ctx.compact() from the auto-trigger by
+    // default. That mapped to pi's MANUAL compaction path, which abort()s the
+    // in-flight turn (agent-session.js:1345) and stops the agent. Instead:
+    //  - LIVE: return { messages: trimmedView } from the context event. This
+    //    feeds pi's transformContext (sdk.js:226 → agent-loop.js:180) so the
+    //    model sees a compacted window EVERY LLM call, with no abort. The turn
+    //    continues. We persist our recall checkpoint (the durable value) first.
+    //  - DURABLE: pi's NATIVE auto-compaction fires at agent-end
+    //    (agent-session.js:1565), continues (return hasQueuedMessages()), and
+    //    emits session_before_compact — where OUR driveNativeCompaction supplies
+    //    the summary and pi truncates the transcript on disk. No ctx.compact().
+    // Legacy: MEGACOMPACT_LEGACY_DURABLE_TRIM=true restores the v0.4.28 ctx.compact
+    // path (kept one release as rollback).
+    pi.on("context", async (event, ctx) => {
+        if (!config.auto)
+            return;
+        const usage = ctx.getContextUsage();
+        const pct = usage?.percent;
+        // Always track context for the dashboard, even if we return early below.
+        runtime.lastCtxTokens = usage?.tokens ?? null;
+        runtime.lastCtxPercent = pct ?? null;
+        runtime.lastCtxWindow = usage?.contextWindow ?? 0;
+        runtime.snapshot(ctx);
+        const messages = event.messages;
+        const view = runtime.engineView(messages);
+        const currentTokens = usage?.tokens ??
+            estimateSessionTokens(view) ??
+            Math.round(((pct ?? 0) / 100) * (usage?.contextWindow ?? 0));
+        // S27 DB-mirror: append ALL incoming messages to raw_transcript.
+        // Runs BEFORE fast-gate so every message is captured, even if we
+        // don't compact this turn. Append is idempotent (content_hash PK).
+        if (config.dbMirror) {
+            try {
+                const db = openStore(runtime.currentStateDir);
+                const epochId = epochIdFor(runtime.rt.sessionId);
+                for (const msg of messages) {
+                    const raw = toRawTranscriptRow(msg, runtime.rt.sessionId, epochId);
+                    if (raw)
+                        appendRawTranscript(db, raw);
+                }
+            }
+            catch (e) {
+                runtime.logger.warn("db-mirror-append-fail", { error: String(e) });
+            }
+        }
+        // S29 FAST GATE: drive the auto-trigger off the context % (the number the
+        // menu bar shows), NOT the token count — the model under-reports tokens,
+        // so a token-only gate misses the overshoot that causes max-output-tokens
+        // truncation. The fire point is the tier's percent threshold (tierPct)
+        // unless overridden by MEGACOMPACT_AUTO_PCT_TRIGGER. `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 doesn't report percent) a tiered config
+        // falls back to the token gate (S27 boot-fallback guarantee) instead of
+        // skipping compaction — a percent-only gate would regress that.
+        let gatePassed = false;
+        if (config.tierPct != null && pct != null) {
+            const firePct = config.autoPctTrigger ?? config.tierPct;
+            gatePassed = pct / 100 >= firePct;
+        }
+        else {
+            // custom tier OR tiered-but-pct-unavailable → token gate (S27 fallback).
+            if (currentTokens < runtime.effectiveThreshold) {
+                runtime.diagCtxFastGate++;
+                return;
+            }
+            const check = autoCompactCheck(currentTokens, runtime.effectiveThreshold); // SERVER-STYLE CONFIRM (local)
+            if (!check.shouldCompact) {
+                runtime.diagCtxNoCompact++;
+                return;
+            }
+            gatePassed = true;
+        }
+        if (!gatePassed) {
+            runtime.diagCtxFastGate++;
+            return;
+        }
+        // Debounce so we don't fire on every context event past threshold.
+        const now = Date.now();
+        if (now < runtime.debounceUntil) {
+            runtime.diagCtxDebounce++;
+            return;
+        }
+        runtime.debounceUntil = now + 2000;
+        // Adaptive compression (Fix E): scale compression strength + keepFrom depth
+        // with how close we are to the model context limit. Null-safe: when the
+        // token-fallback path ran (pct unavailable) use the token-basis pressure
+        // (the same basis the runtime `pressure` getter uses for custom/no-window).
+        const pressure = pct != null ? pressureFromPct(pct) : pressureRatio(currentTokens, runtime.effectiveThreshold);
+        const ran = runCompact(pi, runtime, config, ctx, messages, {
+            compressionPressure: pressure,
+        });
+        if (ran.skipped) {
+            runtime.diagCtxRunSkipped++;
+            return;
+        }
+        // S27 DB-mirror: write checkpoint_epoch with deterministic nonce.
+        // This makes the cache key stable across identical compactions.
+        if (config.dbMirror) {
+            try {
+                const db = openStore(runtime.currentStateDir);
+                const cpId = ran.result.checkpointId ?? `epoch-${Date.now()}`;
+                const epoch = {
+                    epochId: epochIdFor(cpId),
+                    sessionId: runtime.rt.sessionId,
+                    startedSeq: 0,
+                    committedSeq: ran.result.compactedFrom,
+                    checkpointId: cpId,
+                    cutIndex: ran.result.compactedFrom,
+                    summaryMessageText: ran.result.summary,
+                    createdAt: Date.now(),
+                };
+                writeCheckpointEpoch(db, epoch);
+                // S27 Task 6: Fire-and-forget dedup pipeline.
+                // Deduplicates raw_transcript rows for the compacted range.
+                try {
+                    const { dedupTranscript } = await import("../../src/mirror/dedup.js");
+                    dedupTranscript(db, runtime.rt.sessionId, 0, ran.result.compactedFrom);
+                }
+                catch (_dedupErr) {
+                    // Fire-and-forget: dedup failure is non-fatal
+                }
+            }
+            catch (e) {
+                runtime.logger.warn("db-mirror-epoch-fail", { error: String(e) });
+            }
+        }
+        // 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
+        // toggled per-test without reloading the module; config.legacyDurableTrim is
+        // the cached default. (Mirrors how piCompactWouldNoop re-reads its floor.)
+        const legacy = config.legacyDurableTrim ||
+            process.env.MEGACOMPACT_LEGACY_DURABLE_TRIM === "true" ||
+            process.env.MEGACOMPACT_LEGACY_DURABLE_TRIM === "1";
+        if (legacy) {
+            // COMPACT-DEDUP FIX: same race guard as the agent_end path. Skip when a
+            // NATIVE compaction just fired (avoids racing pi and surfacing a spurious
+            // "Already compacted" / "Nothing to compact" toast). Uses lastNativeCompactAt
+            // (NOT lastCompactAt, which runCompact also stamps for our own checkpoint).
+            const sinceCompact = Date.now() - (runtime.rt.lastNativeCompactAt ?? 0);
+            if (sinceCompact < 10_000 || piCompactWouldNoop(ctx))
+                return;
+            ctx.compact({ customInstructions: undefined }); // race-guarded by lastNativeCompactAt cooldown (ctx.compact returns void → not catchable; the cooldown prevents the call)
+            return;
+        }
+        // S16 LIVE trim: collapse the compacted region to a summary + recent anchor.
+        // Non-destructive: pi keeps the real transcript; only this LLM call sees the
+        // trimmed window. We compute the cut on the engine view (pure, tested) then
+        // slice the ORIGINAL pi AgentMessage[] from that index (lossless alignment,
+        // mirroring dropCompactedRange) and prepend a user-role summary message.
+        // A build failure or unsafe cut returns nothing (no trim this call — the
+        // next context event retries). The anchor floor is read live from env (the
+        // config value is the cached default) so it can be tuned per-test / per-run
+        // without reloading the module.
+        try {
+            const anchorEnv = process.env.MEGACOMPACT_ANCHOR_USER_MESSAGES;
+            const anchorUserMessages = anchorEnv != null &&
+                anchorEnv !== "" &&
+                Number.isFinite(Number(anchorEnv))
+                ? Number(anchorEnv)
+                : config.anchorUserMessages;
+            const cut = computeLiveTrimCut(view, {
+                compactedFrom: ran.result.compactedFrom,
+                summary: ran.result.summary,
+                anchorUserMessages,
+            });
+            if (cut === null) {
+                runtime.diagCtxCutNull++;
+                runtime.logger.info("live-trim-skip", {
+                    sessionId: runtime.rt.sessionId,
+                    compactedFrom: ran.result.compactedFrom,
+                    viewLen: view.length,
+                    anchorUserMessages,
+                });
+                return; // unsafe / below anchor floor — no trim this call
+            }
+            const summaryMsg = liveTrimSummaryMessage({
+                compactedFrom: ran.result.compactedFrom,
+                summary: ran.result.summary,
+                anchorUserMessages: config.anchorUserMessages,
+            });
+            // Synthesize a user-role AgentMessage carrying the compacted summary.
+            const summaryAgentMsg = {
+                role: "user",
+                content: summaryMsg.text,
+                timestamp: Date.now(),
+            };
+            const recent = messages.slice(cut); // guardrails-allow PREVENT-PI-002: `cut` is the pre-sanitized `compactedFrom` produced by src/boundary.ts computeDropRange, so the preserved run begins on a toolPair-safe index.
+            runtime.snapshot(ctx);
+            // DIAG (team-run relief): confirm the live trim actually fires + how big
+            // the window still is. The return is non-durable (per-LLM-call only), so
+            // this is the signal that the model is being fed a compacted view while
+            // the on-disk transcript + context meter keep growing.
+            runtime.diagLiveTrimFires++;
+            runtime.logger.info("live-trim", {
+                sessionId: runtime.rt.sessionId,
+                inputMsgs: messages.length,
+                outputMsgs: recent.length + 1,
+                compactedFrom: cut,
+                ctxPct: pct,
+                ctxTokens: usage?.tokens ?? null,
+            });
+            return { messages: [summaryAgentMsg, ...recent] };
+        }
+        catch {
+            runtime.diagCtxThrown++;
+            return; // non-fatal: no trim this call; the next context event retries
+        }
+    });
+}

package/dist/extensions/mega-events/register.js

@@ -0,0 +1,21 @@
+import { registerSessionHandlers } from "./session-handlers.js";
+import { registerAgentHandlers } from "./agent-handlers.js";
+import { registerContextHandler } from "./context-handler.js";
+import { registerCompactHandlers } from "./compact-handlers.js";
+/**
+ * DIAG accessor for the headless test harness: the most recently constructed
+ * MegaRuntime, so a test that loads the compiled extension via its default
+ * export can read diag counters (diagLiveTrimFires / diagBeforeCompactFires /
+ * diagBeforeCompactSupplied / diagAgentEndIdle) after firing synthetic events.
+ * No-op in production — nothing reads this outside tests.
+ */
+export let lastRuntime;
+/** Register all pi lifecycle event handlers. */
+export function registerEventHandlers(pi, runtime, config) {
+    lastRuntime = runtime;
+    // ---- Session lifecycle (state reset points) -------------------------------
+    registerSessionHandlers(pi, runtime, config);
+    registerAgentHandlers(pi, runtime, config);
+    registerContextHandler(pi, runtime, config);
+    registerCompactHandlers(pi, runtime, config);
+}