pi-mega-compact 0.11.4 → 0.11.6

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,9 @@ 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";
+import { buildSeparatedPrompt } from "./separated-prompt.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 +32,24 @@ 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) => {
+            const base = msgs ?? messages;
+            if (!stagedForTail(runtime, config) && !config.messageSeparation)
+                return undefined;
+            let result = stagedForTail(runtime, config)
+                ? withRecallTail(base, runtime, config)
+                : base;
+            if (config.messageSeparation) {
+                result = buildSeparatedPrompt(result);
+            }
+            return { messages: result };
+        };
         // 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 +70,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 +112,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 +152,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 +162,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 +187,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 +345,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 +399,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 };

package/dist/extensions/mega-events/error-classifier.js

@@ -63,7 +63,7 @@ export function classifyErrorDetailed(message) {
             return { category: null, signal: 'length-guard' };
         if (sr === 'aborted')
             return { category: 'cancelled', signal: 'cancelled' };
-        if (sr === 'stop' || sr === 'toolUse' || sr === 'tool_use')
+        if (/^(stop|tool_?use|end_?turn|max_?tokens|complete|finished|done)$/i.test(sr))
             return { category: null, signal: 'success' };
         const usage = m.usage;
         usagePresent = usage != null && typeof usage === 'object';
@@ -100,10 +100,21 @@ export function classifyErrorDetailed(message) {
             }
         }
         if (!sr) {
-            const r = { category: 'transient', signal: 'stream-death-no-stopreason' };
-            if (httpStatus !== undefined)
-                r.httpStatus = httpStatus;
-            return r;
+            // A missing stopReason alone is not sufficient evidence of stream death.
+            // Require at least one corroborating signal: an error field, or 0 total tokens
+            // (indicating the stream died before producing anything). A normal completion
+            // from a runtime that omits stopReason has content and tokens — not an error.
+            const hasError = (m.error != null && m.error !== undefined && m.error !== '') ||
+                (typeof m.errorMessage === 'string' && m.errorMessage !== '');
+            if (hasError || (usagePresent && totalTokens === 0)) {
+                const r = { category: 'transient', signal: 'stream-death-no-stopreason' };
+                if (httpStatus !== undefined)
+                    r.httpStatus = httpStatus;
+                return r;
+            }
+            // No stopReason, no error field, tokens present — likely a normal completion
+            // from a runtime that omits stopReason (pi-crew, etc.). Not an error.
+            return { category: null, signal: 'success' };
         }
         text = parts.join(' ');
     }

package/dist/extensions/mega-events/mirror-append.js

@@ -0,0 +1,107 @@
+import { appendRawTranscript } from "../../src/store/sqlite.js";
+import { computeContentDigest } from "../../src/dedup/digest.js";
+import { ensureHwmTable, readHwm, writeHwm, dropHwm, } from "./context-hwm.js";
+/**
+ * Append incoming messages to raw_transcript with HWM incremental support.
+ *
+ * On fork/rewind (shorter message list or boundary hash mismatch), the HWM
+ * is dropped and all messages are reprocessed.
+ */
+export function appendMirrorMessages(db, messages, sessionId, epochId, currentTurn) {
+    ensureHwmTable(db);
+    const hwm = readHwm(db, sessionId);
+    let tailStart = 0;
+    let needDrop = false;
+    if (hwm) {
+        if (messages.length <= hwm.lastSeq) {
+            // Session was shortened (fork/rewind/clear) — full reprocess.
+            needDrop = true;
+        }
+        else {
+            // Verify boundary integrity: hash of message at hwm.lastSeq-1
+            // must match the stored hash.
+            const boundaryMsg = messages[hwm.lastSeq - 1];
+            const boundaryHash = contentHashOf(boundaryMsg.content);
+            if (boundaryHash === hwm.lastContentHash) {
+                tailStart = hwm.lastSeq;
+            }
+            else {
+                needDrop = true;
+            }
+        }
+    }
+    if (needDrop) {
+        dropHwm(db, sessionId);
+    }
+    // Process tail (or all if tailStart === 0).
+    let rowsProcessed = 0;
+    for (let i = tailStart; i < messages.length; i++) {
+        const raw = toRawRow(messages[i], sessionId, epochId, currentTurn);
+        if (raw) {
+            appendRawTranscript(db, raw);
+            rowsProcessed++;
+        }
+    }
+    // Write new HWM.
+    if (messages.length > 0) {
+        const lastMsg = messages[messages.length - 1];
+        writeHwm(db, {
+            sessionId,
+            lastSeq: messages.length,
+            lastContentHash: contentHashOf(lastMsg.content),
+        });
+    }
+    return { rowsProcessed };
+}
+/** Single rule for hashing message content on BOTH sides of the HWM
+ *  (write + boundary check) — a mismatch here silently defeats the
+ *  incremental path (every event would full-reprocess). null/undefined → "". */
+function contentHashOf(content) {
+    if (content == null)
+        return "";
+    const bytes = typeof content === "string"
+        ? content
+        : JSON.stringify(canonicalize(content));
+    return computeContentDigest(bytes).contentHash;
+}
+/**
+ * Canonicalize a value for deterministic JSON serialization (keys sorted).
+ * This is the same logic as the inline function in context-handler.ts.
+ */
+function canonicalize(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    const sorted = Object.keys(value).sort();
+    const out = {};
+    for (const k of sorted) {
+        out[k] = canonicalize(value[k]);
+    }
+    return out;
+}
+/** Convert an AgentMessage to a RawTranscriptRow (same logic as toRawTranscriptRow in context-handler.ts). */
+function toRawRow(msg, sessionId, epochId, currentTurn) {
+    const m = msg;
+    const content = m.content;
+    if (content == null || content === "")
+        return null;
+    const contentBytes = typeof content === "string"
+        ? content
+        : JSON.stringify(canonicalize(content));
+    return {
+        contentHash: computeContentDigest(contentBytes).contentHash,
+        sessionId,
+        seq: 0, // assigned by appendRawTranscript
+        role: m.role ?? "unknown",
+        contentBytes,
+        toolName: m.toolName ?? null,
+        messageTimestamp: m.timestamp ?? null,
+        checkpointEpoch: epochId,
+        turnIndex: currentTurn ?? null,
+    };
+}
+// Re-export for convenience when the handler only needs the table ensure.
+export { ensureHwmTable, readHwm, writeHwm, dropHwm };

package/dist/extensions/mega-events/outage-advisor.js

@@ -49,5 +49,11 @@ export async function maybeSendProviderOutageAdvisory(effectiveCategory, runtime
         ...(detail?.signal !== undefined ? { signal: detail.signal } : {}),
         ...(detail?.rawText !== undefined ? { rawText: detail.rawText } : {}),
     });
-    await safeSendUserMessage(pi, `[mega-compact] the provider is having issues (${runtime.rt.consecutiveErrors} consecutive failures — timeouts/5xx/rate-limits). Retries are bounded and continue automatically; your context is fine — do NOT clear or reset it. Work resumes as soon as the provider recovers.`);
+    // Advisory is dashboard-only (events tab + log). No user-visible message —
+    // injecting into the conversation scares users and triggers false-positive
+    // re-classification of the resulting turn (2026-07-31 incident).
+    if (!config.advisoryChannel) {
+        // Legacy path (flag OFF): user-role message injection.
+        await safeSendUserMessage(pi, `[mega-compact] the provider is having issues (${runtime.rt.consecutiveErrors} consecutive failures — timeouts/5xx/rate-limits). Retries are bounded and continue automatically; your context is fine — do NOT clear or reset it. Work resumes as soon as the provider recovers.`);
+    }
 }

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

@@ -1,10 +1,126 @@
-import { recordPerfSample } from "../../src/store/sqlite.js";
+import { recordPerfSample, readPerfSamples, } from "../../src/store/sqlite.js";
+import { classifyPrefixBreak } from "../../src/prefix-break.js";
 /** Narrow a turn_end message to its usage block when it is an assistant msg. */
 function usageOf(msg) {
     if (msg.role !== "assistant" || !msg.usage)
         return null;
     return msg.usage;
 }
+/**
+ * Attempt to record a prefix_break sample when a significant cache_hit_pct
+ * drop is detected between two consecutive turns.
+ *
+ * Drop threshold: 20 percentage points.  When triggered, calls
+ * classifyPrefixBreak with the three candidate event timestamps from the
+ * runtime and records a `prefix_break` sample.  Best-effort + non-fatal.
+ *
+ * Also evaluates rolling cache health and emits a degradation event when the
+ * composite score falls below 0.6 (A3, PLAN_V2 Phase 4).
+ *
+ * PREVENT-PI-004: guardrails-allow PREVENT-PI-004: local SQLite write only.
+ * PREVENT-002: SQL is fully parameterized via recordPerfSample.
+ */
+function tryRecordPrefixBreak(stateDir, prevHitPct, currHitPct, breakAt, runtime) {
+    try {
+        if (prevHitPct - currHitPct < 20)
+            return; // no significant drop
+        const events = {
+            lastRecallAt: runtime.rt.lastInjectAt, // S53: inject fires alongside recall
+            lastCompactAt: runtime.rt.lastCompactAt,
+            lastInjectAt: runtime.rt.lastInjectAt,
+        };
+        const { cause, confidence } = classifyPrefixBreak(breakAt, events);
+        recordPerfSample(stateDir, "prefix_break", 0, {
+            cause,
+            confidence,
+            prevHitPct,
+            currHitPct,
+            breakAt,
+        }); // guardrails-allow PREVENT-PI-004: local SQLite write (loopback perf instrumentation)
+        // A3: compute rolling cache health score and emit alert on degradation.
+        tryComputeCacheHealth(stateDir, currHitPct, runtime);
+    }
+    catch {
+        /* non-fatal: prefix-break detection never blocks the agent loop */
+    }
+}
+/**
+ * Compute a rolling cache health score and emit a dashboard event when it
+ * falls below the degradation threshold (0.6 / "yellow").
+ *
+ * The score is a weighted composite of:
+ *   - hitRateScore (0-1): recent cache_hit_pct sample average / 100
+ *   - stabilityScore (0-1): 1 - recent prefix_break count / maxExpectedBreaks
+ *   - churnScore (0-1): 1 - stripe re-assignment rate (derived from prefix_break classifications)
+ *
+ * Weights: hit rate 50%, prefix stability 30%, churn 20%.
+ *
+ * PREVENT-PI-004: guardrails-allow PREVENT-PI-004: local SQLite read, no network.
+ * PREVENT-001: readPerfSamples returns empty array when no data; handled.
+ * PREVENT-011: no `any` — all arrays are typed PerfSampleRow[].
+ */
+function tryComputeCacheHealth(stateDir, currHitPct, runtime) {
+    try {
+        const now = Date.now();
+        const windowMs = 300_000; // 5-minute lookback
+        const sinceTs = now - windowMs;
+        // Read recent cache_hit_pct and prefix_break samples.
+        const hitSamples = readPerfSamples(stateDir, sinceTs, "cache_hit_pct");
+        const breakSamples = readPerfSamples(stateDir, sinceTs, "prefix_break");
+        // hitRateScore: average of recent cache hit percentages / 100.
+        let hitRateAvg = currHitPct;
+        if (hitSamples.length > 0) {
+            const sum = hitSamples.reduce((a, r) => a + r.value, 0);
+            hitRateAvg = sum / hitSamples.length;
+        }
+        const hitRateScore = Math.max(0, Math.min(1, hitRateAvg / 100));
+        // stabilityScore: penalize for frequent prefix breaks.
+        // Assume at most 2 breaks in 5min is tolerable.
+        const maxExpectedBreaks = 2;
+        const stabilityScore = Math.max(0, 1 - breakSamples.length / maxExpectedBreaks);
+        // churnScore: if recent breaks have varied causes, penalize.
+        const causeVariety = new Set(breakSamples.map((r) => {
+            const m = typeof r.meta === "string" ? JSON.parse(r.meta) : null;
+            return typeof m?.cause === "string" ? m.cause : "other";
+        }));
+        const churnPenalty = Math.min(1, causeVariety.size / 4); // 4 possible causes
+        const churnScore = 1 - churnPenalty;
+        // Composite: hitRate dominates.
+        const composite = hitRateScore * 0.5 + stabilityScore * 0.3 + churnScore * 0.2;
+        // Emit degradation event when score < 0.6.
+        if (composite < 0.6) {
+            const prevScore = runtime.rt._lastCacheHealthScore ?? 1;
+            runtime.rt._lastCacheHealthScore = composite;
+            recordPerfSample(stateDir, "cache_health", composite, {
+                hitRateScore: Math.round(hitRateScore * 1000) / 1000,
+                stabilityScore: Math.round(stabilityScore * 1000) / 1000,
+                churnScore: Math.round(churnScore * 1000) / 1000,
+                breakCount: breakSamples.length,
+                hitSampleCount: hitSamples.length,
+                currHitPct,
+                trend: composite < prevScore ? "falling" : "stable",
+            }); // guardrails-allow PREVENT-PI-004: local SQLite write (loopback dashboard event)
+            // Structured log line for the host to pick up.
+            const level = composite < 0.4 ? "error" : "warn";
+            // eslint-disable-next-line no-console
+            console.log(JSON.stringify({
+                ts: now,
+                event: `cache_health_${level}`,
+                composite: Math.round(composite * 1000) / 1000,
+                hitRateAvg: Math.round(hitRateAvg * 10) / 10,
+                breakCount: breakSamples.length,
+                trend: composite < prevScore ? "falling" : "stable",
+            }));
+        }
+        else {
+            // Still healthy — just update the stored score.
+            runtime.rt._lastCacheHealthScore = composite;
+        }
+    }
+    catch {
+        /* non-fatal: cache health computation never blocks */
+    }
+}
 /** Register perf instrumentation handlers + start the 5s cpu/mem interval. */
 export function registerPerfHandler(pi, runtime) {
     // turn_start: record the wall-clock start of the turn. Using Date.now() (not
@@ -23,6 +139,7 @@ export function registerPerfHandler(pi, runtime) {
     });
     // turn_end: compute turn latency + TPS + cache hit % from the assistant
     // message's usage block. One perf_samples row per metric per turn.
+    // S53A: tracks prevHitPct across turns to detect prefix breaks.
     pi.on("turn_end", async (event) => {
         try {
             if (runtime.perfTurnStart > 0) {
@@ -36,7 +153,22 @@ export function registerPerfHandler(pi, runtime) {
                     recordPerfSample(runtime.currentStateDir, "tps", u.output / durSec, { outputTokens: u.output });
                     const denom = u.cacheRead + u.input + u.cacheWrite;
                     const hitPct = denom > 0 ? (u.cacheRead / denom) * 100 : 0;
-                    recordPerfSample(runtime.currentStateDir, "cache_hit_pct", hitPct, { input: u.input, cacheRead: u.cacheRead, cacheWrite: u.cacheWrite });
+                    recordPerfSample(runtime.currentStateDir, "cache_hit_pct", hitPct, {
+                        input: u.input,
+                        cacheRead: u.cacheRead,
+                        cacheWrite: u.cacheWrite,
+                        modelName: runtime.currentModel?.modelName,
+                        modelId: runtime.currentModel?.modelId,
+                    });
+                    // S53A: detect significant cache hit % drop → record prefix_break.
+                    // Only trigger when we have a previous value AND the drop is >20pp.
+                    if (runtime.rt._prevCacheHitPct != null &&
+                        runtime.rt._prevCacheHitPct - hitPct >= 20) {
+                        const breakAt = runtime.perfTurnStart;
+                        tryRecordPrefixBreak(runtime.currentStateDir, runtime.rt._prevCacheHitPct, hitPct, breakAt, runtime);
+                    }
+                    // Stamp for the next turn's comparison (even when no break fires).
+                    runtime.rt._prevCacheHitPct = hitPct;
                 }
             }
         }

package/dist/extensions/mega-events/recall-tail.js

@@ -0,0 +1,59 @@
+/**
+ * True when recall blocks are staged AND the feature flag is ON. Called by the
+ * context handler to decide whether to call withRecallTail.
+ */
+export function stagedForTail(runtime, config) {
+    if (!config.recallTailInject)
+        return false;
+    return (runtime.pendingRecallBlock != null ||
+        runtime.pendingMemoryRecallBlock != null);
+}
+/**
+ * Append staged recall/memory blocks as a single user-role message at the very
+ * tail of the messages array. Returns a NEW array (does not mutate input).
+ *
+ * Sets `runtime.recallInjectedThisTurn = true` when it actually appends, so the
+ * turn_end handler (agent-handlers.ts) consumes the staged blocks only if they
+ * reached a view this turn. If a turn ends with no context event, the flag
+ * stays false and the blocks remain staged for the next turn.
+ *
+ * Stable timestamp (runtime.perfTurnStart ?? Date.now()) so replays within the
+ * turn are byte-identical (mirrors the v0.8.6 summaryAgentMsg rationale).
+ *
+ * Non-fatal: on any failure, returns messages unmodified and does NOT set the
+ * injected flag. PREVENT-PI-003: the injected message has role "user", never
+ * "system".
+ */
+export function withRecallTail(messages, runtime, config) {
+    if (!config.recallTailInject)
+        return messages;
+    try {
+        const blocks = [];
+        if (runtime.pendingRecallBlock != null) {
+            blocks.push(runtime.pendingRecallBlock);
+        }
+        if (runtime.pendingMemoryRecallBlock != null) {
+            blocks.push(runtime.pendingMemoryRecallBlock);
+        }
+        if (blocks.length === 0)
+            return messages;
+        const tailText = blocks.join("\n\n");
+        const timestamp = runtime.perfTurnStart ?? // stable within a turn
+            Date.now();
+        const tailMsg = {
+            role: "user",
+            content: tailText,
+            timestamp,
+        };
+        runtime.rt.recallInjectedThisTurn = true;
+        // Append at the very tail — never splits toolCall/toolResult.
+        // PREVENT-PI-001/002: a single message appended after a complete
+        // transcript prefix cannot split a toolCall/toolResult pair.
+        return [...messages, tailMsg];
+    }
+    catch {
+        // Non-fatal: leave blocks staged (flag stays unset) and return the
+        // unmodified view. The context event still proceeds normally.
+        return messages;
+    }
+}