pi-mega-compact 0.7.8 → 0.7.9

package/dist/extensions/mega-events.js

@@ -1,701 +1,17 @@
-/**
- * mega-events.ts — the pi lifecycle event handlers.
+/** mega-events.ts — barrel re-exporting all pi lifecycle event handlers.
  *
- * Wires every pi event the extension listens for: model/provider capture,
- * session lifecycle + state reset, auto-inline injection, agent/turn tracking,
- * and the auto-trigger compaction pipeline. Keeps the shared MegaRuntime in
- * sync and delegates the heavy lifting to the pipeline + command modules.
+ * Split into focused submodules under extensions/mega-events/:
+ *  - register.ts: lastRuntime + registerEventHandlers (entry point)
+ *  - session-handlers.ts: session lifecycle (model_select, session_start,
+ *    session_tree, before_agent_start, session_shutdown)
+ *  - agent-handlers.ts: agent/turn tracking (agent_start, agent_end,
+ *    turn_start, turn_end)
+ *  - context-handler.ts: live-trim auto-trigger (context event)
+ *  - compact-handlers.ts: native compaction (session_before_compact,
+ *    session_compact)
  */
-import { normalizeSessionId } from "../src/store.js";
-import { openStore, appendRawTranscript, writeCheckpointEpoch, autoMaintain } from "../src/store/sqlite.js";
-import { epochIdFor } from "../src/mirror/epoch.js";
-import { autoCompactCheck } from "../src/compact.js";
-import { estimateSessionTokens, estimateBlockTokens } from "../src/tokens.js";
-import { recentUserQuery, WIDGET_KEY, } from "./mega-runtime.js";
-import { runCompact, doRecall, doRecallAsync, piCompactWouldNoop, runMemoryReview, } from "./mega-pipeline.js";
-import { recallMemoriesAndInline } from "../src/recall.js";
-import { driveNativeCompaction, } from "./mega-compact-driver.js";
-import { computeLiveTrimCut, liveTrimSummaryMessage } from "./mega-trim.js";
-import { pressureFromPct, pressureRatio, memoryReviewCadence, } 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,
-    };
-}
-/**
- * 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) -------------------------------
-    // Capture model/provider whenever it changes (drives real cost estimation).
-    pi.on("model_select", async (_event, ctx) => {
-        runtime.captureModel(ctx);
-        runtime.snapshot(ctx);
-    });
-    pi.on("session_start", async (event, ctx) => {
-        runtime.resetRuntime(ctx.sessionManager.getSessionId());
-        runtime.captureModel(ctx); // best-effort: ctx.model may be set by session start
-        runtime.setStatus(ctx, config.auto ? "mega-compact: ready" : "mega-compact: manual only");
-        // S21: clear any stale memory block from a prior session.
-        runtime.pendingMemoryRecallBlock = undefined;
-        // Auto-inline on resume/fork/continue: stage the most relevant checkpoints
-        // so the next before_agent_start prepends them to the system prompt.
-        // Triggered whenever this session already has persisted checkpoints AND a
-        // usable query — that covers reason "resume"/"fork" (explicit) and
-        // reason "startup" (e.g. `pi --continue`s an existing session, which still
-        // emits "startup" but with a populated message window). A brand-new empty
-        // session has no checkpoints, so it's naturally excluded.
-        if (config.autoInline) {
-            const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
-            const query = recentUserQuery(ctx);
-            if (query && runtime.store.stats(sid).checkpointCount > 0) {
-                // S17: use the async variant on resume so cross-repo HNSW recall can
-                // augment when this repo's store is thin. session_start is an async-safe
-                // point (unlike the mid-turn context handler, which stays sync).
-                const r = await doRecallAsync(runtime, config, ctx, query, "resume", {
-                    crossRepo: config.crossRepoEnabled,
-                });
-                if (!r.empty) {
-                    runtime.pendingRecallBlock = r.block;
-                    const crossLabel = r.toInject.some((h) => h.repoId)
-                        ? " (cross-repo)"
-                        : "";
-                    runtime.setStatus(ctx, `mega-compact: recalled ${r.toInject.length} chkpt${crossLabel}`);
-                    runtime.logger.info("auto-inline", {
-                        reason: event.reason,
-                        query,
-                        injected: r.toInject.map((h) => h.checkpoint.checkpointId),
-                        crossRepo: r.toInject.some((h) => h.repoId),
-                    });
-                }
-            }
-            // S21: parallel memory recall. Same async context so we can await without
-            // breaking the handler contract. Best-effort — never throws.
-            try {
-                const mr = await recallMemoriesAndInline({
-                    query,
-                    stateDir: runtime.getStateDir(),
-                    limit: 5,
-                    crossRepo: config.crossRepoEnabled,
-                    crossRepoCosine: config.crossRepoCosine,
-                });
-                if (!mr.empty)
-                    runtime.pendingMemoryRecallBlock = mr.block;
-            }
-            catch (err) {
-                runtime.logger.warn("memory-recall skipped", { err: String(err) });
-            }
-        }
-        // S27 Task 10: best-effort auto-maintenance on session start (prune rows
-        // older than 30d, checkpoint WAL if >10MB, VACUUM if DB >100MB + >20%
-        // freelist). Never blocks session start — swallows errors and logs a
-        // one-line summary for diagnostics.
-        try {
-            const m = autoMaintain(runtime.currentStateDir);
-            if (m && !m.endsWith("nothing to do"))
-                runtime.logger.info("db-auto-maintain", { result: m });
-        }
-        catch (e) {
-            runtime.logger.warn("db-auto-maintain-fail", { error: String(e) });
-        }
-        runtime.dashboard.event("session_start", {
-            reason: event.reason,
-            sessionId: runtime.rt.sessionId,
-        });
-        runtime.snapshot(ctx);
-    });
-    pi.on("session_tree", async (_event, ctx) => {
-        // Branch navigation invalidates region indexes — reset checkpoint memory but
-        // keep the on-disk store (markers replayed from entries below if needed).
-        runtime.resetRuntime(ctx.sessionManager.getSessionId());
-        runtime.setStatus(ctx, "mega-compact: ready (branch)");
-        if (config.autoInline) {
-            const query = recentUserQuery(ctx);
-            if (query) {
-                const r = doRecall(runtime, config, ctx, query, "resume");
-                if (!r.empty) {
-                    runtime.pendingRecallBlock = r.block;
-                    runtime.logger.info("auto-inline", {
-                        reason: "session_tree",
-                        query,
-                        injected: r.toInject.map((h) => h.checkpoint.checkpointId),
-                    });
-                }
-                // S21: parallel memory recall. Trigram embedder is sub-ms; await is fine.
-                try {
-                    const mr = await recallMemoriesAndInline({
-                        query,
-                        stateDir: runtime.getStateDir(),
-                        limit: 5,
-                        crossRepo: config.crossRepoEnabled,
-                        crossRepoCosine: config.crossRepoCosine,
-                    });
-                    if (!mr.empty)
-                        runtime.pendingMemoryRecallBlock = mr.block;
-                }
-                catch (err) {
-                    runtime.logger.warn("memory-recall skipped", { err: String(err) });
-                }
-            }
-        }
-        runtime.dashboard.event("session_tree", {
-            sessionId: runtime.rt.sessionId,
-        });
-        runtime.snapshot(ctx);
-    });
-    // ---- Auto-inline injection point: prepend staged recall to systemPrompt ----
-    pi.on("before_agent_start", async (event, ctx) => {
-        runtime.captureModel(ctx); // most reliable point ctx.model is populated
-        const cpBlock = runtime.pendingRecallBlock;
-        const memBlock = runtime.pendingMemoryRecallBlock;
-        if (!cpBlock && !memBlock)
-            return;
-        runtime.pendingRecallBlock = undefined;
-        runtime.pendingMemoryRecallBlock = undefined;
-        const composed = [cpBlock, memBlock].filter(Boolean).join("\n\n");
-        return { systemPrompt: `${event.systemPrompt}\n\n${composed}` };
-    });
-    pi.on("session_shutdown", async (_event, ctx) => {
-        runtime.setStatus(ctx, undefined);
-        runtime.activeAgents = 0;
-        runtime.currentTurn = 0;
-        ctx.ui.setWidget(WIDGET_KEY, [], { placement: "aboveEditor" });
-    });
-    // ---- 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 });
-        }
-    });
-    // ---- 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-token
-        // 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
-        }
-    });
-    // ---- 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,
-        });
-    });
-    /**
-     * 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 */
-        }
-    }
-}
+export * from "./mega-events/register.js";
+export * from "./mega-events/session-handlers.js";
+export * from "./mega-events/agent-handlers.js";
+export * from "./mega-events/context-handler.js";
+export * from "./mega-events/compact-handlers.js";