pi-mega-compact 0.5.1 → 0.6.0

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.6.0` — 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,17 @@ 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-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-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 (live tier, gate, dedup, tokens saved). |
+| `/mega-compat-check` | Detect extension conflicts (duplicate commands / overlapping handlers) across installed pi extensions. |
+
+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 / thresholdTokens`, not a manual setting. The base compaction *threshold* (token budget) is still chosen by the `MEGACOMPACT_TIER` env var at startup (`low`/`medium`/`high`/`ultra`/`mega`, default `low`); `/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-stop` | Stop the dashboard server. |
 
@@ -224,10 +227,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
+ ⚡ high·low v0.6.0 │ 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 +261,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 +291,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 +312,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 +352,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 +379,4 @@ neuralwatt-mcr (pi-extension mechanics). Attribution as design sources only.
 
 ## License
 
-[MIT](./LICENSE)
+[BSD-2-Clause](./LICENSE)

package/dist/extensions/dashboard-server.js

@@ -136,6 +136,8 @@ function readSnapshot(snapshotPath) {
             version: 1,
             updatedAt: null,
             tier: "unknown",
+            presetTier: "unknown",
+            pressure: 0,
             config: { fastGatePct: 80, thresholdTokens: 100_000, anchorUserMessages: 1, preserveRecent: 2, auto: true, autoInlineK: 3 },
             session: { id: null, state: null, persistedThisSession: false, lastCheckpointId: null, lastCompactedFrom: 0 },
             context: { tokens: null, percent: null, contextWindow: 0 },
@@ -261,7 +263,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="version-pill">v${dashboardServerVersion}</span><span class="model-pill" id="hdr-model">—</span></h1>
+<h1><span>mega-compact</span><span class="tier" id="hdr-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>
@@ -323,7 +325,9 @@ function dashboardHtml(tierName) {
   <div class="card">
     <h2>Configuration</h2>
     <div class="conf-grid">
-      <span class="label">Tier</span><span class="value" id="cf-tier">${tierName}</span>
+      <span class="label" title="Live pressure band — climbs low→mega as context fills the window.">Tier (live)</span><span class="value" id="cf-tier">${tierName}</span>
+      <span class="label" title="The env-resolved base compaction preset (low/medium/high/ultra/mega) that set the token threshold.">Preset</span><span class="value" id="cf-preset">—</span>
+      <span class="label" title="Live pressure = currentTokens / thresholdTokens (0–100%).">Pressure</span><span class="value" id="cf-pressure">—</span>
       <span class="label">Threshold</span><span class="value" id="cf-threshold">—</span>
       <span class="label">Fast Gate</span><span class="value" id="cf-gate">—</span>
       <span class="label">Auto</span><span class="value" id="cf-auto">—</span>
@@ -502,7 +506,12 @@ function dashboardHtml(tierName) {
     document.getElementById('cr-status').textContent = (crew.activeAgents > 0)
       ? ('▶ ' + crew.activeAgents + ' running') : 'idle';
 
-    document.getElementById('cf-tier').textContent = d.tier;
+    // S24: headline tier is the LIVE pressure band; the config card shows the
+    // env preset + live pressure ratio so the user sees the system react.
+    document.getElementById('hdr-tier').textContent = d.tier;
+    document.getElementById('cf-tier').textContent = d.tier + ' (live)';
+    document.getElementById('cf-preset').textContent = d.presetTier;
+    document.getElementById('cf-pressure').textContent = Math.round((d.pressure || 0) * 100) + '%';
     document.getElementById('cf-threshold').textContent = d.config.thresholdTokens.toLocaleString();
     document.getElementById('cf-gate').textContent = d.config.fastGatePct + '%';
     document.getElementById('cf-auto').textContent = d.config.auto ? 'enabled' : 'disabled';

package/dist/extensions/mega-commands.js

@@ -12,7 +12,6 @@ import { decompressSmart } from "../src/store/compression.js";
 import { loadMetrics, fpRate, p95 } from "../src/monitoring.js";
 import { C, recentUserQuery } from "./mega-runtime.js";
 import { runCompact, doRecall, doRecallAsync } from "./mega-pipeline.js";
-import { setTier, COMPACT_TIERS } from "./mega-config.js";
 /** Resolve a checkpoint by id (or "recent"/"last") from this session's store. */
 export function findCheckpoint(runtime, sid, ref) {
     const all = listCheckpoints(sid, runtime.currentStateDir);
@@ -117,7 +116,8 @@ export function registerCommands(pi, runtime, config) {
             }
             catch { /* non-fatal */ }
             const crossRepoStr = `${crossRepoInjections} cross-repo injections recorded · ${repoCount} repos indexed`;
-            ctx.ui.notify(`[mega-compact] pct=${pct} tokens=${tokens} tier=${config.tier} fastGate=${config.fastGatePct}% ` +
+            ctx.ui.notify(`[mega-compact] pct=${pct} tokens=${tokens} tier=${runtime.pressureBand} (live) preset=${config.tier} ` +
+                `pressure=${Math.round(runtime.pressure * 100)}% fastGate=${config.fastGatePct}% ` +
                 `threshold=${config.thresholdTokens} auto=${config.auto} autoInline=${config.autoInline}\n` +
                 `[mega-compact] store: ${st.checkpointCount} chkpt · ` +
                 `${st.totalTokenEstimate} tok · last=${st.lastCheckpointId ?? "—"} · ` +
@@ -215,25 +215,7 @@ export function registerCommands(pi, runtime, config) {
                 `• data safety — every compressed region is kept verbatim; nothing is permanently deleted. /mega-restore brings any of it back.`);
         },
     });
-    pi.registerCommand("mega-tier", {
-        description: "Show or change the compaction tier at runtime. Usage: /mega-tier [low|medium|high|ultra|mega]",
-        handler: async (args, ctx) => {
-            const arg = args.trim().toLowerCase();
-            if (!arg) {
-                // Show current tier and available options.
-                ctx.ui.notify(`[mega-compact] current tier: ${config.tier} (${config.thresholdTokens} tok)\n` +
-                    `[mega-compact] available tiers: ${Object.entries(COMPACT_TIERS).map(([k, v]) => `${k}=${v}`).join(", ")}`);
-                return;
-            }
-            if (!(arg in COMPACT_TIERS)) {
-                ctx.ui.notify(`[mega-compact] unknown tier "${arg}". Available: ${Object.keys(COMPACT_TIERS).join(", ")}`);
-                return;
-            }
-            const newTier = arg;
-            setTier(config, newTier);
-            runtime.setStatus(ctx, `mega-compact: tier → ${newTier} (${config.thresholdTokens} tok)`);
-            ctx.ui.notify(`[mega-compact] tier changed to ${newTier} (threshold: ${config.thresholdTokens} tokens)`);
-            runtime.snapshot(ctx);
-        },
-    });
+    // NOTE: /mega-tier was removed in S24. The tier the user sees is now the LIVE
+    // pressure band (low/medium/high/ultra/mega), which climbs automatically as
+    // context fills — there is no manual tier to set. See docs/specs/s24-unified-pressure.md.
 }

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

@@ -384,16 +384,19 @@ const TIER_CASES = [
     ["mega", 10_000_000],
 ];
 for (const [tier, threshold] of TIER_CASES) {
-    test(`tier "${tier}" resolves to a ${threshold}-token threshold`, async () => {
+    test(`tier "${tier}" resolves to a ${threshold}-token threshold (preset; live band shown separately)`, async () => {
         // Keep tier + keep threshold UNSET so the tier (not an explicit number)
         // drives the threshold. harness() would otherwise reset the threshold.
         delete process.env.MEGACOMPACT_THRESHOLD_TOKENS;
         process.env.MEGACOMPACT_TIER = tier;
         const h = harness({ keepTier: true, keepThreshold: true });
+        // tokens=1 against a 2M window → near-zero pressure → live band "low".
         const ctx = h.ctx({ getContextUsage: () => ({ tokens: 1, contextWindow: 2_000_000, percent: 0.01 }) });
         await h.commands["mega-status"].handler("", ctx);
         delete process.env.MEGACOMPACT_TIER;
-        assert.ok(h.notifies.some((n) => n.includes(`tier=${tier}`) && n.includes(`threshold=${threshold}`)), `status should report tier=${tier} threshold=${threshold}`);
+        assert.ok(h.notifies.some((n) => n.includes(`preset=${tier}`) && n.includes(`threshold=${threshold}`)), `status should report preset=${tier} threshold=${threshold}`);
+        // S24: the headline tier is the LIVE pressure band, shown as "tier=low (live)".
+        assert.ok(h.notifies.some((n) => n.includes("tier=low (live)")), "live band reported (low at near-zero pressure)");
     });
 }
 test("explicit MEGACOMPACT_THRESHOLD_TOKENS overrides the tier", async () => {
@@ -403,7 +406,7 @@ test("explicit MEGACOMPACT_THRESHOLD_TOKENS overrides the tier", async () => {
     const ctx = h.ctx({ getContextUsage: () => ({ tokens: 1, contextWindow: 2_000_000, percent: 0.01 }) });
     await h.commands["mega-status"].handler("", ctx);
     delete process.env.MEGACOMPACT_TIER;
-    assert.ok(h.notifies.some((n) => n.includes("tier=custom") && n.includes("threshold=777")), "explicit threshold wins over tier (tier=custom)");
+    assert.ok(h.notifies.some((n) => n.includes("preset=custom") && n.includes("threshold=777")), "explicit threshold wins over tier (preset=custom)");
 });
 // ---- /dashboard commands ----------------------------------------------------
 test("/dashboard-status reports no server when pid file missing", async () => {

package/dist/extensions/mega-config.js

@@ -47,11 +47,13 @@ function resolveThreshold() {
     return { tier, thresholdTokens: COMPACT_TIERS[tier] };
 }
 /**
- * Pressure helpers for adaptive compression (Fix E) live in src/config.ts
- * (pi-agnostic) so unit tests can import them without the pi runtime. Re-export
- * here so the extension has one import surface.
+ * Pressure helpers for adaptive compression live in src/config.ts (pi-agnostic)
+ * so unit tests can import them without the pi runtime. Re-export here so the
+ * extension has one import surface. (S24 unified the previously percentage-only
+ * signal into pressureRatio/pressureBand, which the runtime uses as the single
+ * "how full" signal that drives the tier label, trim depth, and memory cadence.)
  */
-export { pressureFromPct, preserveRecentForPressure } from "../src/config.js";
+export { pressureFromPct, preserveRecentForPressure, pressureRatio, pressureBand, memoryReviewCadence, } from "../src/config.js";
 /** Build the resolved config from env + defaults. */
 export function loadConfig() {
     const { tier, thresholdTokens } = resolveThreshold();
@@ -80,11 +82,12 @@ export function loadConfig() {
         debug: envBool("MEGACOMPACT_DEBUG", false),
     };
 }
-/** Mutate tier + threshold in place (used by /mega-tier at runtime). */
-export function setTier(config, tier) {
-    config.tier = tier;
-    config.thresholdTokens = COMPACT_TIERS[tier];
-}
+/**
+ * Remove a cached tier mutation helper here — the live tier the user sees is the
+ * pressure band (MegaRuntime.pressureBand), and the base preset is env-resolved
+ * at load (loadConfig). The /mega-tier command was removed in S24 so there is no
+ * runtime tier mutation; see the S24 spec (docs/specs/s24-unified-pressure.md).
+ */
 /**
  * Resolve the current repo's git root from a cwd. Returns undefined for a
  * non-git directory (caller falls back to a global state dir).

package/dist/extensions/mega-events.js

@@ -14,7 +14,7 @@ import { runCompact, doRecall, doRecallAsync, piCompactWouldNoop } from "./mega-
 import { recallMemoriesAndInline } from "../src/recall.js";
 import { driveNativeCompaction } from "./mega-compact-driver.js";
 import { computeLiveTrimCut, liveTrimSummaryMessage } from "./mega-trim.js";
-import { pressureFromPct } from "./mega-config.js";
+import { pressureFromPct, memoryReviewCadence } from "./mega-config.js";
 /** Register all pi lifecycle event handlers. */
 export function registerEventHandlers(pi, runtime, config) {
     // ---- Session lifecycle (state reset points) -------------------------------
@@ -158,26 +158,31 @@ export function registerEventHandlers(pi, runtime, config) {
     pi.on("turn_end", async (event, ctx) => {
         runtime.dashboard.event("turn_end", { turnIndex: event.turnIndex });
         runtime.snapshot(ctx);
-        // S20: auto-review the conversation every N turns and persist durable
-        // memories. Best-effort + non-fatal: a review failure must never break the
-        // agent loop. Debounced by memoryReviewInterval turns.
-        if (config.memoryAutoReview && runtime.currentTurn > 0 && runtime.currentTurn % config.memoryReviewInterval === 0) {
-            try {
-                const { reviewConversation } = await import("../src/memory.js");
-                const { applyMemoryOps } = await import("../src/memoryOps.js");
-                const entries = ctx.sessionManager.getEntries();
-                const view = runtime.engineView(entries.flatMap((e) => (e.message ? [e.message] : [])));
-                const ops = reviewConversation(view, []);
-                if (ops.length) {
-                    await applyMemoryOps(ops, runtime.currentStateDir);
-                    // S21.2: a memory op landed in this turn window. The pipeline reads
-                    // this counter after a successful compaction and fires
-                    // `consolidateMemories` only when it's > 0.
-                    runtime.memoriesTouchedThisCompaction += ops.length;
+        // S20+S24: auto-review the conversation and persist durable memories. The
+        // review cadence scales with pressure (memoryReviewCadence): as context
+        // fills, the conversation is reviewed more often so memories keep pace with
+        // faster churn. Best-effort + non-fatal: a review failure must never break
+        // the agent loop. Debounced by the pressure-adjusted interval.
+        if (config.memoryAutoReview && runtime.currentTurn > 0) {
+            const cadence = memoryReviewCadence(runtime.pressureBand, config.memoryReviewInterval);
+            if (runtime.currentTurn % cadence === 0) {
+                try {
+                    const { reviewConversation } = await import("../src/memory.js");
+                    const { applyMemoryOps } = await import("../src/memoryOps.js");
+                    const entries = ctx.sessionManager.getEntries();
+                    const view = runtime.engineView(entries.flatMap((e) => (e.message ? [e.message] : [])));
+                    const ops = reviewConversation(view, []);
+                    if (ops.length) {
+                        await applyMemoryOps(ops, runtime.currentStateDir);
+                        // S21.2: a memory op landed in this turn window. The pipeline reads
+                        // this counter after a successful compaction and fires
+                        // `consolidateMemories` only when it's > 0.
+                        runtime.memoriesTouchedThisCompaction += ops.length;
+                    }
+                }
+                catch {
+                    /* non-fatal — auto-review must not break the turn loop */
                 }
-            }
-            catch {
-                /* non-fatal — auto-review must not break the turn loop */
             }
         }
     });

package/dist/extensions/mega-pipeline.js

@@ -133,6 +133,28 @@ function doCompact(view, keepFrom, opts, sid, config, pi, ctx, runtime) {
             /* non-fatal */
         }
     }
+    // S24 review-on-compact: when pressure is high, the just-compacted region is
+    // exactly the context worth remembering, so review it immediately rather than
+    // waiting for the next turn-cadence tick. Fire-and-forget (doCompact is sync):
+    // best-effort + non-fatal, paralleling the consolidate pass above. Only fires
+    // above the `high` band so low-pressure compactions don't pay the review cost.
+    if (!result.deduped && config.memoryAutoReview && runtime.pressureBand !== "low" && runtime.pressureBand !== "medium") {
+        void (async () => {
+            try {
+                const { reviewConversation } = await import("../src/memory.js");
+                const { applyMemoryOps } = await import("../src/memoryOps.js");
+                const ops = reviewConversation(view, []);
+                if (ops.length) {
+                    await applyMemoryOps(ops, runtime.currentStateDir);
+                    runtime.memoriesTouchedThisCompaction += ops.length;
+                    runtime.pushTicker(`${C.green}🧠${C.reset} reviewed ${ops.length} memory op${ops.length === 1 ? "" : "s"} (pressure)`);
+                }
+            }
+            catch {
+                /* non-fatal — review-on-compact must never break the compaction */
+            }
+        })();
+    }
     // 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, {

package/dist/extensions/mega-runtime.js

@@ -17,7 +17,7 @@ import { toEngineMessages } from "../src/adapt.js";
 import { normalizeSessionId } from "../src/store.js";
 import { Logger } from "../src/log.js";
 import { recordModelSnapshot, latestModelSnapshot, upsertRepoRegistry, recordRepoModel } from "../src/store/sqlite.js";
-import { repoStateDir, resolveRepoRoot } from "./mega-config.js";
+import { repoStateDir, resolveRepoRoot, pressureRatio, pressureFromPct, pressureBand } from "./mega-config.js";
 import { Dashboard } from "./mega-dashboard.js";
 export const STATUS_KEY = "mega-compact";
 export const WIDGET_KEY = "mega-compact-stats";
@@ -120,6 +120,24 @@ export class MegaRuntime {
     lastCtxTokens = null;
     lastCtxPercent = null;
     lastCtxWindow = 0;
+    /**
+     * Live 0–1 pressure: how full the context window is relative to the compaction
+     * threshold. Computed from the most recent context event the runtime already
+     * tracks (token count when available — the direct signal — otherwise the usage
+     * percentage). This is the single "how full" number every subsystem reads; the
+     * toolbar/dashboard tier label is `pressureBand` over this, so it climbs
+     * low→mega as context rises (S24). Always finite + in [0,1].
+     */
+    get pressure() {
+        if (this.lastCtxTokens != null && this.lastCtxTokens > 0 && this.config.thresholdTokens > 0) {
+            return pressureRatio(this.lastCtxTokens, this.config.thresholdTokens);
+        }
+        return pressureFromPct(this.lastCtxPercent);
+    }
+    /** Live discrete pressure band (low/medium/high/ultra/mega) over `pressure`. */
+    get pressureBand() {
+        return pressureBand(this.pressure);
+    }
     constructor(config) {
         this.config = config;
         this.store = new VectorStore({ dedupSim: config.dedupSim, stateDir: config.stateDir });
@@ -190,7 +208,11 @@ export class MegaRuntime {
         this.dashboard.snapshot({
             version: 1,
             updatedAt: new Date().toISOString(),
-            tier: this.config.tier,
+            // S24: the headline tier is the LIVE pressure band; the env preset is kept
+            // alongside as presetTier so the dashboard can show both.
+            tier: this.pressureBand,
+            presetTier: this.config.tier,
+            pressure: this.pressure,
             config: {
                 fastGatePct: this.config.fastGatePct,
                 thresholdTokens: this.config.thresholdTokens,
@@ -236,6 +258,11 @@ export class MegaRuntime {
             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}%` : "?%";
+            // S24: the tier label is the LIVE pressure band (low/medium/high/ultra/
+            // mega), not the static env preset. It climbs as context fills, so the
+            // user can see the system react. The base preset is shown as a dim suffix.
+            const liveBand = this.pressureBand;
+            const tierLabel = `${C.bold}${liveBand}${C.reset}${C.gray}·${this.config.tier}${C.reset}`;
             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
@@ -258,7 +285,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} v${C.bold}${ownVersion()}${C.reset} │ ${tokStr}/${maxStr} tokens (${C.bold}${pctStr}${C.reset}) │ ${st.checkpointCount} saved${agentStr}${turnStr}`,
+                ` ${C.amber}⚡ ${tierLabel}${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.
@@ -267,7 +294,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