pi-mega-compact 0.13.1 → 0.13.2

package/dist/extensions/dashboard-server/routes-raptor.js

@@ -0,0 +1,88 @@
+/**
+ * routes-raptor.ts — GET /api/raptor-tree route handler (Part B).
+ *
+ * Returns the hierarchical RAPTOR tree (summary nodes by level) for a session.
+ * When no sessionId is given, resolves to the most recent session that has
+ * raptor nodes. Reads only from the local SQLite store (PREVENT-PI-004 OK).
+ * Uses an inline require to the pi-agnostic src/store/sqlite/raptor.ts reader.
+ */
+import { createRequire } from "node:module";
+import { parse as parseUrl } from "node:url";
+import { openStore } from "../../src/store/sqlite.js";
+const _req = createRequire(import.meta.url);
+/** Find the most recent sessionId that has raptor nodes (else null). */
+function latestRaptorSession(stateDir) {
+    try {
+        const db = openStore(stateDir);
+        const row = db
+            .prepare("SELECT DISTINCT session_id FROM raptor_nodes ORDER BY built_at DESC LIMIT 1")
+            .get();
+        return row?.session_id ?? null;
+    }
+    catch {
+        // no raptor_nodes table yet (fresh DB) — treat as empty
+        return null;
+    }
+}
+function toDTO(node) {
+    return {
+        id: node.id,
+        sessionId: node.sessionId,
+        level: node.level,
+        parentId: node.parentId,
+        children: node.children,
+        summary: node.summary,
+        qualityMarker: node.qualityMarker,
+        tokenEstimate: node.tokenEstimate,
+        builtAt: node.builtAt,
+    };
+}
+function emptyResponse() {
+    return { nodes: [], levels: 0, rootId: null, builtAt: null, empty: true };
+}
+export function handleRaptorTree(req, res, ctx) {
+    if (req.method !== "GET")
+        return false;
+    const parsed = parseUrl(req.url ?? "", true);
+    if (parsed.pathname !== "/api/raptor-tree")
+        return false;
+    try {
+        const { listRaptorNodes } = _req("../../src/store/sqlite/raptor.js");
+        let sessionId = typeof parsed.query.sessionId === "string" ? parsed.query.sessionId : "";
+        if (!sessionId) {
+            sessionId = latestRaptorSession(ctx.stateDir) ?? "";
+            if (!sessionId) {
+                const body = emptyResponse();
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify(body));
+                return true;
+            }
+        }
+        const nodes = listRaptorNodes(sessionId, ctx.stateDir);
+        if (nodes.length === 0) {
+            const body = emptyResponse();
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(body));
+            return true;
+        }
+        const dtos = nodes.map(toDTO);
+        const levels = dtos.reduce((m, n) => Math.max(m, n.level), 0);
+        const root = dtos.find((n) => n.parentId === null);
+        const builtAt = dtos.reduce((m, n) => Math.max(m, n.builtAt), 0);
+        const body = {
+            nodes: dtos,
+            levels,
+            rootId: root?.id ?? null,
+            builtAt,
+            empty: false,
+        };
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(body));
+        return true;
+    }
+    catch (e) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: String(e) }));
+        return true;
+    }
+}

package/dist/extensions/dashboard-server/routes-setup.js

@@ -15,7 +15,7 @@ import { join } from "node:path";
 // ---------------------------------------------------------------------------
 // handleSetupStatus — "/api/setup-status"
 // ---------------------------------------------------------------------------
-function detectCurrentEmbedder() {
+export function detectCurrentEmbedder() {
     const url = process.env["MEGACOMPACT_EMBEDDING_URL"];
     const minilm = process.env["MEGACOMPACT_MINILM"];
     if (url && url.trim().length > 0)

package/dist/extensions/dashboard-server/routes.js

@@ -15,5 +15,7 @@ export { handleProviderCache } from "./routes-cache.js";
 export { handleMemoryStatus } from "./routes-memory.js";
 export { handleSetupStatus, handleSetupDetect, handleSetupConfigure } from "./routes-setup.js";
 export { handleMemoryMap } from "./routes-memory-map.js";
+export { handleRaptorTree } from "./routes-raptor.js";
 export { handleCacheStripes } from "./routes-cache.js";
 export { handleContextHealth, handleCachePoison, handleHealthSettings } from "./routes-health.js";
+export { handleEmbedderHealth } from "./routes-embedder-health.js";

package/dist/extensions/dashboard-server/server.js

@@ -12,7 +12,7 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { log, setLogPath, setDashboardServerVersion } from "./state.js";
-import { buildRouteContext, handleIndex, handleRepoIndex, handleEvents, handleGameState, handleGameScores, handlePerf, handleAchievements, handleSessions, handleTopics, handleTurns, handleMaintenance, handleProviderCache, handleCacheStripes, handleMemoryStatus, handleSetupStatus, handleSetupDetect, handleSetupConfigure, handleMemoryMap, handleContextHealth, handleCachePoison, handleHealthSettings, handleStatic, } from "./routes.js";
+import { buildRouteContext, handleIndex, handleRepoIndex, handleEvents, handleGameState, handleGameScores, handlePerf, handleAchievements, handleSessions, handleTopics, handleTurns, handleMaintenance, handleProviderCache, handleCacheStripes, handleMemoryStatus, handleSetupStatus, handleSetupDetect, handleSetupConfigure, handleMemoryMap, handleRaptorTree, handleContextHealth, handleCachePoison, handleHealthSettings, handleEmbedderHealth, handleStatic, } from "./routes.js";
 export async function launchDashboardServer(stateDir) {
     // Our own package version — exposed at /api/version so the launcher can
     // detect a stale server (started by an older build) and replace it on
@@ -207,12 +207,16 @@ export async function launchDashboardServer(stateDir) {
             return;
         if (handleMemoryMap(req, res, ctx))
             return;
+        if (handleRaptorTree(req, res, ctx))
+            return;
         if (handleContextHealth(req, res, ctx))
             return;
         if (handleCachePoison(req, res, ctx))
             return;
         if (handleHealthSettings(req, res, ctx))
             return;
+        if (handleEmbedderHealth(req, res, ctx))
+            return;
         handleStatic(req, res, ctx);
     });
     // Bind base + range are env-configurable so tests can use a private,

package/dist/extensions/mega-cache-replay.test/_helpers.js

@@ -0,0 +1,175 @@
+/**
+ * Shared helpers for the mega-cache-replay.test split files.
+ * Extracted from extensions/mega-cache-replay.test.ts: baseTmp, env, harness().
+ */
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createRequire } from "node:module";
+export const baseTmp = mkdtempSync(join(tmpdir(), "mc-cache-"));
+let counter = 0;
+export function setupEnv() {
+    process.env.MEGACOMPACT_INDEX_DIR = join(baseTmp, "index");
+    process.env.MEGACOMPACT_PGLITE_DISABLED = "true";
+}
+export function harness() {
+    const stateDir = join(baseTmp, `run-${counter++}`);
+    process.env.MEGACOMPACT_STATE_DIR = stateDir;
+    process.env.MEGACOMPACT_DEBUG = "true";
+    process.env.MEGACOMPACT_THRESHOLD_TOKENS = "50";
+    process.env.MEGACOMPACT_FAST_GATE_PCT = "1";
+    process.env.MEGACOMPACT_ANCHOR_USER_MESSAGES = "1";
+    process.env.MEGACOMPACT_DURABLE_TRIM_FLOOR = "0";
+    process.env.MEGACOMPACT_MEMORY_AUTO_REVIEW = "false";
+    process.env.MEGACOMPACT_RAPTOR_ENABLED = "false";
+    process.env.MEGACOMPACT_L1_ENABLED = "false";
+    process.env.MEGACOMPACT_L2_ENABLED = "false";
+    delete process.env.MEGACOMPACT_LEGACY_DURABLE_TRIM;
+    const usage = {
+        tokens: 200000,
+        contextWindow: 200000,
+        percent: 100,
+    };
+    const handlers = {};
+    const compactCalls = [];
+    function msg(role, text, toolName) {
+        if (role === "assistant" && toolName) {
+            return {
+                role: "assistant",
+                content: [
+                    { type: "toolCall", name: toolName, id: "c1", arguments: {} },
+                ],
+                api: "anthropic-messages",
+                provider: "anthropic",
+                model: "m",
+                usage: {
+                    inputTokens: 1,
+                    outputTokens: 1,
+                    cacheReadTokens: 0,
+                    cacheWriteTokens: 0,
+                },
+                stopReason: "tool_use",
+                timestamp: 0,
+            };
+        }
+        if (role === "toolResult" && toolName) {
+            return {
+                role: "toolResult",
+                content: [{ type: "text", text }],
+                toolCallId: "c1",
+                toolName,
+                isError: false,
+                timestamp: 0,
+            };
+        }
+        return {
+            role: "user",
+            content: text,
+            timestamp: 0,
+        };
+    }
+    function buildSession(tag, n) {
+        const s = [];
+        for (let i = 0; i < n; i++) {
+            s.push(msg("user", `[${tag}] we decided to use approach ${i} for module ${i}`));
+            s.push(msg("assistant", `[${tag}] edited module ${i}`, "Edit"));
+            s.push(msg("toolResult", `[${tag}] edited module ${i}`, "Edit"));
+        }
+        return s;
+    }
+    const toEntry = (m, i) => ({
+        type: "message",
+        id: `e${i}`,
+        parentId: null,
+        timestamp: String(i),
+        message: m,
+    });
+    const sessionManager = {
+        getSessionId: () => "sess_cache_001",
+        getEntries: () => buildSession("A", 14).map(toEntry),
+        getBranch: () => buildSession("A", 14).map(toEntry),
+    };
+    function makeCtx(over = {}) {
+        return {
+            ui: {
+                setStatus: () => { },
+                notify: () => { },
+                select: () => { },
+                confirm: async () => true,
+                input: async () => "",
+                setWidget: () => { },
+            },
+            mode: "tui",
+            hasUI: true,
+            cwd: stateDir,
+            sessionManager,
+            modelRegistry: {},
+            model: undefined,
+            isIdle: () => true,
+            isProjectTrusted: () => true,
+            signal: undefined,
+            abort: () => { },
+            hasPendingMessages: () => false,
+            shutdown: () => { },
+            getContextUsage: () => ({ ...usage }),
+            compact: (opts) => {
+                compactCalls.push(opts);
+                return undefined;
+            },
+            getSystemPrompt: () => "system base",
+            ...over,
+        };
+    }
+    const pi = {
+        on: (ev, h) => {
+            if (!handlers[ev])
+                handlers[ev] = [];
+            handlers[ev].push(h);
+        },
+        registerCommand: () => { },
+        registerTool: () => { },
+        registerShortcut: () => { },
+        registerFlag: () => { },
+        getFlag: () => undefined,
+        registerMessageRenderer: () => { },
+        registerEntryRenderer: () => { },
+        sendMessage: () => { },
+        sendUserMessage: () => { },
+        appendEntry: () => { },
+        setSessionName: () => { },
+        getSessionName: () => undefined,
+        setLabel: () => { },
+        exec: async () => ({ stdout: "", stderr: "", code: 0 }),
+        getActiveTools: () => [],
+        getAllTools: () => [],
+        setActiveTools: () => { },
+        getCommands: () => [],
+        setModel: async () => false,
+        getThinkingLevel: () => "off",
+        setThinkingLevel: () => { },
+    };
+    const require = createRequire(import.meta.url);
+    const mod = require("../mega-compact.js");
+    mod.default(pi);
+    const { lastRuntime } = require("../mega-events.js");
+    const fire = async (ev, event, ctx) => {
+        let r;
+        for (const h of handlers[ev] || [])
+            r = await h(event, ctx);
+        return r;
+    };
+    return {
+        stateDir,
+        handlers,
+        compactCalls,
+        fire,
+        ctx: makeCtx,
+        usage,
+        buildSession,
+        runtime: lastRuntime,
+        clearDebounce: () => {
+            if (lastRuntime)
+                lastRuntime.debounceUntil = 0;
+        },
+    };
+}

package/dist/extensions/mega-commands/dataCommands.js

@@ -0,0 +1,151 @@
+import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
+import { normalizeSessionId } from "../../src/store.js";
+import { latestModelSnapshot, countInjectedGlobal, listRepoRegistry } from "../../src/store/sqlite.js";
+import { loadMetrics, fpRate, p95, defaultMetricsPath } from "../../src/monitoring.js";
+import { C, recentUserQuery } from "../mega-runtime.js";
+import { runCompact, doRecall, doRecallAsync } from "../mega-pipeline.js";
+import { vectorStats, vectorRepoStats, vectorDataInvariant } from "../../src/vectorStore.js";
+/** Register the data/inspection commands (data group). */
+export function registerDataCommands(pi, runtime, config) {
+    pi.registerCommand("mega-compact", {
+        description: "Compress current session context into the local vector store.",
+        handler: async (args, ctx) => {
+            try {
+                const sessionEntries = ctx.sessionManager.getEntries();
+                // Project entries (branch-aware) into the message view.
+                const messages = sessionEntries.flatMap((e) => sessionEntryToContextMessages(e));
+                const summaryArg = args.trim();
+                const ran = runCompact(pi, runtime, config, ctx, messages, summaryArg ? { summary: summaryArg } : {});
+                if ("skipped" in ran && ran.skipped) {
+                    ctx.ui.notify("[mega-compact] Nothing to compact (session too small).");
+                    return;
+                }
+                const r = ran.result;
+                ctx.ui.notify(`[mega-compact] ${r.deduped ? "region already compacted (deduped)" : `persisted ${r.checkpointId}`} · ` +
+                    `${r.tokenEstimate} tok · ${runtime.currentStateDir}`);
+            }
+            catch (e) {
+                ctx.ui.notify(`[mega-compact] /mega-compact failed: ${String(e)}`);
+            }
+        },
+    });
+    pi.registerCommand("mega-recall", {
+        description: "Recall relevant compacted context from the vector store and inline it. Use --cross-repo to search all repos.",
+        handler: async (args, ctx) => {
+            try {
+                // S17: --cross-repo (or --cross repo) runs the async path over every repo's
+                // PGlite HNSW index (stricter cosine floor + source labels).
+                const crossRepo = /--cross[- ]repo\b/.test(args);
+                const query = args.replace(/--cross[- ]repo\b/, "").trim() || recentUserQuery(ctx);
+                if (!query) {
+                    ctx.ui.notify("[mega-compact] /mega-recall needs a query or a prior user message.");
+                    return;
+                }
+                const r = crossRepo
+                    ? await doRecallAsync(runtime, config, ctx, query, "command", { crossRepo: true })
+                    : doRecall(runtime, config, ctx, query, "command");
+                if (r.empty) {
+                    runtime.logger.info("recall-empty", { query, crossRepo });
+                    ctx.ui.notify(`[mega-compact] recall found nothing new for "${query}".`);
+                    return;
+                }
+                // Stage the block so the next before_agent_start prepends it (actual
+                // injection). Report what was selected now for immediate feedback.
+                runtime.pendingRecallBlock = r.block;
+                const list = r.report.map((l) => l).join("\n");
+                runtime.logger.info("recall", { query, crossRepo, injected: r.toInject.map((h) => h.checkpoint.checkpointId) });
+                runtime.setStatus(ctx, `mega-compact: recalled ${r.toInject.length} chkpt${crossRepo ? " (cross-repo)" : ""}`);
+                ctx.ui.notify(`[mega-compact] recall staged ${r.toInject.length} checkpoint(s) for "${query}"${crossRepo ? " (cross-repo)" : ""}:\n${list}\n` +
+                    `(injected at the tail of the next turn's context)`);
+            }
+            catch (e) {
+                ctx.ui.notify(`[mega-compact] /mega-recall failed: ${String(e)}`);
+            }
+        },
+    });
+    pi.registerCommand("mega-status", {
+        description: "Show mega-compact config, context usage, and the data-safety invariant.",
+        handler: async (_args, ctx) => {
+            try {
+                runtime.bindRepo(ctx.cwd);
+                const usage = ctx.getContextUsage();
+                const pct = usage?.percent != null ? `${usage.percent}%` : "n/a";
+                const tokens = usage?.tokens != null ? `${usage.tokens} tok` : "n/a";
+                const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
+                const st = vectorStats(runtime.store, sid);
+                const repo = vectorRepoStats(runtime.store);
+                const di = vectorDataInvariant(runtime.store);
+                const fmtB = (b) => b >= 1_048_576 ? `${(b / 1_048_576).toFixed(1)} MiB` :
+                    b >= 1024 ? `${(b / 1024).toFixed(1)} KiB` : `${b} B`;
+                // Real cost: tokens saved × the captured model's input rate (USD/token),
+                // read from the model_snapshots table (Phase 5b schema). Falls back to 0
+                // when no model has been captured yet. contextWindow ÷ savedRate = context
+                // windows extended (how much "extra" conversation the freed space buys).
+                const model = latestModelSnapshot(runtime.currentStateDir);
+                const rate = model?.inputRate ?? 0;
+                const usd = ((repo.tokensSaved ?? 0) * rate).toFixed(4);
+                const ctxWindow = usage?.contextWindow ?? 0;
+                const daysExtended = ctxWindow > 0 && repo.tokensSaved > 0
+                    ? (repo.tokensSaved / ctxWindow).toFixed(1)
+                    : "0";
+                // Identified model/provider (captured on model_select / session_start).
+                // Shows the human model name + provider so the user knows WHICH model's
+                // pricing drives the cost figure. Falls back when none captured yet.
+                const modelStr = model
+                    ? `${model.modelName ?? model.modelId ?? "?"} · ${model.providerName ?? model.provider ?? "?"}`
+                    : "unknown (no model captured)";
+                const costStr = `≈ $${usd} saved · ${daysExtended} context-windows extended`;
+                // Recall-quality badge (Phase 4): trust score from monitoring metrics.
+                // H1 fix: loadMetrics expects a *file* path (dashboard.json), not the
+                // state dir — passing the dir made existsSync() true (dirs exist) then
+                // readFileSync() threw EISDIR, silently caught → metrics always zero.
+                const m = loadMetrics(defaultMetricsPath(runtime.currentStateDir));
+                const fp = fpRate(m, "L2");
+                const p95L2 = p95(m.latency.L2 ?? []);
+                const relPct = (st.dedupHitRate * 100).toFixed(0);
+                const qualityStr = `recall ${relPct}% relevant · FP ${(fp * 100).toFixed(1)}% · L2 p95 ${p95L2.toFixed(0)}ms`;
+                // S18: cross-repo stats from the machine-wide index (best-effort; the
+                // index dir may be unset → 0/empty, never throws).
+                let crossRepoInjections = 0;
+                let repoCount = 0;
+                try {
+                    crossRepoInjections = countInjectedGlobal(process.env.MEGACOMPACT_INDEX_DIR);
+                    repoCount = listRepoRegistry(process.env.MEGACOMPACT_INDEX_DIR).length;
+                }
+                catch { /* non-fatal */ }
+                const crossRepoStr = `${crossRepoInjections} cross-repo injections recorded · ${repoCount} repos indexed`;
+                // Effective compaction threshold = tierPct × model context window (kept
+                // BELOW pi's native ~80% auto-compact for any model size). Falls back to
+                // the boot token value when the window is unknown (custom tier / pre-
+                // model-select). Display matches the dashboard's percentage-based view.
+                const effThreshold = config.tierPct != null && ctxWindow > 0
+                    ? Math.round(config.tierPct * ctxWindow)
+                    : config.thresholdTokens;
+                const winStr = ctxWindow > 0
+                    ? (ctxWindow >= 1_000_000 ? `${Math.round(ctxWindow / 1_000_000)}M` : `${Math.round(ctxWindow / 1_000)}k`)
+                    : "?";
+                const tierPctStr = config.tierPct != null ? `${Math.round(config.tierPct * 100)}%` : "n/a";
+                ctx.ui.notify(`[mega-compact] pct=${pct} tokens=${tokens} tier=${runtime.pressureBand} (live) preset=${config.tier} ` +
+                    `pressure=${Math.round(runtime.pressure * 100)}% fastGate=${config.fastGatePct}% ` +
+                    `threshold=${effThreshold.toLocaleString()} (${tierPctStr} of ${winStr} window) tierPct=${config.tierPct != null ? config.tierPct.toFixed(2) : "n/a"} auto=${config.auto} autoInline=${config.autoInline}\n` +
+                    `[mega-compact] store: ${st.checkpointCount} chkpt · ` +
+                    `${st.totalTokenEstimate} tok · last=${st.lastCheckpointId ?? "—"} · ` +
+                    `injected=${st.injectedCount} · dedup=${(st.dedupHitRate * 100).toFixed(0)}%\n` +
+                    `[mega-compact] anchor=${config.anchorUserMessages} preserveRecent=${config.preserveRecent} ` +
+                    `autoInlineK=${config.autoInlineK} dedupSim=${config.dedupSim} debug=${config.debug}\n` +
+                    `[mega-compact] 🛡 data-safe: ${di.regionsRetained} regions retained ` +
+                    `(${fmtB(di.compressedOriginalBytes)} compressed-original) · ` +
+                    `${di.duplicatesCollapsed} dedup-duplicates collapsed · ` +
+                    `${C.green}0 bytes permanently deleted${C.reset}\n` +
+                    `[mega-compact] 💰 ${costStr}\n` +
+                    `[mega-compact] 🤖 model: ${modelStr}\n` +
+                    `[mega-compact] 🎯 ${qualityStr}\n` +
+                    `[mega-compact] 🌐 ${crossRepoStr}\n` +
+                    `[mega-compact] stateDir=${runtime.currentStateDir}`);
+            }
+            catch (e) {
+                ctx.ui.notify(`[mega-compact] /mega-status error: ${String(e)}`);
+            }
+        },
+    });
+}

package/dist/extensions/mega-commands/helpers.js

@@ -0,0 +1,61 @@
+import { listCheckpoints } from "../../src/store/sqlite.js";
+import { defaultEventsPath } from "../../src/monitoring.js";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+/** Resolve a checkpoint by id (or "recent"/"last") from this session's store. */
+export function findCheckpoint(runtime, sid, ref) {
+    const all = listCheckpoints(sid, runtime.currentStateDir);
+    if (all.length === 0)
+        return undefined;
+    if (!ref || ref === "recent" || ref === "last")
+        return all[all.length - 1];
+    return all.find((c) => c.checkpointId === ref) ?? all.find((c) => c.checkpointId.endsWith(ref));
+}
+/**
+ * Try to peek at recent events.log and mega-compact.log for low recall quality signals.
+ * Best-effort, non-fatal — returns true if a low-quality signal was found.
+ */
+export function checkRecallQuality(stateDir) {
+    const eventPaths = [
+        defaultEventsPath(stateDir),
+        path.join(stateDir, "mega-compact.log"),
+    ];
+    for (const fp of eventPaths) {
+        try {
+            if (!existsSync(fp))
+                continue;
+            const buf = readFileSync(fp, { encoding: "utf-8" });
+            // Only scan last 64 KiB of the file
+            const tail = buf.length > 65536 ? buf.slice(buf.length - 65536) : buf;
+            const lines = tail.split("\n").filter(Boolean);
+            for (const line of lines) {
+                try {
+                    // guardrails-allow PREVENT-001: JSON.parse with null check
+                    const parsed = JSON.parse(line);
+                    if (typeof parsed !== "object" || parsed === null)
+                        continue;
+                    // Check for recall_metrics_low_quality event (latest format)
+                    if (parsed.event === "recall_metrics_low_quality" && parsed.score !== undefined) {
+                        if (typeof parsed.score === "number" && parsed.score < 0.4)
+                            return true;
+                    }
+                    // Check for recall_metrics with low relevanceScore
+                    if (parsed.event === "recall_metrics" && parsed.relevanceScore !== undefined) {
+                        if (typeof parsed.relevanceScore === "number" && parsed.relevanceScore < 0.4)
+                            return true;
+                    }
+                    // Check for RecallQualityEvent format from monitoring.ts
+                    if (parsed.score !== undefined && typeof parsed.score === "number" && parsed.score < 0.4)
+                        return true;
+                }
+                catch {
+                    // skip unparseable lines
+                }
+            }
+        }
+        catch {
+            // non-fatal: skip if can't read
+        }
+    }
+    return false;
+}

package/dist/extensions/mega-commands/historyCommands.js

@@ -0,0 +1,97 @@
+import { normalizeSessionId } from "../../src/store.js";
+import { listCheckpoints } from "../../src/store/sqlite.js";
+import { decompressSmart } from "../../src/store/compression.js";
+import { C } from "../mega-runtime.js";
+import { findCheckpoint } from "./helpers.js";
+/** Register the checkpoint history/inspection commands. */
+export function registerHistoryCommands(pi, runtime) {
+    pi.registerCommand("mega-restore", {
+        description: "Re-inject a checkpoint's verbatim original region into context. Usage: /mega-restore <chkpt|recent>",
+        handler: async (args, ctx) => {
+            try {
+                runtime.bindRepo(ctx.cwd);
+                const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
+                const cp = findCheckpoint(runtime, sid, args.trim());
+                if (!cp) {
+                    ctx.ui.notify(`[mega-compact] no checkpoint found${args.trim() ? ` for "${args.trim()}"` : ""} in this session. Try /mega-history.`);
+                    return;
+                }
+                if (!cp.compressedOriginal) {
+                    ctx.ui.notify(`[mega-compact] ${cp.checkpointId} has no recoverable original (pre-blob or direct add). Cannot restore verbatim.`);
+                    return;
+                }
+                const original = decompressSmart(cp.compressedOriginal).toString("utf-8");
+                // Re-inject verbatim via before_agent_start (PREVENT-PI-003) — never
+                // touches live messages, only prepends the restored region to systemPrompt.
+                runtime.pendingRecallBlock = `The following compacted context was RESTORED from checkpoint ${cp.checkpointId} (verbatim original region):\n\n${original}`;
+                const files = cp.filesModified?.length ? cp.filesModified.join(", ") : "(no files captured)";
+                ctx.ui.notify(`[mega-compact] ♻ restored ${cp.checkpointId} — ${original.length} chars re-injected on next turn.\n` +
+                    `[mega-compact] files: ${files}`);
+                runtime.dashboard.event("restore", { checkpointId: cp.checkpointId, chars: original.length });
+            }
+            catch (e) {
+                ctx.ui.notify(`[mega-compact] /mega-restore failed (checkpoint may be corrupt): ${String(e)}`);
+            }
+        },
+    });
+    pi.registerCommand("mega-history", {
+        description: "List this session's checkpoints (id, date, files, tokens). Usage: /mega-history",
+        handler: async (_args, ctx) => {
+            runtime.bindRepo(ctx.cwd);
+            const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
+            const all = listCheckpoints(sid, runtime.currentStateDir);
+            if (all.length === 0) {
+                ctx.ui.notify("[mega-compact] no checkpoints in this session yet.");
+                return;
+            }
+            const rows = all.map((c) => {
+                const when = c.timestamp ? new Date(c.timestamp).toISOString().slice(0, 16).replace("T", " ") : "—";
+                const files = c.filesModified?.length ? c.filesModified.map((f) => f.split("/").pop() ?? f).join(", ") : "—";
+                const orig = c.originalTokenEstimate ?? 0;
+                const stored = c.tokenEstimate ?? 0;
+                const saved = Math.max(0, orig - stored);
+                return `  ${c.checkpointId}  ${when}  ${C.cyan}${saved}t saved${C.reset}  ${files}`;
+            });
+            ctx.ui.notify(`[mega-compact] ${all.length} checkpoint(s) in this session:\n` + rows.join("\n") +
+                `\n[mega-compact] /mega-view <chkpt> to see the original region · /mega-restore <chkpt> to re-inject it`);
+        },
+    });
+    pi.registerCommand("mega-view", {
+        description: "Show a checkpoint's verbatim original region. Usage: /mega-view <chkpt|recent>",
+        handler: async (args, ctx) => {
+            try {
+                runtime.bindRepo(ctx.cwd);
+                const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
+                const cp = findCheckpoint(runtime, sid, args.trim());
+                if (!cp) {
+                    ctx.ui.notify(`[mega-compact] no checkpoint found${args.trim() ? ` for "${args.trim()}"` : ""}. Try /mega-history.`);
+                    return;
+                }
+                if (!cp.compressedOriginal) {
+                    ctx.ui.notify(`[mega-compact] ${cp.checkpointId} summary:\n${cp.summary.slice(0, 500)}${cp.summary.length > 500 ? "…" : ""}\n(no verbatim original stored)`);
+                    return;
+                }
+                const original = decompressSmart(cp.compressedOriginal).toString("utf-8");
+                ctx.ui.notify(`[mega-compact] ${cp.checkpointId} — original region (${original.length} chars):\n` +
+                    `${original.slice(0, 1500)}${original.length > 1500 ? "\n…(truncated)" : ""}`);
+            }
+            catch (e) {
+                ctx.ui.notify(`[mega-compact] /mega-view failed (checkpoint may be corrupt): ${String(e)}`);
+            }
+        },
+    });
+    pi.registerCommand("mega-help", {
+        description: "Plain-language glossary of what mega-compact's stats mean.",
+        handler: async (_args, ctx) => {
+            ctx.ui.notify(`[mega-compact] glossary — what the numbers mean:\n` +
+                `• token — a chunk of text (~4 chars). Context window = how much text fits in memory at once.\n` +
+                `• space freed — how much conversation we've compressed away to make room (the win).\n` +
+                `• memory held — how much compact summary we're currently keeping as your 'notes'.\n` +
+                `• saved checkpoint — a compact summary of an old conversation chunk we stored.\n` +
+                `• repeat-skipped — how often new text matched something we already had, so we didn't store a duplicate.\n` +
+                `• injected — times we pasted an old saved note back into the chat because it was relevant.\n` +
+                `• recall relevance — of those, how often the note was actually on-topic.\n` +
+                `• data safety — every compressed region is kept verbatim; nothing is permanently deleted. /mega-restore brings any of it back.`);
+        },
+    });
+}