pi-mega-compact 0.5.0 → 0.5.2

package/README.md

@@ -6,10 +6,13 @@ sessions into a **local SQLite store** and offers **deduped inline recall** —
 running **locally inside the extension**, with **no remote MCP server** and
 **zero network calls at runtime** (PREVENT-PI-004).
 
-> **v0.2.0** — storage backend is now **`better-sqlite3`** (a single,
-> in-process, FS-backed SQLite database) replacing the old per-session gzipped
-> JSON checkpoint files. The legacy `.checkpoints.json.gz` snapshots are
-> retained as disaster-recovery fallbacks and auto-imported on first run.
+> **Current version:** `v0.5.1` — storage backend is **`node:sqlite`**
+> (`DatabaseSync`, a Node ≥22.13 built-in), replacing the old `better-sqlite3`
+> native addon and the per-session gzipped JSON checkpoint files. **Zero native
+> build step, fully local, zero network at runtime.** Legacy
+> `.checkpoints.json.gz` snapshots are retained as disaster-recovery fallbacks
+> and auto-imported on first run. Cross-repo recall, durable memory, and a
+> localhost dashboard round out the continuity story.
 
 ---
 
@@ -110,9 +113,9 @@ OpenAI-style contract and the `MEGACOMPACT_EMBEDDING_KEY` / `MEGACOMPACT_EMBEDDI
 
 ### Requirements
 
-- **Node >= 18**
-- install builds the **`better-sqlite3`** native module (one-time, local
-  compile). No network call and no API key are needed at runtime.
+- **Node >= 22.13** (the synchronous `node:sqlite` backend requires it; see
+  `engines.node`). No native module is compiled — the store is a Node built-in.
+- No network call and no API key are needed at runtime (PREVENT-PI-004).
 - A pi coding agent install with package support (`pi install` / `pi update
   --extensions`). npm-installed packages are auto-discovered via the package's
   `pi` manifest entry; local checkouts load from `~/.pi/agent/extensions/`.
@@ -135,8 +138,10 @@ source (which pi loads directly) and the compiled `dist/`, so nothing else needs
 building.
 
 > **Tip — keep the spec unpinned.** Use `npm:pi-mega-compact`, not
-> `npm:pi-mega-compact@0.4.11`. Version-pinned specs are *skipped* by
-> `pi update --extensions`, so a pin would freeze you on that release.
+> `npm:pi-mega-compact@0.5.1`. Version-pinned specs are *skipped* by
+> `pi update --extensions`, so a pin would freeze you on that release. The
+> installed version is always visible in the toolbar widget (`⚡ <tier> vX.Y.Z`)
+> and via `/mega-status`.
 
 > **From a git checkout (development only).** To hack on the extension, clone and
 > build locally, then symlink it into pi's extensions dir — but this bypasses the
@@ -158,7 +163,7 @@ building.
 > `pi update --extensions` on the device. (`.gitignore` rejects `*.tgz` so one can't
 > be committed by accident.)
 
-### Storage backend (v0.5.0+)
+### Storage
 
 pi-mega-compact uses a dual local backend — **zero network, no native build step**:
 
@@ -167,22 +172,14 @@ pi-mega-compact uses a dual local backend — **zero network, no native build st
 
 Kill-switch: `MEGACOMPACT_PGLITE_DISABLED=1` fully disables the PGlite index (falls back to sync scan). Requires Node ≥22.13 (`engines.node`).
 
-### Cross-repo recall (v0.5.0+)
+### Cross-repo recall
 
 On resume, recall augments from other repos' checkpoints when this repo's store is thin; `/mega-recall --cross-repo` searches all repos via the HNSW index. Cross-repo hits use a stricter cosine floor (`MEGACOMPACT_CROSSREPO_COSINE`, default 0.90) and are labeled with their source repo. A machine-wide injected-set (`~/.mega-compact-index/index.sqlite`) prevents re-injecting the same foreign checkpoint.
 
-### Memory (v0.5.0+)
+### Memory
 
 pi-mega-compact auto-reviews the conversation every 10 turns and writes durable `decision`/`fact`/`preference` memories to SQLite (local, hallucination-guarded). Relevant memories are injected as RAG context on recall (capped, deduped). Manual: `/mega-memory save|list|forget`.
 
-### Verify
-
-```bash
-npm test          # all unit/integration tests pass (346 as of v0.5.0)
-npm run lint      # tsc --noEmit + guardrails scan clean
-python3 scripts/regression_check.py --all   # spec/plan regression gate
-```
-
 ### Uninstall
 
 ```bash
@@ -211,11 +208,16 @@ The commands (slash commands inside pi):
 |---|---|
 | `/mega-compact [summary...]` | Manually compact the current session. A summary arg is used verbatim; otherwise the COLLAPSE heuristics build one. Persists a `chkpt_xxx`. |
 | `/mega-compact off` | Disable auto-compaction for this session. |
-| `/mega-status` | Show config + current context usage + store stats (checkpoint count, dedup rate, tokens saved). |
+| `/mega-status` | Show config + current context usage + store stats (checkpoint count, dedup rate, tokens saved) + the **installed version**. |
 | `/mega-recall [query]` | Semantic-search the local store, dedupe against the current window, and inline the top-K relevant checkpoints. No query → uses your latest message. `--cross-repo` searches all repos. |
 | `/mega-memory save <text>` / `save <category> <text>` / `list` / `search <query>` / `forget <text>` / `consolidate` | Manage durable memories (decisions, facts, preferences) written by auto-review and recalled as RAG context. Also `/m` shortform. |
+| `/mega-restore <chkpt\|recent>` | Re-inject a checkpoint's verbatim original region into context. |
+| `/mega-history` | List this session's checkpoints (id, date, files, tokens). |
+| `/mega-view <chkpt\|recent>` | Show a checkpoint's verbatim original region. |
+| `/mega-help` | Explain the toolbar widget terms (tier, gate, dedup, tokens saved). |
 | `/mega-tier [name]` | Set the compaction tier (`low` / `medium` / `high` / `ultra` / `mega`). Shows current tier with no arg. |
-| `/mega-dashboard` | Start the **localhost-only** live dashboard and open it in a browser (token gauge, store stats, live event stream). |
+| `/mega-compat-check` | Detect extension conflicts (duplicate commands / overlapping handlers) across installed pi extensions. |
+| `/mega-dashboard` | Start the **localhost-only** live dashboard and open it in a browser (token gauge, store stats, live event stream, per-repo + cross-repo drift). |
 | `/mega-dashboard-status` | Report dashboard server status. |
 | `/mega-dashboard-stop` | Stop the dashboard server. |
 
@@ -224,10 +226,13 @@ The commands (slash commands inside pi):
 Above the pi editor the extension shows a compact widget:
 
 ```
- ⚡ medium │ 142k/200k tokens (71%) │ 3 chkpts │ 🤖 2 agents │ turn 5
+ ⚡ medium v0.5.1 │ 142k/200k tokens (71%) │ 3 chkpts │ 🤖 2 agents │ turn 5
    ◐ armed │ dedup: 92% │ saved: 45k tok
 ```
 
+- **Version** — the installed npm version (read from `package.json` at runtime),
+  so the widget always reflects what `pi update --extensions` last pulled. If
+  this looks stale after an update, restart the dashboard server / pi session.
 - **Tier** — active compaction tier (low/medium/high/ultra/mega)
 - **Token usage** — current / max context window and %
 - **Checkpoints** — persisted checkpoints for the session
@@ -255,10 +260,10 @@ before starting pi.
 | `MEGACOMPACT_DEDUP_SIM` | `0.90` | Cosine threshold to collapse near-dupes. |
 | `MEGACOMPACT_STATE_DIR` | _(none — per-repo default)_ | Override the store location. By default state is per-repo at `<repo>/.pi/mega-compact/`; this env var forces a single explicit dir (used as the fallback for non-git cwds). |
 
-#### Dedup pipeline flags (v0.2.0 — single source: `src/config/dedup.ts`)
+#### Dedup pipeline flags (single source: `src/config/dedup.ts`)
 
 These gate the L0/L1/L2/RAPTOR dedup tiers. Defaults reproduce the all-active
-Sprint 13 behavior. `MARK_ONLY_*` tiers run + record their decision but never
+behavior. `MARK_ONLY_*` tiers run + record their decision but never
 collapse (safe partial-rollout / auto-degrade state).
 
 | Variable | Default | Meaning |
@@ -285,18 +290,18 @@ See `docs/DEDUP_RUNBOOK.md` for incident response (SEV tiers, first-15-min
 checklist, MARK_ONLY degrade) and `docs/RETENTION_POLICY.md` for TTL / soft-delete
 / VACUUM.
 
-#### Continuity + memory knobs (v0.5.0)
+#### Continuity + memory knobs
 
 | Variable | Default | Meaning |
 |---|---|---|
-| `MEGACOMPACT_LEGACY_DURABLE_TRIM` | `false` | Restore the v0.4.28 auto-trigger (`ctx.compact()` stops the agent). One-release rollback; default uses live context-event trim + pi native auto-compaction (compact-and-continue). |
+| `MEGACOMPACT_LEGACY_DURABLE_TRIM` | `false` | Restore the legacy auto-trigger (`ctx.compact()` stops the agent). One-release rollback; default uses live context-event trim + pi native auto-compaction (compact-and-continue). |
 | `MEGACOMPACT_CROSSREPO_ENABLED` | `true` | Cross-repo recall on resume + `/mega-recall --cross-repo` (HNSW index over every repo). |
 | `MEGACOMPACT_CROSSREPO_COSINE` | `0.90` | Stricter cosine floor for cross-repo hits (vs `0.85` same-repo). |
 | `MEGACOMPACT_MEMORY_AUTO_REVIEW` | `true` | Auto-review the conversation every `MEGACOMPACT_MEMORY_REVIEW_INTERVAL` turns → durable memories. |
 | `MEGACOMPACT_MEMORY_REVIEW_INTERVAL` | `10` | Turns between auto-review cycles. |
-| `MEGACOMPACT_PGLITE_DISABLED` | `1` | Kill-switch for the PGlite/HNSW cross-repo index (falls back to sync per-session scan). |
+| `MEGACOMPACT_PGLITE_DISABLED` | _(unset — index on)_ | Kill-switch for the PGlite/HNSW cross-repo index; set `1`/`true` to disable (falls back to sync per-session scan). |
 
-#### Dashboard (v0.5.0)
+#### Dashboard
 
 The localhost-only dashboard adds a **Summary** + **All-repos** view over the
 machine-wide `repo_registry`, plus a **cross-repo drift** report (`GET /api/drift`)
@@ -306,78 +311,35 @@ All read-only — the report never writes the index.
 
 ---
 
-## Reporting for testers (what to capture)
-
-If you're testing pi-mega-compact, the maintainers need **local evidence**, not
-guesswork. The store and logs are plain local files — never a network port.
-
-1. **Install + run it** (see [Installation](#install)).
-2. **Work a real session** until context fills past the gate (80%+) — you should
-   see the status chip flip to `● ready`, then `◐ armed`, a checkpoint persist,
-   and context visibly drop.
-3. **Resume and confirm recall:** restart pi, ask about something you worked on
-   earlier; relevant checkpoints should auto-inline (or use
-   `/mega-recall <topic>`).
-4. **Watch the live signal** while testing:
-   ```bash
-   tail -f ~/.pi/agent/extensions/pi-mega-compact/events.log | jq .
-   ```
-   Each line is `{ts, tier, result, latencyMs, falsePositive?}`.
-5. **Run the dashboard** (`/mega-dashboard`) and check the token gauge, store
-   stats, and live event stream.
-6. **Try `/mega-tier`** to see and switch compaction tiers.
-
-### What to include in a bug report
-
-- Output of `/mega-status` (config + store stats).
-- Output of `/mega-dashboard-status`.
-- Your pi version + OS + Node version (`node -v`).
-- A slice of `events.log` around the problem (the `result`/`tier` lines).
-- `dashboard.json` from the state dir (aggregate metrics: hit rate, FP rate,
-  per-tier p95, storage bytes).
-- If you suspect data loss or duplication: the checkpoint count and the
-  `sqlite.db` size, plus the output of the DR drill (below).
-
-**Disaster-recovery drill** (validates the store against its JSON snapshots and
-rebuilds if corrupt — see `docs/RETENTION_POLICY.md` §5):
-
-```bash
-scripts/dedup-restore-drill.sh ~/.pi/agent/extensions/pi-mega-compact
-```
-
-**Benchmark** (dedup hit rate, compression ratio, per-tier p95, storage at
-100 / 1K / 10K checkpoints):
-
-```bash
-npm run build
-node scripts/dedup-benchmark.mjs 100 1000 10000
-```
-
-Open issues at: https://github.com/TheArchitectit/pi-mega-compact/issues
-
----
-
 ## Architecture & layout
 
 ```
 extensions/mega-compact.ts   pi extension entry; wires src/ into pi lifecycle
+extensions/mega-trim.ts      live context-event trim (compact-and-continue, no abort)
+extensions/mega-conflict-cmds.ts  extension-conflict detector (/mega-compat-check)
+extensions/dashboard-server.ts     localhost dashboard (HTML + snapshot/version/drift APIs)
 src/adapt.ts                  the single pi↔engine message adapter (index-aligned)
 src/engine.ts                 Layer 4: compactSession() Trident pipeline + recall()
 src/vectorStore.ts            Layer 3: local vector DB (add/search/dedupe + near-dup)
 src/embedder.ts               default TrigramEmbedder (deterministic, 512-dim)
 src/httpEmbedder.ts           BYO localhost embedder seam (MEGACOMPACT_EMBEDDING_URL)
-src/store/sqlite.ts           the "one store" — better-sqlite3 context_chunks + session_state (FTS5 trigram)
+src/store/sqlite.ts           the "one store" — node:sqlite context_chunks + session_state (FTS5 trigram)
+src/store/vectorIndex.ts      async PGlite/HNSW cross-repo vector index (redundant, best-effort)
 src/store/migrate.ts          JSON → SQLite migration (legacy .checkpoints.json.gz retained)
 src/store/backfill.ts         resumable backfill orchestrator (L0/L1/L2/RAPTOR)
+src/memory.ts                 durable memories (decision/fact/preference) + auto-review
+src/memoryOps.ts              memory apply/consolidate ops
+src/memoryRecall.ts           memory recall + auto-inline (RAG context)
+src/driftDetection.ts         cross-repo drift report (stale/idle/compaction-lag/model-churn)
 src/monitoring.ts             local events.log + dashboard.json metrics + FP alerts
 src/canary.ts                 sequential L0→L1→L2→RAPTOR rollout, auto-disable on p95 breach
 src/config/dedup.ts           single source of truth for ALL dedup tier flags + thresholds
 src/store.ts                  state dir + JSON DR helpers + compression re-exports
-src/compact.ts               Layer 2: summarize / merge / autoCompactCheck
-src/supersede.ts             Layer 1: obsolete file-read pruning
-src/boundary.ts              drop-boundary guards (anchor floor + tool-pair)
-src/tokens.ts                deterministic token estimator
-src/types.ts                 engine-internal types
+src/compact.ts                Layer 2: summarize / merge / autoCompactCheck
+src/supersede.ts              Layer 1: obsolete file-read pruning
+src/boundary.ts               drop-boundary guards (anchor floor + tool-pair)
+src/tokens.ts                 deterministic token estimator
+src/types.ts                  engine-internal types
 ```
 
 The `src/` directory is **pi-agnostic** and fully unit-tested (`node --test`).
@@ -389,34 +351,22 @@ The extension entry adapts between the engine and pi's runtime types.
 
 ```bash
 npm run build      # tsc
-npm test           # build + node --test on dist/**/*.test.js
+npm test           # build + node --test on dist/**/*.test.js (346 tests)
 npm run lint       # tsc --noEmit + guardrails-scan
 npm run guardrails # regression_check + guardrails-scan
 ```
 
 The agent-guardrails suite (Four Laws, scope, secrets, regression) gates every
-sprint.
+change.
 
 ---
 
-## Status
-
-- ✅ Sprint 1 — core engine (Layers 1–2, pure functions)
-- ✅ Sprint 2 — local vector store (Layer 3)
-- ✅ Sprint 3 — pi extension wiring (Layer 4 persist + trigger)
-- ✅ Sprint 4 — unified recall layer (Layer 5: auto-inline + on-demand + sentinel)
-- ✅ Sprint 5 — commands / UX / config polish (status chip, store stats, debug log)
-- ✅ Sprint 6 — hardening, docs, release (`install.sh`, CHANGELOG, `v0.1.0`)
-- ✅ Sprint 8 — SQLite storage backbone (`better-sqlite3`, one store) + compression v2
-- ✅ Sprints 9–11 — L0 exact-hash + L1 MinHash/LSH near-dup dedup tiers
-- ✅ Sprint 12 — L2 semantic cosine + MMR; BYO localhost embedder (`HttpEmbedder`)
-- ✅ Sprint 13 — RAPTOR hierarchical pre-compression (shadow mode)
-- ✅ Sprint 14 — full pipeline: flags, backfill, monitoring, canary rollout
-- ✅ Sprint 15 — benchmarks, DR drill, docs, `v0.2.0`
-
-See `SPRINT_PLAN.md` for the full breakdown and `PLAN.md` for architecture,
-`RESEARCH.md` for the pi-API constraints that shaped it, `CHANGELOG.md` for
-release notes.
+## Testing & bug reports
+
+Full QA instructions — environment setup, the manual test checklist, what to
+include in a bug report, and known limitations — live in
+[`TESTER_GUIDE.md`](TESTER_GUIDE.md). Open issues at
+[github.com/TheArchitectit/pi-mega-compact/issues](https://github.com/TheArchitectit/pi-mega-compact/issues).
 
 ---
 
@@ -428,4 +378,4 @@ neuralwatt-mcr (pi-extension mechanics). Attribution as design sources only.
 
 ## License
 
-[MIT](./LICENSE)
+[BSD-2-Clause](./LICENSE)

package/dist/extensions/dashboard-server.js

@@ -119,6 +119,11 @@ function readIndex() {
     }
 }
 // ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+/** Package version of this extension, surfaced in the dashboard header. */
+let dashboardServerVersion = "0.0.0";
+// ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 function readSnapshot(snapshotPath) {
@@ -169,6 +174,7 @@ function dashboardHtml(tierName) {
   body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; background: #0d1117; color: #c9d1d9; padding: 24px; line-height: 1.5; }
   h1 { font-size: 20px; font-weight: 600; margin-bottom: 20px; display: flex; align-items: center; gap: 10px; color: #f0f6fc; }
   h1 .tier { background: #1f6feb; color: #fff; font-size: 11px; font-weight: 700; padding: 2px 8px; border-radius: 10px; text-transform: uppercase; letter-spacing: .5px; }
+  h1 .version-pill { background: #30363d; color: #8b949e; font-size: 11px; font-weight: 600; padding: 2px 8px; border-radius: 10px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
   .grid { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; margin-bottom: 20px; }
   .card { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 16px; }
   .card.safe { border-color: #238636; }
@@ -255,7 +261,7 @@ function dashboardHtml(tierName) {
 
 <div class="offline-banner" id="offline-banner">Dashboard data unavailable — waiting for a pi session to write snapshot...</div>
 
-<h1><span>mega-compact</span><span class="tier">${tierName}</span><span class="model-pill" id="hdr-model">—</span></h1>
+<h1><span>mega-compact</span><span class="tier">${tierName}</span><span class="version-pill">v${dashboardServerVersion}</span><span class="model-pill" id="hdr-model">—</span></h1>
 
 <nav class="tabs">
   <button class="tab active" data-tab="current">Current repo</button>
@@ -689,6 +695,7 @@ export async function launchDashboardServer(stateDir) {
             const pkg = JSON.parse(readFileSync(p, "utf-8"));
             if (pkg.version) {
                 SERVER_VERSION = pkg.version;
+                dashboardServerVersion = pkg.version;
                 break;
             }
         }

package/dist/extensions/mega-runtime.js

@@ -9,7 +9,9 @@
  * original closure.
  */
 import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
-import { join } from "node:path";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
 import { VectorStore } from "../src/vectorStore.js";
 import { toEngineMessages } from "../src/adapt.js";
 import { normalizeSessionId } from "../src/store.js";
@@ -20,6 +22,23 @@ 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";
+/** Cached npm version, read once from this extension's own package.json. */
+let CACHED_VERSION = null;
+function ownVersion() {
+    if (CACHED_VERSION !== null)
+        return CACHED_VERSION;
+    let v = "?";
+    try {
+        const here = dirname(fileURLToPath(import.meta.url)); // .../extensions
+        const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf-8"));
+        v = pkg.version ?? "?";
+    }
+    catch {
+        v = "?";
+    }
+    CACHED_VERSION = v;
+    return v;
+}
 /** 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. */
@@ -239,7 +258,7 @@ export class MegaRuntime {
             // 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}`,
+                ` ${C.amber}⚡ ${this.config.tier}${C.reset} v${C.bold}${ownVersion()}${C.reset} │ ${tokStr}/${maxStr} tokens (${C.bold}${pctStr}${C.reset}) │ ${st.checkpointCount} saved${agentStr}${turnStr}`,
                 `   ${triggerLabel} │ ${C.magenta}repeat-skipped: ${dedupStr}${C.reset} │ ${C.gray}memory held:${C.reset} ${usedStr} │ ${C.gray}space freed:${C.reset} ${savedStr}`,
             ];
             // Phase 3 — compact progress bar: session tokens saved toward the rolling goal.
@@ -248,7 +267,10 @@ export class MegaRuntime {
                 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)}`);
+                // Session tokens saved, with the repo-wide total held alongside so the
+                // bar reads "saved X of goal" and the right side shows saved vs total.
+                const totalHeld = st.totalTokenEstimate > 0 ? st.totalTokenEstimate : repo.totalTokenEstimate;
+                lines.push(`   ${C.green}saved ${fmt(this.rt.tokensSaved)} ${bar}${C.reset} ${pct}% of ${fmt(goal)} ${C.gray}│${C.reset} ${C.blue}${fmt(this.rt.tokensSaved)}${C.reset}/${C.blue}${fmt(totalHeld)}${C.reset} tok held`);
             }
             // Live "now processing" line + why + recent deduped/compacted events,
             // collapsed to ONE rotating line (fresh only). The ticker ring buffer

package/dist/extensions/openclaw-mega-compact.js

@@ -0,0 +1,291 @@
+/**
+ * openclaw-mega-compact — OpenClaw plugin adapter for the pi-mega-compact engine.
+ *
+ * Wires the pi-agnostic Trident engine (src/) into OpenClaw's plugin lifecycle:
+ *  - Registers a CompactionProvider that replaces the built-in summarizeInStages.
+ *  - Exposes `mega_status` and `mega_recall` tools for on-demand inspection.
+ *  - Hooks into `before_compaction` / `after_compaction` for diagnostics.
+ *
+ * Design constraints:
+ *  - NO imports from `@earendil-works/pi-coding-agent` or pi-agent-core.
+ *  - The engine core (src/) is pi-agnostic; this file is the sole OpenClaw boundary.
+ *  - No network at runtime — everything is local (stores + extractive summarizer).
+ */
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { compactSession, setDefaultStore, } from "../src/engine.js";
+import { recallAndInline } from "../src/recall.js";
+import { VectorStore } from "../src/vectorStore.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const PLUGIN_ID = "mega-compact";
+const PLUGIN_LABEL = "Mega Compact (Trident)";
+/** Default state directory for vector store persistence. */
+const STATE_DIR = process.env.MEGA_COMPACT_STATE_DIR ?? undefined;
+/** Minimum messages before we bother compacting. */
+const MIN_MESSAGES_FOR_COMPACT = 6;
+// ---------------------------------------------------------------------------
+// Message conversion — OpenClaw unknown[] → EngineMessage[]
+// ---------------------------------------------------------------------------
+/**
+ * Best-effort conversion from OpenClaw's opaque message array to our
+ * EngineMessage shape. OpenClaw messages are typed as `unknown[]` so we
+ * handle whatever shape comes through gracefully.
+ */
+function toEngineMessages(messages) {
+    return messages.map((msg) => {
+        if (!msg || typeof msg !== "object") {
+            // Primitive fallback — treat as custom text.
+            return {
+                role: "custom",
+                text: String(msg ?? ""),
+            };
+        }
+        const m = msg;
+        const role = typeof m.role === "string" ? m.role : "custom";
+        // Normalize role to one of our four engine roles.
+        let engineRole;
+        switch (role) {
+            case "user":
+                engineRole = "user";
+                break;
+            case "assistant":
+                engineRole = "assistant";
+                break;
+            case "tool":
+            case "function":
+                engineRole = "tool";
+                break;
+            default:
+                engineRole = "custom";
+                break;
+        }
+        // Extract text content from common message shapes.
+        const text = typeof m.content === "string"
+            ? m.content
+            : typeof m.text === "string"
+                ? m.text
+                : Array.isArray(m.content)
+                    ? m.content
+                        .filter((part) => part.type === "text" && typeof part.text === "string")
+                        .map((part) => part.text)
+                        .join("\n")
+                    : "";
+        // Preserve tool metadata when present.
+        const toolName = typeof m.name === "string"
+            ? m.name
+            : typeof m.toolName === "string"
+                ? m.toolName
+                : undefined;
+        const input = typeof m.input === "string"
+            ? m.input
+            : typeof m.arguments === "string"
+                ? m.arguments
+                : m.arguments !== undefined
+                    ? JSON.stringify(m.arguments)
+                    : undefined;
+        const output = typeof m.output === "string"
+            ? m.output
+            : engineRole === "tool" && typeof m.content === "string"
+                ? m.content
+                : undefined;
+        return { role: engineRole, text, toolName, input, output };
+    });
+}
+// ---------------------------------------------------------------------------
+// Compaction provider
+// ---------------------------------------------------------------------------
+function createCompactionProvider(store) {
+    return {
+        id: PLUGIN_ID,
+        label: PLUGIN_LABEL,
+        async summarize({ messages, signal, compressionRatio, }) {
+            // Abort check — bail early if the caller cancelled.
+            if (signal?.aborted) {
+                throw new DOMException("Aborted", "AbortError");
+            }
+            const engineMessages = toEngineMessages(messages);
+            // Nothing meaningful to compact.
+            if (engineMessages.length < MIN_MESSAGES_FOR_COMPACT) {
+                return "";
+            }
+            // Map compression ratio → keepFrom boundary.
+            // compressionRatio=0.5 means "compact the oldest 50%".
+            // Default to compacting the oldest half if not specified.
+            const ratio = compressionRatio ?? 0.5;
+            const keepFrom = Math.max(MIN_MESSAGES_FOR_COMPACT, Math.floor(engineMessages.length * (1 - ratio)));
+            // Abort check after conversion (conversion is cheap but check anyway).
+            if (signal?.aborted) {
+                throw new DOMException("Aborted", "AbortError");
+            }
+            const sessionId = `openclaw-${Date.now()}`;
+            const input = {
+                sessionId,
+                messages: engineMessages,
+                keepFrom,
+            };
+            const result = compactSession(input, store);
+            if (result.skipped) {
+                return "";
+            }
+            return result.summary;
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Plugin entry
+// ---------------------------------------------------------------------------
+export default definePluginEntry({
+    id: PLUGIN_ID,
+    name: "Mega Compact",
+    description: "Layered, local, vector-backed context compressor (Trident engine) for OpenClaw compaction.",
+    register(api) {
+        const logger = api.logger;
+        // Resolve state directory — prefer plugin config override.
+        const pluginCfg = (api.pluginConfig ?? {});
+        const stateDir = typeof pluginCfg.stateDir === "string" && pluginCfg.stateDir.length > 0
+            ? pluginCfg.stateDir
+            : STATE_DIR;
+        // Initialize vector store.
+        let store;
+        try {
+            store = new VectorStore({ stateDir });
+            setDefaultStore(store);
+            logger.info?.(`${PLUGIN_ID}: vector store initialized (stateDir=${stateDir ?? "default"})`);
+        }
+        catch (err) {
+            logger.error?.(`${PLUGIN_ID}: failed to init vector store:`, err);
+            return; // Hard bail — no point registering if store is broken.
+        }
+        // -----------------------------------------------------------------------
+        // Register compaction provider
+        // -----------------------------------------------------------------------
+        const provider = createCompactionProvider(store);
+        api.registerCompactionProvider(provider);
+        logger.info?.(`${PLUGIN_ID}: registered compaction provider "${provider.id}"`);
+        // -----------------------------------------------------------------------
+        // Hooks — before / after compaction diagnostics
+        // -----------------------------------------------------------------------
+        api.registerHook({
+            event: "before_compaction",
+            handler: async (ctx) => {
+                const msgCount = Array.isArray(ctx?.messages) ? ctx.messages.length : 0;
+                logger.info?.(`${PLUGIN_ID}: before_compaction — ${msgCount} messages in scope`);
+            },
+        });
+        api.registerHook({
+            event: "after_compaction",
+            handler: async (ctx) => {
+                const summaryLen = typeof ctx?.summary === "string" ? ctx.summary.length : 0;
+                logger.info?.(`${PLUGIN_ID}: after_compaction — summary ${summaryLen} chars`);
+            },
+        });
+        // -----------------------------------------------------------------------
+        // Tool: mega_status
+        // -----------------------------------------------------------------------
+        api.registerTool({
+            name: "mega_status",
+            description: "Show the current status of the mega-compact engine: vector store stats, checkpoint count, and recent compaction activity.",
+            parameters: {
+                type: "object",
+                properties: {
+                    sessionId: {
+                        type: "string",
+                        description: "Optional session ID to scope stats to.",
+                    },
+                },
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const sessionId = args?.sessionId ?? "global";
+                try {
+                    const stats = store.stats(sessionId);
+                    const parts = [
+                        `**Mega Compact Status**`,
+                        `Session: ${sessionId}`,
+                        `Checkpoints: ${stats.checkpointCount}`,
+                        `Total tokens saved: ${stats.totalTokenEstimate}`,
+                        `Last checkpoint: ${stats.lastCheckpointId ?? "—"}`,
+                        `Injected count: ${stats.injectedCount}`,
+                        `Dedup hit rate: ${(stats.dedupHitRate * 100).toFixed(0)}%`,
+                    ];
+                    if (stats.lastSummary) {
+                        parts.push(`\nLast summary (truncated):\n  ${stats.lastSummary.slice(0, 120).replace(/\n/g, " ")}…`);
+                    }
+                    return { content: [{ type: "text", text: parts.join("\n") }] };
+                }
+                catch (err) {
+                    return {
+                        content: [{ type: "text", text: `Error reading mega-compact status: ${err}` }],
+                        isError: true,
+                    };
+                }
+            },
+        });
+        // -----------------------------------------------------------------------
+        // Tool: mega_recall
+        // -----------------------------------------------------------------------
+        api.registerTool({
+            name: "mega_recall",
+            description: "Recall and inline relevant context from the mega-compact vector store for the current session.",
+            parameters: {
+                type: "object",
+                properties: {
+                    sessionId: {
+                        type: "string",
+                        description: "Session ID to recall context for.",
+                    },
+                    query: {
+                        type: "string",
+                        description: "Natural language query for relevant context.",
+                    },
+                    limit: {
+                        type: "number",
+                        description: "Max checkpoints to recall (default 3).",
+                    },
+                },
+                required: ["sessionId", "query"],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const { sessionId, query, limit } = args;
+                if (!sessionId || !query) {
+                    return {
+                        content: [{ type: "text", text: "Both `sessionId` and `query` are required." }],
+                        isError: true,
+                    };
+                }
+                try {
+                    const result = recallAndInline({ sessionId, query, limit: limit ?? 3, source: "command", skipInjected: false }, store);
+                    if (result.toInject.length === 0) {
+                        return {
+                            content: [{ type: "text", text: "No relevant context found in the mega-compact store." }],
+                        };
+                    }
+                    const parts = [
+                        `**Recalled ${result.toInject.length} checkpoint(s):**`,
+                        ...result.report,
+                        "",
+                        "---",
+                        result.block,
+                    ];
+                    return { content: [{ type: "text", text: parts.join("\n") }] };
+                }
+                catch (err) {
+                    return {
+                        content: [{ type: "text", text: `Error during mega-recall: ${err}` }],
+                        isError: true,
+                    };
+                }
+            },
+        });
+        // -----------------------------------------------------------------------
+        // Cleanup on shutdown
+        // -----------------------------------------------------------------------
+        api.on("shutdown", () => {
+            logger.info?.(`${PLUGIN_ID}: shutting down — clearing default store`);
+            setDefaultStore(undefined);
+        });
+        logger.info?.(`${PLUGIN_ID}: plugin registered (tools: mega_status, mega_recall)`);
+    },
+});

package/dist/src/minilm.js

@@ -0,0 +1,92 @@
+/**
+ * minilm.ts — local MiniLM (all-MiniLM-L6-v2) sentence embedder (Sprint 12).
+ *
+ * Implements the `Embedder` interface so it drops into the existing VectorStore
+ * dedup cascade and search with no call-site changes. Inference is 100% local:
+ * the ONNX model + WordPiece vocab are on-disk artifacts fetched once by
+ * scripts/setup-minilm.mjs. There is NO network call at runtime (PREVENT-PI-004).
+ *
+ * Inputs (dynamic): input_ids, attention_mask, token_type_ids (int64).
+ * Output: last_hidden_state (batch, seq, 384). We mean-pool over non-padded
+ * tokens (attention_mask == 1) and L2-normalize → 384-dim unit vector.
+ *
+ * The ONNX session + tokenizer are loaded LAZILY on first embed() so the default
+ * TrigramEmbedder path (and its zero native-init cost) is untouched unless
+ * MEGACOMPACT_EMBEDDER=minilm is selected.
+ */
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { existsSync } from "node:fs";
+import { l2Normalize, awaitSync } from "./embedder.js";
+import { WordPieceTokenizer } from "./wordpiece.js";
+export const MINILM_DIM = 384;
+export const MINILM_MAX_LEN = 256;
+/** Resolve the model directory: MEGACOMPACT_MINILM_DIR > ./models/minilm > ~/.pi … */
+function resolveModelDir() {
+    if (process.env.MEGACOMPACT_MINILM_DIR)
+        return process.env.MEGACOMPACT_MINILM_DIR;
+    // Repo-local vendored path (gitignored).
+    const local = join(process.cwd(), "models", "minilm");
+    if (existsSync(local))
+        return local;
+    return join(homedir(), ".pi", "agent", "extensions", "mega-compact", "models", "minilm");
+}
+export class MiniLMEmbedder {
+    dim = MINILM_DIM;
+    session = null;
+    tokenizer = null;
+    modelDir;
+    loadPromise = null;
+    constructor(modelDir = resolveModelDir()) {
+        this.modelDir = modelDir;
+    }
+    async ensureLoaded() {
+        if (this.session && this.tokenizer)
+            return;
+        if (this.loadPromise)
+            return this.loadPromise;
+        this.loadPromise = (async () => {
+            const ort = await import("onnxruntime-node");
+            const modelPath = join(this.modelDir, "model_quantized.onnx");
+            const vocabPath = join(this.modelDir, "vocab.txt");
+            if (!existsSync(modelPath) || !existsSync(vocabPath)) {
+                throw new Error(`MiniLM artifacts missing in ${this.modelDir}. Run: node scripts/setup-minilm.mjs`);
+            }
+            // 1 thread is plenty for a single short-region embed and bounds CPU.
+            this.session = await ort.InferenceSession.create(modelPath, {
+                executionProviders: ["cpu"],
+                graphOptimizationLevel: "all",
+            });
+            this.tokenizer = WordPieceTokenizer.fromVocabFile(vocabPath);
+        })();
+        return this.loadPromise;
+    }
+    embed(text) {
+        awaitSync(this.ensureLoaded());
+        const enc = this.tokenizer.encode(text, MINILM_MAX_LEN);
+        const n = enc.inputIds.length;
+        const BigInt64 = (arr) => arr.map((x) => BigInt(x));
+        const ort = awaitSync(import("onnxruntime-node"));
+        const tensors = {
+            input_ids: new ort.Tensor("int64", BigInt64(enc.inputIds), [1, n]),
+            attention_mask: new ort.Tensor("int64", BigInt64(enc.attentionMask), [1, n]),
+            token_type_ids: new ort.Tensor("int64", BigInt64(enc.tokenTypeIds), [1, n]),
+        };
+        const out = awaitSync(this.session.run(tensors));
+        const hidden = out.last_hidden_state.data;
+        // hidden shape: [1, n, 384]. Mean-pool over non-padded positions.
+        const pooled = new Array(MINILM_DIM).fill(0);
+        let count = 0;
+        for (let i = 0; i < n; i++) {
+            if (enc.attentionMask[i] === 0)
+                continue;
+            const base = i * MINILM_DIM;
+            for (let d = 0; d < MINILM_DIM; d++)
+                pooled[d] += hidden[base + d];
+            count++;
+        }
+        if (count === 0)
+            return l2Normalize(new Array(MINILM_DIM).fill(0));
+        return l2Normalize(pooled.map((x) => x / count));
+    }
+}

package/dist/src/wordpiece.js

@@ -0,0 +1,129 @@
+/**
+ * wordpiece.ts — a self-contained WordPiece tokenizer for BERT/MiniLM.
+ *
+ * Loads the canonical `vocab.txt` (bert-base-uncased, ~30K tokens) from disk and
+ * implements the standard uncased BERT preprocessing + greedy longest-match
+ * WordPiece segmentation. No native dependency, no network — the vocab file is a
+ * local artifact fetched once by scripts/setup-minilm.mjs (PREVENT-PI-004).
+ *
+ * This mirrors HuggingFace `BertTokenizer` closely enough for sentence-embedding
+ * use: lowercase, strip accents, split on whitespace + punctuation, then
+ * WordPiece each token with the `##` continuation convention. Special tokens
+ * [CLS]/[SEP] are added by the caller's encode().
+ */
+import { readFileSync, existsSync } from "node:fs";
+const UNK = "[UNK]";
+const CLS = "[CLS]";
+const SEP = "[SEP]";
+const PAD = "[PAD]";
+const MAX_INPUT_CHARS_PER_WORD = 200;
+export class WordPieceTokenizer {
+    vocab;
+    clsId;
+    sepId;
+    padId;
+    unkId;
+    constructor(vocab) {
+        this.vocab = vocab;
+        this.clsId = vocab.get(CLS) ?? 101;
+        this.sepId = vocab.get(SEP) ?? 102;
+        this.padId = vocab.get(PAD) ?? 0;
+        this.unkId = vocab.get(UNK) ?? 100;
+    }
+    /** Build a tokenizer from a vocab.txt file (one token per line, index = line). */
+    static fromVocabFile(path) {
+        if (!existsSync(path)) {
+            throw new Error(`WordPiece vocab not found at ${path}. Run: node scripts/setup-minilm.mjs`);
+        }
+        const lines = readFileSync(path, "utf-8").split("\n");
+        const vocab = new Map();
+        for (let i = 0; i < lines.length; i++) {
+            const tok = lines[i].replace(/\r$/, "");
+            if (tok.length > 0 || i < lines.length - 1)
+                vocab.set(tok, i);
+        }
+        return new WordPieceTokenizer(vocab);
+    }
+    /** Uncased BERT basic tokenization: lowercase, strip accents, split on ws+punct. */
+    basicTokenize(text) {
+        // NFD + strip combining marks (accent removal), then lowercase.
+        const cleaned = text
+            .normalize("NFD")
+            .replace(/[̀-ͯ]/g, "")
+            .toLowerCase();
+        const tokens = [];
+        let buf = "";
+        const flush = () => {
+            if (buf.length > 0) {
+                tokens.push(buf);
+                buf = "";
+            }
+        };
+        for (const ch of cleaned) {
+            if (/\s/.test(ch)) {
+                flush();
+            }
+            else if (/[!-/:-@[-`{-~¡-¿]/.test(ch)) {
+                // Punctuation becomes its own token.
+                flush();
+                tokens.push(ch);
+            }
+            else {
+                buf += ch;
+            }
+        }
+        flush();
+        return tokens;
+    }
+    /** Greedy longest-match WordPiece for a single word. */
+    wordpiece(word) {
+        if (word.length > MAX_INPUT_CHARS_PER_WORD)
+            return [UNK];
+        const pieces = [];
+        let start = 0;
+        while (start < word.length) {
+            let end = word.length;
+            let cur = null;
+            while (start < end) {
+                let sub = word.slice(start, end);
+                if (start > 0)
+                    sub = "##" + sub;
+                if (this.vocab.has(sub)) {
+                    cur = sub;
+                    break;
+                }
+                end--;
+            }
+            if (cur === null)
+                return [UNK]; // any unmatchable piece → whole word is UNK
+            pieces.push(cur);
+            start = end;
+        }
+        return pieces;
+    }
+    /** Tokenize text into WordPiece token strings (no special tokens). */
+    tokenize(text) {
+        const out = [];
+        for (const word of this.basicTokenize(text)) {
+            for (const piece of this.wordpiece(word))
+                out.push(piece);
+        }
+        return out;
+    }
+    /**
+     * Encode text into model inputs with [CLS]…[SEP], truncated to `maxLen`.
+     * attention_mask is all 1s (no padding for single-sequence inference).
+     */
+    encode(text, maxLen = 256) {
+        const pieces = this.tokenize(text).slice(0, Math.max(0, maxLen - 2));
+        const inputIds = [this.clsId];
+        for (const p of pieces)
+            inputIds.push(this.vocab.get(p) ?? this.unkId);
+        inputIds.push(this.sepId);
+        return {
+            inputIds,
+            attentionMask: inputIds.map(() => 1),
+            tokenTypeIds: inputIds.map(() => 0),
+        };
+    }
+}

package/extensions/dashboard-server.ts

@@ -131,6 +131,9 @@ function readIndex(): { updatedAt: string; summary: unknown; repos: unknown[] }
 // Types
 // ---------------------------------------------------------------------------
 
+/** Package version of this extension, surfaced in the dashboard header. */
+let dashboardServerVersion = "0.0.0";
+
 interface Snapshot {
   version: number;
   updatedAt: string | null;
@@ -253,6 +256,7 @@ function dashboardHtml(tierName: string): string {
   body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; background: #0d1117; color: #c9d1d9; padding: 24px; line-height: 1.5; }
   h1 { font-size: 20px; font-weight: 600; margin-bottom: 20px; display: flex; align-items: center; gap: 10px; color: #f0f6fc; }
   h1 .tier { background: #1f6feb; color: #fff; font-size: 11px; font-weight: 700; padding: 2px 8px; border-radius: 10px; text-transform: uppercase; letter-spacing: .5px; }
+  h1 .version-pill { background: #30363d; color: #8b949e; font-size: 11px; font-weight: 600; padding: 2px 8px; border-radius: 10px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
   .grid { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; margin-bottom: 20px; }
   .card { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 16px; }
   .card.safe { border-color: #238636; }
@@ -339,7 +343,7 @@ function dashboardHtml(tierName: string): string {
 
 <div class="offline-banner" id="offline-banner">Dashboard data unavailable — waiting for a pi session to write snapshot...</div>
 
-<h1><span>mega-compact</span><span class="tier">${tierName}</span><span class="model-pill" id="hdr-model">—</span></h1>
+<h1><span>mega-compact</span><span class="tier">${tierName}</span><span class="version-pill">v${dashboardServerVersion}</span><span class="model-pill" id="hdr-model">—</span></h1>
 
 <nav class="tabs">
   <button class="tab active" data-tab="current">Current repo</button>
@@ -772,7 +776,7 @@ export async function launchDashboardServer(stateDir: string): Promise<{ port: n
     for (const p of candidates) {
       if (!existsSync(p)) continue;
       const pkg = JSON.parse(readFileSync(p, "utf-8"));
-      if (pkg.version) { SERVER_VERSION = pkg.version; break; }
+      if (pkg.version) { SERVER_VERSION = pkg.version; dashboardServerVersion = pkg.version; break; }
     }
   } catch { /* non-fatal */ }
 

package/extensions/mega-runtime.ts

@@ -12,7 +12,9 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import { join } from "node:path";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
 import { VectorStore } from "../src/vectorStore.js";
 import { toEngineMessages } from "../src/adapt.js";
 import { normalizeSessionId } from "../src/store.js";
@@ -25,6 +27,22 @@ export const STATUS_KEY = "mega-compact";
 export const WIDGET_KEY = "mega-compact-stats";
 export const MARKER_TYPE = "mega-compact-marker";
 
+/** Cached npm version, read once from this extension's own package.json. */
+let CACHED_VERSION: string | null = null;
+function ownVersion(): string {
+  if (CACHED_VERSION !== null) return CACHED_VERSION;
+  let v = "?";
+  try {
+    const here = dirname(fileURLToPath(import.meta.url)); // .../extensions
+    const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf-8"));
+    v = pkg.version ?? "?";
+  } catch {
+    v = "?";
+  }
+  CACHED_VERSION = v;
+  return v;
+}
+
 /** Per-session runtime state kept in the closure (mirrors neuralwatt-mcr). */
 interface SessionRuntime {
   sessionId: string;
@@ -265,7 +283,7 @@ export class MegaRuntime {
       // 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}`,
+        ` ${C.amber}⚡ ${this.config.tier}${C.reset} v${C.bold}${ownVersion()}${C.reset} │ ${tokStr}/${maxStr} tokens (${C.bold}${pctStr}${C.reset}) │ ${st.checkpointCount} saved${agentStr}${turnStr}`,
         `   ${triggerLabel} │ ${C.magenta}repeat-skipped: ${dedupStr}${C.reset} │ ${C.gray}memory held:${C.reset} ${usedStr} │ ${C.gray}space freed:${C.reset} ${savedStr}`,
       ];
       // Phase 3 — compact progress bar: session tokens saved toward the rolling goal.
@@ -274,7 +292,10 @@ export class MegaRuntime {
         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)}`);
+        // Session tokens saved, with the repo-wide total held alongside so the
+        // bar reads "saved X of goal" and the right side shows saved vs total.
+        const totalHeld = st.totalTokenEstimate > 0 ? st.totalTokenEstimate : repo.totalTokenEstimate;
+        lines.push(`   ${C.green}saved ${fmt(this.rt.tokensSaved)} ${bar}${C.reset} ${pct}% of ${fmt(goal)} ${C.gray}│${C.reset} ${C.blue}${fmt(this.rt.tokensSaved)}${C.reset}/${C.blue}${fmt(totalHeld)}${C.reset} tok held`);
       }
       // Live "now processing" line + why + recent deduped/compacted events,
       // collapsed to ONE rotating line (fresh only). The ticker ring buffer

package/package.json

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