pi-mega-compact 0.7.6 → 0.7.8

package/README.md

@@ -6,22 +6,37 @@ 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).
 
-> **Current version:** `v0.7.5` — 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.** S27 added a **raw-transcript
-> mirror + dedup pipeline** (byte-stable prompt cache via deterministic epoch
-> nonce) and **DB maintenance /commands** (`/mega-db-stats` · `prune` ·
-> `vacuum` · `check` · `reconcile`) plus best-effort auto-maintenance on
-> `session_start`. Legacy `.checkpoints.json.gz` snapshots are retained as
-> disaster-recovery fallbacks and auto-imported on first run. The S24 line ties
-> auto-compact, the tier label, trim depth, and durable-memory review to one
-> **unified pressure signal**, adds a **cross-repo memory-RAG index**, and
-> relieves context **during team runs** (not just at the end).
+> **Status - v0.7.7.** Storage uses the built-in `node:sqlite` backend
+> (`DatabaseSync`, Node >=22.13): zero native build step, fully local, and zero
+> network at runtime. See [RELEASE_NOTES.md](RELEASE_NOTES.md) for the full
+> changelog.
 
 ---
 
-## What this is (the 30-second version)
+## Features
+
+- **Local & private** - everything stays on your disk. No telemetry, no API key, no MCP server, no cloud. The only network surface is an optional localhost dashboard you open yourself.
+- **Two-layer compaction** - a non-destructive live summary every LLM call, plus durable checkpoints that relieve context mid-run (not just at the end).
+- **Vector store + dedup** - each checkpoint is embedded and stored locally; an L0->L2 + RAPTOR cascade collapses duplicate work so storage and recall stay lean.
+- **Automatic recall** - the most relevant checkpoints are re-inlined on resume or branch switch; cross-repo memory-RAG augments a thin store with decisions from other repos.
+- **Live dashboard** - a localhost-only view of token usage, store stats, savings, per-repo activity, and an **Active Repos tab** that shows every currently-open session (last 30 minutes) side by side — so running multiple sessions at once is visible in one place.
+- **Database maintenance** - `/mega-db-*` commands plus best-effort auto-maintenance on session start.
+
+## Table of contents
+
+- [Overview](#overview)
+- [How it works](#how-it-works)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Configuration](#configuration)
+- [Dashboard](#dashboard)
+- [Architecture](#architecture)
+- [Development](#development)
+- [Testing & bug reports](#testing--bug-reports)
+- [Acknowledgements](#acknowledgements)
+- [License](#license)
+
+## Overview
 
 pi's context window is finite. When a session gets long — especially a team run
 with sub-agents — pi-mega-compact keeps it going without overflowing:
@@ -217,7 +232,7 @@ rm -f ~/.pi/agent/extensions/pi-mega-compact
 
 ---
 
-## How to use it
+## Usage
 
 Once installed and registered, pi-mega-compact runs **automatically** — you don't
 have to drive it. Past the context threshold it compacts in the background and
@@ -225,6 +240,8 @@ drops a checkpoint; on resume it re-inlines the relevant ones silently.
 
 The commands (slash commands inside pi):
 
+### Commands
+
 | Command | Description |
 |---|---|
 | `/mega-compact [summary...]` | Manually compact the current session. A summary arg is used verbatim; otherwise the COLLAPSE heuristics build one. Persists a `chkpt_xxx`. |
@@ -242,18 +259,21 @@ The commands (slash commands inside pi):
 | `/mega-db-vacuum` | `VACUUM` the DB (rebuild pages, reclaim freelist). Heavy: briefly doubles disk usage. |
 | `/mega-db-check` | `PRAGMA integrity_check` + `wal_checkpoint(TRUNCATE)`. Fold the WAL into the main file and verify DB health. Use after a crash. |
 | `/mega-db-reconcile` | Fix `dedup_mirror.ref_count` drift vs actual `raw_transcript` refs, delete orphan dedup rows, backfill missing `content_ref`. Run after `/mega-db-prune` or a crash. |
-
-The **tier** you see in the toolbar and dashboard is a *live pressure band* (`low` → `medium` → `high` → `ultra` → `mega`) that climbs automatically as your context window fills and falls back as it's relieved — it is driven by `currentTokens / effectiveThreshold`, not a manual setting. The base compaction *threshold* is set by `MEGACOMPACT_TIER` at startup as a **% of the model context window** (`low` 50% · `medium` 60% · `high` 70% · `ultra` 70% · `mega` 75%; default `low`) — the fire point is `tierPct × contextWindow`, so it always lands below pi's native ~80% auto-compaction (any model size). The old static token amounts (50k/100k/200k/1M/10M) are now only the boot fallback used before the first context event reports a window. `/mega-tier` was removed in v0.6.0. Higher pressure also deepens the live trim and reviews durable memory more often — the whole system reacts as one.
-| `/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 [open]` | Start the **localhost-only** live dashboard and open it in a browser (token gauge, store stats, live event stream, per-repo + All-repos/Summary views, cross-repo drift). |
+| `/mega-dashboard-status` | Report dashboard server status (port / url / live). |
 | `/mega-dashboard-stop` | Stop the dashboard server. |
 
+### The tier system
+
+The **tier** you see in the toolbar and dashboard is a *live pressure band* (`low` → `medium` → `high` → `ultra` → `mega`) that climbs automatically as your context window fills and falls back as it's relieved — it is driven by `currentTokens / effectiveThreshold`, not a manual setting. The base compaction *threshold* is set by `MEGACOMPACT_TIER` at startup as a **% of the model context window** (`low` 50% · `medium` 60% · `high` 70% · `ultra` 70% · `mega` 75%; default `low`) — the fire point is `tierPct × contextWindow`, so it always lands below pi's native ~80% auto-compaction (any model size). The old static token amounts (50k/100k/200k/1M/10M) are now only the boot fallback used before the first context event reports a window. `/mega-tier` was removed in v0.7.6. Higher pressure also deepens the live trim and reviews durable memory more often — the whole system reacts as one.
+
+
 ### Live stats widget
 
 Above the pi editor the extension shows a compact widget:
 
 ```
- ⚡ high·low v0.6.0 │ 142k/200k tokens (71%) │ 3 chkpts │ 🤖 2 agents │ turn 5
+ ⚡ high·low v0.7.7 │ 142k/200k tokens (71%) │ 3 chkpts │ 🤖 2 agents │ turn 5
    ◐ armed │ dedup: 92% │ saved: 45k tok
 ```
 
@@ -272,7 +292,7 @@ Above the pi editor the extension shows a compact widget:
 > **auto-maintenance** pass runs on `session_start`: it prunes rows older than
 > 30d, checkpoints the WAL if it's over 10 MB, and VACUUMs if the DB is over
 > 100 MB AND the freelist is >20% of pages. It never blocks session start and
-> logs a one-line summary to the diagnostic log. (v0.7.5+)
+> logs a one-line summary to the diagnostic log. (v0.7.6+)
 
 ---
 
@@ -281,6 +301,8 @@ Above the pi editor the extension shows a compact widget:
 All defaults are in `src/config/dedup.ts` (single source of truth). Set env vars
 before starting pi.
 
+### Core settings
+
 | Variable | Default | Meaning |
 |---|---|---|
 | `MEGACOMPACT_FAST_GATE_PCT` | `70` | Context-usage % that arms the auto-trigger. Defaults to the tier's % of window (`tierPct*100`): low 50 · med 60 · high 70 · ultra 70 · mega 75. Override raises the arming floor. |
@@ -294,7 +316,7 @@ 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 (single source: `src/config/dedup.ts`)
+### Dedup pipeline flags
 
 These gate the L0/L1/L2/RAPTOR dedup tiers. Defaults reproduce the all-active
 behavior. `MARK_ONLY_*` tiers run + record their decision but never
@@ -324,7 +346,7 @@ 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
+### Continuity & memory
 
 | Variable | Default | Meaning |
 |---|---|---|
@@ -335,17 +357,84 @@ checklist, MARK_ONLY degrade) and `docs/RETENTION_POLICY.md` for TTL / soft-dele
 | `MEGACOMPACT_MEMORY_REVIEW_INTERVAL` | `10` | Turns between auto-review cycles. |
 | `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
-
-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`)
-flagging stale repos (>30d idle), compaction lag (an active repo >24h behind the
-most-recently-active repo's last compaction), and recent model churn (within 7d).
-All read-only — the report never writes the index.
+## Dashboard
+
+The localhost-only dashboard (started with `/mega-dashboard`) is a single-page
+app served from a detached child process on `127.0.0.1` (random port in
+9320–9329). Every API is read-only — the server never writes the index or your
+store. It reads the machine-wide `repo_registry`
+(`~/.mega-compact-index/index.sqlite`) plus the current repo's own `node:sqlite`
+store.
+
+### Tabs
+
+- **Current repo** — the live single-session view: context-window gauge, trigger
+  status, the Vector Store (checkpoints / dropped / kept / freed / injected /
+  dedup / collapsed), the repo-wide aggregate, the Data Safety card, the live
+  Model & Cost Savings card, and crew/agent activity.
+- **All repos** — a machine-wide table aggregated from `repo_registry`
+  (`GET /api/index`): one row per repo with checkpoints, tokens saved,
+  compressed-originals, last-compacted, and active model. Each row opens a
+  per-repo detail modal. Currently-open sessions are badged **active** (see
+  below).
+- **Summary** — machine-wide header tiles plus a **savings-by-model** table
+  (tokens in/out/freed, context window, $ saved) grouped by the model you were
+  running.
+
+### Active Repos tab
+
+The dashboard has a dedicated **Active Repos** tab that lists every server /
+session seen within the **last 30 minutes**, each with its live tier,
+context %, and session state. It is backed by `GET /api/servers`, which walks
+the machine-wide `repo_registry`, reads each repo's per-process
+`dashboard.json` snapshot, and returns one row per currently-open session —
+so 1–6 sessions running at once are visible together in a single table instead
+of only the single current-repo view. Each row shows that repo's live
+cache-hit / compaction / time-saved totals (see below).
+
+The older **All repos** view and `GET /api/summary` still surface an
+`activeRepos` count, and `GET /api/repos?active=Nh` filters to repos seen
+within the last *N* hours (e.g. `?active=24h`, hour-granular) for the
+longer-window cross-repo table.
+
+### Metrics (DB-backed, durable)
+
+The dashboard's cumulative **Cache hits**, **Compactions**, and **Estimated
+time saved** cards are backed by **SQLite `meta` counters**
+(`compact_count`, `recall_injected`, `cache_hit_tokens_saved`, plus the
+existing `tokens_saved` / `deduped`), not the per-process `dashboard.json`
+snapshot. Because they live in the repo's `node:sqlite` store, the totals are
+**durable across session restarts** and travel with the repo's state dir —
+`dashboard.json` is now just the live per-process view that feeds the Active
+Repos rows. The cards show:
+
+- **Cache hits** = dedup collapses (`deduped`) + recall re-injections
+  (`recall_injected`) — as **current session** and **repo-wide total**.
+- **Compactions** = current session (`checkpointCount`) + repo-wide total
+  (`compact_count` from `meta`).
+- **Estimated time saved** = compact time saved + cache-hit time saved, derived
+  from tokens ÷ ~2k tok/s and labeled `est.`, as current session + total.
+
+### Localhost API
+
+`GET /api/snapshot` (current-repo live state),
+`/api/servers` (**Active Repos** — sessions active in the last 30 min, with
+tier / context % / state / live cache-hit & compaction totals),
+`/api/index` (all repos), `/api/repos` (with `?active=Nh` filter), `/api/summary`
+(header tiles + `activeRepos`), `/api/drift` (cross-repo drift: stale /
+compaction-lag / model-churn — read-only), `/api/events` (SSE live event stream),
+and `/api/version`.
+
+### Data safety
+
+Every compacted region is kept verbatim (compressed);
+the Data Safety card shows regions retained, compressed-originals bytes, dedup
+duplicates, and permanently-deleted bytes (**always 0**). Nothing is permanently
+deleted — any region is restorable.
 
 ---
 
-## Architecture & layout
+## Architecture
 
 ```
 extensions/mega-compact.ts   pi extension entry; wires src/ into pi lifecycle
@@ -385,7 +474,7 @@ 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 (353 tests)
+npm test           # build + node --test on dist/**/*.test.js (407 tests)
 npm run lint       # tsc --noEmit + guardrails-scan
 npm run guardrails # regression_check + guardrails-scan
 ```

package/dist/extensions/dashboard-server.js

@@ -45,6 +45,7 @@ function log(...parts) {
 // concurrent writer's WAL never blocks the request). All registry data lives in
 // SQLite (the project's one-store invariant) — there is no JSON mirror. Same
 // index-dir resolution as src/store/sqlite.ts getIndexDir().
+const ACTIVE_WINDOW_SEC = 1800;
 function getIndexDir() {
     const override = process.env.MEGACOMPACT_INDEX_DIR;
     if (override && override.trim() !== "")
@@ -169,9 +170,6 @@ function readIndex() {
 // ---------------------------------------------------------------------------
 /** Package version of this extension, surfaced in the dashboard header. */
 let dashboardServerVersion = "0.0.0";
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
 function readSnapshot(snapshotPath) {
     try {
         const raw = readFileSync(snapshotPath, "utf-8");
@@ -192,6 +190,9 @@ function readSnapshot(snapshotPath) {
             crew: { activeAgents: 0, currentTurn: 0 },
             repo: { checkpointCount: 0, totalTokenEstimate: 0, originalTokens: 0, tokensSaved: 0, sessionCount: 0, dedupAttempts: 0, dedupCollapsed: 0, storageDedupRate: 0 },
             integrity: { regionsRetained: 0, compressedOriginalBytes: 0, duplicatesCollapsed: 0, bytesPermanentlyDeleted: 0 },
+            cacheHits: { session: 0, total: 0, sessionTokensSaved: 0, totalTokensSaved: 0 },
+            compacts: { session: 0, total: 0 },
+            timeSaved: { compact: { sessionSec: 0, totalSec: 0 }, cacheHit: { sessionSec: 0, totalSec: 0 } },
             compression: { session: { tokensIn: 0, tokensOut: 0, tokensFreed: 0, compressionPct: 0, dedupPct: 0 }, repo: { tokensIn: 0, tokensOut: 0, tokensFreed: 0, compressionPct: 0, dedupPct: 0 } },
             model: undefined,
         };
@@ -315,6 +316,7 @@ function dashboardHtml(tierName) {
 <nav class="tabs">
   <button class="tab active" data-tab="current">Current repo</button>
   <button class="tab" data-tab="all">All repos</button>
+  <button class="tab" data-tab="active">Active Repos</button>
   <button class="tab" data-tab="summary">Summary</button>
 </nav>
 
@@ -416,6 +418,26 @@ function dashboardHtml(tierName) {
     </ul>
     <p class="legend-note">Hover any label above for a quick explanation.</p>
   </div>
+  <div class="card">
+    <h2>💾 Cache Hits &amp; Compactions</h2>
+    <div class="stat-grid">
+      <span class="label">Cache Hits (session)</span><span class="value" id="ch-session">0</span>
+      <span class="label">Cache Hits (total)</span><span class="value" id="ch-total">0</span>
+      <span class="label">Tokens Saved (session)</span><span class="value" id="ch-tok-session">0</span>
+      <span class="label">Tokens Saved (total)</span><span class="value" id="ch-tok-total">0</span>
+      <span class="label">Compactions (session)</span><span class="value" id="cp-session">0</span>
+      <span class="label">Compactions (total)</span><span class="value" id="cp-total">0</span>
+    </div>
+  </div>
+  <div class="card">
+    <h2>⏱ Time Saved (est.)</h2>
+    <div class="stat-grid">
+      <span class="label">Compact (session)</span><span class="value" id="ts-compact-session">0</span>
+      <span class="label">Compact (total)</span><span class="value" id="ts-compact-total">0</span>
+      <span class="label">Cache Hit (session)</span><span class="value" id="ts-cache-session">0</span>
+      <span class="label">Cache Hit (total)</span><span class="value" id="ts-cache-total">0</span>
+    </div>
+  </div>
 </div>
 
 <div class="events">
@@ -441,6 +463,28 @@ function dashboardHtml(tierName) {
 <div class="updated" id="updated"></div>
 </div><!-- /panel-current -->
 
+<!-- Active repos (live cache-hit / compaction stats across machines) -->
+<div class="tab-panel" id="panel-active">
+  <div class="card">
+    <h2>Active Repos — Live Cache Hits &amp; Compactions</h2>
+    <p class="legend-note">Repos seen within the last 30 minutes, with their per-repo cache-hit, compaction, and time-saved (est.) totals pulled live from each repo's dashboard.json.</p>
+    <table class="repos">
+      <thead>
+        <tr>
+          <th>Repo</th><th>Model</th><th>Tier</th>
+          <th style="text-align:right">Context %</th><th>State</th>
+          <th style="text-align:right">Compactions (s/t)</th>
+          <th style="text-align:right">Cache Hits (s/t)</th>
+          <th style="text-align:right">Compact s/t (s)</th>
+          <th style="text-align:right">CacheHit s/t (s)</th>
+        </tr>
+      </thead>
+      <tbody id="active-rows"><tr><td colspan="9" class="repo-none">loading…</td></tr></tbody>
+    </table>
+    <div class="updated" id="active-updated"></div>
+  </div>
+</div>
+
 <!-- Per-repo detail modal -->
 <div class="repo-detail" id="repo-detail">
   <div class="repo-detail-box">
@@ -635,6 +679,21 @@ function dashboardHtml(tierName) {
       document.getElementById('cost-windows').textContent = '0 context-windows extended';
     }
 
+    // --- Cache hits & compactions (live counters) ---------------------------
+    var ch = d.cacheHits || { session: 0, total: 0, sessionTokensSaved: 0, totalTokensSaved: 0 };
+    var cp = d.compacts || { session: 0, total: 0 };
+    var ts = d.timeSaved || { compact: { sessionSec: 0, totalSec: 0 }, cacheHit: { sessionSec: 0, totalSec: 0 } };
+    document.getElementById('ch-session').textContent = (ch.session || 0).toLocaleString();
+    document.getElementById('ch-total').textContent = (ch.total || 0).toLocaleString();
+    document.getElementById('ch-tok-session').textContent = (ch.sessionTokensSaved || 0).toLocaleString();
+    document.getElementById('ch-tok-total').textContent = (ch.totalTokensSaved || 0).toLocaleString();
+    document.getElementById('cp-session').textContent = (cp.session || 0).toLocaleString();
+    document.getElementById('cp-total').textContent = (cp.total || 0).toLocaleString();
+    document.getElementById('ts-compact-session').textContent = fmtSec(ts.compact.sessionSec);
+    document.getElementById('ts-compact-total').textContent = fmtSec(ts.compact.totalSec);
+    document.getElementById('ts-cache-session').textContent = fmtSec(ts.cacheHit.sessionSec);
+    document.getElementById('ts-cache-total').textContent = fmtSec(ts.cacheHit.totalSec);
+
     document.getElementById('updated').textContent = 'Updated ' + new Date(d.updatedAt).toLocaleTimeString();
   }
 
@@ -840,9 +899,51 @@ function dashboardHtml(tierName) {
   pollIndex();
   setInterval(pollIndex, 5000);
 
+  // --- Active repos (live cache-hit / compaction stats) ---------------------
+  function fmtSec(s) {
+    s = s || 0;
+    if (s >= 3600) return (s / 3600).toFixed(1) + 'h';
+    if (s >= 60) return Math.round(s / 60) + 'm';
+    if (s >= 1) return s.toFixed(1) + 's';
+    return Math.round(s * 1000) + 'ms';
+  }
+  function renderActiveRepos(d) {
+    d = d || { updatedAt: null, servers: [] };
+    var servers = d.servers || [];
+    var rowsEl = document.getElementById('active-rows');
+    if (!rowsEl) return;
+    if (!servers.length) {
+      rowsEl.innerHTML = '<tr><td colspan="9" class="repo-none">No active repositories.</td></tr>';
+    } else {
+      rowsEl.innerHTML = servers.map(function(r) {
+        var ch = r.cacheHits || { session: 0, total: 0, sessionTokensSaved: 0, totalTokensSaved: 0 };
+        var cp = r.compacts || { session: 0, total: 0 };
+        var ts = r.timeSaved || { compact: { sessionSec: 0, totalSec: 0 }, cacheHit: { sessionSec: 0, totalSec: 0 } };
+        return '<tr>' +
+          '<td title="' + sanitize(r.repoRoot) + '">' + sanitize(r.displayName || r.repoRoot) + '</td>' +
+          '<td>' + sanitize(r.model || '—') + '</td>' +
+          '<td>' + sanitize(r.tier || '—') + '</td>' +
+          '<td class="num">' + (r.contextPct != null ? Math.round(r.contextPct * 100) + '%' : '—') + '</td>' +
+          '<td>' + sanitize(r.state || '—') + '</td>' +
+          '<td class="num">' + (cp.session || 0) + ' / ' + (cp.total || 0) + '</td>' +
+          '<td class="num">' + (ch.session || 0) + ' / ' + (ch.total || 0) + '</td>' +
+          '<td class="num">' + fmtSec(ts.compact.sessionSec) + ' / ' + fmtSec(ts.compact.totalSec) + '</td>' +
+          '<td class="num">' + fmtSec(ts.cacheHit.sessionSec) + ' / ' + fmtSec(ts.cacheHit.totalSec) + '</td>' +
+        '</tr>';
+      }).join('');
+    }
+    var upd = document.getElementById('active-updated');
+    if (upd) upd.textContent = d.updatedAt ? 'Updated ' + new Date(d.updatedAt).toLocaleTimeString() : '';
+  }
+  function pollServers() {
+    fetch('/api/servers').then(function(r) { return r.json(); }).then(renderActiveRepos).catch(function() {});
+  }
+  pollServers();
+  setInterval(pollServers, 5000);
+
   // --- Tab switching ------------------------------------------------------
   var tabs = document.querySelectorAll('.tab');
-  var panels = { current: 'panel-current', all: 'panel-all', summary: 'panel-summary' };
+  var panels = { current: 'panel-current', all: 'panel-all', active: 'panel-active', summary: 'panel-summary' };
   for (var i = 0; i < tabs.length; i++) {
     tabs[i].addEventListener('click', function() {
       var name = this.getAttribute('data-tab');
@@ -855,6 +956,7 @@ function dashboardHtml(tierName) {
         }
       }
       if (name === 'all' || name === 'summary') pollIndex();
+      if (name === 'active') pollServers();
     });
   }
 })();
@@ -1063,6 +1165,37 @@ export async function launchDashboardServer(stateDir) {
             res.end(JSON.stringify(report));
             return;
         }
+        if (req.url === "/api/servers") {
+            try {
+                const idx = readIndex();
+                const nowSec = Math.floor(Date.now() / 1000);
+                const servers = (idx?.repos ?? []).filter((r) => (r.lastSeen ?? 0) >= nowSec - ACTIVE_WINDOW_SEC).map((r) => {
+                    const out = { repoRoot: r.repoRoot, displayName: r.displayName, model: r.modelName, provider: r.providerName, lastSeen: r.lastSeen, lastCompactedAt: r.lastCompactedAt };
+                    try {
+                        const p = join(r.stateDir, "dashboard.json");
+                        if (existsSync(p)) {
+                            const snap = JSON.parse(readFileSync(p, "utf-8"));
+                            out.tier = snap.tier ?? null;
+                            out.contextPct = (snap.context && snap.context.percent != null) ? snap.context.percent : null;
+                            out.state = (snap.session && snap.session.state) || null;
+                            out.cacheHits = snap.cacheHits ?? null;
+                            out.compacts = snap.compacts ?? null;
+                            out.timeSaved = snap.timeSaved ?? null;
+                            out.updatedAt = snap.updatedAt ?? null;
+                        }
+                    }
+                    catch { /* best-effort */ }
+                    return out;
+                }).sort((a, b) => b.lastSeen - a.lastSeen);
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ updatedAt: new Date().toISOString(), servers }));
+            }
+            catch {
+                res.writeHead(500, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "servers_unavailable" }));
+            }
+            return;
+        }
         if (req.url === "/api/events") {
             res.writeHead(200, {
                 "Content-Type": "text/event-stream",

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

@@ -195,6 +195,65 @@ describe("multi-repo /api/index (S19)", () => {
         }
     });
 });
+describe("multi-repo /api/servers (active cache-hit stats)", () => {
+    test("returns active repos with live dashboard.json cache-hit/compaction stats", async () => {
+        const dir = mkdtempSync(join(tmpdir(), "dash-servers-"));
+        const indexDir = mkdtempSync(join(tmpdir(), "index-servers-"));
+        process.env.MEGACOMPACT_INDEX_DIR = indexDir;
+        process.env.MEGACOMPACT_DASHBOARD_PORT = "19323";
+        const { upsertRepoRegistry } = await import("../src/store/sqlite.js");
+        const activeState = mkdtempSync(join(tmpdir(), "srv-active-"));
+        writeFileSync(join(activeState, "dashboard.json"), JSON.stringify({
+            updatedAt: new Date().toISOString(),
+            tier: "high",
+            context: { tokens: 5000, percent: 0.42, contextWindow: 12000 },
+            session: { id: "s1", state: "idle" },
+            cacheHits: { session: 3, total: 7, sessionTokensSaved: 1200, totalTokensSaved: 9000 },
+            compacts: { session: 2, total: 5 },
+            timeSaved: { compact: { sessionSec: 1.5, totalSec: 4 }, cacheHit: { sessionSec: 0.6, totalSec: 4.5 } },
+        }, null, 2));
+        upsertRepoRegistry({ repoRoot: "/home/u/active", displayName: "active", stateDir: activeState, checkpointCount: 4, tokensSaved: 9000, compressedOriginalBytes: 0, lastSeen: Math.floor(Date.now() / 1000), modelName: "gpt-4o", providerName: "OpenAI" }, indexDir);
+        const staleState = mkdtempSync(join(tmpdir(), "srv-stale-"));
+        writeFileSync(join(staleState, "dashboard.json"), JSON.stringify({ updatedAt: new Date().toISOString(), tier: "low" }, null, 2));
+        const longAgo = Math.floor(Date.now() / 1000) - 7 * 86_400;
+        upsertRepoRegistry({ repoRoot: "/home/u/stale", displayName: "stale", stateDir: staleState, checkpointCount: 1, tokensSaved: 100, compressedOriginalBytes: 0, lastSeen: longAgo }, indexDir);
+        const child = spawn(process.execPath, [SERVER_ENTRY, dir], { stdio: "ignore" });
+        try {
+            await waitFor(async () => {
+                try {
+                    const raw = JSON.parse(readFileSync(join(dir, "port.pid"), "utf-8"));
+                    const res = await fetch(`http://localhost:${raw.port}/api/version`);
+                    return res.ok;
+                }
+                catch {
+                    return false;
+                }
+            });
+            const raw = JSON.parse(readFileSync(join(dir, "port.pid"), "utf-8"));
+            const body = (await fetch(`http://localhost:${raw.port}/api/servers`).then((r) => r.json()));
+            assert.equal(body.servers.length, 1, "only the active repo is returned");
+            const s = body.servers[0];
+            assert.equal(s.displayName, "active");
+            assert.equal(s.tier, "high");
+            assert.equal(s.model, "gpt-4o");
+            assert.equal(s.provider, "OpenAI");
+            assert.equal(s.contextPct, 0.42);
+            assert.equal(s.state, "idle");
+            assert.deepEqual(s.cacheHits, { session: 3, total: 7, sessionTokensSaved: 1200, totalTokensSaved: 9000 });
+            assert.deepEqual(s.compacts, { session: 2, total: 5 });
+            const ts = s.timeSaved;
+            assert.equal(ts.compact.sessionSec, 1.5);
+            assert.equal(ts.cacheHit.sessionSec, 0.6);
+        }
+        finally {
+            child.kill("SIGTERM");
+            delete process.env.MEGACOMPACT_INDEX_DIR;
+            delete process.env.MEGACOMPACT_DASHBOARD_PORT;
+            rmSync(dir, { recursive: true, force: true });
+            rmSync(indexDir, { recursive: true, force: true });
+        }
+    });
+});
 // ---------------------------------------------------------------------------
 // Lifecycle integration — launch the compiled server as a real subprocess
 // (the same way the /dashboard command spawns it) and assert the two failure