pi-mega-compact 0.4.14 → 0.4.16

package/dist/extensions/mega-pipeline.js

@@ -0,0 +1,140 @@
+/**
+ * mega-pipeline.ts — the compaction + recall pipelines.
+ *
+ * `runCompact` runs the full Trident pipeline (fast-gate aside) and persists a
+ * checkpoint. `doRecall` is the unified Layer-5 recall entry point. Both mutate
+ * the shared MegaRuntime (token accounting, ticker, status, events) and are
+ * driven by the event + command handlers in mega-events.ts / mega-commands.ts.
+ */
+import { compactSession } from "../src/engine.js";
+import { recallAndInline } from "../src/recall.js";
+import { normalizeSessionId } from "../src/store.js";
+import { touchSession, logDaily } from "../src/store/sqlite.js";
+import { C, MARKER_TYPE, } from "./mega-runtime.js";
+import { resolveRepoRoot } from "./mega-config.js";
+/** Run the full compaction pipeline and persist a checkpoint. Returns the result. */
+export function runCompact(pi, runtime, config, ctx, messages, opts = {}) {
+    runtime.bindRepo(ctx.cwd);
+    const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
+    runtime.resetRuntime(sid);
+    runtime.rt.sessionId = sid;
+    const view = runtime.engineView(messages);
+    const keepFrom = opts.keepFrom ?? Math.max(0, view.length - config.preserveRecent);
+    if (keepFrom <= 0)
+        return { skipped: true };
+    runtime.pulsing = true; // animate the status line while the (sync) pipeline runs
+    const result = compactSession({
+        sessionId: sid,
+        messages: view,
+        keepFrom,
+        summary: opts.summary,
+        timestamp: Date.now(),
+        onTier: runtime.makeTierCallback(ctx),
+    }, runtime.store);
+    runtime.pulsing = false;
+    if (result.skipped)
+        return { skipped: true };
+    if (!result.deduped) {
+        runtime.rt.persistedThisSession = true;
+        runtime.rt.lastCheckpointId = result.checkpointId;
+    }
+    runtime.rt.lastCompactedFrom = result.compactedFrom;
+    runtime.rt.lastCompactedTokens = result.tokenEstimate;
+    runtime.rt.dedupAttempts++;
+    // Honest "tokens saved" for this session-instance only:
+    //   new checkpoint      → original − stored
+    //   deduped onto existing → whole original region (nothing new stored)
+    // Resets to 0 on session_start (rt is rebuilt) — so a fresh session shows 0
+    // while the repo's cumulative saved (SQLite meta) keeps the running total.
+    const saved = result.deduped
+        ? result.originalTokenEstimate
+        : Math.max(0, result.originalTokenEstimate - result.tokenEstimate);
+    runtime.rt.tokensSaved += saved;
+    if (result.deduped)
+        runtime.rt.dedupSkips++;
+    // Grow the rolling "saved" goal so the progress bar always has a fresh
+    // denominator (we don't want it pinned at 100% once we pass an old target).
+    if (runtime.rt.tokensSaved > runtime.savedGoal)
+        runtime.savedGoal = Math.ceil((runtime.rt.tokensSaved * 1.25) / 10_000) * 10_000;
+    // Live toolbar "now processing" line: what file/region just got compacted or
+    // deduped. Reset to the last-seen action after a few seconds (see snapshot).
+    const files = result.filesModified ?? [];
+    const fileLabel = files.length
+        ? files.map((f) => f.split("/").pop() ?? f).slice(0, 2).join(", ")
+        : result.regionHash.slice(0, 8);
+    runtime.currentActivity = result.deduped
+        ? `♻ deduped ${fileLabel}`
+        : `🗜 compacted ${result.checkpointId} · ${fileLabel}`;
+    runtime.lastActivityAt = Date.now();
+    // Explain-why line: surfaced while fresh. Pulls the dedup reason (which for
+    // L2 includes the cosine sim) so the user sees WHY a region was kept/dropped.
+    runtime.lastWhy = result.deduped
+        ? `why: deduped@${result.dedupReason ?? "tier"}`
+        : `why: compacted → ${result.checkpointId}`;
+    // Recall/activity ticker: record this event in the ring buffer.
+    const savedK = (saved / 1000).toFixed(1);
+    runtime.pushTicker(result.deduped
+        ? `${C.green}♻${C.reset} deduped ${fileLabel} · ${savedK}k saved`
+        : `${C.cyan}🗜${C.reset} ${result.checkpointId} · +${savedK}k · ${fileLabel}`);
+    // The per-tier trace has settled into the final outcome — fold it back into
+    // the activity line and stop showing the live trace.
+    runtime.tierTrace = undefined;
+    // Record session activity + a daily-log entry in the per-repo SQLite store
+    // (foundation for resume-sessions / daily-log features). Best-effort — never
+    // block a compaction on bookkeeping.
+    try {
+        const root = resolveRepoRoot(ctx.cwd);
+        touchSession(sid, root, runtime.currentStateDir);
+        logDaily(sid, "compact", result.checkpointId, saved, runtime.currentStateDir);
+    }
+    catch {
+        /* non-fatal: stats bookkeeping only */
+    }
+    // Sentinel marker: a non-LLM bookkeeping entry so subsequent triggers can
+    // skip re-vectorizing an already-compacted region (zero token cost).
+    pi.appendEntry(MARKER_TYPE, {
+        checkpointId: result.checkpointId,
+        regionHash: result.regionHash,
+        tokenEstimate: result.tokenEstimate,
+        deduped: result.deduped,
+    });
+    runtime.setStatus(ctx, runtime.rt.persistedThisSession
+        ? `mega-compact: ${result.checkpointId} · ${saved} tok saved`
+        : `mega-compact: ready`);
+    runtime.logger.info("compact", {
+        sessionId: sid,
+        checkpointId: result.checkpointId ?? "(deduped)",
+        deduped: result.deduped,
+        tokenEstimate: saved,
+        compactedFrom: result.compactedFrom,
+    });
+    runtime.dashboard.event("compact", {
+        sessionId: sid,
+        checkpointId: result.checkpointId ?? "(deduped)",
+        deduped: result.deduped,
+        tokenEstimate: saved,
+        compactedFrom: result.compactedFrom,
+    });
+    runtime.snapshot(ctx);
+    return { skipped: false, result, keepFrom, saved };
+}
+/**
+ * Unified recall (Layer 5). The ONE path that injects. Returns the recall
+ * result; callers decide whether to stage it for before_agent_start (resume)
+ * or report it (command).
+ */
+export function doRecall(runtime, config, ctx, query, source) {
+    runtime.bindRepo(ctx.cwd);
+    const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
+    const result = recallAndInline({ sessionId: sid, query, limit: config.autoInlineK, source, skipInjected: true }, runtime.store);
+    runtime.dashboard.event("recall", { source, query: query.slice(0, 120), injected: result.toInject.length, empty: result.empty });
+    if (!result.empty && result.toInject.length > 0) {
+        const top = result.toInject[0];
+        const scorePct = Math.round((top.score ?? 0) * 100);
+        const files = top.checkpoint.filesModified ?? [];
+        const label = files.length ? files.map((f) => f.split("/").pop() ?? f).slice(0, 2).join(", ") : top.checkpoint.checkpointId;
+        runtime.pushTicker(`${C.amber}↩${C.reset} recalled ${top.checkpoint.checkpointId} · ${scorePct}% · ${label}`);
+        runtime.lastWhy = `why: recalled@${scorePct}% (${result.toInject.length} chkpt)`;
+    }
+    return result;
+}

package/dist/extensions/mega-runtime.js

@@ -0,0 +1,370 @@
+/**
+ * mega-runtime.ts — the shared live state of the mega-compact extension.
+ *
+ * The original mega-compact.ts was a single large closure over ~20 mutable
+ * variables. This module lifts that state into a `MegaRuntime` class so the
+ * event/command/pipeline modules can share it without re-declaring it. All
+ * behavior (store/dashboard rebinding, dashboard snapshot shape, the
+ * above-editor widget math, model capture) is preserved byte-for-byte from the
+ * original closure.
+ */
+import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+import { VectorStore } from "../src/vectorStore.js";
+import { toEngineMessages } from "../src/adapt.js";
+import { normalizeSessionId } from "../src/store.js";
+import { Logger } from "../src/log.js";
+import { recordModelSnapshot } from "../src/store/sqlite.js";
+import { repoStateDir, resolveRepoRoot } from "./mega-config.js";
+import { Dashboard } from "./mega-dashboard.js";
+export const STATUS_KEY = "mega-compact";
+export const WIDGET_KEY = "mega-compact-stats";
+export const MARKER_TYPE = "mega-compact-marker";
+/** ANSI palette for the toolbar. The pi TUI's Text component preserves ANSI
+ *  escape codes (see wrapTextWithAnsi), so raw escapes render as colors. No
+ *  chalk dependency needed — these are just strings. */
+export const C = {
+    reset: "\x1b[0m",
+    dim: "\x1b[2m",
+    bold: "\x1b[1m",
+    amber: "\x1b[38;5;214m", // tier / ready
+    green: "\x1b[38;5;120m", // saved
+    cyan: "\x1b[38;5;51m", // used / live activity
+    teal: "\x1b[38;5;37m", // processing (compress/dedup)
+    magenta: "\x1b[38;5;201m", // dedup rate
+    blue: "\x1b[38;5;75m", // repo totals
+    gray: "\x1b[38;5;245m", // labels
+};
+const PULSE = ["◐", "◓", "◑", "◒"];
+export class MegaRuntime {
+    config;
+    // Store/dashboard/logger are rebound per-repo by bindRepo() so each git repo
+    // gets its own isolated state dir. They start bound to the global default.
+    store;
+    logger;
+    dashboard;
+    activeRepoRoot = null;
+    currentStateDir;
+    // The only mutable per-session state. Reset on session_start / session_tree.
+    rt = {
+        sessionId: normalizeSessionId(undefined),
+        persistedThisSession: false,
+        lastCheckpointId: undefined,
+        lastCompactedFrom: 0,
+        lastCompactedTokens: 0,
+        dedupSkips: 0,
+        dedupAttempts: 0,
+        tokensSaved: 0,
+    };
+    debounceUntil = 0;
+    // Agent tracking for real-time widget updates
+    activeAgents = 0;
+    currentTurn = 0;
+    // Recall block produced by auto-inline (resume/branch) that the next
+    // before_agent_start should prepend to the system prompt. Unset after use.
+    pendingRecallBlock;
+    statusKey; // current status text for dashboard
+    // Active model/provider (for real cost estimation). Captured from ctx.model
+    // on model_select + session_start; persisted to SQL so cost + the dashboard
+    // can read it without a live ctx.
+    currentModel;
+    // Live "what it's doing right now" line for the toolbar. Set on each
+    // compaction; shown in teal while recent, then kept as the last-seen action so
+    // the widget is never blank. Cleared on session reset.
+    currentActivity;
+    lastActivityAt = 0;
+    // Live per-tier dedup trace (Phase 1): e.g. "L0 ✓ → L1 ✓ → L2 0.91 → stored".
+    // Built from the store's sync onTier callback during a compaction so the user
+    // watches each tier evaluate in real time. Cleared once the outcome settles.
+    tierTrace;
+    // Phase 3 — standout toolbar state.
+    // Recall/activity ticker: a small ring buffer (≤5) of recent compact/recall
+    // events so the widget shows a live history instead of a single last action.
+    ticker = [];
+    TICKER_MAX = 5;
+    // Pulsing status: set true while a compaction is in flight, cleared on result.
+    pulsing = false;
+    // Rolling "saved" goal for the progress bar — grows as we save more, so the
+    // bar always has a meaningful denominator (never sits at 100% forever).
+    savedGoal = 50_000;
+    // Last explain-why line (dedup reason / anchor-kept / superseded), surfaced
+    // while fresh.
+    lastWhy = undefined;
+    // Context tracking for the dashboard (updated in the context handler).
+    lastCtxTokens = null;
+    lastCtxPercent = null;
+    lastCtxWindow = 0;
+    constructor(config) {
+        this.config = config;
+        this.store = new VectorStore({ dedupSim: config.dedupSim, stateDir: config.stateDir });
+        this.logger = new Logger({ enabled: config.debug, path: join(config.stateDir, "mega-compact.log") });
+        this.dashboard = new Dashboard(config.stateDir);
+        this.currentStateDir = config.stateDir;
+    }
+    // ---- per-repo binding -----------------------------------------------------
+    /**
+     * Point store/dashboard/logger at the current repo's state dir. Rebuilds the
+     * instances only when the repo root changes, so cross-repo dedup stats, db,
+     * and events are fully isolated. Falls back to the global default outside git.
+     */
+    bindRepo(cwd) {
+        const dir = cwd ? repoStateDir(cwd, this.config.stateDir) : this.config.stateDir;
+        const key = cwd ? resolveRepoRoot(cwd) ?? dir : dir;
+        if (key === this.activeRepoRoot)
+            return dir;
+        this.activeRepoRoot = key;
+        this.currentStateDir = dir;
+        this.store = new VectorStore({ dedupSim: this.config.dedupSim, stateDir: dir });
+        this.logger = new Logger({ enabled: this.config.debug, path: join(dir, "mega-compact.log") });
+        this.dashboard = new Dashboard(dir);
+        return dir;
+    }
+    // ---- dashboard snapshot + widget ------------------------------------------
+    /** Collect live state and write it to disk (+ paint the above-editor widget). */
+    snapshot(ctx) {
+        if (ctx)
+            this.bindRepo(ctx.cwd);
+        const st = this.store.stats(this.rt.sessionId);
+        const repo = this.store.repoStats();
+        const di = this.store.dataInvariant();
+        const armed = this.lastCtxPercent != null && this.lastCtxPercent >= this.config.fastGatePct;
+        const ready = armed && (this.lastCtxTokens ?? 0) >= this.config.thresholdTokens;
+        this.dashboard.snapshot({
+            version: 1,
+            updatedAt: new Date().toISOString(),
+            tier: this.config.tier,
+            config: {
+                fastGatePct: this.config.fastGatePct,
+                thresholdTokens: this.config.thresholdTokens,
+                anchorUserMessages: this.config.anchorUserMessages,
+                preserveRecent: this.config.preserveRecent,
+                auto: this.config.auto,
+                autoInline: this.config.autoInline,
+            },
+            session: {
+                id: this.rt.sessionId,
+                state: this.statusKey ?? "idle",
+                persistedThisSession: this.rt.persistedThisSession,
+                lastCheckpointId: this.rt.lastCheckpointId ?? null,
+                lastCompactedFrom: this.rt.lastCompactedFrom,
+                lastCompactedTokens: this.rt.lastCompactedTokens,
+                dedupSkips: this.rt.dedupSkips,
+                dedupAttempts: this.rt.dedupAttempts,
+            },
+            context: { tokens: this.lastCtxTokens, percent: this.lastCtxPercent, contextWindow: this.lastCtxWindow },
+            trigger: { armed, ready, currentTokens: this.lastCtxTokens, thresholdTokens: this.config.thresholdTokens, fastGatePct: this.config.fastGatePct },
+            crew: { activeAgents: this.activeAgents, currentTurn: this.currentTurn },
+            store: { checkpointCount: st.checkpointCount, totalTokenEstimate: st.totalTokenEstimate, originalTokens: st.originalTokens, tokensSaved: this.rt.tokensSaved, injectedCount: st.injectedCount, dedupHitRate: st.dedupHitRate, storageDedupRate: st.storageDedupRate, dedupAttempts: st.dedupAttempts, dedupCollapsed: st.dedupCollapsed },
+            repo: {
+                checkpointCount: repo.checkpointCount,
+                totalTokenEstimate: repo.totalTokenEstimate,
+                originalTokens: repo.originalTokens,
+                tokensSaved: repo.tokensSaved,
+                sessionCount: repo.sessionCount,
+                dedupAttempts: repo.dedupAttempts,
+                dedupCollapsed: repo.dedupCollapsed,
+                storageDedupRate: repo.storageDedupRate,
+            },
+            integrity: {
+                regionsRetained: di.regionsRetained,
+                compressedOriginalBytes: di.compressedOriginalBytes,
+                duplicatesCollapsed: di.duplicatesCollapsed,
+                bytesPermanentlyDeleted: di.bytesPermanentlyDeleted,
+            },
+        });
+        // Live stats widget above the editor
+        if (ctx) {
+            const tokStr = this.lastCtxTokens != null ? `${Math.round(this.lastCtxTokens / 1000)}k` : "?";
+            const maxStr = this.lastCtxWindow > 0 ? `${Math.round(this.lastCtxWindow / 1000)}k` : "?";
+            const pctStr = this.lastCtxPercent != null ? `${Math.round(this.lastCtxPercent * 10) / 10}%` : "?%";
+            const triggerLabel = ready ? `${C.green}● ready${C.reset}` : armed ? `${C.amber}◐ armed${C.reset}` : `${C.gray}○ idle${C.reset}`;
+            // Storage dedup rate is cumulative (store-wide, per-repo) and survives
+            // session resets. Always show a number: 0% before any compaction, a
+            // decimal for sub-10% rates so small-but-real dedup isn't rounded away.
+            const storageRate = st.storageDedupRate; // 0..1
+            const dedupStr = storageRate * 100 >= 10
+                ? `${Math.round(storageRate * 100)}%`
+                : `${(storageRate * 100).toFixed(1)}%`;
+            // saved = tokens removed from context (cumulative original − stored).
+            // Show BOTH this-session (rt.tokensSaved) and repo-wide-total
+            // (repo.tokensSaved) so the user sees per-session progress vs the running
+            // repo total. "used" = stored checkpoint tokens (repo.totalTokenEstimate
+            // vs st.totalTokenEstimate). Use "k" only at/above 1000 so small-but-real
+            // numbers stay visible (previously Math.round(x/1000) zeroed <1000).
+            const fmt = (x) => (x >= 1000 ? `${(x / 1000).toFixed(1)}k` : `${x}`);
+            const savedStr = `${C.green}${fmt(this.rt.tokensSaved)} sess${C.reset} / ${C.blue}${fmt(repo.tokensSaved)} repo${C.reset}`;
+            const usedStr = `${C.cyan}${fmt(st.totalTokenEstimate)} sess${C.reset} / ${C.blue}${fmt(repo.totalTokenEstimate)} repo${C.reset}`;
+            const agentStr = this.activeAgents > 0 ? ` │ 🤖 ${this.activeAgents} agent${this.activeAgents === 1 ? "" : "s"}` : "";
+            const turnStr = this.currentTurn > 0 ? ` │ turn ${this.currentTurn}` : "";
+            // Phase 3 — pulsing status glyph while a compaction is in flight.
+            const pulse = this.pulsing ? `${C.cyan}${PULSE[Math.floor(Date.now() / 250) % PULSE.length]}${C.reset} ` : "";
+            const lines = [
+                ` ${C.amber}⚡ ${this.config.tier}${C.reset} │ ${tokStr}/${maxStr} tokens (${C.bold}${pctStr}${C.reset}) │ ${st.checkpointCount} saved${agentStr}${turnStr}`,
+                `   ${triggerLabel} │ ${C.magenta}repeat-skipped: ${dedupStr}${C.reset} │ ${C.gray}memory held:${C.reset} ${usedStr} │ ${C.gray}space freed:${C.reset} ${savedStr}`,
+            ];
+            // Phase 3 — compact progress bar: session tokens saved toward the rolling goal.
+            if (this.rt.tokensSaved > 0) {
+                const goal = Math.max(this.savedGoal, 1);
+                const pct = Math.min(100, Math.round((this.rt.tokensSaved / goal) * 100));
+                const filled = Math.round((pct / 100) * 10);
+                const bar = "▓".repeat(filled) + "░".repeat(10 - filled);
+                lines.push(`   ${C.green}saved ${fmt(this.rt.tokensSaved)} ${bar}${C.reset} ${pct}% of ${fmt(goal)}`);
+            }
+            // Live "now processing" line — teal while fresh (≤4s), then the last-seen
+            // action keeps the widget lively. Cleared on session reset.
+            const fresh = Date.now() - this.lastActivityAt < 4000;
+            if (this.tierTrace && fresh) {
+                lines.push(`   ${pulse}${this.tierTrace}`);
+            }
+            else if (this.currentActivity) {
+                lines.push(`   ${fresh ? C.teal : C.dim}${this.currentActivity}${C.reset}`);
+            }
+            else if (this.pulsing) {
+                lines.push(`   ${pulse}${C.teal}compacting…${C.reset}`);
+            }
+            // Phase 3 — explain-why line (fresh only).
+            if (this.lastWhy && fresh)
+                lines.push(`   ${C.gray}${this.lastWhy}${C.reset}`);
+            // Phase 3 — recall/activity ticker (most-recent first), fresh only.
+            if (fresh) {
+                for (let i = this.ticker.length - 1; i >= 0; i--) {
+                    if (lines.length >= 9)
+                        break; // leave room for the hint line (MAX 10)
+                    lines.push(`   ${i === this.ticker.length - 1 ? "" : C.dim}${this.ticker[i].text}${C.reset}`);
+                }
+            }
+            // Plain-language hint so first-time users understand the widget. Always
+            // last, dimmed. "/mega-help explains these terms."
+            if (lines.length < 10) {
+                lines.push(`   ${C.dim}auto-compresses old context to free space · nothing deleted · /mega-help${C.reset}`);
+            }
+            ctx.ui.setWidget(WIDGET_KEY, lines, { placement: "aboveEditor" });
+        }
+    }
+    setStatus(ctx, text) {
+        this.statusKey = text;
+        ctx.ui.setStatus(STATUS_KEY, text);
+    }
+    resetRuntime(sessionId) {
+        const sid = normalizeSessionId(sessionId);
+        if (this.rt.sessionId === sid && this.rt.persistedThisSession)
+            return; // same session, keep checkpoint memory
+        this.rt = {
+            sessionId: sid,
+            persistedThisSession: false,
+            lastCheckpointId: undefined,
+            lastCompactedFrom: 0,
+            lastCompactedTokens: 0,
+            dedupSkips: 0,
+            dedupAttempts: 0,
+            tokensSaved: 0,
+        };
+        this.statusKey = undefined;
+        this.activeAgents = 0;
+        this.currentTurn = 0;
+        this.currentActivity = undefined;
+        this.lastActivityAt = 0;
+        this.tierTrace = undefined;
+        this.ticker.length = 0;
+        this.pulsing = false;
+        this.savedGoal = 50_000;
+        this.lastWhy = undefined;
+    }
+    /**
+     * Capture the active model/provider from ctx.model and persist it so cost
+     * estimation + the dashboard can read real pricing. Cheap + idempotent-ish:
+     * only writes a new row when the model id changes (models change rarely).
+     */
+    captureModel(ctx) {
+        const m = ctx.model;
+        if (!m)
+            return;
+        if (this.currentModel && this.currentModel.modelId === m.id && this.currentModel.provider === m.provider)
+            return;
+        let providerName = null;
+        try {
+            providerName = ctx.modelRegistry?.getProviderDisplayName(m.provider) ?? null;
+        }
+        catch { /* optional */ }
+        const snap = {
+            provider: m.provider,
+            providerName,
+            modelId: m.id,
+            modelName: m.name ?? null,
+            inputRate: m.cost?.input ?? 0,
+            outputRate: m.cost?.output ?? 0,
+            contextWindow: m.contextWindow ?? 0,
+            maxTokens: m.maxTokens ?? 0,
+            reasoning: !!m.reasoning,
+        };
+        this.currentModel = { ...snap, capturedAt: Date.now() };
+        try {
+            const repo = resolveRepoRoot(ctx.cwd) ?? this.currentStateDir;
+            recordModelSnapshot(repo, snap, this.currentStateDir);
+        }
+        catch { /* non-fatal: cost estimation degrades to model-in-memory only */ }
+    }
+    /** Build the sync onTier callback that paints the live per-tier trace. */
+    makeTierCallback(ctx) {
+        const order = ["L0", "L1", "L2", "new"];
+        const seen = new Map();
+        const glyph = (status) => status === "deduped" ? `${C.green}✓${C.reset}` :
+            status === "passed" ? `${C.dim}○${C.reset}` :
+                status === "scanning" ? `${C.amber}…${C.reset}` :
+                    `${C.cyan}●${C.reset}`;
+        return (ev) => {
+            const label = ev.tier === "new"
+                ? `${C.cyan}stored${C.reset}`
+                : `${ev.tier} ${glyph(ev.status)}` +
+                    (ev.detail ? ` ${C.gray}(${ev.detail})${C.reset}` : "");
+            // Show the most recent outcome per tier (collapses re-fires).
+            seen.set(ev.tier, label);
+            const show = [];
+            for (const t of order)
+                if (seen.has(t))
+                    show.push(seen.get(t));
+            this.tierTrace = `${C.teal}⚙${C.reset} ${show.join(` ${C.gray}→${C.reset} `)}`;
+            this.lastActivityAt = Date.now();
+            try {
+                this.snapshot(ctx);
+            }
+            catch { /* non-fatal */ }
+        };
+    }
+    // Phase 3 — recall/activity ticker ring buffer.
+    pushTicker(text) {
+        this.ticker.push({ text, at: Date.now() });
+        while (this.ticker.length > this.TICKER_MAX)
+            this.ticker.shift();
+        this.lastActivityAt = Date.now();
+    }
+    /** Convert the messages pi hands us in the `context` event into the engine view. */
+    engineView(messages) {
+        return toEngineMessages(messages);
+    }
+}
+/**
+ * Latest user message text — used as the auto-inline recall query.
+ * Kept as a free function (not instance state) since it only reads ctx.
+ */
+export function recentUserQuery(ctx) {
+    try {
+        const entries = ctx.sessionManager.getEntries();
+        for (let i = entries.length - 1; i >= 0; i--) {
+            const msgs = sessionEntryToContextMessages(entries[i]);
+            for (let j = msgs.length - 1; j >= 0; j--) {
+                if (msgs[j].role === "user") {
+                    const c = msgs[j].content;
+                    if (typeof c === "string")
+                        return c;
+                    if (Array.isArray(c))
+                        return c.map((b) => b.text).join(" ");
+                }
+            }
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+    return "";
+}

package/dist/src/store/sqlite.js

@@ -170,6 +170,24 @@ function initSchema(db) {
     );
     CREATE INDEX IF NOT EXISTS idx_daily_log_day ON daily_log(day);
 
+    -- Active model/provider for cost estimation + the future multi-repo
+    -- dashboard (Phase 5b). One row per (repo, model change); latest wins.
+    CREATE TABLE IF NOT EXISTS model_snapshots (
+      id            INTEGER PRIMARY KEY AUTOINCREMENT,
+      repo_root     TEXT NOT NULL,
+      provider      TEXT NOT NULL,
+      provider_name TEXT,
+      model_id      TEXT NOT NULL,
+      model_name    TEXT,
+      input_rate    REAL,          -- USD per input token (Model.cost.input)
+      output_rate   REAL,          -- USD per output token (Model.cost.output)
+      context_window INTEGER,
+      max_tokens    INTEGER,
+      reasoning     INTEGER DEFAULT 0,
+      captured_at   INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_model_repo ON model_snapshots(repo_root);
+
     -- Lessons learned (future recall/browse feature seed).
     CREATE TABLE IF NOT EXISTS lessons (
       id            INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -535,6 +553,48 @@ export function repoStats(stateDir = getStateDir()) {
         storageDedupRate: ds.attempts === 0 ? 0 : ds.deduped / ds.attempts,
     };
 }
+/** Persist the active model/provider for a repo (latest row wins per repo). */
+export function recordModelSnapshot(repoRoot, snap, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    db.prepare(`INSERT INTO model_snapshots
+       (repo_root, provider, provider_name, model_id, model_name, input_rate,
+        output_rate, context_window, max_tokens, reasoning, captured_at)
+     VALUES (@repo_root, @provider, @provider_name, @model_id, @model_name,
+             @input_rate, @output_rate, @context_window, @max_tokens, @reasoning, @captured_at)`).run({
+        repo_root: repoRoot,
+        provider: snap.provider,
+        provider_name: snap.providerName,
+        model_id: snap.modelId,
+        model_name: snap.modelName,
+        input_rate: snap.inputRate,
+        output_rate: snap.outputRate,
+        context_window: snap.contextWindow,
+        max_tokens: snap.maxTokens,
+        reasoning: snap.reasoning ? 1 : 0,
+        captured_at: Date.now(),
+    });
+}
+/** Most recent model/provider snapshot for a repo, or undefined. */
+export function latestModelSnapshot(stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const row = db
+        .prepare(`SELECT * FROM model_snapshots ORDER BY captured_at DESC LIMIT 1`)
+        .get();
+    if (!row)
+        return undefined;
+    return {
+        provider: row.provider,
+        providerName: row.provider_name,
+        modelId: row.model_id,
+        modelName: row.model_name,
+        inputRate: row.input_rate,
+        outputRate: row.output_rate,
+        contextWindow: row.context_window,
+        maxTokens: row.max_tokens,
+        reasoning: row.reasoning === 1,
+        capturedAt: row.captured_at,
+    };
+}
 /** Close and evict a cached connection (test teardown only). */
 export function closeStore(stateDir) {
     const db = cache.get(stateDir);

package/extensions/dashboard-server.ts

@@ -133,6 +133,15 @@ function dashboardHtml(tierName: string): string {
   .card.safe h2 { color: #3fb950; }
   .safe-note { font-size: 12px; color: #8b949e; margin: 12px 0 0; line-height: 1.5; }
   .value.ok { color: #3fb950; }
+  .label {
+    cursor: help;
+    border-bottom: 1px dotted #484f58;
+  }
+  .card.legend { grid-column: 1 / -1; }
+  .legend-list { margin: 0; padding-left: 18px; color: #c9d1d9; }
+  .legend-list li { margin-bottom: 8px; line-height: 1.5; }
+  .legend-list b { color: #f0f6fc; }
+  .legend-note { font-size: 12px; color: #8b949e; margin: 12px 0 0; font-style: italic; }
   .card h2 { font-size: 12px; text-transform: uppercase; letter-spacing: .5px; color: #8b949e; margin-bottom: 12px; font-weight: 600; }
   .meter-track { background: #21262d; border-radius: 4px; height: 20px; overflow: hidden; margin: 8px 0; }
   .meter-fill { height: 100%; border-radius: 4px; transition: width .6s ease; min-width: 2px; }
@@ -190,15 +199,15 @@ function dashboardHtml(tierName: string): string {
   <div class="card">
     <h2>Vector Store</h2>
     <div class="stat-grid">
-      <span class="label">Checkpoints</span><span class="value" id="st-count">0</span>
-      <span class="label">Tokens Stored</span><span class="value" id="st-tokens">0</span>
-      <span class="label">Original Tokens</span><span class="value" id="st-orig">0</span>
-      <span class="label">Tokens Saved</span><span class="value" id="st-saved">0</span>
-      <span class="label">Injected</span><span class="value" id="st-injected">0</span>
-      <span class="label">Dedup Rate</span><span class="value" id="st-dedup">0%</span>
-      <span class="label">Storage Dedup</span><span class="value" id="st-sdedup">0%</span>
-      <span class="label">Collapsed</span><span class="value" id="st-collapsed">0</span>
-      <span class="label">Last ID</span><span class="value" id="st-lastid">—</span>
+      <span class="label" title="A saved summary of a chunk of your conversation that was compacted to free up space.">Checkpoints</span><span class="value" id="st-count">0</span>
+      <span class="label" title="How much conversation we are currently holding as compact summaries (the 'memory' this extension keeps). Smaller is better.">Tokens Stored</span><span class="value" id="st-tokens">0</span>
+      <span class="label" title="Total size of the original conversation text before it was compacted.">Original Tokens</span><span class="value" id="st-orig">0</span>
+      <span class="label" title="How much conversation space we have freed up for you (original size minus the compact summary we kept).">Tokens Saved</span><span class="value" id="st-saved">0</span>
+      <span class="label" title="How many times old context was automatically brought back into the conversation because it was relevant to what you were doing.">Injected</span><span class="value" id="st-injected">0</span>
+      <span class="label" title="Of the times we recalled old context, how often it was actually on-topic.">Recall Relevance</span><span class="value" id="st-dedup">0%</span>
+      <span class="label" title="How often new content matched something we already had, so we skipped storing a duplicate copy. Higher = less wasted space.">Storage Dedup</span><span class="value" id="st-sdedup">0%</span>
+      <span class="label" title="How many duplicate chunks we collapsed into one instead of storing separately.">Collapsed</span><span class="value" id="st-collapsed">0</span>
+      <span class="label" title="The ID of the most recent saved checkpoint.">Last ID</span><span class="value" id="st-lastid">—</span>
     </div>
   </div>
   <div class="card">
@@ -241,6 +250,18 @@ function dashboardHtml(tierName: string): string {
       <span class="label">Status</span><span class="value" id="cr-status">idle</span>
     </div>
   </div>
+  <div class="card legend">
+    <h2>What these numbers mean</h2>
+    <ul class="legend-list">
+      <li><b>Tokens saved</b> — conversation space this extension has freed up for you (it compacted old text into short summaries).</li>
+      <li><b>Tokens stored</b> — how much "memory" (compact summaries) the extension is currently holding for this repo.</li>
+      <li><b>Injected</b> — times old context was automatically pasted back in because it was relevant to your current task.</li>
+      <li><b>Recall relevance</b> — of those, how often the recalled context was actually on-topic.</li>
+      <li><b>Storage dedup</b> — how often new content matched something already saved, so a duplicate copy was skipped (saves space).</li>
+      <li><b>Data safety</b> — every compacted region is kept verbatim (compressed). Nothing is permanently deleted; you can restore any of it.</li>
+    </ul>
+    <p class="legend-note">Hover any label above for a quick explanation.</p>
+  </div>
 </div>
 
 <div class="events">