pi-mega-compact 0.6.6 → 0.6.9

package/dist/extensions/dashboard-server.js

@@ -83,7 +83,52 @@ function readIndex() {
             inputRate: r.input_rate ?? null,
             outputRate: r.output_rate ?? null,
             lastSeen: Number(r.last_seen ?? 0),
+            // Defaults — enriched below from each repo's own store.
+            tokensKept: 0,
+            tokensDropped: 0,
+            sessions: 0,
+            contextWindow: null,
+            maxTokens: null,
+            reasoning: null,
         }));
+        // Enrich each repo with per-store token + model detail read directly via
+        // node:sqlite (same zero-dependency invariant as readIndex; no store graph
+        // import). Best-effort: a missing/corrupt store degrades to the defaults
+        // above so the dashboard never fails to render.
+        for (const repo of mapped) {
+            try {
+                const storePath = join(repo.stateDir, "sqlite.db");
+                if (existsSync(storePath)) {
+                    const sdb = new DatabaseSync(storePath, { readOnly: true });
+                    try {
+                        const tok = sdb
+                            .prepare(`SELECT COALESCE(SUM(token_estimate),0) AS kept,
+                        COALESCE(SUM(original_token_estimate),0) AS dropped,
+                        COUNT(DISTINCT session_id) AS sess
+                 FROM context_chunks WHERE dedup_status != 'removed'`)
+                            .get();
+                        repo.tokensKept = Number(tok.kept ?? 0);
+                        repo.tokensDropped = Number(tok.dropped ?? 0);
+                        repo.sessions = Number(tok.sess ?? 0);
+                        const mrow = sdb
+                            .prepare(`SELECT context_window, max_tokens, reasoning
+                 FROM model_snapshots ORDER BY captured_at DESC LIMIT 1`)
+                            .get();
+                        if (mrow) {
+                            repo.contextWindow = Number(mrow.context_window ?? 0) || null;
+                            repo.maxTokens = Number(mrow.max_tokens ?? 0) || null;
+                            repo.reasoning = Number(mrow.reasoning ?? 0) === 1;
+                        }
+                    }
+                    finally {
+                        sdb.close();
+                    }
+                }
+            }
+            catch {
+                /* best-effort — keep the defaults */
+            }
+        }
         // Defensive display hygiene (belt-and-suspenders — the real fix is that
         // tests now isolate via MEGACOMPACT_INDEX_DIR): drop transient test/temp
         // paths that should never have been real repos, and collapse duplicate
@@ -443,15 +488,23 @@ function dashboardHtml(tierName) {
     <thead>
       <tr>
         <th>Model</th><th>Provider</th>
-        <th style="text-align:right">Repos</th>
+        <th style="text-align:right" title="Tokens dropped from context by compaction (the input reclaimed)">Tokens In</th>
+        <th style="text-align:right" title="Tokens kept as compacted summaries still in context (the output retained)">Tokens Out</th>
+        <th style="text-align:right">Freed</th>
+        <th style="text-align:right" title="Model context window (max input tokens the model accepts)">Ctx Window</th>
+        <th style="text-align:right" title="Model max output tokens per turn">Max Out</th>
+        <th style="text-align:right" title="Reasoning-capable model">Reas.</th>
+        <th style="text-align:right" title="Distinct sessions with at least one checkpoint">Sessions</th>
         <th style="text-align:right">Checkpoints</th>
-        <th style="text-align:right">Tokens Saved</th>
+        <th style="text-align:right" title="USD per input token">In $/tok</th>
+        <th style="text-align:right" title="USD per output token">Out $/tok</th>
         <th style="text-align:right">$ Saved</th>
         <th style="text-align:right">Last Used</th>
       </tr>
     </thead>
-    <tbody id="bm-rows"><tr><td colspan="7" class="repo-none">loading…</td></tr></tbody>
+    <tbody id="bm-rows"><tr><td colspan="14" class="repo-none">loading…</td></tr></tbody>
   </table>
+  <p class="legend-note" style="margin-top:8px">Tokens In = Σ original region tokens dropped by compaction. Tokens Out = Σ compacted summary tokens still retained in context. Freed = Tokens In − Tokens Out (net context reclaimed). Ctx Window / Max Out / Reas. come from the latest captured model snapshot for each repo.</p>
 
   <div class="updated" id="sm-updated"></div>
 </div>
@@ -673,33 +726,67 @@ function dashboardHtml(tierName) {
     var rows = document.getElementById('bm-rows');
     if (!rows) return;
     if (!repos || !repos.length) {
-      rows.innerHTML = '<tr><td colspan="7" class="repo-none">No repositories registered yet.</td></tr>';
+      rows.innerHTML = '<tr><td colspan="14" class="repo-none">No repositories registered yet.</td></tr>';
       return;
     }
     var groups = {};
     for (var i = 0; i < repos.length; i++) {
       var r = repos[i];
       var key = (r.modelName && String(r.modelName).trim()) || '(unknown)';
-      if (!groups[key]) groups[key] = { model: key, provider: r.providerName || r.provider || '—', repos: 0, checkpoints: 0, tokensSaved: 0, usd: 0, lastAt: 0, rates: [] };
+      if (!groups[key]) groups[key] = {
+        model: key, provider: r.providerName || r.provider || '—', repos: 0, checkpoints: 0,
+        tokensSaved: 0, tokensIn: 0, tokensOut: 0, sessions: 0, usd: 0, lastAt: 0,
+        inRates: [], outRates: [], ctxWindows: [], maxTokens: [], reasoning: null,
+      };
       var g = groups[key];
       g.repos++;
       g.checkpoints += (r.checkpointCount || 0);
       g.tokensSaved += (r.tokensSaved || 0);
-      if (r.inputRate) { g.usd += (r.tokensSaved || 0) * r.inputRate; g.rates.push(r.inputRate); }
+      g.tokensIn += (r.tokensDropped || 0);
+      g.tokensOut += (r.tokensKept || 0);
+      g.sessions += (r.sessions || 0);
+      if (r.inputRate) { g.usd += (r.tokensSaved || 0) * r.inputRate; g.inRates.push(r.inputRate); }
+      if (r.outputRate) g.outRates.push(r.outputRate);
+      if (r.contextWindow) g.ctxWindows.push(r.contextWindow);
+      if (r.maxTokens) g.maxTokens.push(r.maxTokens);
+      if (r.reasoning != null) g.reasoning = r.reasoning;
       if (r.lastCompactedAt && r.lastCompactedAt > g.lastAt) g.lastAt = r.lastCompactedAt;
     }
     var arr = [];
     for (var k in groups) { if (Object.prototype.hasOwnProperty.call(groups, k)) arr.push(groups[k]); }
     arr.sort(function(a, b) { return b.tokensSaved - a.tokensSaved; });
+    // Helper: a set of numeric samples collapses to a single value when all
+    // repos in the group agree, otherwise shows the range (min–max) so the
+    // user can see mixed-config model groups at a glance.
+    function collapseNum(samples) {
+      if (!samples || !samples.length) return '—';
+      var lo = Math.min.apply(null, samples), hi = Math.max.apply(null, samples);
+      return lo === hi ? lo.toLocaleString() : lo.toLocaleString() + '–' + hi.toLocaleString();
+    }
+    function collapseRate(samples) {
+      if (!samples || !samples.length) return '—';
+      var lo = Math.min.apply(null, samples), hi = Math.max.apply(null, samples);
+      var fmt = function(v) { return '$' + v.toFixed(6); };
+      return lo === hi ? fmt(lo) : fmt(lo) + '–' + fmt(hi);
+    }
     rows.innerHTML = arr.map(function(g) {
+      var freed = (g.tokensIn || 0) - (g.tokensOut || 0);
       var usd = g.usd > 0 ? '$' + g.usd.toFixed(4) : '—';
       var when = g.lastAt ? new Date(g.lastAt).toLocaleString() : '—';
+      var reas = g.reasoning == null ? '—' : (g.reasoning ? 'yes' : 'no');
       return '<tr>' +
         '<td><span class="repo-model">' + sanitize(g.model) + '</span></td>' +
         '<td>' + sanitize(g.provider) + '</td>' +
-        '<td class="num">' + g.repos.toLocaleString() + '</td>' +
+        '<td class="num">' + (g.tokensIn || 0).toLocaleString() + '</td>' +
+        '<td class="num">' + (g.tokensOut || 0).toLocaleString() + '</td>' +
+        '<td class="num">' + freed.toLocaleString() + '</td>' +
+        '<td class="num">' + collapseNum(g.ctxWindows) + '</td>' +
+        '<td class="num">' + collapseNum(g.maxTokens) + '</td>' +
+        '<td class="num">' + reas + '</td>' +
+        '<td class="num">' + g.sessions.toLocaleString() + '</td>' +
         '<td class="num">' + g.checkpoints.toLocaleString() + '</td>' +
-        '<td class="num">' + g.tokensSaved.toLocaleString() + '</td>' +
+        '<td class="num">' + collapseRate(g.inRates) + '</td>' +
+        '<td class="num">' + collapseRate(g.outRates) + '</td>' +
         '<td class="num">' + sanitize(usd) + '</td>' +
         '<td class="num">' + sanitize(when) + '</td>' +
       '</tr>';

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

@@ -332,9 +332,11 @@ export class MegaRuntime {
             const repoKept = repo.totalTokenEstimate;
             const repoFreed = repo.tokensSaved;
             const repoPct = repoIn > 0 ? repoFreed / repoIn : 0;
-            // Retro gradient bar — 12 cells, each cell shaded by fill so it reads as a
-            // smooth green→amber→red ramp instead of a flat block. Higher fill = more
-            // reclaimed, so the bar trends green at the right end.
+            // 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));
@@ -353,10 +355,16 @@ export class MegaRuntime {
             const sTxt = (sessPct * 100).toFixed(sessPct * 100 >= 10 ? 0 : 1);
             const rTxt = (repoPct * 100).toFixed(repoPct * 100 >= 10 ? 0 : 1);
             const lines = [
-                // L1 — header: tier + ctx fill bar + tokens + checkpoints + agents
-                ` ${C.amber}⚡ ${tierLabel}${C.reset} v${C.bold}${ownVersion()}${C.reset} ${ramp(ctxPct)} ${C.bold}${pctStr}${C.reset} ${tokStr}/${maxStr} │ ${st.checkpointCount} chk${agentStr}${turnStr}`,
-                // L2 — status + dedup + session + all-time savings bars
-                `   ${triggerLabel} ${C.magenta}dup ${dedupStr}${C.reset} ${C.gray}sess${C.reset} ${ramp(sessPct)} ${C.green}${sTxt}%${C.reset} ${C.gray}all-time${C.reset} ${ramp(repoPct)} ${C.blue}${rTxt}%${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`,
             ];
             // Live "now processing" line + why + recent deduped/compacted events,
             // collapsed to ONE rotating line (fresh only). The ticker ring buffer
@@ -379,11 +387,8 @@ export class MegaRuntime {
             else if (this.pulsing) {
                 lines.push(`   ${pulse}${C.teal}compacting…${C.reset}`);
             }
-            // L4 — accounting: session + all-time in/out/freed, one compact line.
-            // in = dropped into compaction, out = kept summaries, freed = saved.
-            if (lines.length < 10) {
-                lines.push(`   ${C.dim}session ↑${fmt(sessIn)} in ↓${fmt(sessKept)} out ↓${fmt(sessFreed)} freed · all-time ↑${fmt(repoIn)} in ↓${fmt(repoKept)} out ↓${fmt(repoFreed)} freed${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/compact.js

@@ -16,7 +16,11 @@ function truncate(s, max) {
     return s.length <= max ? s : `${s.slice(0, max)}…`;
 }
 function firstText(m) {
-    const t = m.text.trim();
+    // PREVENT crash: pi can hand us a message with text: undefined (pure
+    // tool-call/tool-result). Guard the trim so the legacy summarizeMessages
+    // path can't throw the same undefined-text crash the extractive path did.
+    const raw = m.text ?? "";
+    const t = raw.trim();
     return t.length > 0 ? t : undefined;
 }
 /** Heuristic: does this text look like chatty filler we can collapse? */

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/supersede.js

@@ -9,13 +9,16 @@
 import { extractFileCandidates } from "./compact.js";
 /** Classify a message's relationship to a file path. */
 function fileOps(msg) {
-    // msg.text may be undefined for pure tool-call/result messages; the guard
-    // lives in extractFileCandidates, but the early return short-circuits the
-    // write-detection regex too so we never classify an empty message.
-    const paths = extractFileCandidates(msg.text);
+    // PREVENT crash: msg.text may be undefined for pure tool-call/result
+    // messages. extractFileCandidates guards the split, but if it returned a
+    // hit we'd still call .toLowerCase() on the raw (possibly-undefined) text.
+    // Coerce once so both extractFileCandidates and the write-detection regex
+    // are safe, and the early return still skips empty messages.
+    const text = msg.text ?? "";
+    const paths = extractFileCandidates(text);
     if (paths.length === 0)
         return [];
-    const low = msg.text.toLowerCase();
+    const low = text.toLowerCase();
     const isWrite = /\b(write|edit|create|save|append|overwrite|update|patch|modify)\b/.test(low);
     return paths.map((p) => ({ path: p, op: isWrite ? "write" : "read" }));
 }

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/dashboard-server.ts

@@ -70,6 +70,17 @@ interface IndexRepo {
   inputRate: number | null;
   outputRate: number | null;
   lastSeen: number;
+  // Per-repo token + model detail (S25 dashboard enrichment), read directly
+  // from each repo's node:sqlite store at stateDir. tokensKept = Σ stored
+  // summary tokens ("out"); tokensDropped = Σ original region tokens ("in");
+  // sessions = distinct sessions with a checkpoint; contextWindow/maxTokens/
+  // reasoning come from the latest model_snapshots row for that repo.
+  tokensKept: number;
+  tokensDropped: number;
+  sessions: number;
+  contextWindow: number | null;
+  maxTokens: number | null;
+  reasoning: boolean | null;
 }
 
 interface IndexSummary {
@@ -107,7 +118,54 @@ function readIndex(): IndexIndex | null {
       inputRate: (r.input_rate as number | null) ?? null,
       outputRate: (r.output_rate as number | null) ?? null,
       lastSeen: Number(r.last_seen ?? 0),
+      // Defaults — enriched below from each repo's own store.
+      tokensKept: 0,
+      tokensDropped: 0,
+      sessions: 0,
+      contextWindow: null,
+      maxTokens: null,
+      reasoning: null,
     }));
+    // Enrich each repo with per-store token + model detail read directly via
+    // node:sqlite (same zero-dependency invariant as readIndex; no store graph
+    // import). Best-effort: a missing/corrupt store degrades to the defaults
+    // above so the dashboard never fails to render.
+    for (const repo of mapped) {
+      try {
+        const storePath = join(repo.stateDir, "sqlite.db");
+        if (existsSync(storePath)) {
+          const sdb = new DatabaseSync(storePath, { readOnly: true });
+          try {
+            const tok = sdb
+              .prepare(
+                `SELECT COALESCE(SUM(token_estimate),0) AS kept,
+                        COALESCE(SUM(original_token_estimate),0) AS dropped,
+                        COUNT(DISTINCT session_id) AS sess
+                 FROM context_chunks WHERE dedup_status != 'removed'`,
+              )
+              .get() as { kept: number; dropped: number; sess: number };
+            repo.tokensKept = Number(tok.kept ?? 0);
+            repo.tokensDropped = Number(tok.dropped ?? 0);
+            repo.sessions = Number(tok.sess ?? 0);
+            const mrow = sdb
+              .prepare(
+                `SELECT context_window, max_tokens, reasoning
+                 FROM model_snapshots ORDER BY captured_at DESC LIMIT 1`,
+              )
+              .get() as { context_window: number; max_tokens: number; reasoning: number } | undefined;
+            if (mrow) {
+              repo.contextWindow = Number(mrow.context_window ?? 0) || null;
+              repo.maxTokens = Number(mrow.max_tokens ?? 0) || null;
+              repo.reasoning = Number(mrow.reasoning ?? 0) === 1;
+            }
+          } finally {
+            sdb.close();
+          }
+        }
+      } catch {
+        /* best-effort — keep the defaults */
+      }
+    }
     // Defensive display hygiene (belt-and-suspenders — the real fix is that
     // tests now isolate via MEGACOMPACT_INDEX_DIR): drop transient test/temp
     // paths that should never have been real repos, and collapse duplicate
@@ -541,15 +599,23 @@ function dashboardHtml(tierName: string): string {
     <thead>
       <tr>
         <th>Model</th><th>Provider</th>
-        <th style="text-align:right">Repos</th>
+        <th style="text-align:right" title="Tokens dropped from context by compaction (the input reclaimed)">Tokens In</th>
+        <th style="text-align:right" title="Tokens kept as compacted summaries still in context (the output retained)">Tokens Out</th>
+        <th style="text-align:right">Freed</th>
+        <th style="text-align:right" title="Model context window (max input tokens the model accepts)">Ctx Window</th>
+        <th style="text-align:right" title="Model max output tokens per turn">Max Out</th>
+        <th style="text-align:right" title="Reasoning-capable model">Reas.</th>
+        <th style="text-align:right" title="Distinct sessions with at least one checkpoint">Sessions</th>
         <th style="text-align:right">Checkpoints</th>
-        <th style="text-align:right">Tokens Saved</th>
+        <th style="text-align:right" title="USD per input token">In $/tok</th>
+        <th style="text-align:right" title="USD per output token">Out $/tok</th>
         <th style="text-align:right">$ Saved</th>
         <th style="text-align:right">Last Used</th>
       </tr>
     </thead>
-    <tbody id="bm-rows"><tr><td colspan="7" class="repo-none">loading…</td></tr></tbody>
+    <tbody id="bm-rows"><tr><td colspan="14" class="repo-none">loading…</td></tr></tbody>
   </table>
+  <p class="legend-note" style="margin-top:8px">Tokens In = Σ original region tokens dropped by compaction. Tokens Out = Σ compacted summary tokens still retained in context. Freed = Tokens In − Tokens Out (net context reclaimed). Ctx Window / Max Out / Reas. come from the latest captured model snapshot for each repo.</p>
 
   <div class="updated" id="sm-updated"></div>
 </div>
@@ -771,33 +837,67 @@ function dashboardHtml(tierName: string): string {
     var rows = document.getElementById('bm-rows');
     if (!rows) return;
     if (!repos || !repos.length) {
-      rows.innerHTML = '<tr><td colspan="7" class="repo-none">No repositories registered yet.</td></tr>';
+      rows.innerHTML = '<tr><td colspan="14" class="repo-none">No repositories registered yet.</td></tr>';
       return;
     }
     var groups = {};
     for (var i = 0; i < repos.length; i++) {
       var r = repos[i];
       var key = (r.modelName && String(r.modelName).trim()) || '(unknown)';
-      if (!groups[key]) groups[key] = { model: key, provider: r.providerName || r.provider || '—', repos: 0, checkpoints: 0, tokensSaved: 0, usd: 0, lastAt: 0, rates: [] };
+      if (!groups[key]) groups[key] = {
+        model: key, provider: r.providerName || r.provider || '—', repos: 0, checkpoints: 0,
+        tokensSaved: 0, tokensIn: 0, tokensOut: 0, sessions: 0, usd: 0, lastAt: 0,
+        inRates: [], outRates: [], ctxWindows: [], maxTokens: [], reasoning: null,
+      };
       var g = groups[key];
       g.repos++;
       g.checkpoints += (r.checkpointCount || 0);
       g.tokensSaved += (r.tokensSaved || 0);
-      if (r.inputRate) { g.usd += (r.tokensSaved || 0) * r.inputRate; g.rates.push(r.inputRate); }
+      g.tokensIn += (r.tokensDropped || 0);
+      g.tokensOut += (r.tokensKept || 0);
+      g.sessions += (r.sessions || 0);
+      if (r.inputRate) { g.usd += (r.tokensSaved || 0) * r.inputRate; g.inRates.push(r.inputRate); }
+      if (r.outputRate) g.outRates.push(r.outputRate);
+      if (r.contextWindow) g.ctxWindows.push(r.contextWindow);
+      if (r.maxTokens) g.maxTokens.push(r.maxTokens);
+      if (r.reasoning != null) g.reasoning = r.reasoning;
       if (r.lastCompactedAt && r.lastCompactedAt > g.lastAt) g.lastAt = r.lastCompactedAt;
     }
     var arr = [];
     for (var k in groups) { if (Object.prototype.hasOwnProperty.call(groups, k)) arr.push(groups[k]); }
     arr.sort(function(a, b) { return b.tokensSaved - a.tokensSaved; });
+    // Helper: a set of numeric samples collapses to a single value when all
+    // repos in the group agree, otherwise shows the range (min–max) so the
+    // user can see mixed-config model groups at a glance.
+    function collapseNum(samples) {
+      if (!samples || !samples.length) return '—';
+      var lo = Math.min.apply(null, samples), hi = Math.max.apply(null, samples);
+      return lo === hi ? lo.toLocaleString() : lo.toLocaleString() + '–' + hi.toLocaleString();
+    }
+    function collapseRate(samples) {
+      if (!samples || !samples.length) return '—';
+      var lo = Math.min.apply(null, samples), hi = Math.max.apply(null, samples);
+      var fmt = function(v) { return '$' + v.toFixed(6); };
+      return lo === hi ? fmt(lo) : fmt(lo) + '–' + fmt(hi);
+    }
     rows.innerHTML = arr.map(function(g) {
+      var freed = (g.tokensIn || 0) - (g.tokensOut || 0);
       var usd = g.usd > 0 ? '$' + g.usd.toFixed(4) : '—';
       var when = g.lastAt ? new Date(g.lastAt).toLocaleString() : '—';
+      var reas = g.reasoning == null ? '—' : (g.reasoning ? 'yes' : 'no');
       return '<tr>' +
         '<td><span class="repo-model">' + sanitize(g.model) + '</span></td>' +
         '<td>' + sanitize(g.provider) + '</td>' +
-        '<td class="num">' + g.repos.toLocaleString() + '</td>' +
+        '<td class="num">' + (g.tokensIn || 0).toLocaleString() + '</td>' +
+        '<td class="num">' + (g.tokensOut || 0).toLocaleString() + '</td>' +
+        '<td class="num">' + freed.toLocaleString() + '</td>' +
+        '<td class="num">' + collapseNum(g.ctxWindows) + '</td>' +
+        '<td class="num">' + collapseNum(g.maxTokens) + '</td>' +
+        '<td class="num">' + reas + '</td>' +
+        '<td class="num">' + g.sessions.toLocaleString() + '</td>' +
         '<td class="num">' + g.checkpoints.toLocaleString() + '</td>' +
-        '<td class="num">' + g.tokensSaved.toLocaleString() + '</td>' +
+        '<td class="num">' + collapseRate(g.inRates) + '</td>' +
+        '<td class="num">' + collapseRate(g.outRates) + '</td>' +
         '<td class="num">' + sanitize(usd) + '</td>' +
         '<td class="num">' + sanitize(when) + '</td>' +
       '</tr>';

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

@@ -361,9 +361,11 @@ export class MegaRuntime {
       const repoKept = repo.totalTokenEstimate;
       const repoFreed = repo.tokensSaved;
       const repoPct = repoIn > 0 ? repoFreed / repoIn : 0;
-      // Retro gradient bar — 12 cells, each cell shaded by fill so it reads as a
-      // smooth green→amber→red ramp instead of a flat block. Higher fill = more
-      // reclaimed, so the bar trends green at the right end.
+      // 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));
@@ -380,10 +382,16 @@ export class MegaRuntime {
       const sTxt = (sessPct * 100).toFixed(sessPct * 100 >= 10 ? 0 : 1);
       const rTxt = (repoPct * 100).toFixed(repoPct * 100 >= 10 ? 0 : 1);
       const lines = [
-        // L1 — header: tier + ctx fill bar + tokens + checkpoints + agents
-        ` ${C.amber}⚡ ${tierLabel}${C.reset} v${C.bold}${ownVersion()}${C.reset} ${ramp(ctxPct)} ${C.bold}${pctStr}${C.reset} ${tokStr}/${maxStr} │ ${st.checkpointCount} chk${agentStr}${turnStr}`,
-        // L2 — status + dedup + session + all-time savings bars
-        `   ${triggerLabel} ${C.magenta}dup ${dedupStr}${C.reset} ${C.gray}sess${C.reset} ${ramp(sessPct)} ${C.green}${sTxt}%${C.reset} ${C.gray}all-time${C.reset} ${ramp(repoPct)} ${C.blue}${rTxt}%${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`,
       ];
       // Live "now processing" line + why + recent deduped/compacted events,
       // collapsed to ONE rotating line (fresh only). The ticker ring buffer
@@ -404,11 +412,8 @@ export class MegaRuntime {
       } else if (this.pulsing) {
         lines.push(`   ${pulse}${C.teal}compacting…${C.reset}`);
       }
-      // L4 — accounting: session + all-time in/out/freed, one compact line.
-      // in = dropped into compaction, out = kept summaries, freed = saved.
-      if (lines.length < 10) {
-        lines.push(`   ${C.dim}session ↑${fmt(sessIn)} in ↓${fmt(sessKept)} out ↓${fmt(sessFreed)} freed · all-time ↑${fmt(repoIn)} in ↓${fmt(repoKept)} out ↓${fmt(repoFreed)} freed${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.6",
+  "version": "0.6.9",
   "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/compact.ts

@@ -23,7 +23,11 @@ function truncate(s: string, max: number): string {
 }
 
 function firstText(m: EngineMessage): string | undefined {
-  const t = m.text.trim();
+  // PREVENT crash: pi can hand us a message with text: undefined (pure
+  // tool-call/tool-result). Guard the trim so the legacy summarizeMessages
+  // path can't throw the same undefined-text crash the extractive path did.
+  const raw = m.text ?? "";
+  const t = raw.trim();
   return t.length > 0 ? t : undefined;
 }
 

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/supersede.ts

@@ -12,12 +12,15 @@ import { extractFileCandidates } from "./compact.js";
 
 /** Classify a message's relationship to a file path. */
 function fileOps(msg: EngineMessage): { path: string; op: "read" | "write" }[] {
-  // msg.text may be undefined for pure tool-call/result messages; the guard
-  // lives in extractFileCandidates, but the early return short-circuits the
-  // write-detection regex too so we never classify an empty message.
-  const paths = extractFileCandidates(msg.text);
+  // PREVENT crash: msg.text may be undefined for pure tool-call/result
+  // messages. extractFileCandidates guards the split, but if it returned a
+  // hit we'd still call .toLowerCase() on the raw (possibly-undefined) text.
+  // Coerce once so both extractFileCandidates and the write-detection regex
+  // are safe, and the early return still skips empty messages.
+  const text = msg.text ?? "";
+  const paths = extractFileCandidates(text);
   if (paths.length === 0) return [];
-  const low = msg.text.toLowerCase();
+  const low = text.toLowerCase();
   const isWrite = /\b(write|edit|create|save|append|overwrite|update|patch|modify)\b/.test(low);
   return paths.map((p) => ({ path: p, op: isWrite ? "write" : "read" }));
 }

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 [];