pi-mega-compact 0.11.3 → 0.11.5

package/dist/extensions/mega-commands.js

@@ -13,6 +13,11 @@ import { loadMetrics, fpRate, p95, defaultMetricsPath } from "../src/monitoring.
 import { C, recentUserQuery } from "./mega-runtime.js";
 import { runCompact, doRecall, doRecallAsync } from "./mega-pipeline.js";
 import { vectorStats, vectorRepoStats, vectorDataInvariant } from "../src/vectorStore.js";
+import { spawnSync } from "node:child_process"; // guardrails-allow PREVENT-PI-004: local subprocess detection only (no network)
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { createRequire } from "node:module";
 /** Resolve a checkpoint by id (or "recent"/"last") from this session's store. */
 export function findCheckpoint(runtime, sid, ref) {
     const all = listCheckpoints(sid, runtime.currentStateDir);
@@ -73,7 +78,7 @@ export function registerCommands(pi, runtime, config) {
                 runtime.logger.info("recall", { query, crossRepo, injected: r.toInject.map((h) => h.checkpoint.checkpointId) });
                 runtime.setStatus(ctx, `mega-compact: recalled ${r.toInject.length} chkpt${crossRepo ? " (cross-repo)" : ""}`);
                 ctx.ui.notify(`[mega-compact] recall staged ${r.toInject.length} checkpoint(s) for "${query}"${crossRepo ? " (cross-repo)" : ""}:\n${list}\n` +
-                    `(injected at the next turn via system prompt)`);
+                    `(injected at the tail of the next turn's context)`);
             }
             catch (e) {
                 ctx.ui.notify(`[mega-compact] /mega-recall failed: ${String(e)}`);
@@ -255,6 +260,189 @@ export function registerCommands(pi, runtime, config) {
                 `• data safety — every compressed region is kept verbatim; nothing is permanently deleted. /mega-restore brings any of it back.`);
         },
     });
+    pi.registerCommand("mega-setup", {
+        description: "Local embedding setup wizard — detect available embedders and configure mega-compact.",
+        handler: async (_args, ctx) => {
+            try {
+                const log = (msg) => ctx.ui.notify(msg);
+                // --- 1. Current config ---
+                const embeddingUrl = process.env["MEGACOMPACT_EMBEDDING_URL"];
+                const minilm = process.env["MEGACOMPACT_MINILM"];
+                let currentEmbedder = "TrigramEmbedder (heuristic, default)";
+                if (embeddingUrl)
+                    currentEmbedder = `httpEmbedder → ${embeddingUrl}`;
+                else if (minilm)
+                    currentEmbedder = "MiniLM (experimental)";
+                // --- 2. Detection ---
+                let ollamaDetected = false;
+                let ollamaModels = [];
+                let ollamaRunning = false;
+                let llamaDetected = false;
+                let onnxDetected = false;
+                try {
+                    const ollamaVer = spawnSync("ollama", ["--version"], {
+                        timeout: 5000,
+                        encoding: "utf-8",
+                        stdio: ["ignore", "pipe", "pipe"],
+                    }); // guardrails-allow PREVENT-PI-004: local subprocess detection only
+                    if (ollamaVer.status === 0) {
+                        ollamaDetected = true;
+                        try {
+                            const listResult = spawnSync("ollama", ["list"], {
+                                timeout: 5000,
+                                encoding: "utf-8",
+                                stdio: ["ignore", "pipe", "pipe"],
+                            }); // guardrails-allow PREVENT-PI-004: local subprocess detection only
+                            if (listResult.status === 0) {
+                                ollamaRunning = true;
+                                const lines = listResult.stdout?.split("\n") ?? [];
+                                for (const line of lines) {
+                                    const name = line.split(/\s+/)[0];
+                                    if (name && name !== "NAME")
+                                        ollamaModels.push(name);
+                                }
+                            }
+                        }
+                        catch {
+                            // ollama list fails if server not running — that's fine
+                        }
+                    }
+                }
+                catch {
+                    // ollama not found
+                }
+                try {
+                    const whichLlama = spawnSync("which", ["llama-server"], {
+                        timeout: 3000,
+                        encoding: "utf-8",
+                        stdio: ["ignore", "pipe", "pipe"],
+                    }); // guardrails-allow PREVENT-PI-004: local subprocess detection only
+                    llamaDetected = whichLlama.status === 0;
+                }
+                catch {
+                    // not found
+                }
+                try {
+                    const req = createRequire(import.meta.url);
+                    try {
+                        req.resolve("onnxruntime-node");
+                        onnxDetected = true;
+                    }
+                    catch {
+                        // not in node_modules
+                    }
+                }
+                catch {
+                    // require error
+                }
+                const choices = [];
+                if (ollamaDetected && ollamaRunning) {
+                    const model = ollamaModels.find((m) => m.includes("nomic-embed") ||
+                        m.includes("embed") ||
+                        m.includes("mxbai"));
+                    const suggestedModel = model ?? "nomic-embed-text";
+                    choices.push({
+                        label: `Use Ollama (${suggestedModel}) at localhost:11434`,
+                        value: `ollama:${suggestedModel}`,
+                    });
+                }
+                else if (ollamaDetected && !ollamaRunning) {
+                    choices.push({
+                        label: "Ollama detected but server is not running — start it first",
+                        value: "ollama:offline",
+                    });
+                }
+                if (llamaDetected) {
+                    choices.push({
+                        label: "Use llama.cpp server at localhost:8080",
+                        value: "llama:default",
+                    });
+                }
+                if (onnxDetected) {
+                    choices.push({
+                        label: "Use ONNX Runtime (experimental, requires config)",
+                        value: "onnx:default",
+                    });
+                }
+                choices.push({
+                    label: "Keep TrigramEmbedder (default, no setup)",
+                    value: "trigram",
+                });
+                // --- 4. Prompt user ---
+                log(`Current embedder: ${currentEmbedder}`);
+                let selected = "trigram";
+                if (choices.length > 1) {
+                    try {
+                        const labels = choices.map((c) => c.label);
+                        const picked = await ctx.ui.select("Select an embedder to configure:", labels);
+                        if (picked === undefined) {
+                            log("Setup cancelled by user.");
+                            return;
+                        }
+                        const match = choices.find((c) => c.label === picked);
+                        selected = match?.value ?? "trigram";
+                    }
+                    catch {
+                        log("Setup cancelled by user.");
+                        return;
+                    }
+                }
+                else {
+                    log("No local embedders detected. Keeping TrigramEmbedder default.");
+                }
+                // --- 5. Apply selection ---
+                if (selected.startsWith("ollama:")) {
+                    const model = selected.split(":")[1];
+                    const url = `http://localhost:11434/api/embeddings`; // guardrails-allow PREVENT-PI-004: localhost-only config string, not a runtime fetch
+                    const lines = [
+                        `# Mega-Compact Embedder Configuration — Ollama`,
+                        `# Generated by /megasetup at ${new Date().toISOString()}`,
+                        `export MEGACOMPACT_EMBEDDING_URL="${url}"`,
+                        `# Optional: uncomment to set cache size (default 1000)`,
+                        `# export MEGACOMPACT_EMBED_CACHE=1000`,
+                    ];
+                    const envContent = lines.join("\n") + "\n";
+                    // Write .mega-compact.env to state dir
+                    const stateDir = process.env["MEGACOMPACT_STATE_DIR"] ?? path.join(os.homedir(), ".pi", "mega-compact");
+                    try {
+                        mkdirSync(stateDir, { recursive: true });
+                        writeFileSync(path.join(stateDir, ".mega-compact.env"), envContent, "utf-8");
+                    }
+                    catch {
+                        // non-fatal
+                    }
+                    log(`Configured for Ollama (${model}).\n\nAdd to your shell profile (~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish):\n\n  source "${path.join(stateDir, ".mega-compact.env")}"\n\nOr export manually:\n\n  export MEGACOMPACT_EMBEDDING_URL="${url}"\n\nThen restart pi to activate the http embedder.`);
+                }
+                else if (selected.startsWith("llama:")) {
+                    const url = "http://localhost:8080/v1/embeddings"; // guardrails-allow PREVENT-PI-004: localhost-only config string, not a runtime fetch
+                    const lines = [
+                        `# Mega-Compact Embedder Configuration — llama.cpp`,
+                        `# Generated by /megasetup at ${new Date().toISOString()}`,
+                        `export MEGACOMPACT_EMBEDDING_URL="${url}"`,
+                    ];
+                    const envContent = lines.join("\n") + "\n";
+                    const stateDir = process.env["MEGACOMPACT_STATE_DIR"] ?? path.join(os.homedir(), ".pi", "mega-compact");
+                    try {
+                        mkdirSync(stateDir, { recursive: true });
+                        writeFileSync(path.join(stateDir, ".mega-compact.env"), envContent, "utf-8");
+                    }
+                    catch {
+                        // non-fatal
+                    }
+                    log(`Configured for llama.cpp server.\n\nAdd to your shell profile:\n\n  source "${path.join(stateDir, ".mega-compact.env")}"\n\nOr export manually:\n\n  export MEGACOMPACT_EMBEDDING_URL="${url}"\n\nThen restart pi to activate the http embedder.`);
+                }
+                else if (selected.startsWith("onnx:")) {
+                    log("ONNX Runtime configuration is experimental.\n\nSet MEGACOMPACT_EMBEDDING_URL to your local ONNX server URL, or see docs for manual setup.\nKeeping TrigramEmbedder for now.");
+                }
+                else {
+                    log("Keeping TrigramEmbedder (default). No configuration needed.");
+                }
+            }
+            catch (e) {
+                ctx.ui.notify(`[mega-compact] /mega-setup failed: ${String(e)}`);
+            }
+        },
+    });
     // NOTE: /mega-tier was removed in S24. The tier the user sees is now the LIVE
     // pressure band (low/medium/high/ultra/mega), which climbs automatically as
     // context fills — there is no manual tier to set. See docs/specs/s24-unified-pressure.md.

package/dist/extensions/mega-config.js

@@ -148,6 +148,8 @@ export function loadConfig() {
         errorRetryBackoffMs: envFlag("MEGACOMPACT_ERROR_RETRY_BACKOFF_MS", 5000),
         errorRetrySessionMax: envFlag("MEGACOMPACT_ERROR_RETRY_SESSION_MAX", 3),
         poisonedContextRepeatThreshold: envFlag("MEGACOMPACT_POISONED_REPEAT_THRESHOLD", 3),
+        providerOutageAdviseThreshold: envFlag("MEGACOMPACT_PROVIDER_OUTAGE_THRESHOLD", 3),
+        advisoryChannel: envBool("MEGACOMPACT_ADVISORY_CHANNEL", true),
         autoPctTrigger,
         autoInlineK: envFlag("MEGACOMPACT_AUTO_INLINE_K", 3),
         dedupSim: Number(process.env.MEGACOMPACT_DEDUP_SIM ?? "0.9"),
@@ -164,6 +166,7 @@ export function loadConfig() {
         memoryReviewInterval: envFlag("MEGACOMPACT_MEMORY_REVIEW_INTERVAL", 10),
         recallMaxTokens: envFlag("MEGACOMPACT_RECALL_MAX_TOKENS", 1500),
         windowDedupe: envBool("MEGACOMPACT_WINDOW_DEDUPE", true),
+        recallTailInject: envBool("MEGACOMPACT_RECALL_TAIL_INJECT", true),
         tuiWidget: envBool("MEGACOMPACT_TUI_WIDGET", true),
         // D.1: env-overridable recompact delta (minimum context growth % before
         // re-compacting instead of replaying the cached live trim). Default 50.

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

@@ -5,8 +5,9 @@ import { evaluateAndUnlockAchievements } from "../../src/store/sqlite/game-achie
 import { ensureConversationIdFor, recordTurnWrite, } from "../mega-turn-store.js";
 import { isMegaCache } from "../../src/game/scoring.js";
 import { resolveRepoRoot } from "../mega-config.js";
-import { classifyError, errorRetryBackoffMs, extractErrorSignature, isKnownRetryableTransient, } from "./error-classifier.js";
+import { classifyError, classifyErrorDetailed, errorRetryBackoffMs, extractErrorSignature, isKnownRetryableTransient, } from "./error-classifier.js";
 import { safeSendUserMessage } from "./send-safe.js";
+import { maybeSendProviderOutageAdvisory } from "./outage-advisor.js";
 import { vectorStats } from "../../src/vectorStore.js";
 /** Register agent/turn tracking event handlers. */
 export function registerAgentHandlers(pi, runtime, config) {
@@ -153,7 +154,10 @@ export function registerAgentHandlers(pi, runtime, config) {
                                 try {
                                     if (runtime.rt.sessionId !== liveSid)
                                         return; // session reset
-                                    const since2 = now - (runtime.rt.lastNativeCompactAt ?? 0);
+                                    // IMPORTANT: recompute Date.now() inside the timeout.
+                                    // `now` above is the durable-trim handler's timestamp and can be
+                                    // ~500ms stale by the time this callback runs.
+                                    const since2 = Date.now() - (runtime.rt.lastNativeCompactAt ?? 0);
                                     if (runtime.rt.lastNativeCompactAt !== stamp &&
                                         since2 < cooldownMs)
                                         return;
@@ -226,6 +230,15 @@ export function registerAgentHandlers(pi, runtime, config) {
     pi.on("turn_end", async (event, ctx) => {
         runtime.dashboard.event("turn_end", { turnIndex: event.turnIndex });
         runtime.snapshot(ctx);
+        // S53: consume staged recall blocks ONLY if they were actually injected
+        // into a view this turn. If no context event fired (edge: turn ended
+        // before any LLM call), recallInjectedThisTurn stays false and the blocks
+        // remain staged for the next turn's first context event.
+        if (config.recallTailInject && runtime.rt.recallInjectedThisTurn) {
+            runtime.pendingRecallBlock = undefined;
+            runtime.pendingMemoryRecallBlock = undefined;
+            runtime.rt.recallInjectedThisTurn = false;
+        }
         // S43 (per-turn tracking): record one turn row with the cached metrics so
         // the turn layer is queryable + forkable. Best-effort + non-fatal: a write
         // failure never breaks the agent loop.
@@ -336,6 +349,7 @@ export function registerAgentHandlers(pi, runtime, config) {
             }
             else {
                 const category = classifyError(event.message);
+                const detail = classifyErrorDetailed(event.message);
                 // R3: stateful poisoned-context signal — repeated identical error text
                 // across consecutive turns. The classifier is stateless, so this
                 // upgrade happens here. A 'transient' (or 'poisoned-context') turn
@@ -373,6 +387,13 @@ export function registerAgentHandlers(pi, runtime, config) {
                             if (!isKnownRetryableTransient(errSig)) {
                                 effectiveCategory = "poisoned-context";
                             }
+                            else {
+                                runtime.logger.info("repeat-upgrade-declined", {
+                                    sessionId: runtime.rt.sessionId,
+                                    signature: (errSig || '').slice(0, 500),
+                                    repeatCount: runtime.rt.errorTextRepeatCount,
+                                });
+                            }
                         }
                     }
                 }
@@ -388,6 +409,9 @@ export function registerAgentHandlers(pi, runtime, config) {
                     runtime.rt.consecutiveErrors = 0; // S38.6: circuit-breaker reset on success
                     // R4: a successful assistant turn consumes any queued nudge.
                     runtime.rt.retryNudgePending = false;
+                    // R10: reset outage advisory so a recovered-then-flapping
+                    // provider re-advises once per episode.
+                    runtime.rt.providerOutageAdvised = false;
                 }
                 else if (effectiveCategory === "compaction-noop") {
                     // (4) pi race / manual compact catch — NOT retryable. The compaction
@@ -487,22 +511,31 @@ export function registerAgentHandlers(pi, runtime, config) {
                     runtime.rt.consecutiveErrors++; // still counts toward the circuit breaker
                     runtime.rt.poisonedCount++; // R7: dashboard counter
                     const sig = errSig || "unknown";
-                    // (a) dashboard + log
+                    // (a) dashboard + log — R11: include signal + rawText for forensics
                     runtime.dashboard.event("poisoned_context", {
                         signature: sig,
                         repeatCount: runtime.rt.errorTextRepeatCount,
                         turnIndex: event.turnIndex,
                         sessionId: runtime.rt.sessionId,
+                        signal: detail.signal,
+                        rawText: (errSig || '').slice(0, 500),
+                        ...(detail.httpStatus !== undefined ? { httpStatus: detail.httpStatus } : {}),
                     });
                     runtime.logger.warn("poisoned-context", {
                         sessionId: runtime.rt.sessionId,
                         turnIndex: event.turnIndex,
                         signature: sig,
                         repeatCount: runtime.rt.errorTextRepeatCount,
+                        signal: detail.signal,
+                        rawText: (errSig || '').slice(0, 500),
+                        ...(detail.httpStatus !== undefined ? { httpStatus: detail.httpStatus } : {}),
                     });
-                    // (b) one-per-session advise message (throttled by poisonedAdviseSent)
-                    if (!runtime.rt.poisonedAdviseSent) {
-                        runtime.rt.poisonedAdviseSent = true;
+                    // (b) throttle flag: set unconditionally so the advise fires at
+                    // most once per session regardless of channel.
+                    runtime.rt.poisonedAdviseSent = true;
+                    // Legacy flag-OFF path: user-role advise message.
+                    // Default ON (advisoryChannel=true): dashboard-only, no user message.
+                    if (!config.advisoryChannel) {
                         // PREVENT-PI-003: user-role sendUserMessage only.
                         await safeSendUserMessage(pi, "[mega-compact] this session's context may be poisoned (the provider is rejecting every request). Run /clear or /new to start a fresh context.");
                     }
@@ -552,6 +585,8 @@ export function registerAgentHandlers(pi, runtime, config) {
                     }
                     // S38.6: circuit-breaker — stop retrying after too many consecutive errors.
                     runtime.rt.consecutiveErrors++;
+                    // R10: send calm "provider outage" advisory once per episode.
+                    await maybeSendProviderOutageAdvisory(effectiveCategory, runtime, pi, config, { signal: detail.signal, rawText: (errSig || '').slice(0, 500) });
                     if (runtime.rt.consecutiveErrors > config.maxConsecutiveErrors) {
                         runtime.dashboard.event("error_retry_circuit_open", {
                             consecutive: runtime.rt.consecutiveErrors,

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

@@ -46,6 +46,7 @@ async function nudgeResume(pi, runtime) {
         const now = Date.now();
         if (now >= runtime.resumeNudgeUntil) {
             runtime.resumeNudgeUntil = now + 30_000;
+            runtime.rt.extensionInitiatedTurn = true; // R13: suppress self-classification
             await safeSendUserMessage(pi, "[mega-compact] continue from the compacted context above.");
         }
     }

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

@@ -1,4 +1,4 @@
-import { openStore, appendRawTranscript, writeCheckpointEpoch, } from "../../src/store/sqlite.js";
+import { openStore, 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";
@@ -9,75 +9,8 @@ import { openTurnStore } from "../../src/store/turns/connection.js";
 import { buildTopicModel, createTopicStore, bumpWikiCompactCounter, } from "../../src/topics/index.js";
 import { computeLiveTrimCut, liveTrimSummaryMessage } from "../mega-trim.js";
 import { pressureFromPct, pressureRatio, } from "../mega-config.js";
-import { computeContentDigest } from "../../src/dedup/digest.js";
-/**
- * Recursively canonicalize a value for deterministic JSON serialization:
- * - Objects: keys sorted alphabetically, values recursively canonicalized
- * - Arrays: elements recursively canonicalized (array ORDER is preserved)
- * - Primitives: returned as-is
- *
- * F5 fix: shallow-sorted JSON.stringify(content, Object.keys(content).sort())
- * omitted nested keys not in the top-level keys array and only sorted one level.
- * This recursively sorts every object at every depth so semantically-equal
- * differently-ordered content hashes identically.
- */
-function canonicalize(value) {
-    if (value === null || value === undefined)
-        return value;
-    if (typeof value !== "object")
-        return value;
-    if (Array.isArray(value))
-        return value.map(canonicalize);
-    // Plain object: sort keys, recursively canonicalize values.
-    const sorted = Object.keys(value).sort();
-    const out = {};
-    for (const k of sorted) {
-        out[k] = canonicalize(value[k]);
-    }
-    return out;
-}
-/**
- * Convert a pi AgentMessage to a RawTranscriptRow for the DB mirror.
- * content_bytes is canonical JSON (sorted keys, recursive) for deterministic
- * storage; contentHash is the canonical digest (normalize + hash) that matches
- * what dedupTranscript computes so the two pipelines use the same linkage key.
- *
- * F4 fix: the hash key MUST match on both sides of the append/dedup split.
- * Using computeContentDigest here (normalize → hash) ensures content_ref set
- * by dedupTranscript always resolves to an existing dedup_mirror row even for
- * whitespace/case-variant content. F5 fix: recursive canonicalize replaces the
- * broken shallow-sorted JSON.stringify replacer.
- */
-function toRawTranscriptRow(msg, sessionId, epochId, currentTurn) {
-    // Narrow to Message union (has content + timestamp).
-    const m = msg;
-    const content = m.content;
-    if (content == null || content === "")
-        return null;
-    // Canonical bytes: string content → normalize for consistent byte content;
-    // object content → recursive canonicalize then JSON (no replacer).
-    const contentBytes = typeof content === "string"
-        ? content // F5: strings are primitives; their byte content is fixed
-        : JSON.stringify(canonicalize(content));
-    // F4 fix: use the same digest as dedupTranscript so contentHash is consistent
-    // on both sides of the append/dedup split. computeContentDigest normalizes
-    // (strip ANSI, NFC, case-fold, collapse whitespace) then hashes → the same
-    // key is stored in raw_transcript.content_hash AND used as the dedup link.
-    const { contentHash } = computeContentDigest(contentBytes);
-    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,
-        // S50: label the row with the turn that produced it (per-turn dedup /
-        // compression-by-turn metrics). Null when the writer omits it (back-compat).
-        turnIndex: currentTurn ?? null,
-    };
-}
+import { appendMirrorMessages } from "./mirror-append.js";
+import { stagedForTail, withRecallTail } from "./recall-tail.js";
 /** Register the context event handler (live-trim auto-trigger). */
 export function registerContextHandler(pi, runtime, config) {
     // ---- Auto-trigger: live trim (compact and continue) + native durable ----
@@ -98,6 +31,17 @@ export function registerContextHandler(pi, runtime, config) {
         const usage = ctx.getContextUsage();
         const pct = usage?.percent;
         const messages = event.messages;
+        // S53: helper to inject the staged recall/memory block as a user-role
+        // tail message at any view-return point. Returns undefined when nothing
+        // is staged (or the flag is OFF) so the caller falls through to its
+        // normal return. The F3 mirror append (above the gates) runs on the
+        // REAL transcript before any view is built, so the injected tail never
+        // reaches raw_transcript (PREVENT-PI: append-only, view-only).
+        const tailResult = (msgs) => {
+            if (!stagedForTail(runtime, config))
+                return undefined;
+            return { messages: withRecallTail(msgs ?? messages, runtime, config) };
+        };
         // Always track context for the dashboard/widget, even when auto is off.
         // (v0.8 regression: !config.auto gate sat above this, leaving ctx stats
         // null -> widget '?% / ?/?' when auto disabled. Track first, THEN gate.)
@@ -118,21 +62,24 @@ export function registerContextHandler(pi, runtime, config) {
         runtime.lastCtxPercent = pct ?? null;
         runtime.lastCtxWindow = usage?.contextWindow ?? 0;
         runtime.snapshot(ctx);
-        if (!config.auto)
+        if (!config.auto) {
+            const tailed = tailResult();
+            if (tailed)
+                return tailed;
             return;
+        }
         const view = viewForFallback ?? runtime.engineView(messages);
-        // S27 DB-mirror: append ALL incoming messages to raw_transcript.
+        // S27 DB-mirror: append 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).
+        // F3: high-water mark (mirror-append.ts) skips already-processed
+        // messages on subsequent events. On fork/rewind (shorter list or
+        // boundary hash mismatch) the mark is dropped, falling back to a
+        // full reprocess.
         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, runtime.currentTurn);
-                    if (raw)
-                        appendRawTranscript(db, raw);
-                }
+                appendMirrorMessages(db, messages, runtime.rt.sessionId, epochIdFor(runtime.rt.sessionId), runtime.currentTurn);
             }
             catch (e) {
                 runtime.logger.warn("db-mirror-append-fail", { error: String(e) });
@@ -157,18 +104,18 @@ export function registerContextHandler(pi, runtime, config) {
             // custom tier OR tiered-but-pct-unavailable → token gate (S27 fallback).
             if (currentTokens < runtime.effectiveThreshold) {
                 runtime.diagCtxFastGate++;
-                return;
+                return tailResult() ?? undefined;
             }
             const check = autoCompactCheck(currentTokens, runtime.effectiveThreshold); // SERVER-STYLE CONFIRM (local)
             if (!check.shouldCompact) {
                 runtime.diagCtxNoCompact++;
-                return;
+                return tailResult() ?? undefined;
             }
             gatePassed = true;
         }
         if (!gatePassed) {
             runtime.diagCtxFastGate++;
-            return;
+            return tailResult() ?? undefined;
         }
         // D.2: Replay MUST be exempt from debounce — replay is free (no compute,
         // no re-write) and prevents unnecessary KV-cache invalidation. Check
@@ -197,9 +144,8 @@ export function registerContextHandler(pi, runtime, config) {
                 runtime.snapshot(ctx);
                 // v0.8.7: shallow-copy the cached summary so pi's transformContext can't
                 // mutate the shared reference across replays (audit P3).
-                return {
-                    messages: [{ ...runtime.trimCache.summaryAgentMsg }, ...recent],
-                };
+                const replayView = [{ ...runtime.trimCache.summaryAgentMsg }, ...recent];
+                return tailResult(replayView) ?? { messages: replayView };
             }
             // else: context grew enough → fall through to re-compact (cache is stale)
         }
@@ -208,7 +154,7 @@ export function registerContextHandler(pi, runtime, config) {
         const now = Date.now();
         if (now < runtime.debounceUntil) {
             runtime.diagCtxDebounce++;
-            return;
+            return tailResult() ?? undefined;
         }
         runtime.debounceUntil = now + 2000;
         // Adaptive compression (Fix E): scale compression strength + keepFrom depth
@@ -233,11 +179,10 @@ export function registerContextHandler(pi, runtime, config) {
                 runtime.diagLiveTrimFires++;
                 runtime.diagLiveTrimReplays++;
                 runtime.snapshot(ctx);
-                return {
-                    messages: [{ ...runtime.trimCache.summaryAgentMsg }, ...recent],
-                };
+                const skipView = [{ ...runtime.trimCache.summaryAgentMsg }, ...recent];
+                return tailResult(skipView) ?? { messages: skipView };
             }
-            return;
+            return tailResult() ?? undefined;
         }
         // S27 DB-mirror: write checkpoint_epoch with deterministic nonce.
         // This makes the cache key stable across identical compactions.
@@ -392,7 +337,7 @@ export function registerContextHandler(pi, runtime, config) {
                     viewLen: view.length,
                     anchorUserMessages,
                 });
-                return; // unsafe / below anchor floor — no trim this call
+                return tailResult() ?? undefined; // unsafe / below anchor floor — no trim this call
             }
             const summaryMsg = liveTrimSummaryMessage({
                 compactedFrom: ran.result.compactedFrom,
@@ -446,11 +391,11 @@ export function registerContextHandler(pi, runtime, config) {
                 ctxPct: pct,
                 ctxTokens: usage?.tokens ?? null,
             });
-            return { messages: [summaryAgentMsg, ...recent] };
+            return tailResult([summaryAgentMsg, ...recent]) ?? { messages: [summaryAgentMsg, ...recent] };
         }
         catch {
             runtime.diagCtxThrown++;
-            return; // non-fatal: no trim this call; the next context event retries
+            return tailResult() ?? undefined; // non-fatal: no trim this call; the next context event retries
         }
     });
 }

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

@@ -0,0 +1,51 @@
+const TABLE_DDL = `CREATE TABLE IF NOT EXISTS context_hwm (
+  session_id        TEXT PRIMARY KEY,
+  last_seq          INTEGER NOT NULL,
+  last_content_hash TEXT NOT NULL
+)`;
+/** Ensure the context_hwm table exists. Idempotent. */
+export function ensureHwmTable(db) {
+    try {
+        db.exec(TABLE_DDL);
+    }
+    catch {
+        // non-fatal
+    }
+}
+/** Read the high-water mark for a session. Returns undefined if none. */
+export function readHwm(db, sessionId) {
+    try {
+        const row = db
+            .prepare("SELECT session_id, last_seq, last_content_hash FROM context_hwm WHERE session_id = ?")
+            .get(sessionId);
+        if (!row)
+            return undefined;
+        return {
+            sessionId: row.session_id,
+            lastSeq: Number(row.last_seq),
+            lastContentHash: row.last_content_hash,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Write (INSERT OR REPLACE) the high-water mark for a session. */
+export function writeHwm(db, hwm) {
+    try {
+        db.prepare("INSERT OR REPLACE INTO context_hwm (session_id, last_seq, last_content_hash) VALUES (?, ?, ?)").run(hwm.sessionId, hwm.lastSeq, hwm.lastContentHash);
+    }
+    catch {
+        // non-fatal
+    }
+}
+/** Drop the high-water mark for a session (invalidation). */
+export function dropHwm(db, sessionId) {
+    try {
+        db.prepare("DELETE FROM context_hwm WHERE session_id = ?").run(sessionId);
+    }
+    catch {
+        // non-fatal
+    }
+}
+export const TEST_ONLY = { TABLE_DDL };