pi-mega-compact 0.20.87 → 0.21.0

package/dist/extensions/dashboard-server/routes-rag-settings-helpers.js

@@ -134,6 +134,13 @@ export const SETTINGS = [
             num("MEGACOMPACT_THRASH_REARM_PCT", "Thrash Re-arm %", "After an ineffective compaction (live window did not shrink), refuse to re-fire until the live window grows by this fraction of the effective threshold. Default 0.10 (10%)", 0.1, 0.01, 0.5),
         ],
     },
+    {
+        name: "Three-Way Failback",
+        settings: [
+            boolDirect("MEGACOMPACT_THREE_WAY_FAILBACK", "Three-Way Failback", "Umbrella for the 3-way failback safety system: TriggerGuard (stages a recall block even when session_start never fires), the live-window ReductionValidator + persisted ThrashGuard (stops ineffective compaction re-fire loops), the 3-source read-only recall vote + same-repo relevance floor, and InjectionConfirm (asserts the staged block reached the message list pi sends). OFF = byte-identical pre-3WF behavior (v0.20.83). Runtime reads envBool(plain key), so this uses the plain-write convention (not _DISABLED).", true),
+            boolDirect("MEGACOMPACT_RECALL_TAIL_INJECT", "Recall Tail Inject", "Compose the staged recall block as a trailing user message on the context event (tail inject) instead of the legacy system-prompt prepend. Tail mode keeps the cache prefix stable and is the mode InjectionConfirm verifies against ContextEvent.messages; OFF falls back to the legacy prepend path (verified by string-contains). Runtime reads envBool(plain key), so this uses the plain-write convention (not _DISABLED).", true),
+        ],
+    },
     VECTOR_CORTEX_SETTINGS,
     {
         name: "Cost API",

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

@@ -0,0 +1,63 @@
+/**
+ * context-handler/injectionConfirm.fixture.ts — shared fixtures for the 3WF-4
+ * InjectionConfirm tests.
+ *
+ * Split out so each test file stays under the extensions/300-soft-cap the way
+ * src/recall/recall3wf.fixture.ts does for 3WF-3. These are REAL fixtures, not
+ * mocks/stubs: a REAL VectorStore over a temp stateDir with REAL checkpoints
+ * persisted via compactSession; the MegaRuntime is a minimal typed stub exposing
+ * only the fields confirmInjection touches (store, pendingRecallBlock,
+ * pendingMemoryRecallBlock, appendEvent), matching the triggerGuard/thrashGuard
+ * test conventions.
+ */
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { VectorStore } from "../../../src/vectorStore.js";
+import { compactSession } from "../../../src/engine.js";
+/** Real EngineMessage fixture. */
+export function msg(role, text) {
+    return { role, text };
+}
+/** A user-role AgentMessage carrying `text` (the tail-block shape). */
+export function userMsg(text) {
+    return { role: "user", content: text, timestamp: 1 };
+}
+/** Fresh isolated state dir per VectorStore. */
+export function freshStore() {
+    const dir = mkdtempSync(join(tmpdir(), "mc-inject-"));
+    return { store: new VectorStore({ dedupSim: 0.9, stateDir: dir }), dir };
+}
+/** Persist N distinct checkpoints with ascending timestamps. */
+export function seed(store, topics, sid = "sess_inject") {
+    topics.forEach((t, i) => {
+        compactSession({
+            sessionId: sid,
+            messages: [msg("user", t), msg("assistant", "ok")],
+            keepFrom: 2,
+            timestamp: i + 1,
+        }, store);
+    });
+}
+/** Minimal MegaRuntime stub exposing only the confirmInjection touch-points. */
+export function runtimeStub(store, over = {}) {
+    const events = [];
+    const runtime = {
+        store,
+        pendingRecallBlock: over.pendingRecallBlock,
+        pendingMemoryRecallBlock: over.pendingMemoryRecallBlock,
+        perfTurnStart: undefined,
+        rt: { recallInjectedThisTurn: false },
+        appendEvent: (name, payload) => {
+            events.push({ name, payload });
+        },
+    };
+    return { runtime, events };
+}
+/** Config stub: only the flags confirmInjection reads. */
+export function configStub(over = {}) {
+    return {
+        threeWayFailback: over.threeWayFailback ?? true,
+        recallTailInject: over.recallTailInject ?? true,
+    };
+}

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

@@ -0,0 +1,107 @@
+import { vectorList } from "../../../src/vectorStore.js";
+import { normalizeSessionId } from "../../../src/store.js";
+import { buildFloorBlock } from "../../../src/failback/floor.js";
+import { withRecallTail } from "../recall-tail.js";
+import { messageContentText } from "./messageText.js";
+/**
+ * The marker substring used to locate a staged block inside a message. The
+ * block's first non-empty line, capped, so prompt reshapes (cache striping /
+ * message separation) that regroup messages cannot defeat the match, while a
+ * genuinely dropped block still fails it.
+ */
+export function blockMarker(block) {
+    const line = block
+        .split("\n")
+        .map((l) => l.trim())
+        .find((l) => l.length > 0);
+    return (line ?? "").slice(0, 80);
+}
+/**
+ * PURE decision function: did the staged block land in this view, and if not,
+ * which rung should repair it? Takes the already-extracted message texts so it
+ * stays free of pi types and is directly unit-testable.
+ */
+export function decideInjection(input, messageTexts, hasPendingBlocks) {
+    const marker = input.staged ? blockMarker(input.staged) : "";
+    // Nothing staged => nothing to assert; NOT a miss. Injecting a floor here
+    // would push provenance text into sessions that never had recall to lose.
+    if (!marker)
+        return { landed: true, recovered: "none" };
+    const landed = messageTexts.some((t) => t.includes(marker));
+    if (landed)
+        return { landed: true, recovered: "none" };
+    // Absent: recompose when the runtime still holds pending blocks, else floor.
+    return { landed: false, recovered: hasPendingBlocks ? "recomposed" : "floor" };
+}
+/** Append `text` as a user-role tail message (same shape as recall-tail.ts). */
+function withFloorTail(view, text) {
+    const tailMsg = {
+        role: "user",
+        content: text,
+        timestamp: Date.now(),
+    };
+    return { messages: [...view.messages, tailMsg] };
+}
+/**
+ * Thin caller: verify (and if needed repair) one composed view. Returns the view
+ * to actually return from the handler. `sessionId` sources the floor checkpoints.
+ *
+ * The recompose rung deliberately re-appends via `withRecallTail` onto the
+ * ALREADY-COMPOSED view rather than re-running `buildTailResult`: the reshape
+ * stages (cache striping / message separation) are the realistic way a tail
+ * message gets regrouped away, and re-running the same composition would
+ * reproduce the same loss. Appending after the reshape is the actual repair, and
+ * it keeps the PREVENT-PI-001/002 tail-append invariant (a single user-role
+ * message after a complete prefix can never split a toolCall/toolResult pair).
+ */
+export function confirmInjection(runtime, config, view, sessionId) {
+    try {
+        if (!config.threeWayFailback)
+            return view;
+        // What the tail composition was supposed to inject. BOTH staged blocks
+        // count: withRecallTail joins recall + memory blocks into one tail
+        // message, so either one going missing is a real injection failure.
+        const staged = runtime.pendingRecallBlock ?? runtime.pendingMemoryRecallBlock ?? null;
+        // Can the recompose rung actually re-append? Only when a block is still
+        // staged on the runtime. When it is not (blocks consumed between
+        // composition and this check), or when withRecallTail declines to append,
+        // the ladder falls through to the floor rung below.
+        const hasPending = runtime.pendingRecallBlock != null ||
+            runtime.pendingMemoryRecallBlock != null;
+        // Legacy prepend mode: the block is not expected in the message list —
+        // verify our composed return value contains it instead (A3 degrade path).
+        if (!config.recallTailInject) {
+            const composed = view.messages.map(messageContentText).join("\n");
+            const marker = staged ? blockMarker(staged) : "";
+            runtime.appendEvent("injection_confirmed", {
+                mode: "prepend",
+                landed: marker ? composed.includes(marker) : true,
+            });
+            return view;
+        }
+        const verdict = decideInjection({ staged, tailMode: true }, view.messages.map(messageContentText), hasPending);
+        if (verdict.landed) {
+            runtime.appendEvent("injection_confirmed", { mode: "tail", landed: true });
+            return view;
+        }
+        if (verdict.recovered === "recomposed") {
+            const rebuilt = withRecallTail(view.messages, runtime, config);
+            // withRecallTail returns the input array unchanged on failure; only
+            // treat a genuine append as a recovery.
+            if (rebuilt.length > view.messages.length) {
+                runtime.appendEvent("injection_recovered", { via: "recomposed" });
+                return { messages: rebuilt };
+            }
+        }
+        const floor = buildFloorBlock(vectorList(runtime.store, normalizeSessionId(sessionId)));
+        runtime.appendEvent("injection_recovered", {
+            via: "floor",
+            basis: floor.basis,
+        });
+        return withFloorTail(view, floor.text);
+    }
+    catch {
+        // Non-fatal: return the unverified view (pre-sprint behavior).
+        return view;
+    }
+}

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

@@ -48,8 +48,17 @@ export const ReductionValidator = {
  * Infinity/NaN into meta (getMetaNumber would read it back as 0). Skip arming
  * + log instead; the next over-threshold event simply re-fires (pre-sprint
  * behavior) rather than corrupting the guard.
+ *
+ * 3WF-5 telemetry: `logger` is the debug-gated runtime logger (mega-compact.log,
+ * silent unless config.debug) — which means the breadcrumb was invisible to the
+ * dashboard Events tab, whose SSE tail reads the repo's events.log. `emit` is
+ * the always-on events.log sink (MegaRuntime.appendEvent), so the armed
+ * breadcrumb lands in the same stream as the other 3WF events
+ * (three_way_guard_fired / three_way_floor_used / injection_confirmed /
+ * injection_recovered). Both sinks are optional + best-effort; passing neither
+ * keeps the pre-3WF-5 behavior.
  */
-export function armThrashGuard(currentTokens, rearmPct, effectiveThreshold, stateDir, logger) {
+export function armThrashGuard(currentTokens, rearmPct, effectiveThreshold, stateDir, logger, emit) {
     if (!Number.isFinite(currentTokens) || currentTokens <= 0)
         return;
     if (!Number.isFinite(rearmPct) || rearmPct <= 0)
@@ -65,11 +74,18 @@ export function armThrashGuard(currentTokens, rearmPct, effectiveThreshold, stat
         const n = Math.round(rearmPct * effectiveThreshold);
         setMetaNumber(THRASH_BASELINE_KEY, Math.round(currentTokens), stateDir);
         setMetaNumber(THRASH_BLOCKED_KEY, Math.round(currentTokens + n), stateDir);
-        logger?.info("thrasguard_armed", {
+        const fields = {
             baselineTokens: Math.round(currentTokens),
             blockedUntilTokens: Math.round(currentTokens + n),
             rearmTokens: n,
-        });
+        };
+        logger?.info("thrasguard_armed", fields);
+        try {
+            emit?.("thrasguard_armed", fields);
+        }
+        catch {
+            /* non-fatal: events.log sink must never break arming */
+        }
     }
     catch {
         /* non-fatal: best-effort meta write */
@@ -177,7 +193,13 @@ export function evaluatePendingReduction(runtime, currentTokens, config) {
             // Remember which event armed us so the consult later in THIS SAME event
             // does not swallow it (see armedOnEvent).
             armedOnEvent.set(runtime, currentTokens);
-            armThrashGuard(currentTokens, config.thrashRearmPct, runtime.effectiveThreshold, runtime.currentStateDir, runtime.logger);
+            // 3WF-5: also emit the breadcrumb on the always-on events.log sink so
+            // the dashboard Events tab sees it (runtime.logger is debug-gated).
+            // Optional-chained: a thin runtime stub without appendEvent stays valid.
+            const emit = typeof runtime.appendEvent === "function"
+                ? runtime.appendEvent.bind(runtime)
+                : undefined;
+            armThrashGuard(currentTokens, config.thrashRearmPct, runtime.effectiveThreshold, runtime.currentStateDir, runtime.logger, emit);
         }
     }
     catch {

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

@@ -0,0 +1,128 @@
+/**
+ * context-handler/threeWayTelemetry.fixture.ts — shared fixtures for the 3WF-5
+ * telemetry verification tests.
+ *
+ * Split out so the test file stays under the soft cap, mirroring
+ * src/recall/recall3wf.fixture.ts (3WF-3) and injectionConfirm.fixture.ts (3WF-4).
+ *
+ * These are REAL fixtures, not mocks/stubs. The critical difference from the
+ * 3WF-1..4 fixtures: those record `appendEvent` calls into an in-memory array,
+ * which proves the CALL happened but says nothing about the wire format or the
+ * file the dashboard actually tails. Here `appendEvent` is wired to the REAL
+ * `appendEventImpl` (extensions/mega-runtime/append-event.ts) against a temp
+ * stateDir, so each breadcrumb is serialized to a real events.log exactly as it
+ * is in production. The tests then read that file back and parse the JSON — the
+ * `ts` + `event` shape is observed, never simulated.
+ */
+import { mkdtempSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { VectorStore } from "../../../src/vectorStore.js";
+import { compactSession } from "../../../src/engine.js";
+import { appendEventImpl } from "../../mega-runtime/append-event.js";
+/** Real EngineMessage fixture. */
+export function msg(role, text) {
+    return { role, text };
+}
+/** A user-role AgentMessage carrying `text` (the tail-block shape). */
+export function userMsg(text) {
+    return { role: "user", content: text, timestamp: 1 };
+}
+/** Fresh isolated state dir per VectorStore. */
+export function freshStore() {
+    const dir = mkdtempSync(join(tmpdir(), "mc-3wf5-"));
+    return { store: new VectorStore({ dedupSim: 0.9, stateDir: dir }), dir };
+}
+/** Persist N distinct checkpoints with ascending timestamps. */
+export function seed(store, topics, sid) {
+    topics.forEach((t, i) => {
+        compactSession({
+            sessionId: sid,
+            messages: [msg("user", t), msg("assistant", "ok")],
+            keepFrom: 2,
+            timestamp: i + 1,
+        }, store);
+    });
+}
+/**
+ * Read + JSON-parse every line of the REAL events.log written under `stateDir`.
+ * PREVENT-001: parse failures are surfaced as null and filtered, never thrown.
+ */
+export function readEventsLog(stateDir) {
+    const path = join(stateDir, "events.log");
+    if (!existsSync(path))
+        return [];
+    return readFileSync(path, "utf-8")
+        .split("\n")
+        .filter((l) => l.trim().length > 0)
+        .map((line) => {
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed == null || typeof parsed !== "object")
+                return null;
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((e) => e != null);
+}
+/** Silent logger (the debug-gated sink is not under test here). */
+export const noopLogger = {
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+};
+/**
+ * MegaRuntime whose `appendEvent` is the REAL events.log writer bound to
+ * `stateDir`. Only the fields the 3WF guards touch are populated.
+ */
+export function realEventRuntime(store, stateDir, over = {}) {
+    const self = {
+        store,
+        currentStateDir: stateDir,
+        pendingRecallBlock: over.pendingRecallBlock,
+        pendingMemoryRecallBlock: over.pendingMemoryRecallBlock,
+        effectiveThreshold: over.effectiveThreshold ?? 100_000,
+        lastCtxWindow: 0,
+        logger: noopLogger,
+        perfTurnStart: undefined,
+        rt: { recallInjectedThisTurn: false, lastCheckpointId: null },
+        appendEvent(event, fields) {
+            appendEventImpl({ currentStateDir: stateDir }, event, fields);
+        },
+    };
+    return self;
+}
+/** ctx stub with a configurable session id + latest-user query. */
+export function ctxStub(opts = {}) {
+    const sessionId = opts.sessionId ?? "sess_3wf5";
+    const query = opts.query ?? "dedupe race in store";
+    return {
+        cwd: "/tmp",
+        sessionManager: {
+            getSessionId: () => sessionId,
+            getEntries: () => [
+                {
+                    type: "message",
+                    id: "e1",
+                    parentId: null,
+                    timestamp: "1",
+                    message: { role: "user", content: query },
+                },
+            ],
+        },
+    };
+}
+/** Config stub: only the flags the 3WF guards read. */
+export function configStub(over = {}) {
+    return {
+        threeWayFailback: over.threeWayFailback ?? true,
+        recallTailInject: over.recallTailInject ?? true,
+        thrashRearmPct: over.thrashRearmPct ?? 0.1,
+        autoInlineK: 3,
+        tier: "custom",
+        tierPct: null,
+    };
+}

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

@@ -2,6 +2,7 @@ import { normalizeSessionId } from "../../../src/store.js";
 import { recall } from "../../../src/engine.js";
 import { formatRecallBlock } from "../../../src/recall.js";
 import { vectorStats, vectorList } from "../../../src/vectorStore.js";
+import { buildFloorBlock as sharedFloorBlock, FLOOR_UNAVAILABLE_TEXT, } from "../../../src/failback/floor.js";
 import { recentUserQuery } from "../../mega-runtime.js";
 /** One-shot completion marker per MegaRuntime (dies with the runtime). */
 const guardDone = new WeakMap();
@@ -61,26 +62,19 @@ export function runTriggerGuard(runtime, config, ctx) {
         /* never throws; best-effort guard */
     }
 }
-/** Build the provenance floor string from the session's newest checkpoint. */
+/**
+ * Build the provenance floor string from the session's newest checkpoint.
+ *
+ * 3WF-4: the text construction moved to the SHARED pure builder
+ * (src/failback/floor.ts) — this keeps the store read (`vectorList`, unfiltered,
+ * exactly as 3WF-1 shipped) and the string return type, so output is
+ * byte-identical to the pre-refactor version.
+ */
 function buildFloorBlock(runtime, sid) {
     try {
-        const cps = vectorList(runtime.store, sid);
-        let newest = cps[0];
-        for (const cp of cps) {
-            if (!newest || (cp.timestamp ?? 0) > (newest.timestamp ?? 0))
-                newest = cp;
-        }
-        const summary = newest?.summary?.trim();
-        if (summary) {
-            return ("The following compacted context is the most recent checkpoint from " +
-                "this session (recall found no query-relevant match):\n\n" + summary);
-        }
-        return ("This session has compacted context but recall could not surface a " +
-            "checkpoint relevant to the current request; the most recent checkpoint " +
-            "summary is unavailable.");
+        return sharedFloorBlock(vectorList(runtime.store, sid)).text;
     }
     catch {
-        return ("This session has compacted context but recall could not surface a " +
-            "checkpoint relevant to the current request.");
+        return FLOOR_UNAVAILABLE_TEXT;
     }
 }

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

@@ -2,6 +2,7 @@ import { estimateSessionTokens } from "../../src/tokens.js";
 import { piCompactWouldNoop } from "../mega-pipeline.js";
 import { buildTailResult } from "./context-handler/tailResult.js";
 import { runTriggerGuard } from "./context-handler/triggerGuard.js";
+import { confirmInjection } from "./context-handler/injectionConfirm.js";
 import { persistEpochAndMaintain } from "./context-handler/afterCompact.js";
 import { appendMirrorAndLedger } from "./context-handler/dbMirrorAppend.js";
 import { evaluateGate, thrashGuardBlocks } from "./context-handler/gateCheck.js";
@@ -43,7 +44,22 @@ export function registerContextHandler(pi, runtime, config) {
         // 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.
-        const tailResult = buildTailResult(runtime, config, messages);
+        const composeTail = buildTailResult(runtime, config, messages);
+        // 3WF-4 InjectionConfirm: wrap the tail factory so EVERY return point of
+        // this handler (gate / replay / debounce / thrash-guard / pipeline /
+        // live-trim) is verified — the staged block's marker must be present in
+        // the message list pi will send (tail mode), else we re-compose from the
+        // runtime's pending blocks and finally fall back to the shared floor.
+        // A composition that yields nothing staged (undefined) is passed through
+        // untouched, so flag-OFF and no-recall paths are byte-identical.
+        const tailResult = config.threeWayFailback
+            ? (msgs) => {
+                const view = composeTail(msgs);
+                if (!view)
+                    return view;
+                return confirmInjection(runtime, config, view, ctx.sessionManager.getSessionId());
+            }
+            : composeTail;
         // 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.)

package/dist/src/failback/floor.js

@@ -0,0 +1,35 @@
+/** Floor text when the newest checkpoint summary is available (prefix). */
+const WITH_SUMMARY_PREFIX = "The following compacted context is the most recent checkpoint from " +
+    "this session (recall found no query-relevant match):\n\n";
+/** Floor text when checkpoints exist but no usable summary does. */
+const NO_SUMMARY_TEXT = "This session has compacted context but recall could not surface a " +
+    "checkpoint relevant to the current request; the most recent checkpoint " +
+    "summary is unavailable.";
+/** Floor text when the checkpoint read itself failed (hard last resort). */
+export const FLOOR_UNAVAILABLE_TEXT = "This session has compacted context but recall could not surface a " +
+    "checkpoint relevant to the current request.";
+/** The newest checkpoint by timestamp (first element wins ties, as before). */
+export function newestCheckpoint(cps) {
+    let newest = cps[0];
+    for (const cp of cps) {
+        if (!newest || (cp.timestamp ?? 0) > (newest.timestamp ?? 0))
+            newest = cp;
+    }
+    return newest;
+}
+/**
+ * Build the provenance floor from an already-read checkpoint list. Pure: the
+ * caller owns the read (and any dedup-status filtering), so both legacy call
+ * sites keep byte-identical output.
+ */
+export function buildFloorBlock(cps) {
+    const summary = newestCheckpoint(cps)?.summary?.trim();
+    if (summary) {
+        return { text: WITH_SUMMARY_PREFIX + summary, basis: "lastCheckpoint" };
+    }
+    return { text: NO_SUMMARY_TEXT, basis: "lastCheckpoint" };
+}
+/** The hard last-resort floor (checkpoint read unavailable or threw). */
+export function unavailableFloorBlock() {
+    return { text: FLOOR_UNAVAILABLE_TEXT, basis: "none" };
+}

package/dist/src/recall/validator.js

@@ -26,36 +26,22 @@ import { defaultEmbedder, cosineSimilarity } from "../embedder.js";
 // [] for live sessions). Mirrors vector-search.ts / tieredRouter.ts.
 import { listCheckpoints } from "../store/sqlite.js";
 import { RECALL_MIN_COSINE } from "../config.js";
-/** Build the provenance floor block from the session's newest checkpoint. */
+import { buildFloorBlock as sharedFloorBlock, unavailableFloorBlock, } from "../failback/floor.js";
+/**
+ * Build the provenance floor block from the session's newest checkpoint.
+ *
+ * 3WF-4: the text construction moved to the SHARED pure builder
+ * (src/failback/floor.ts). This wrapper keeps THIS call site's read semantics —
+ * `listCheckpoints` filtered to `dedupStatus !== "removed"` — so the output is
+ * byte-identical to the pre-refactor 3WF-3 version.
+ */
 function buildFloorBlock(sessionId, store) {
     try {
         const cps = listCheckpoints(sessionId, store.stateDir).filter((c) => c.dedupStatus !== "removed");
-        let newest = cps[0];
-        for (const cp of cps) {
-            if (!newest || (cp.timestamp ?? 0) > (newest.timestamp ?? 0))
-                newest = cp;
-        }
-        const summary = newest?.summary?.trim();
-        if (summary) {
-            return {
-                text: "The following compacted context is the most recent checkpoint from " +
-                    "this session (recall found no query-relevant match):\n\n" + summary,
-                basis: "lastCheckpoint",
-            };
-        }
-        return {
-            text: "This session has compacted context but recall could not surface a " +
-                "checkpoint relevant to the current request; the most recent checkpoint " +
-                "summary is unavailable.",
-            basis: "lastCheckpoint",
-        };
+        return sharedFloorBlock(cps);
     }
     catch {
-        return {
-            text: "This session has compacted context but recall could not surface a " +
-                "checkpoint relevant to the current request.",
-            basis: "none",
-        };
+        return unavailableFloorBlock();
     }
 }
 /**

package/extensions/dashboard-server/routes-rag-settings-helpers.ts

@@ -296,6 +296,23 @@ export const SETTINGS: ReadonlyArray<SettingGroup> = [
 			),
 		],
 	},
+	{
+		name: "Three-Way Failback",
+		settings: [
+			boolDirect(
+				"MEGACOMPACT_THREE_WAY_FAILBACK",
+				"Three-Way Failback",
+				"Umbrella for the 3-way failback safety system: TriggerGuard (stages a recall block even when session_start never fires), the live-window ReductionValidator + persisted ThrashGuard (stops ineffective compaction re-fire loops), the 3-source read-only recall vote + same-repo relevance floor, and InjectionConfirm (asserts the staged block reached the message list pi sends). OFF = byte-identical pre-3WF behavior (v0.20.83). Runtime reads envBool(plain key), so this uses the plain-write convention (not _DISABLED).",
+				true,
+			),
+			boolDirect(
+				"MEGACOMPACT_RECALL_TAIL_INJECT",
+				"Recall Tail Inject",
+				"Compose the staged recall block as a trailing user message on the context event (tail inject) instead of the legacy system-prompt prepend. Tail mode keeps the cache prefix stable and is the mode InjectionConfirm verifies against ContextEvent.messages; OFF falls back to the legacy prepend path (verified by string-contains). Runtime reads envBool(plain key), so this uses the plain-write convention (not _DISABLED).",
+				true,
+			),
+		],
+	},
 	VECTOR_CORTEX_SETTINGS,
 	{
 		name: "Cost API",

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

@@ -0,0 +1,90 @@
+/**
+ * context-handler/injectionConfirm.fixture.ts — shared fixtures for the 3WF-4
+ * InjectionConfirm tests.
+ *
+ * Split out so each test file stays under the extensions/300-soft-cap the way
+ * src/recall/recall3wf.fixture.ts does for 3WF-3. These are REAL fixtures, not
+ * mocks/stubs: a REAL VectorStore over a temp stateDir with REAL checkpoints
+ * persisted via compactSession; the MegaRuntime is a minimal typed stub exposing
+ * only the fields confirmInjection touches (store, pendingRecallBlock,
+ * pendingMemoryRecallBlock, appendEvent), matching the triggerGuard/thrashGuard
+ * test conventions.
+ */
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { VectorStore } from "../../../src/vectorStore.js";
+import { compactSession } from "../../../src/engine.js";
+import type { MegaRuntime } from "../../mega-runtime.js";
+import type { MegaConfig } from "../../mega-config.js";
+
+/** Real EngineMessage fixture. */
+export function msg(role: "user" | "assistant", text: string): any {
+	return { role, text };
+}
+
+/** A user-role AgentMessage carrying `text` (the tail-block shape). */
+export function userMsg(text: string): AgentMessage {
+	return { role: "user", content: text, timestamp: 1 } as unknown as AgentMessage;
+}
+
+/** Recorded appendEvent calls, for telemetry assertions. */
+export interface RecordedEvent {
+	name: string;
+	payload: Record<string, unknown>;
+}
+
+/** Fresh isolated state dir per VectorStore. */
+export function freshStore(): { store: VectorStore; dir: string } {
+	const dir = mkdtempSync(join(tmpdir(), "mc-inject-"));
+	return { store: new VectorStore({ dedupSim: 0.9, stateDir: dir }), dir };
+}
+
+/** Persist N distinct checkpoints with ascending timestamps. */
+export function seed(store: VectorStore, topics: string[], sid = "sess_inject"): void {
+	topics.forEach((t, i) => {
+		compactSession(
+			{
+				sessionId: sid,
+				messages: [msg("user", t), msg("assistant", "ok")],
+				keepFrom: 2,
+				timestamp: i + 1,
+			},
+			store,
+		);
+	});
+}
+
+/** Minimal MegaRuntime stub exposing only the confirmInjection touch-points. */
+export function runtimeStub(
+	store: VectorStore,
+	over: Partial<{
+		pendingRecallBlock: string | undefined;
+		pendingMemoryRecallBlock: string | undefined;
+	}> = {},
+): { runtime: MegaRuntime; events: RecordedEvent[] } {
+	const events: RecordedEvent[] = [];
+	const runtime = {
+		store,
+		pendingRecallBlock: over.pendingRecallBlock,
+		pendingMemoryRecallBlock: over.pendingMemoryRecallBlock,
+		perfTurnStart: undefined,
+		rt: { recallInjectedThisTurn: false },
+		appendEvent: (name: string, payload: Record<string, unknown>) => {
+			events.push({ name, payload });
+		},
+	} as unknown as MegaRuntime;
+	return { runtime, events };
+}
+
+/** Config stub: only the flags confirmInjection reads. */
+export function configStub(
+	over: Partial<{ threeWayFailback: boolean; recallTailInject: boolean }> = {},
+): MegaConfig {
+	return {
+		threeWayFailback: over.threeWayFailback ?? true,
+		recallTailInject: over.recallTailInject ?? true,
+	} as unknown as MegaConfig;
+}

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

@@ -0,0 +1,168 @@
+/**
+ * context-handler/injectionConfirm.ts — 3WF-4 InjectionConfirm.
+ *
+ * QA amendment A3 (binding): pi exposes NO prompt readback API, so the only
+ * verifiable proxy for what the provider will actually receive is the pre-LLM
+ * message list. In DEFAULT tail mode (`recallTailInject` ON) the staged recall
+ * block rides in as a user-role tail message, so we assert the block's marker
+ * text is present in the message list we are about to return. In LEGACY prepend
+ * mode (`recallTailInject` OFF) the block never enters the message list at all,
+ * so the guard degrades to a string-contains check over our own composed return
+ * value and never reports a false miss.
+ *
+ * Recovery ladder when the marker is absent (tail mode only):
+ *   1. recomposed — rebuild the view from the runtime's pending blocks via the
+ *      SAME `buildTailResult` composition the handler uses (self-repair on this
+ *      event; the user sees nothing).
+ *   2. floor — nothing pending either: append the shared provenance floor text
+ *      (src/failback/floor.ts) as a user-role tail message so the model is never
+ *      silently left with no compacted-context provenance at all.
+ *
+ * Stack position: wraps the `tailResult` closure returned by buildTailResult, so
+ * EVERY return point of the context handler (gate / replay / debounce /
+ * thrash-guard / pipeline / live-trim) is verified with one wiring point.
+ *
+ * Non-fatal everywhere: any throw degrades to the unverified view (pre-sprint
+ * behavior). Flag OFF => the wrapper is never installed (byte-identical).
+ */
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { MegaRuntime } from "../../mega-runtime.js";
+import type { MegaConfig } from "../../mega-config.js";
+import type { InjectionVerdict } from "../../../src/failback/types.js";
+import { vectorList } from "../../../src/vectorStore.js";
+import { normalizeSessionId } from "../../../src/store.js";
+import { buildFloorBlock } from "../../../src/failback/floor.js";
+import { withRecallTail } from "../recall-tail.js";
+import { messageContentText } from "./messageText.js";
+
+/** A composed context view (the shape every handler return point produces). */
+export interface TailView {
+	messages: AgentMessage[];
+}
+
+/** The staged blocks + mode this pass verifies (pure inputs, no pi runtime). */
+export interface ConfirmInput {
+	/** The staged block text expected to have landed (null => nothing to verify). */
+	staged: string | null;
+	/** False in legacy prepend mode: verify the return string, not the list. */
+	tailMode: boolean;
+}
+
+/**
+ * The marker substring used to locate a staged block inside a message. The
+ * block's first non-empty line, capped, so prompt reshapes (cache striping /
+ * message separation) that regroup messages cannot defeat the match, while a
+ * genuinely dropped block still fails it.
+ */
+export function blockMarker(block: string): string {
+	const line = block
+		.split("\n")
+		.map((l) => l.trim())
+		.find((l) => l.length > 0);
+	return (line ?? "").slice(0, 80);
+}
+
+/**
+ * PURE decision function: did the staged block land in this view, and if not,
+ * which rung should repair it? Takes the already-extracted message texts so it
+ * stays free of pi types and is directly unit-testable.
+ */
+export function decideInjection(
+	input: ConfirmInput,
+	messageTexts: readonly string[],
+	hasPendingBlocks: boolean,
+): InjectionVerdict {
+	const marker = input.staged ? blockMarker(input.staged) : "";
+	// Nothing staged => nothing to assert; NOT a miss. Injecting a floor here
+	// would push provenance text into sessions that never had recall to lose.
+	if (!marker) return { landed: true, recovered: "none" };
+	const landed = messageTexts.some((t) => t.includes(marker));
+	if (landed) return { landed: true, recovered: "none" };
+	// Absent: recompose when the runtime still holds pending blocks, else floor.
+	return { landed: false, recovered: hasPendingBlocks ? "recomposed" : "floor" };
+}
+
+/** Append `text` as a user-role tail message (same shape as recall-tail.ts). */
+function withFloorTail(view: TailView, text: string): TailView {
+	const tailMsg = {
+		role: "user" as const,
+		content: text,
+		timestamp: Date.now(),
+	} as unknown as AgentMessage;
+	return { messages: [...view.messages, tailMsg] };
+}
+
+/**
+ * Thin caller: verify (and if needed repair) one composed view. Returns the view
+ * to actually return from the handler. `sessionId` sources the floor checkpoints.
+ *
+ * The recompose rung deliberately re-appends via `withRecallTail` onto the
+ * ALREADY-COMPOSED view rather than re-running `buildTailResult`: the reshape
+ * stages (cache striping / message separation) are the realistic way a tail
+ * message gets regrouped away, and re-running the same composition would
+ * reproduce the same loss. Appending after the reshape is the actual repair, and
+ * it keeps the PREVENT-PI-001/002 tail-append invariant (a single user-role
+ * message after a complete prefix can never split a toolCall/toolResult pair).
+ */
+export function confirmInjection(
+	runtime: MegaRuntime,
+	config: MegaConfig,
+	view: TailView,
+	sessionId: string,
+): TailView {
+	try {
+		if (!config.threeWayFailback) return view;
+		// What the tail composition was supposed to inject. BOTH staged blocks
+		// count: withRecallTail joins recall + memory blocks into one tail
+		// message, so either one going missing is a real injection failure.
+		const staged =
+			runtime.pendingRecallBlock ?? runtime.pendingMemoryRecallBlock ?? null;
+		// Can the recompose rung actually re-append? Only when a block is still
+		// staged on the runtime. When it is not (blocks consumed between
+		// composition and this check), or when withRecallTail declines to append,
+		// the ladder falls through to the floor rung below.
+		const hasPending =
+			runtime.pendingRecallBlock != null ||
+			runtime.pendingMemoryRecallBlock != null;
+		// Legacy prepend mode: the block is not expected in the message list —
+		// verify our composed return value contains it instead (A3 degrade path).
+		if (!config.recallTailInject) {
+			const composed = view.messages.map(messageContentText).join("\n");
+			const marker = staged ? blockMarker(staged) : "";
+			runtime.appendEvent("injection_confirmed", {
+				mode: "prepend",
+				landed: marker ? composed.includes(marker) : true,
+			});
+			return view;
+		}
+		const verdict = decideInjection(
+			{ staged, tailMode: true },
+			view.messages.map(messageContentText),
+			hasPending,
+		);
+		if (verdict.landed) {
+			runtime.appendEvent("injection_confirmed", { mode: "tail", landed: true });
+			return view;
+		}
+		if (verdict.recovered === "recomposed") {
+			const rebuilt = withRecallTail(view.messages, runtime, config);
+			// withRecallTail returns the input array unchanged on failure; only
+			// treat a genuine append as a recovery.
+			if (rebuilt.length > view.messages.length) {
+				runtime.appendEvent("injection_recovered", { via: "recomposed" });
+				return { messages: rebuilt };
+			}
+		}
+		const floor = buildFloorBlock(
+			vectorList(runtime.store, normalizeSessionId(sessionId)),
+		);
+		runtime.appendEvent("injection_recovered", {
+			via: "floor",
+			basis: floor.basis,
+		});
+		return withFloorTail(view, floor.text);
+	} catch {
+		// Non-fatal: return the unverified view (pre-sprint behavior).
+		return view;
+	}
+}

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

@@ -75,6 +75,15 @@ export const ReductionValidator = {
  * Infinity/NaN into meta (getMetaNumber would read it back as 0). Skip arming
  * + log instead; the next over-threshold event simply re-fires (pre-sprint
  * behavior) rather than corrupting the guard.
+ *
+ * 3WF-5 telemetry: `logger` is the debug-gated runtime logger (mega-compact.log,
+ * silent unless config.debug) — which means the breadcrumb was invisible to the
+ * dashboard Events tab, whose SSE tail reads the repo's events.log. `emit` is
+ * the always-on events.log sink (MegaRuntime.appendEvent), so the armed
+ * breadcrumb lands in the same stream as the other 3WF events
+ * (three_way_guard_fired / three_way_floor_used / injection_confirmed /
+ * injection_recovered). Both sinks are optional + best-effort; passing neither
+ * keeps the pre-3WF-5 behavior.
  */
 export function armThrashGuard(
 	currentTokens: number,
@@ -82,6 +91,7 @@ export function armThrashGuard(
 	effectiveThreshold: number,
 	stateDir: string,
 	logger?: { info(event: string, fields?: Record<string, unknown>): void },
+	emit?: (event: string, fields: Record<string, unknown>) => void,
 ): void {
 	if (!Number.isFinite(currentTokens) || currentTokens <= 0) return;
 	if (!Number.isFinite(rearmPct) || rearmPct <= 0) return;
@@ -96,11 +106,17 @@ export function armThrashGuard(
 		const n = Math.round(rearmPct * effectiveThreshold);
 		setMetaNumber(THRASH_BASELINE_KEY, Math.round(currentTokens), stateDir);
 		setMetaNumber(THRASH_BLOCKED_KEY, Math.round(currentTokens + n), stateDir);
-		logger?.info("thrasguard_armed", {
+		const fields = {
 			baselineTokens: Math.round(currentTokens),
 			blockedUntilTokens: Math.round(currentTokens + n),
 			rearmTokens: n,
-		});
+		};
+		logger?.info("thrasguard_armed", fields);
+		try {
+			emit?.("thrasguard_armed", fields);
+		} catch {
+			/* non-fatal: events.log sink must never break arming */
+		}
 	} catch {
 		/* non-fatal: best-effort meta write */
 	}
@@ -214,12 +230,20 @@ export function evaluatePendingReduction(
 			// Remember which event armed us so the consult later in THIS SAME event
 			// does not swallow it (see armedOnEvent).
 			armedOnEvent.set(runtime, currentTokens);
+			// 3WF-5: also emit the breadcrumb on the always-on events.log sink so
+			// the dashboard Events tab sees it (runtime.logger is debug-gated).
+			// Optional-chained: a thin runtime stub without appendEvent stays valid.
+			const emit =
+				typeof runtime.appendEvent === "function"
+					? runtime.appendEvent.bind(runtime)
+					: undefined;
 			armThrashGuard(
 				currentTokens,
 				config.thrashRearmPct,
 				runtime.effectiveThreshold,
 				runtime.currentStateDir,
 				runtime.logger,
+				emit,
 			);
 		}
 	} catch {

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

@@ -0,0 +1,164 @@
+/**
+ * context-handler/threeWayTelemetry.fixture.ts — shared fixtures for the 3WF-5
+ * telemetry verification tests.
+ *
+ * Split out so the test file stays under the soft cap, mirroring
+ * src/recall/recall3wf.fixture.ts (3WF-3) and injectionConfirm.fixture.ts (3WF-4).
+ *
+ * These are REAL fixtures, not mocks/stubs. The critical difference from the
+ * 3WF-1..4 fixtures: those record `appendEvent` calls into an in-memory array,
+ * which proves the CALL happened but says nothing about the wire format or the
+ * file the dashboard actually tails. Here `appendEvent` is wired to the REAL
+ * `appendEventImpl` (extensions/mega-runtime/append-event.ts) against a temp
+ * stateDir, so each breadcrumb is serialized to a real events.log exactly as it
+ * is in production. The tests then read that file back and parse the JSON — the
+ * `ts` + `event` shape is observed, never simulated.
+ */
+import { mkdtempSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { VectorStore } from "../../../src/vectorStore.js";
+import { compactSession } from "../../../src/engine.js";
+import { appendEventImpl } from "../../mega-runtime/append-event.js";
+import type { MegaRuntime } from "../../mega-runtime.js";
+import type { MegaConfig } from "../../mega-config.js";
+import type { Logger } from "../../../src/log.js";
+
+/** Real EngineMessage fixture. */
+export function msg(role: "user" | "assistant", text: string): any {
+	return { role, text };
+}
+
+/** A user-role AgentMessage carrying `text` (the tail-block shape). */
+export function userMsg(text: string): AgentMessage {
+	return { role: "user", content: text, timestamp: 1 } as unknown as AgentMessage;
+}
+
+/** One parsed events.log line. `ts` + `event` are the contract the dashboard
+ *  Events tab (server.ts SSE tail of stateDir/events.log) consumes. */
+export interface LoggedEvent {
+	ts: unknown;
+	event: unknown;
+	[k: string]: unknown;
+}
+
+/** Fresh isolated state dir per VectorStore. */
+export function freshStore(): { store: VectorStore; dir: string } {
+	const dir = mkdtempSync(join(tmpdir(), "mc-3wf5-"));
+	return { store: new VectorStore({ dedupSim: 0.9, stateDir: dir }), dir };
+}
+
+/** Persist N distinct checkpoints with ascending timestamps. */
+export function seed(store: VectorStore, topics: string[], sid: string): void {
+	topics.forEach((t, i) => {
+		compactSession(
+			{
+				sessionId: sid,
+				messages: [msg("user", t), msg("assistant", "ok")],
+				keepFrom: 2,
+				timestamp: i + 1,
+			},
+			store,
+		);
+	});
+}
+
+/**
+ * Read + JSON-parse every line of the REAL events.log written under `stateDir`.
+ * PREVENT-001: parse failures are surfaced as null and filtered, never thrown.
+ */
+export function readEventsLog(stateDir: string): LoggedEvent[] {
+	const path = join(stateDir, "events.log");
+	if (!existsSync(path)) return [];
+	return readFileSync(path, "utf-8")
+		.split("\n")
+		.filter((l) => l.trim().length > 0)
+		.map((line): LoggedEvent | null => {
+			try {
+				const parsed: unknown = JSON.parse(line);
+				if (parsed == null || typeof parsed !== "object") return null;
+				return parsed as LoggedEvent;
+			} catch {
+				return null;
+			}
+		})
+		.filter((e): e is LoggedEvent => e != null);
+}
+
+/** Silent logger (the debug-gated sink is not under test here). */
+export const noopLogger: Logger = {
+	info: () => {},
+	warn: () => {},
+	error: () => {},
+} as unknown as Logger;
+
+/**
+ * MegaRuntime whose `appendEvent` is the REAL events.log writer bound to
+ * `stateDir`. Only the fields the 3WF guards touch are populated.
+ */
+export function realEventRuntime(
+	store: VectorStore,
+	stateDir: string,
+	over: Partial<{
+		pendingRecallBlock: string | undefined;
+		pendingMemoryRecallBlock: string | undefined;
+		effectiveThreshold: number;
+	}> = {},
+): MegaRuntime {
+	const self = {
+		store,
+		currentStateDir: stateDir,
+		pendingRecallBlock: over.pendingRecallBlock,
+		pendingMemoryRecallBlock: over.pendingMemoryRecallBlock,
+		effectiveThreshold: over.effectiveThreshold ?? 100_000,
+		lastCtxWindow: 0,
+		logger: noopLogger,
+		perfTurnStart: undefined,
+		rt: { recallInjectedThisTurn: false, lastCheckpointId: null as string | null },
+		appendEvent(event: string, fields: Record<string, unknown>): void {
+			appendEventImpl({ currentStateDir: stateDir }, event, fields);
+		},
+	};
+	return self as unknown as MegaRuntime;
+}
+
+/** ctx stub with a configurable session id + latest-user query. */
+export function ctxStub(opts: { sessionId?: string; query?: string } = {}): any {
+	const sessionId = opts.sessionId ?? "sess_3wf5";
+	const query = opts.query ?? "dedupe race in store";
+	return {
+		cwd: "/tmp",
+		sessionManager: {
+			getSessionId: () => sessionId,
+			getEntries: () => [
+				{
+					type: "message",
+					id: "e1",
+					parentId: null,
+					timestamp: "1",
+					message: { role: "user", content: query },
+				},
+			],
+		},
+	};
+}
+
+/** Config stub: only the flags the 3WF guards read. */
+export function configStub(
+	over: Partial<{
+		threeWayFailback: boolean;
+		recallTailInject: boolean;
+		thrashRearmPct: number;
+	}> = {},
+): MegaConfig {
+	return {
+		threeWayFailback: over.threeWayFailback ?? true,
+		recallTailInject: over.recallTailInject ?? true,
+		thrashRearmPct: over.thrashRearmPct ?? 0.1,
+		autoInlineK: 3,
+		tier: "custom",
+		tierPct: null,
+	} as unknown as MegaConfig;
+}

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

@@ -30,6 +30,10 @@ import { normalizeSessionId } from "../../../src/store.js";
 import { recall } from "../../../src/engine.js";
 import { formatRecallBlock } from "../../../src/recall.js";
 import { vectorStats, vectorList } from "../../../src/vectorStore.js";
+import {
+	buildFloorBlock as sharedFloorBlock,
+	FLOOR_UNAVAILABLE_TEXT,
+} from "../../../src/failback/floor.js";
 import { recentUserQuery } from "../../mega-runtime.js";
 
 /** One-shot completion marker per MegaRuntime (dies with the runtime). */
@@ -108,30 +112,18 @@ export function runTriggerGuard(
 	}
 }
 
-/** Build the provenance floor string from the session's newest checkpoint. */
+/**
+ * Build the provenance floor string from the session's newest checkpoint.
+ *
+ * 3WF-4: the text construction moved to the SHARED pure builder
+ * (src/failback/floor.ts) — this keeps the store read (`vectorList`, unfiltered,
+ * exactly as 3WF-1 shipped) and the string return type, so output is
+ * byte-identical to the pre-refactor version.
+ */
 function buildFloorBlock(runtime: MegaRuntime, sid: string): string {
 	try {
-		const cps = vectorList(runtime.store, sid);
-		let newest = cps[0];
-		for (const cp of cps) {
-			if (!newest || (cp.timestamp ?? 0) > (newest.timestamp ?? 0)) newest = cp;
-		}
-		const summary = newest?.summary?.trim();
-		if (summary) {
-			return (
-				"The following compacted context is the most recent checkpoint from " +
-				"this session (recall found no query-relevant match):\n\n" + summary
-			);
-		}
-		return (
-			"This session has compacted context but recall could not surface a " +
-			"checkpoint relevant to the current request; the most recent checkpoint " +
-			"summary is unavailable."
-		);
+		return sharedFloorBlock(vectorList(runtime.store, sid)).text;
 	} catch {
-		return (
-			"This session has compacted context but recall could not surface a " +
-			"checkpoint relevant to the current request."
-		);
+		return FLOOR_UNAVAILABLE_TEXT;
 	}
 }

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

@@ -24,6 +24,7 @@ import { piCompactWouldNoop } from "../mega-pipeline.js";
 import type { MegaConfig } from "../mega-config.js";
 import { buildTailResult } from "./context-handler/tailResult.js";
 import { runTriggerGuard } from "./context-handler/triggerGuard.js";
+import { confirmInjection } from "./context-handler/injectionConfirm.js";
 import { persistEpochAndMaintain } from "./context-handler/afterCompact.js";
 import { appendMirrorAndLedger } from "./context-handler/dbMirrorAppend.js";
 import { evaluateGate, thrashGuardBlocks } from "./context-handler/gateCheck.js";
@@ -72,7 +73,21 @@ export function registerContextHandler(
 		// 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.
-		const tailResult = buildTailResult(runtime, config, messages);
+		const composeTail = buildTailResult(runtime, config, messages);
+		// 3WF-4 InjectionConfirm: wrap the tail factory so EVERY return point of
+		// this handler (gate / replay / debounce / thrash-guard / pipeline /
+		// live-trim) is verified — the staged block's marker must be present in
+		// the message list pi will send (tail mode), else we re-compose from the
+		// runtime's pending blocks and finally fall back to the shared floor.
+		// A composition that yields nothing staged (undefined) is passed through
+		// untouched, so flag-OFF and no-recall paths are byte-identical.
+		const tailResult: typeof composeTail = config.threeWayFailback
+			? (msgs) => {
+					const view = composeTail(msgs);
+					if (!view) return view;
+					return confirmInjection(runtime, config, view, ctx.sessionManager.getSessionId());
+				}
+			: composeTail;
 		// 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.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.87",
+  "version": "0.21.0",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",

package/src/failback/floor.ts

@@ -0,0 +1,71 @@
+/**
+ * src/failback/floor.ts — the SHARED pure provenance-floor builder (3WF-4).
+ *
+ * Consolidation refactor (ZERO behavior change). Before this module the same
+ * floor text was built twice:
+ *   (a) `extensions/mega-events/context-handler/triggerGuard.ts` (3WF-1) —
+ *       read checkpoints via `vectorList` (unfiltered), returned a bare string;
+ *   (b) `src/recall/validator.ts` (3WF-3) — read checkpoints via
+ *       `listCheckpoints` filtered to `dedupStatus !== "removed"`, returned a
+ *       `FloorBlock`.
+ * The three text variants were byte-identical between the two; only the
+ * checkpoint READ differed. So this module takes the already-read checkpoint
+ * list from the caller (staying pure — no store, no pi types, no I/O) and each
+ * call site keeps its own read semantics. Output is byte-identical to both.
+ *
+ * 3WF-4's InjectionConfirm is the third consumer: when neither the message list
+ * nor the runtime's pending blocks yield a block, it needs the SAME last-resort
+ * floor text rather than a fourth copy.
+ *
+ * Non-fatal by construction: every branch returns a `FloorBlock`; the `none`
+ * basis carries the shortest text (used when the checkpoint read itself threw).
+ */
+import type { StoredCheckpoint } from "../store.js";
+import type { FloorBlock } from "./types.js";
+
+/** Floor text when the newest checkpoint summary is available (prefix). */
+const WITH_SUMMARY_PREFIX =
+	"The following compacted context is the most recent checkpoint from " +
+	"this session (recall found no query-relevant match):\n\n";
+
+/** Floor text when checkpoints exist but no usable summary does. */
+const NO_SUMMARY_TEXT =
+	"This session has compacted context but recall could not surface a " +
+	"checkpoint relevant to the current request; the most recent checkpoint " +
+	"summary is unavailable.";
+
+/** Floor text when the checkpoint read itself failed (hard last resort). */
+export const FLOOR_UNAVAILABLE_TEXT =
+	"This session has compacted context but recall could not surface a " +
+	"checkpoint relevant to the current request.";
+
+/** The newest checkpoint by timestamp (first element wins ties, as before). */
+export function newestCheckpoint(
+	cps: readonly StoredCheckpoint[],
+): StoredCheckpoint | undefined {
+	let newest = cps[0];
+	for (const cp of cps) {
+		if (!newest || (cp.timestamp ?? 0) > (newest.timestamp ?? 0)) newest = cp;
+	}
+	return newest;
+}
+
+/**
+ * Build the provenance floor from an already-read checkpoint list. Pure: the
+ * caller owns the read (and any dedup-status filtering), so both legacy call
+ * sites keep byte-identical output.
+ */
+export function buildFloorBlock(
+	cps: readonly StoredCheckpoint[],
+): FloorBlock {
+	const summary = newestCheckpoint(cps)?.summary?.trim();
+	if (summary) {
+		return { text: WITH_SUMMARY_PREFIX + summary, basis: "lastCheckpoint" };
+	}
+	return { text: NO_SUMMARY_TEXT, basis: "lastCheckpoint" };
+}
+
+/** The hard last-resort floor (checkpoint read unavailable or threw). */
+export function unavailableFloorBlock(): FloorBlock {
+	return { text: FLOOR_UNAVAILABLE_TEXT, basis: "none" };
+}

package/src/failback/types.ts

@@ -103,6 +103,22 @@ export interface RecallCandidate {
 	source: "vector" | "fts5" | "recency";
 }
 
+/**
+ * Verdict of an InjectionConfirm pass (3WF-4). There is NO prompt readback API
+ * in pi, so the only verifiable proxy for what the provider will receive is the
+ * pre-LLM message list (`ContextEvent.messages`, transformed). `landed` is true
+ * when the staged block's text was found there (tail mode) or in the composed
+ * return string (legacy prepend mode). `recovered` records which repair rung
+ * this event used: none (already landed), recomposed (rebuilt from the runtime's
+ * pending blocks), or floor (last-resort provenance text).
+ */
+export interface InjectionVerdict {
+	/** True when the staged block text is present in the verified view. */
+	landed: boolean;
+	/** Which repair rung ran to make the block present. */
+	recovered: "none" | "recomposed" | "floor";
+}
+
 /**
  * Outcome of the three-source recall vote. `winners` are the agreed candidates
  * (ranked), `votes` counts how many distinct sources named each checkpointId,

package/src/recall/validator.ts

@@ -28,6 +28,10 @@ import { listCheckpoints } from "../store/sqlite.js";
 import { RECALL_MIN_COSINE } from "../config.js";
 import type { VectorStore } from "../vectorStore.js";
 import type { RecallCandidate, FloorBlock } from "../failback/types.js";
+import {
+	buildFloorBlock as sharedFloorBlock,
+	unavailableFloorBlock,
+} from "../failback/floor.js";
 
 /** Options for the recall validator. */
 export interface ValidateOptions {
@@ -54,39 +58,22 @@ export type ValidationOutcome =
 	| { kind: "candidate"; candidate: RecallCandidate }
 	| { kind: "floor"; floor: FloorBlock };
 
-/** Build the provenance floor block from the session's newest checkpoint. */
+/**
+ * Build the provenance floor block from the session's newest checkpoint.
+ *
+ * 3WF-4: the text construction moved to the SHARED pure builder
+ * (src/failback/floor.ts). This wrapper keeps THIS call site's read semantics —
+ * `listCheckpoints` filtered to `dedupStatus !== "removed"` — so the output is
+ * byte-identical to the pre-refactor 3WF-3 version.
+ */
 function buildFloorBlock(sessionId: string, store: VectorStore): FloorBlock {
 	try {
 		const cps = listCheckpoints(sessionId, store.stateDir).filter(
 			(c) => c.dedupStatus !== "removed",
 		);
-		let newest = cps[0];
-		for (const cp of cps) {
-			if (!newest || (cp.timestamp ?? 0) > (newest.timestamp ?? 0)) newest = cp;
-		}
-		const summary = newest?.summary?.trim();
-		if (summary) {
-			return {
-				text:
-					"The following compacted context is the most recent checkpoint from " +
-					"this session (recall found no query-relevant match):\n\n" + summary,
-				basis: "lastCheckpoint",
-			};
-		}
-		return {
-			text:
-				"This session has compacted context but recall could not surface a " +
-				"checkpoint relevant to the current request; the most recent checkpoint " +
-				"summary is unavailable.",
-			basis: "lastCheckpoint",
-		};
+		return sharedFloorBlock(cps);
 	} catch {
-		return {
-			text:
-				"This session has compacted context but recall could not surface a " +
-				"checkpoint relevant to the current request.",
-			basis: "none",
-		};
+		return unavailableFloorBlock();
 	}
 }