pi-mega-compact 0.6.5 → 0.6.7

package/dist/extensions/mega-pipeline.js

@@ -192,6 +192,10 @@ function doCompact(view, keepFrom, opts, sid, config, pi, ctx, runtime) {
                 embedding: cp.embedding,
             }));
             if (leaves.length >= 2) {
+                // S25: stamp the tree with the newest checkpoint epoch so the
+                // freshness guard in raptorSearchHits can reject stale trees after a
+                // later compaction adds newer checkpoints.
+                const builtAt = all.length > 0 ? Math.max(...all.map((c) => c.timestamp)) : Date.now();
                 runRaptor(leaves, {
                     stateDir: runtime.currentStateDir,
                     sessionId: sid,
@@ -199,6 +203,7 @@ function doCompact(view, keepFrom, opts, sid, config, pi, ctx, runtime) {
                     clustersPerLevel: dd.RAPTOR_CLUSTERS_PER_LEVEL,
                     consistencyThreshold: dd.RAPTOR_CONSISTENCY,
                     logger: runtime.logger,
+                    builtAt: Number.isFinite(builtAt) ? builtAt : Date.now(),
                 });
             }
         }

package/dist/extensions/mega-runtime.js

@@ -53,6 +53,7 @@ export const C = {
     magenta: "\x1b[38;5;201m", // dedup rate
     blue: "\x1b[38;5;75m", // repo totals
     gray: "\x1b[38;5;245m", // labels
+    red: "\x1b[38;5;203m", // pressure / overflow
 };
 const PULSE = ["◐", "◓", "◑", "◒"];
 export class MegaRuntime {
@@ -315,7 +316,7 @@ export class MegaRuntime {
             // 1e6, k at/above 1e3, raw below — so 5,472,700 → "5.5M", 24,100 → "24.1k",
             // 142 → "142". Dropped (in) = Freed + Kept; Freed = rt.tokensSaved (session)
             // / repo.tokensSaved meta (repo); Kept = totalTokenEstimate (stored).
-            const fmt = (x) => x >= 1_000_000 ? `${(x / 1_000_000).toFixed(1)}M`
+            const fmt = (x) => x >= 1_000_000 ? `${(x / 1_000_000).toFixed(1)}mil`
                 : x >= 1000 ? `${(x / 1000).toFixed(1)}k`
                     : `${Math.round(x)}`;
             const agentStr = this.activeAgents > 0 ? ` │ 🤖 ${this.activeAgents} agent${this.activeAgents === 1 ? "" : "s"}` : "";
@@ -331,21 +332,40 @@ export class MegaRuntime {
             const repoKept = repo.totalTokenEstimate;
             const repoFreed = repo.tokensSaved;
             const repoPct = repoIn > 0 ? repoFreed / repoIn : 0;
+            // Retro gradient bar — `w` cells, each shaded by fill position so it
+            // reads as a smooth green→amber→red ramp. Used for CONTEXT fill where
+            // low=green (room to spare) and high=red (near the limit) — the only
+            // live-moving metric worth a bar. Savings ratios saturate near 100% and
+            // are shown as explanatory numbers instead (see L2).
+            const ramp = (pct, w = 12) => {
+                const cells = ["▏", "▎", "▍", "▌", "▋", "▊", "▉", "█"];
+                const scaled = Math.max(0, Math.min(w, pct * w));
+                const full = Math.floor(scaled);
+                const frac = scaled - full;
+                const fracCell = frac > 0 ? cells[Math.round(frac * (cells.length - 1))] : "";
+                let out = "";
+                for (let i = 0; i < full; i++)
+                    out += (i / w < 0.6 ? C.green : i / w < 0.85 ? C.amber : C.red) + "█";
+                if (fracCell)
+                    out += (full / w < 0.6 ? C.green : full / w < 0.85 ? C.amber : C.red) + fracCell;
+                out += C.dim + "░".repeat(Math.max(0, w - full - (fracCell ? 1 : 0))) + C.reset;
+                return out;
+            };
+            const ctxPct = this.lastCtxPercent != null ? this.lastCtxPercent / 100 : 0;
+            const sTxt = (sessPct * 100).toFixed(sessPct * 100 >= 10 ? 0 : 1);
+            const rTxt = (repoPct * 100).toFixed(repoPct * 100 >= 10 ? 0 : 1);
             const lines = [
-                ` ${C.amber}⚡ ${tierLabel}${C.reset} v${C.bold}${ownVersion()}${C.reset} │ ${tokStr}/${maxStr} tokens (${C.bold}${pctStr}${C.reset}) │ ${st.checkpointCount} saved${agentStr}${turnStr}`,
-                `   ${triggerLabel} │ ${C.magenta}repeat-skipped: ${dedupStr}${C.reset}`,
-                `   ${C.gray}dropped ${fmt(sessIn)} → kept ${fmt(sessKept)} sess / ${fmt(repoKept)} repo · freed ${fmt(sessFreed)} sess / ${fmt(repoFreed)} repo${C.reset}`,
+                // L1 — header: tier + ctx-fill bar (20-cell, green=room→red=full) +
+                // tokens + status glyph + checkpoints + agents/turn. Widened to use the
+                // terminal width; the context bar is the only live-moving bar.
+                ` ${C.amber}⚡ ${tierLabel}${C.reset} v${C.bold}${ownVersion()}${C.reset} ${ramp(ctxPct, 20)} ${C.bold}${pctStr}${C.reset} ${tokStr}/${maxStr} │ ${triggerLabel} │ ${st.checkpointCount} chk${agentStr}${turnStr}`,
+                // L2 — savings EXPLAINED, not bar'd. The freed/(freed+kept) ratio
+                // saturates near 100% once cumulative freed dwarfs live kept (4.8mil
+                // freed vs 612 kept), so a bar is visually useless. Instead show the
+                // compaction story: "in→kept (X% freed)" reads as "compacted N tokens
+                // down to M, freeing X%". Plus repo-wide chk/session counts.
+                `   ${C.magenta}dup ${dedupStr}${C.reset} │ ${C.gray}sess${C.reset} ${fmt(sessIn)}→${fmt(sessKept)} kept ${C.green}(${sTxt}% freed)${C.reset} · ${C.gray}all-time${C.reset} ${fmt(repoIn)}→${fmt(repoKept)} kept ${C.blue}(${rTxt}% freed)${C.reset} │ ${repo.checkpointCount} chk/${repo.sessionCount} sess`,
             ];
-            // Compression meter — the single headline "% tokens saved" (Freed / In),
-            // same formula as the dashboard. Higher = better, so it reads green.
-            {
-                const w = 10;
-                const filled = Math.max(0, Math.min(w, Math.round(sessPct * w)));
-                const cbar = C.green + "▓".repeat(filled) + C.dim + "░".repeat(w - filled) + C.reset;
-                const sTxt = (sessPct * 100).toFixed(sessPct * 100 >= 10 ? 0 : 1);
-                const rTxt = (repoPct * 100).toFixed(repoPct * 100 >= 10 ? 0 : 1);
-                lines.push(`   ${cbar} ${sTxt}% tokens saved (sess) · ${rTxt}% repo${C.reset}`);
-            }
             // Live "now processing" line + why + recent deduped/compacted events,
             // collapsed to ONE rotating line (fresh only). The ticker ring buffer
             // (≤5 most-recent events) is cycled one-per-repaint so the line scrolls
@@ -367,12 +387,8 @@ export class MegaRuntime {
             else if (this.pulsing) {
                 lines.push(`   ${pulse}${C.teal}compacting…${C.reset}`);
             }
-            // Token accounting summary, always last + dimmed. Shows the total
-            // tokens dropped (in) + kept (out) for this session, then the freed
-            // (saved) tokens for both this session and all-time across the repo.
-            if (lines.length < 10) {
-                lines.push(`   ${C.dim}session ↑${fmt(sessIn)} in ↓${fmt(sessKept)} out · saved ${fmt(sessFreed)} session / ${fmt(repoFreed)} all-time${C.reset}`);
-            }
+            // (Accounting folded into L2's "in→kept (X% freed)" framing — freed =
+            //  in − kept is implied, and the saturated-ratio bars are gone.)
             ctx.ui.setWidget(WIDGET_KEY, lines, { placement: "aboveEditor" });
         }
     }

package/dist/src/adapt.js

@@ -36,25 +36,41 @@ export function messageToolName(m) {
 function contentText(content) {
     if (typeof content === "string")
         return content;
+    // PREVENT crash: pi blocks can arrive with `text: undefined` or a missing
+    // `content` field (tool/custom messages). Coerce to a string at the single
+    // choke point so every downstream `.matchAll`/`.split`/`.toLowerCase` is safe
+    // (extractive.ts, compact.ts, supersede.ts, summarizer.ts, boundary.ts).
+    if (!Array.isArray(content))
+        return "";
     return content
-        .filter((c) => c.type === "text" && typeof c.text === "string")
+        .filter((c) => c?.type === "text" && typeof c.text === "string")
         .map((c) => c.text)
         .join("\n");
 }
 /** Project any AgentMessage into a single text blob the engine can reason on. */
 function messageText(m) {
+    let out;
     switch (m.role) {
         case "toolResult":
         case "user":
         case "assistant":
         case "custom":
-            return contentText(m.content);
+            out = contentText(m.content);
+            break;
         case "bashExecution":
-            return `${m.command}\n${m.output}`;
+            out = `${m.command ?? ""}\n${m.output ?? ""}`;
+            break;
         case "branchSummary":
         case "compactionSummary":
-            return m.summary;
+            out = m.summary ?? "";
+            break;
+        default:
+            out = "";
+            break;
     }
+    // PREVENT crash: final safety net — never let `undefined`/`null` escape the
+    // adapter into the engine, which assumes `text: string` everywhere.
+    return out ?? "";
 }
 /**
  * Convert a pi message array into the engine's EngineMessage view, keeping

package/dist/src/dedup/raptor/index.js

@@ -35,7 +35,8 @@ export function runRaptor(leaves, opts) {
             clustersPerLevel: opts.clustersPerLevel,
             consistencyThreshold: opts.consistencyThreshold,
         });
-        saveRaptorTree(opts.sessionId, tree, opts.stateDir);
+        const builtAt = opts.builtAt ?? Date.now();
+        saveRaptorTree(opts.sessionId, tree, builtAt, opts.stateDir);
         logger?.info("raptor_build", {
             sessionId: opts.sessionId,
             nodes: tree.nodes.size,
@@ -80,6 +81,12 @@ export function rehydrateRaptorTree(sessionId, stateDir) {
     const nodes = listRaptorNodes(sessionId, stateDir);
     if (nodes.length === 0)
         return null;
+    // S25: derive freshness + fallback metadata from the persisted nodes.
+    // builtAt = max node built_at (0 when unknown → caller treats as stale).
+    // timedOut = the tree's root is the extractive-fallback marker (level 99).
+    const builtAt = nodes.reduce((max, n) => Math.max(max, n.builtAt), 0);
+    const root = nodes.reduce((best, n) => (!best || n.level > (best?.level ?? -1) ? n : best), null);
+    const timedOut = root != null && root.level >= 99;
     const tree = {
         nodes: new Map(nodes.map((n) => [
             n.id,
@@ -94,9 +101,10 @@ export function rehydrateRaptorTree(sessionId, stateDir) {
                 tokenEstimate: n.tokenEstimate,
             },
         ])),
-        rootId: nodes.reduce((best, n) => (!best || n.level > (best?.level ?? -1) ? n : best), null)?.id ?? null,
+        rootId: root?.id ?? null,
         levels: Math.max(1, ...nodes.map((n) => n.level + 1)),
-        timedOut: false,
+        timedOut,
+        builtAt,
     };
     return tree;
 }

package/dist/src/extractive.js

@@ -179,15 +179,20 @@ export function extractiveSummarize(messages) {
     if (messages.length === 0) {
         return { topicSummary: "(empty)", keyDecisions: [], nextSteps: [], filesModified: [], tokenEstimate: 0 };
     }
-    const toolMsgs = messages.filter((m) => m.role === "tool");
+    // PREVENT crash: tool/custom messages can arrive with `text: undefined` when
+    // only `input`/`output` is set (the type says string, but pi's runtime does
+    // not always fill it). Coerce to "" once at the entry so every downstream
+    // `.text` / `.matchAll` / `.split` access is safe.
+    const safe = messages.map((m) => ({ ...m, text: m.text ?? "" }));
+    const toolMsgs = safe.filter((m) => m.role === "tool");
     const tools = [...new Set(messages.flatMap((m) => (m.toolName ? [m.toolName] : [])))].sort();
-    const recentUser = collectRecentUserRequests(messages, MAX_RECENT_USER);
-    const currentWork = inferCurrentWork(messages);
-    const keyFiles = collectKeyFiles(messages);
-    const pending = inferPendingWork(messages);
-    const keyDecisions = extractDecisions(messages);
+    const recentUser = collectRecentUserRequests(safe, MAX_RECENT_USER);
+    const currentWork = inferCurrentWork(safe);
+    const keyFiles = collectKeyFiles(safe);
+    const pending = inferPendingWork(safe);
+    const keyDecisions = extractDecisions(safe);
     const filesModified = extractFilesModified(toolMsgs);
-    const topicSummary = buildTopicSummary(messages, tools, recentUser, currentWork, keyFiles, pending);
+    const topicSummary = buildTopicSummary(safe, tools, recentUser, currentWork, keyFiles, pending);
     const tokenEstimate = estimateBlockTokens(topicSummary);
     return { topicSummary, keyDecisions, nextSteps: pending, filesModified, tokenEstimate };
 }

package/dist/src/extractive.test.js

@@ -4,6 +4,23 @@ import { extractiveSummarize } from "./extractive.js";
 function msg(role, text, toolName) {
     return toolName ? { role, text, toolName, input: text, output: text } : { role, text };
 }
+// ---- Crash regression: undefined text (S25 hotfix) ------------------------
+// pi tool/custom messages can arrive with `text: undefined` when only
+// input/output is set. The adapter (adapt.ts) now coerces to "", and
+// extractiveSummarize guards its entry too. This test pins the no-crash
+// contract directly against the engine entry (defense in depth).
+test("extractiveSummarize does not crash on messages with undefined text", () => {
+    const messages = [
+        { role: "user", text: "please edit src/index.ts" },
+        { role: "assistant", text: undefined, toolName: "Edit", input: "src/index.ts" },
+        { role: "tool", text: undefined, toolName: "Edit", output: "ok" },
+        { role: "assistant", text: "done editing src/index.ts" },
+    ];
+    // Must not throw — previously crashed at text.matchAll in extractFilePaths.
+    const s = extractiveSummarize(messages);
+    assert.ok(typeof s.topicSummary === "string");
+    assert.ok(s.topicSummary.length >= 0);
+});
 // ---- Determinism -----------------------------------------------------------
 test("extractive summary is deterministic", () => {
     const messages = [

package/dist/src/store/backfill.js

@@ -180,7 +180,9 @@ export function backfillRaptor(sessionId, stateDir, embedder = defaultEmbedder()
         return { phase: "RAPTOR", processed: 0, batches: 0, interrupted: false, cursor: undefined };
     }
     const tree = buildRaptorTree(leaves, { embedder });
-    saveRaptorTree(sessionId, tree, stateDir);
+    // S25: freshness-guard timestamp = newest checkpoint's epoch.
+    const builtAt = all.length > 0 ? Math.max(...all.map((c) => c.timestamp)) : Date.now();
+    saveRaptorTree(sessionId, tree, Number.isFinite(builtAt) ? builtAt : Date.now(), stateDir);
     const db = openStore(stateDir);
     ensureProgressTable(db);
     savePhaseCursor(db, "RAPTOR", leaves[leaves.length - 1].id, leaves.length);

package/dist/src/store/sqlite.js

@@ -372,6 +372,7 @@ function initSchema(db) {
       embedding_blob BLOB,         -- float32 centroid
       quality_marker TEXT DEFAULT 'low',
       token_estimate INTEGER,
+      built_at     INTEGER,        -- S25: epoch ms when the tree was built (freshness guard)
       PRIMARY KEY (session_id, id)
     );
     CREATE INDEX IF NOT EXISTS idx_raptor_session ON raptor_nodes(session_id);
@@ -469,6 +470,9 @@ function initSchema(db) {
     ensureColumn(db, "memories", "target", "TEXT");
     ensureColumn(db, "memories", "last_referenced", "INTEGER");
     ensureColumn(db, "memories", "source_turn", "INTEGER");
+    // S25: RAPTOR freshness-guard timestamp. Additive; old DBs have NULL → 0 →
+    // treated as stale → flat fallback (safe).
+    ensureColumn(db, "raptor_nodes", "built_at", "INTEGER");
     const v = db.prepare("SELECT value FROM meta WHERE key='schema_version'").get();
     if (!v) {
         db.prepare("INSERT INTO meta(key, value) VALUES(?, ?)").run("schema_version", String(SCHEMA_VERSION));
@@ -879,6 +883,15 @@ export function listCheckpoints(sessionId, stateDir = getStateDir()) {
         .all(sid);
     return rows.map(rowToCheckpoint);
 }
+/** S25: the newest checkpoint timestamp for a session, or 0 when none. Used by
+ *  the RAPTOR freshness guard to reject a tree older than the live checkpoints. */
+export function maxCheckpointTimestamp(sessionId, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const row = db
+        .prepare("SELECT MAX(timestamp) AS mx FROM context_chunks WHERE session_id = ?")
+        .get(normalizeSessionId(sessionId));
+    return Number(row?.mx ?? 0);
+}
 /** Next sequential checkpoint id (chkpt_001 …) for a session. */
 export function nextCheckpointId(sessionId, stateDir = getStateDir()) {
     const db = openStore(stateDir);
@@ -1050,15 +1063,16 @@ export function closeStore(stateDir) {
 /** Persist a single RAPTOR node (upsert by (session_id, id)). */
 export function upsertRaptorNode(node, stateDir = getStateDir()) {
     const db = openStore(stateDir);
-    db.prepare(`INSERT INTO raptor_nodes(id, session_id, level, parent_id, children, summary, embedding_blob, quality_marker, token_estimate)
-     VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?)
+    db.prepare(`INSERT INTO raptor_nodes(id, session_id, level, parent_id, children, summary, embedding_blob, quality_marker, token_estimate, built_at)
+     VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
      ON CONFLICT(session_id, id) DO UPDATE SET
        level=excluded.level, parent_id=excluded.parent_id, children=excluded.children,
        summary=excluded.summary, embedding_blob=excluded.embedding_blob,
-       quality_marker=excluded.quality_marker, token_estimate=excluded.token_estimate`).run(node.id, node.sessionId, node.level, node.parentId, jsonText(node.children), node.summary, encodeEmbedding(node.embedding), node.qualityMarker, node.tokenEstimate);
+       quality_marker=excluded.quality_marker, token_estimate=excluded.token_estimate,
+       built_at=excluded.built_at`).run(node.id, node.sessionId, node.level, node.parentId, jsonText(node.children), node.summary, encodeEmbedding(node.embedding), node.qualityMarker, node.tokenEstimate, node.builtAt);
 }
 /** Persist an entire built RAPTOR tree for a session (shadow or live). */
-export function saveRaptorTree(sessionId, tree, stateDir = getStateDir()) {
+export function saveRaptorTree(sessionId, tree, builtAt, stateDir = getStateDir()) {
     for (const node of tree.nodes.values()) {
         upsertRaptorNode({
             id: node.id,
@@ -1070,6 +1084,7 @@ export function saveRaptorTree(sessionId, tree, stateDir = getStateDir()) {
             embedding: node.embedding,
             qualityMarker: node.qualityMarker,
             tokenEstimate: node.tokenEstimate,
+            builtAt,
         }, stateDir);
     }
 }
@@ -1089,6 +1104,7 @@ export function listRaptorNodes(sessionId, stateDir = getStateDir()) {
         embedding: decodeEmbedding(row.embedding_blob),
         qualityMarker: row.quality_marker ?? "low",
         tokenEstimate: row.token_estimate ?? 0,
+        builtAt: Number(row.built_at ?? 0),
     }));
 }
 /** Delete all RAPTOR nodes for a session (rollback/cleanup). */

package/dist/src/vectorStore.js

@@ -19,9 +19,9 @@ import { isNearDuplicate } from "./dedup/l1-verify.js";
 import { mmrRerank } from "./dedup/mmr.js";
 import { topK } from "./dedup/topk.js";
 import { openBloom, saveBloom } from "./store/bloom.js";
-import { listCheckpoints, nextCheckpointId, upsertCheckpoint, getCheckpoint, loadSessionState, saveSessionState, upsertMinhashSignature, insertLshBuckets, lshCandidateChunks, setDedupStatus, addTokensSaved, getDedupStats, bumpDedupStats, repoStats as repoStatsFromStore, dataInvariantStats, } from "./store/sqlite.js";
+import { listCheckpoints, nextCheckpointId, upsertCheckpoint, getCheckpoint, loadSessionState, saveSessionState, upsertMinhashSignature, insertLshBuckets, lshCandidateChunks, setDedupStatus, addTokensSaved, getDedupStats, bumpDedupStats, repoStats as repoStatsFromStore, dataInvariantStats, maxCheckpointTimestamp, } from "./store/sqlite.js";
 import { initVectorIndex, searchAsync as vectorIndexSearch, } from "./store/vectorIndex.js";
-import { rehydrateRaptorTree } from "./dedup/raptor/index.js";
+import { rehydrateRaptorTree, isShadowMode } from "./dedup/raptor/index.js";
 import { stagedExpansion } from "./dedup/raptor/retrieval.js";
 import { migrateJsonToSqlite } from "./store/migrate.js";
 /** Default L2 semantic-dedup enable flag (trigram embedder is local, zero-network). */
@@ -440,10 +440,24 @@ export class VectorStore {
      * exists (small sessions — flat search remains the path). Best-effort/non-fatal.
      */
     raptorSearchHits(sid, query, k) {
+        const t0 = Date.now();
         try {
+            // S25 gate (a): honor the shadow contract at SERVE time. The tree is still
+            // built + persisted (logging-only) but NOT merged into recall while
+            // RAPTOR_SHADOW_MODE is anything other than "false".
+            if (isShadowMode())
+                return [];
             const tree = rehydrateRaptorTree(sid, this.stateDir);
             if (!tree || !tree.rootId)
                 return [];
+            // S25 gate (b): freshness + fallback guards. Skip a tree built before the
+            // newest checkpoint (stale → may reference trimmed/deduped leaves) or one
+            // whose root is a budget-exhausted extractive fallback (level 99).
+            if (tree.timedOut)
+                return [];
+            const maxTs = maxCheckpointTimestamp(sid, this.stateDir);
+            if (tree.builtAt && tree.builtAt < maxTs)
+                return [];
             const leafIds = stagedExpansion(query, tree, {
                 embedder: this.embedder,
                 k,
@@ -460,6 +474,9 @@ export class VectorStore {
                 if (cp)
                     hits.push({ checkpoint: cp, score: cosineSimilarity(qv, cp.embedding) });
             }
+            // S25 monitoring: emit a raptor_serve decision so canary.ts can track
+            // p95 latency + the tier's live traffic (non-fatal, best-effort).
+            this.record("RAPTOR", hits.length > 0 ? "new" : "mark_only", `leaves=${leafIds.length}`, Date.now() - t0);
             return hits;
         }
         catch {

package/extensions/mega-pipeline.ts

@@ -240,6 +240,10 @@ function doCompact(
         embedding: cp.embedding,
       }));
       if (leaves.length >= 2) {
+        // S25: stamp the tree with the newest checkpoint epoch so the
+        // freshness guard in raptorSearchHits can reject stale trees after a
+        // later compaction adds newer checkpoints.
+        const builtAt = all.length > 0 ? Math.max(...all.map((c) => c.timestamp)) : Date.now();
         runRaptor(
           leaves,
           {
@@ -249,6 +253,7 @@ function doCompact(
             clustersPerLevel: dd.RAPTOR_CLUSTERS_PER_LEVEL,
             consistencyThreshold: dd.RAPTOR_CONSISTENCY,
             logger: runtime.logger,
+            builtAt: Number.isFinite(builtAt) ? builtAt : Date.now(),
           },
         );
       }

package/extensions/mega-runtime.ts

@@ -69,6 +69,7 @@ export const C = {
   magenta: "\x1b[38;5;201m", // dedup rate
   blue: "\x1b[38;5;75m", // repo totals
   gray: "\x1b[38;5;245m", // labels
+  red: "\x1b[38;5;203m", // pressure / overflow
 };
 
 const PULSE = ["◐", "◓", "◑", "◒"];
@@ -344,7 +345,7 @@ export class MegaRuntime {
       // 142 → "142". Dropped (in) = Freed + Kept; Freed = rt.tokensSaved (session)
       // / repo.tokensSaved meta (repo); Kept = totalTokenEstimate (stored).
       const fmt = (x: number) =>
-        x >= 1_000_000 ? `${(x / 1_000_000).toFixed(1)}M`
+        x >= 1_000_000 ? `${(x / 1_000_000).toFixed(1)}mil`
         : x >= 1000 ? `${(x / 1000).toFixed(1)}k`
         : `${Math.round(x)}`;
       const agentStr = this.activeAgents > 0 ? ` │ 🤖 ${this.activeAgents} agent${this.activeAgents === 1 ? "" : "s"}` : "";
@@ -360,21 +361,38 @@ export class MegaRuntime {
       const repoKept = repo.totalTokenEstimate;
       const repoFreed = repo.tokensSaved;
       const repoPct = repoIn > 0 ? repoFreed / repoIn : 0;
+      // Retro gradient bar — `w` cells, each shaded by fill position so it
+      // reads as a smooth green→amber→red ramp. Used for CONTEXT fill where
+      // low=green (room to spare) and high=red (near the limit) — the only
+      // live-moving metric worth a bar. Savings ratios saturate near 100% and
+      // are shown as explanatory numbers instead (see L2).
+      const ramp = (pct: number, w = 12): string => {
+        const cells = ["▏","▎","▍","▌","▋","▊","▉","█"];
+        const scaled = Math.max(0, Math.min(w, pct * w));
+        const full = Math.floor(scaled);
+        const frac = scaled - full;
+        const fracCell = frac > 0 ? cells[Math.round(frac * (cells.length - 1))] : "";
+        let out = "";
+        for (let i = 0; i < full; i++) out += (i / w < 0.6 ? C.green : i / w < 0.85 ? C.amber : C.red) + "█";
+        if (fracCell) out += (full / w < 0.6 ? C.green : full / w < 0.85 ? C.amber : C.red) + fracCell;
+        out += C.dim + "░".repeat(Math.max(0, w - full - (fracCell ? 1 : 0))) + C.reset;
+        return out;
+      };
+      const ctxPct = this.lastCtxPercent != null ? this.lastCtxPercent / 100 : 0;
+      const sTxt = (sessPct * 100).toFixed(sessPct * 100 >= 10 ? 0 : 1);
+      const rTxt = (repoPct * 100).toFixed(repoPct * 100 >= 10 ? 0 : 1);
       const lines = [
-        ` ${C.amber}⚡ ${tierLabel}${C.reset} v${C.bold}${ownVersion()}${C.reset} │ ${tokStr}/${maxStr} tokens (${C.bold}${pctStr}${C.reset}) │ ${st.checkpointCount} saved${agentStr}${turnStr}`,
-        `   ${triggerLabel} │ ${C.magenta}repeat-skipped: ${dedupStr}${C.reset}`,
-        `   ${C.gray}dropped ${fmt(sessIn)} → kept ${fmt(sessKept)} sess / ${fmt(repoKept)} repo · freed ${fmt(sessFreed)} sess / ${fmt(repoFreed)} repo${C.reset}`,
+        // L1 — header: tier + ctx-fill bar (20-cell, green=room→red=full) +
+        // tokens + status glyph + checkpoints + agents/turn. Widened to use the
+        // terminal width; the context bar is the only live-moving bar.
+        ` ${C.amber}⚡ ${tierLabel}${C.reset} v${C.bold}${ownVersion()}${C.reset} ${ramp(ctxPct, 20)} ${C.bold}${pctStr}${C.reset} ${tokStr}/${maxStr} │ ${triggerLabel} │ ${st.checkpointCount} chk${agentStr}${turnStr}`,
+        // L2 — savings EXPLAINED, not bar'd. The freed/(freed+kept) ratio
+        // saturates near 100% once cumulative freed dwarfs live kept (4.8mil
+        // freed vs 612 kept), so a bar is visually useless. Instead show the
+        // compaction story: "in→kept (X% freed)" reads as "compacted N tokens
+        // down to M, freeing X%". Plus repo-wide chk/session counts.
+        `   ${C.magenta}dup ${dedupStr}${C.reset} │ ${C.gray}sess${C.reset} ${fmt(sessIn)}→${fmt(sessKept)} kept ${C.green}(${sTxt}% freed)${C.reset} · ${C.gray}all-time${C.reset} ${fmt(repoIn)}→${fmt(repoKept)} kept ${C.blue}(${rTxt}% freed)${C.reset} │ ${repo.checkpointCount} chk/${repo.sessionCount} sess`,
       ];
-      // Compression meter — the single headline "% tokens saved" (Freed / In),
-      // same formula as the dashboard. Higher = better, so it reads green.
-      {
-        const w = 10;
-        const filled = Math.max(0, Math.min(w, Math.round(sessPct * w)));
-        const cbar = C.green + "▓".repeat(filled) + C.dim + "░".repeat(w - filled) + C.reset;
-        const sTxt = (sessPct * 100).toFixed(sessPct * 100 >= 10 ? 0 : 1);
-        const rTxt = (repoPct * 100).toFixed(repoPct * 100 >= 10 ? 0 : 1);
-        lines.push(`   ${cbar} ${sTxt}% tokens saved (sess) · ${rTxt}% repo${C.reset}`);
-      }
       // Live "now processing" line + why + recent deduped/compacted events,
       // collapsed to ONE rotating line (fresh only). The ticker ring buffer
       // (≤5 most-recent events) is cycled one-per-repaint so the line scrolls
@@ -394,12 +412,8 @@ export class MegaRuntime {
       } else if (this.pulsing) {
         lines.push(`   ${pulse}${C.teal}compacting…${C.reset}`);
       }
-      // Token accounting summary, always last + dimmed. Shows the total
-      // tokens dropped (in) + kept (out) for this session, then the freed
-      // (saved) tokens for both this session and all-time across the repo.
-      if (lines.length < 10) {
-        lines.push(`   ${C.dim}session ↑${fmt(sessIn)} in ↓${fmt(sessKept)} out · saved ${fmt(sessFreed)} session / ${fmt(repoFreed)} all-time${C.reset}`);
-      }
+      // (Accounting folded into L2's "in→kept (X% freed)" framing — freed =
+      //  in − kept is implied, and the saturated-ratio bars are gone.)
       ctx.ui.setWidget(WIDGET_KEY, lines, { placement: "aboveEditor" });
     }
   }

package/package.json

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

package/src/adapt.ts

@@ -44,26 +44,41 @@ export function messageToolName(m: AgentMessage): string | undefined {
 /** Pull the text out of a string-or-blocks content field. */
 function contentText(content: string | Array<{ type: string; text?: string }>): string {
   if (typeof content === "string") return content;
+  // PREVENT crash: pi blocks can arrive with `text: undefined` or a missing
+  // `content` field (tool/custom messages). Coerce to a string at the single
+  // choke point so every downstream `.matchAll`/`.split`/`.toLowerCase` is safe
+  // (extractive.ts, compact.ts, supersede.ts, summarizer.ts, boundary.ts).
+  if (!Array.isArray(content)) return "";
   return content
-    .filter((c) => c.type === "text" && typeof c.text === "string")
+    .filter((c) => c?.type === "text" && typeof c.text === "string")
     .map((c) => c.text as string)
     .join("\n");
 }
 
 /** Project any AgentMessage into a single text blob the engine can reason on. */
 function messageText(m: AgentMessage): string {
+  let out: string;
   switch (m.role) {
     case "toolResult":
     case "user":
     case "assistant":
     case "custom":
-      return contentText((m as { content: string | Array<{ type: string; text?: string }> }).content);
+      out = contentText((m as { content: string | Array<{ type: string; text?: string }> }).content);
+      break;
     case "bashExecution":
-      return `${(m as { command: string }).command}\n${(m as { output: string }).output}`;
+      out = `${(m as { command: string }).command ?? ""}\n${(m as { output: string }).output ?? ""}`;
+      break;
     case "branchSummary":
     case "compactionSummary":
-      return (m as { summary: string }).summary;
+      out = (m as { summary: string }).summary ?? "";
+      break;
+    default:
+      out = "";
+      break;
   }
+  // PREVENT crash: final safety net — never let `undefined`/`null` escape the
+  // adapter into the engine, which assumes `text: string` everywhere.
+  return out ?? "";
 }
 
 /**

package/src/dedup/raptor/index.ts

@@ -31,6 +31,8 @@ export interface RaptorOrchestratorOptions {
   consistencyThreshold?: number;
   /** Best-effort logger for shadow events. */
   logger?: Logger;
+  /** S25: epoch ms to stamp on every node (freshness guard). Defaults to now. */
+  builtAt?: number;
 }
 
 /**
@@ -54,7 +56,8 @@ export function runRaptor(
       clustersPerLevel: opts.clustersPerLevel,
       consistencyThreshold: opts.consistencyThreshold,
     });
-    saveRaptorTree(opts.sessionId, tree, opts.stateDir);
+    const builtAt = opts.builtAt ?? Date.now();
+    saveRaptorTree(opts.sessionId, tree, builtAt, opts.stateDir);
     logger?.info("raptor_build", {
       sessionId: opts.sessionId,
       nodes: tree.nodes.size,
@@ -105,6 +108,15 @@ export function rehydrateRaptorTree(
 ): RaptorTree | null {
   const nodes = listRaptorNodes(sessionId, stateDir);
   if (nodes.length === 0) return null;
+  // S25: derive freshness + fallback metadata from the persisted nodes.
+  // builtAt = max node built_at (0 when unknown → caller treats as stale).
+  // timedOut = the tree's root is the extractive-fallback marker (level 99).
+  const builtAt = nodes.reduce((max, n) => Math.max(max, n.builtAt), 0);
+  const root = nodes.reduce<typeof nodes[number] | null>(
+    (best, n) => (!best || n.level > (best?.level ?? -1) ? n : best),
+    null,
+  );
+  const timedOut = root != null && root.level >= 99;
   const tree: RaptorTree = {
     nodes: new Map(
       nodes.map((n) => [
@@ -121,13 +133,10 @@ export function rehydrateRaptorTree(
         },
       ]),
     ),
-    rootId:
-      nodes.reduce<typeof nodes[number] | null>(
-        (best, n) => (!best || n.level > (best?.level ?? -1) ? n : best),
-        null,
-      )?.id ?? null,
+    rootId: root?.id ?? null,
     levels: Math.max(1, ...nodes.map((n) => n.level + 1)),
-    timedOut: false,
+    timedOut,
+    builtAt,
   };
   return tree;
 }

package/src/dedup/raptor/tree.ts

@@ -40,6 +40,8 @@ export interface RaptorTree {
   levels: number;
   /** True when the budget forced an extractive fallback root. */
   timedOut: boolean;
+  /** S25: epoch ms when the tree was built (freshness guard). 0 when unknown. */
+  builtAt?: number;
 }
 
 export interface Leaf {

package/src/extractive.test.ts

@@ -7,6 +7,24 @@ function msg(role: EngineMessage["role"], text: string, toolName?: string): Engi
   return toolName ? { role, text, toolName, input: text, output: text } : { role, text };
 }
 
+// ---- Crash regression: undefined text (S25 hotfix) ------------------------
+// pi tool/custom messages can arrive with `text: undefined` when only
+// input/output is set. The adapter (adapt.ts) now coerces to "", and
+// extractiveSummarize guards its entry too. This test pins the no-crash
+// contract directly against the engine entry (defense in depth).
+test("extractiveSummarize does not crash on messages with undefined text", () => {
+  const messages = [
+    { role: "user", text: "please edit src/index.ts" },
+    { role: "assistant", text: undefined as unknown as string, toolName: "Edit", input: "src/index.ts" },
+    { role: "tool", text: undefined as unknown as string, toolName: "Edit", output: "ok" },
+    { role: "assistant", text: "done editing src/index.ts" },
+  ] as EngineMessage[];
+  // Must not throw — previously crashed at text.matchAll in extractFilePaths.
+  const s = extractiveSummarize(messages);
+  assert.ok(typeof s.topicSummary === "string");
+  assert.ok(s.topicSummary.length >= 0);
+});
+
 // ---- Determinism -----------------------------------------------------------
 
 test("extractive summary is deterministic", () => {

package/src/extractive.ts

@@ -226,18 +226,24 @@ export function extractiveSummarize(messages: EngineMessage[]): ExtractiveSummar
     return { topicSummary: "(empty)", keyDecisions: [], nextSteps: [], filesModified: [], tokenEstimate: 0 };
   }
 
-  const toolMsgs = messages.filter((m) => m.role === "tool");
+  // PREVENT crash: tool/custom messages can arrive with `text: undefined` when
+  // only `input`/`output` is set (the type says string, but pi's runtime does
+  // not always fill it). Coerce to "" once at the entry so every downstream
+  // `.text` / `.matchAll` / `.split` access is safe.
+  const safe = messages.map((m) => ({ ...m, text: m.text ?? "" }));
+
+  const toolMsgs = safe.filter((m) => m.role === "tool");
   const tools = [...new Set(messages.flatMap((m) => (m.toolName ? [m.toolName] : [])))].sort();
 
-  const recentUser = collectRecentUserRequests(messages, MAX_RECENT_USER);
-  const currentWork = inferCurrentWork(messages);
-  const keyFiles = collectKeyFiles(messages);
-  const pending = inferPendingWork(messages);
-  const keyDecisions = extractDecisions(messages);
+  const recentUser = collectRecentUserRequests(safe, MAX_RECENT_USER);
+  const currentWork = inferCurrentWork(safe);
+  const keyFiles = collectKeyFiles(safe);
+  const pending = inferPendingWork(safe);
+  const keyDecisions = extractDecisions(safe);
   const filesModified = extractFilesModified(toolMsgs);
 
   const topicSummary = buildTopicSummary(
-    messages, tools, recentUser, currentWork, keyFiles, pending,
+    safe, tools, recentUser, currentWork, keyFiles, pending,
   );
 
   const tokenEstimate = estimateBlockTokens(topicSummary);

package/src/store/backfill.ts

@@ -254,7 +254,9 @@ export function backfillRaptor(
     return { phase: "RAPTOR", processed: 0, batches: 0, interrupted: false, cursor: undefined };
   }
   const tree = buildRaptorTree(leaves, { embedder });
-  saveRaptorTree(sessionId, tree, stateDir);
+  // S25: freshness-guard timestamp = newest checkpoint's epoch.
+  const builtAt = all.length > 0 ? Math.max(...all.map((c) => c.timestamp)) : Date.now();
+  saveRaptorTree(sessionId, tree, Number.isFinite(builtAt) ? builtAt : Date.now(), stateDir);
   const db = openStore(stateDir);
   ensureProgressTable(db);
   savePhaseCursor(db, "RAPTOR", leaves[leaves.length - 1].id, leaves.length);

package/src/store/sqlite.ts

@@ -458,6 +458,7 @@ function initSchema(db: DatabaseSync): void {
       embedding_blob BLOB,         -- float32 centroid
       quality_marker TEXT DEFAULT 'low',
       token_estimate INTEGER,
+      built_at     INTEGER,        -- S25: epoch ms when the tree was built (freshness guard)
       PRIMARY KEY (session_id, id)
     );
     CREATE INDEX IF NOT EXISTS idx_raptor_session ON raptor_nodes(session_id);
@@ -555,6 +556,9 @@ function initSchema(db: DatabaseSync): void {
   ensureColumn(db, "memories", "target", "TEXT");
   ensureColumn(db, "memories", "last_referenced", "INTEGER");
   ensureColumn(db, "memories", "source_turn", "INTEGER");
+  // S25: RAPTOR freshness-guard timestamp. Additive; old DBs have NULL → 0 →
+  // treated as stale → flat fallback (safe).
+  ensureColumn(db, "raptor_nodes", "built_at", "INTEGER");
   const v = db.prepare("SELECT value FROM meta WHERE key='schema_version'").get() as
     | { value: string }
     | undefined;
@@ -1103,6 +1107,16 @@ export function listCheckpoints(sessionId: string, stateDir: string = getStateDi
   return rows.map(rowToCheckpoint);
 }
 
+/** S25: the newest checkpoint timestamp for a session, or 0 when none. Used by
+ *  the RAPTOR freshness guard to reject a tree older than the live checkpoints. */
+export function maxCheckpointTimestamp(sessionId: string, stateDir: string = getStateDir()): number {
+  const db = openStore(stateDir);
+  const row = db
+    .prepare("SELECT MAX(timestamp) AS mx FROM context_chunks WHERE session_id = ?")
+    .get(normalizeSessionId(sessionId)) as { mx: number | null } | undefined;
+  return Number(row?.mx ?? 0);
+}
+
 /** Next sequential checkpoint id (chkpt_001 …) for a session. */
 export function nextCheckpointId(sessionId: string, stateDir: string = getStateDir()): string {
   const db = openStore(stateDir);
@@ -1404,18 +1418,21 @@ export interface StoredRaptorNode {
   embedding: number[];
   qualityMarker: string;
   tokenEstimate: number;
+  /** S25: epoch ms when the tree containing this node was built. */
+  builtAt: number;
 }
 
 /** Persist a single RAPTOR node (upsert by (session_id, id)). */
 export function upsertRaptorNode(node: StoredRaptorNode, stateDir: string = getStateDir()): void {
   const db = openStore(stateDir);
   db.prepare(
-    `INSERT INTO raptor_nodes(id, session_id, level, parent_id, children, summary, embedding_blob, quality_marker, token_estimate)
-     VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `INSERT INTO raptor_nodes(id, session_id, level, parent_id, children, summary, embedding_blob, quality_marker, token_estimate, built_at)
+     VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
      ON CONFLICT(session_id, id) DO UPDATE SET
        level=excluded.level, parent_id=excluded.parent_id, children=excluded.children,
        summary=excluded.summary, embedding_blob=excluded.embedding_blob,
-       quality_marker=excluded.quality_marker, token_estimate=excluded.token_estimate`,
+       quality_marker=excluded.quality_marker, token_estimate=excluded.token_estimate,
+       built_at=excluded.built_at`,
   ).run(
     node.id,
     node.sessionId,
@@ -1426,13 +1443,26 @@ export function upsertRaptorNode(node: StoredRaptorNode, stateDir: string = getS
     encodeEmbedding(node.embedding),
     node.qualityMarker,
     node.tokenEstimate,
+    node.builtAt,
   );
 }
 
 /** Persist an entire built RAPTOR tree for a session (shadow or live). */
 export function saveRaptorTree(
   sessionId: string,
-  tree: { nodes: Map<string, { id: string; level: number; parentId: string | null; children: string[]; summary: string; embedding: number[]; qualityMarker: string; tokenEstimate: number }> },
+  tree: {
+    nodes: Map<string, {
+      id: string;
+      level: number;
+      parentId: string | null;
+      children: string[];
+      summary: string;
+      embedding: number[];
+      qualityMarker: string;
+      tokenEstimate: number;
+    }>
+  },
+  builtAt: number,
   stateDir: string = getStateDir(),
 ): void {
   for (const node of tree.nodes.values()) {
@@ -1447,6 +1477,7 @@ export function saveRaptorTree(
         embedding: node.embedding,
         qualityMarker: node.qualityMarker,
         tokenEstimate: node.tokenEstimate,
+        builtAt,
       },
       stateDir,
     );
@@ -1469,6 +1500,7 @@ export function listRaptorNodes(sessionId: string, stateDir: string = getStateDi
     embedding: decodeEmbedding(row.embedding_blob),
     qualityMarker: row.quality_marker ?? "low",
     tokenEstimate: row.token_estimate ?? 0,
+    builtAt: Number(row.built_at ?? 0),
   }));
 }
 

package/src/vectorStore.ts

@@ -38,13 +38,14 @@ import {
   bumpDedupStats,
   repoStats as repoStatsFromStore,
   dataInvariantStats,
+  maxCheckpointTimestamp,
 } from "./store/sqlite.js";
 import {
   initVectorIndex,
   searchAsync as vectorIndexSearch,
   type VectorIndexHit,
 } from "./store/vectorIndex.js";
-import { rehydrateRaptorTree } from "./dedup/raptor/index.js";
+import { rehydrateRaptorTree, isShadowMode } from "./dedup/raptor/index.js";
 import { stagedExpansion } from "./dedup/raptor/retrieval.js";
 import { migrateJsonToSqlite } from "./store/migrate.js";
 
@@ -557,9 +558,20 @@ export class VectorStore {
    * exists (small sessions — flat search remains the path). Best-effort/non-fatal.
    */
   private raptorSearchHits(sid: string, query: string, k: number): SearchHit[] {
+    const t0 = Date.now();
     try {
+      // S25 gate (a): honor the shadow contract at SERVE time. The tree is still
+      // built + persisted (logging-only) but NOT merged into recall while
+      // RAPTOR_SHADOW_MODE is anything other than "false".
+      if (isShadowMode()) return [];
       const tree = rehydrateRaptorTree(sid, this.stateDir);
       if (!tree || !tree.rootId) return [];
+      // S25 gate (b): freshness + fallback guards. Skip a tree built before the
+      // newest checkpoint (stale → may reference trimmed/deduped leaves) or one
+      // whose root is a budget-exhausted extractive fallback (level 99).
+      if (tree.timedOut) return [];
+      const maxTs = maxCheckpointTimestamp(sid, this.stateDir);
+      if (tree.builtAt && tree.builtAt < maxTs) return [];
       const leafIds = stagedExpansion(query, tree, {
         embedder: this.embedder,
         k,
@@ -576,6 +588,9 @@ export class VectorStore {
         const cp = all.find((c) => c.checkpointId === id);
         if (cp) hits.push({ checkpoint: cp, score: cosineSimilarity(qv, cp.embedding) });
       }
+      // S25 monitoring: emit a raptor_serve decision so canary.ts can track
+      // p95 latency + the tier's live traffic (non-fatal, best-effort).
+      this.record("RAPTOR", hits.length > 0 ? "new" : "mark_only", `leaves=${leafIds.length}`, Date.now() - t0);
       return hits;
     } catch {
       return [];