omp-vcc 0.1.2 → 0.1.5

package/README.md

@@ -1,105 +1,113 @@
-# @zhulinchng/omp-vcc — Algorithmic VCC Compaction for oh-my-pi
+# Algorithmic VCC Compaction for oh-my-pi
 
-> Fast, deterministic, lossless compaction — no LLM calls. Port of [`sting8k/pi-vcc`](https://github.com/sting8k/pi-vcc) (`@0.7.0`) into [oh-my-pi](https://github.com/can1357/oh-my-pi), inspired by [`lllyasviel/VCC`](https://github.com/lllyasviel/VCC) and paper [`arxiv:2603.29678`](https://arxiv.org/pdf/2603.29678) *View-oriented Conversation Compiler for Agent Trace Analysis* (Zhang & Agrawala, 2026-03-31).
+> Fast, deterministic, lossless compaction. No LLM calls. Port of [`sting8k/pi-vcc@0.7.0`](https://github.com/sting8k/pi-vcc) into [oh-my-pi](https://github.com/can1357/oh-my-pi). Paper [`arxiv:2603.29678`](https://arxiv.org/pdf/2603.29678) (Zhang & Agrawala).
 
 ## Quick start
 
-> **New here?** → [`docs/setup.md`](docs/setup.md) — 5-minute install with prerequisites, 4 install options (link / npm / git), verify, first `/omp-vcc`, recall, config, and troubleshooting. The commands below are the tldr.
-
 ```sh
-# from source (local)
-omp plugin link /Users/zhu/code/projects/omp-vcc
+omp plugin link /Users/zhu/code/projects/omp-vcc        # local
+omp plugin install omp-vcc                               # npmjs, no auth
+omp plugin install @zhulinchng/omp-vcc                   # GitHub Packages, needs PAT
+omp plugin install github:zhulinchng/omp-vcc             # git, latest main
 omp plugin list --json | jq '.[] | select(.name|contains("omp-vcc"))'
-
-# from npm (unscoped)
-omp plugin install omp-vcc
-
-# from GitHub Packages (scoped, requires auth — see below)
-omp plugin install @zhulinchng/omp-vcc
-
-# from git
-omp plugin install github:zhulinchng/omp-vcc
 ```
 
-## What you get
+New here → [`docs/setup.md`](docs/setup.md).
 
-- **Auto** threshold/overflow compaction via `session_before_compact` hook — no LLM summary, 30–470 ms, 35–99% reduction.
-- **Manual** `/omp-vcc [keep:N] [focus]` (and `/pi-vcc` alias) — e.g. `/omp-vcc keep:2 fix auth` keeps last 2 user turns.
-- **Recall** `vcc_recall({query:"redis cache", scope:"all", page:1})` or `/vcc-recall hook|inject scope:all page:2` — ranked regex → TF-IDF OR, 5/page, `mode:'touched'` and `#N:path` drill-down.
+## What you get
 
+- **Manual** `/omp-vcc [keep:N] [focus]` (`/pi-vcc` alias) — compact only, single-line toast `90k→22k` — e.g. `/omp-vcc keep:2 fix auth` (detailed savings via `/vcc-stats`).
+- **Recall** `vcc_recall({query, scope, page, mode, expand})` + `/vcc-recall` — regex → TF-IDF OR, 5/page, `mode:'touched'`, `#N:path` drill-down.
+- **Savings** toast `90k→22k (76% saved)` single line (inline `Last compaction` detail removed; use `/vcc-stats`), divider, `/vcc-stats` + `vcc_stats` tool (50-capped history, per-pi), `details.savings` persisted, `/tmp/omp-vcc-debug.json`.
 ## Commands
 
-| Command | Description |
-| --- | --- |
-| `/omp-vcc [keep:N] [focus]` | Algorithmic compaction, smart-keep may boost `keep:1` to keep more when tail small (5 k → 25 k). `keep:0` compacts all. |
-| `/pi-vcc` | Alias for migration |
-| `/vcc-recall [query] [scope:all] [page:N]` | Search compacted history (V_adapt). Plain keywords best. |
-| `/pi-vcc-recall` | Alias |
+| `/omp-vcc [keep:N] [focus]` | Compact only. `keep:0` = all. Smart-keep boosts `keep:1` (5k→25k) unless explicit. Toast single line; detail via `/vcc-stats`. |
+| `/pi-vcc` | Legacy alias for `/omp-vcc` |
+| `/vcc-recall [query] [scope:all] [page:N] [mode:touched]` | Search compacted history |
+| `/pi-vcc-recall` | Legacy alias for `/vcc-recall` |
+| `/vcc-stats [history\|all]` | Last savings + history table (single, no alias) |
 
-Tool `vcc_recall` mirrors the command, plus `expand:[indices]` and `mode:'touched'` for file index.
+Tools: `vcc_recall`, `vcc_stats` (approval `read`). Extension-only — no `commands/*.md` file slash commands (avoids duplicate `/omp-vcc`).
 
 ## Configuration
 
-File `~/.omp/omp-vcc/config.json` (XDG-aware: `$OMP_VCC_CONFIG_PATH` > `$PI_VCC_CONFIG_PATH` (legacy) > `$OMP_DIR`/`$PI_CODING_AGENT_DIR` > `~/.omp/omp-vcc/config.json`, migrates legacy `~/.pi/agent/pi-vcc-config.json`):
+File `~/.omp/omp-vcc/config.json` — XDG: `$OMP_VCC_CONFIG_PATH` > `$PI_VCC_CONFIG_PATH` > `$OMP_DIR`/`$PI_CODING_AGENT_DIR` > `~/.omp/omp-vcc/config.json` (migrates `~/.pi/agent/pi-vcc-config.json` once).
 
 ```json
 {
+  "vccEnabled": true,
   "overrideDefaultCompaction": true,
   "smartKeepTail": true,
   "continueAfterThresholdCompact": true,
-  "debug": false
+  "debug": false,
+  "chainShakeHint": false
 }
 ```
 
+| Flag | Default | Effect |
+|---|---|---|
+| `vccEnabled` | `true` | Master switch. `false` = no interception. |
+| `overrideDefaultCompaction` | `true` | `true` = VCC handles threshold/overflow. `false` = host `methodOrder` handles them; `/omp-vcc` still works. |
+| `smartKeepTail` | `true` | Grow `keep:1` when tail <5k (cap 25k). Explicit `keep:N` never boosted. |
+| `continueAfterThresholdCompact` | `true` | Invisible-continue (`omp-vcc-auto-continue`) after threshold compact. |
+| `debug` | `false` | Write `/tmp/omp-vcc-debug.json` per compaction. |
+| `chainShakeHint` | `false` | Eager post-VCC `shake` chain. Host rescue already auto-shakes on dead-end; this forces it. |
+
+Toggle live: `omp config set plugins."@zhulinchng/omp-vcc".debug true` or `/settings` → `@zhulinchng/omp-vcc`. File is source of truth; `ctx.settings` overlays at runtime.
+
 ## How it works
 
-VCC compiles the raw JSONL trace via **lex → parse IR → monotonic line assignment → view lowering** into three views sharing one coordinate system:
+VCC compiles JSONL trace via **lex → parse IR → monotonic line assignment → view lowering** into `V_full` (identity), `V_ui` (5 sections + ranked brief), `V_adapt(b,ρ)` (recall). Pointer invariant `V_ui → V_full[s:e]` via `(#N)` refs.
 
-- `V_full` identity (defines coordinates)
-- `V_ui` one-line tool summaries with pointers (`* Read "src/pets.py" (file.txt:18-20)`)
-- `V_adapt(b, ρ)` projection via predicate `ρ` preserving headers/role tags and `(f:s-e)` pointers, two transposed modalities (document vs index oriented)
+```
+Calibrate cpt → SmartKeep → BuildOwnCut → Normalize → FilterNoise → BuildSections → Brief (1100→2000 tok, 120 lines) → Merge
+```
+
+See [`docs/harness.md`](docs/harness.md) for host impact and [`docs/architecture.md`](docs/architecture.md) for pipeline.
+
+## Combining with shake and snapcompact
 
-`omp-vcc` implements `V_ui` as the structured summary (5 sections + ranked brief transcript) and `V_adapt` as `vcc_recall`. Pointer invariant `V_ui → V_full[s:e]` holds structurally. Diagrams and pipeline in [`docs/architecture.md`](docs/architecture.md); paper mapping in [`docs/paper-notes.md`](docs/paper-notes.md); setup in [`docs/setup.md`](docs/setup.md).
+VCC summarizes **history**; `shake` elides `artifact://` blocks in **kept tail** (disjoint); `snapcompact` is an alternative history archiver (vision bitmaps, needs `model.input includes "image"`). One `CompactionEntry` per trigger — combos are additive or sequential, never double-summarization.
 
-## Related work
+| Trigger | `override` | Result |
+|---|---|---|
+| threshold, `override:true` (default) | VCC handles; host auto-shakes if still over band (`#rescueCompactionDeadEnd`) | VCC + shake if dead-end |
+| threshold, `override:false` | Host walks `methodOrder` (`remote→snapcompact→handoff→shake→soft`) | VCC → snapcompact/shake fallback |
+| `/omp-vcc keep:2` | Always VCC (sentinel `__omp_vcc__`) | VCC |
+| `/omp-vcc` then `/compact snapcompact` | Sequential | VCC entry, then snapcompact entry |
 
-- **pi-vcc** — TypeScript algorithmic compactor, zero LLM, `RANKED_BRIEF_BUDGET_TOKENS=1100` ceil 2000, `charsPerBlock 15`
-- **VCC** — Python `VCC.py` adaptive/transposed views, `SEP`, `match_lines`, `_tokenize`, `_trunc`, projection model
-- **Paper** — AppWorld evaluation: +1.1–4.2 task_goal points, ½–⅔ token halving, smaller memory
+Additive VCC+shake is automatic. Eager chain: `chainShakeHint:true`. Explicit mode (`snapcompact`/`shake`/`soft`/…) bypasses VCC even when `override:true` (`hook.ts:733`). Full table: [`docs/setup.md`](docs/setup.md) + [`docs/harness.md §8`](docs/harness.md#8-working-with-existing-compaction-strategies).
 
-## Develop
+## Development
 
-```bash
-omp plugin link .
-omp plugin doctor
+```sh
 bunx tsc --noEmit
-bun run smoke       # or bun run scripts/smoke.ts
-bun test
+bun test                  # 515 tests, 48 files, 1443 expects, 0 fail
+bun test tests/e2e --timeout 120000  # 111 E2E
+bun run smoke             # 9 checks: 3 hooks + 4 cmds + 2 tools + pipeline
+omp plugin link . && omp plugin doctor
 ```
 
-Capabilities: `extension`, `skill`, `command` — entry `extensions/main.ts`.
+`type:module`, `allowImportingTsExtensions`, `// @ts-nocheck` on vendored `extensions/vcc-core/**`, zero `dist/`. `prepublishOnly` runs `tsc && test && smoke`.
 
 ## Verification
 
 ```sh
-bunx tsc --noEmit
-bun test          # 310 tests across 33 files, 768 expects
-bun run smoke     # ok: session_before_compact hooked, vcc_recall registered
-omp plugin link /Users/zhu/code/projects/omp-vcc && omp plugin doctor
+bunx tsc --noEmit && bun test && bun run smoke
+omp -e @zhulinchng/omp-vcc
+/omp-vcc keep:1   # expect [Session Goal] + toast omp-vcc: kept 1/2 turns
+/vcc-stats        # table + history
+cat /tmp/omp-vcc-debug.json  # when debug:true
 ```
 
-In a live `omp` session: `/omp-vcc keep:1` shows `[Session Goal]` toast `omp-vcc: kept 1/5 turns, ~2.1k tok`; with `debug:true` check `/tmp/omp-vcc-debug.json`. Full proof matrix and mermaid flows in [`docs/verification.md`](docs/verification.md).
-## Publish
+Full matrix: [`docs/verification.md`](docs/verification.md). Harness map: [`docs/harness.md §9`](docs/harness.md#9-verification-map-claim--evidence).
+
+## Docs
+
+[`setup`](docs/setup.md) · [`configuration`](docs/configuration.md) · [`architecture`](docs/architecture.md) · [`harness`](docs/harness.md) · [`verification`](docs/verification.md) · [`omp-compaction`](docs/omp-compaction.md) · [`omp-snapcompact`](docs/omp-snapcompact.md) · [`paper-notes`](docs/paper-notes.md) · [`PUBLISHING`](docs/PUBLISHING.md)
 
-- npmjs (unscoped): `npm publish --registry https://registry.npmjs.org --access public` (package `omp-vcc`)
-- GitHub Packages (scoped): `npm publish --registry https://npm.pkg.github.com` (package `@zhulinchng/omp-vcc`, needs `GITHUB_TOKEN` with `read:packages, write:packages`)
-- Consumer GPR auth: add to `~/.npmrc`:
-  ```
-  @zhulinchng:registry=https://npm.pkg.github.com
-  //npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT
-  ```
-- Marketplace: add an entry to `.omp-plugin/marketplace.json` (see `plugin-skill/assets/templates/marketplace-entry.json.template`).
+Publishing: `npm publish --access public` (unscoped `omp-vcc`), `gh release create vX.Y.Z` → GPR (`@zhulinchng/omp-vcc`). Consumer GPR auth: `@zhulinchng:registry=https://npm.pkg.github.com`.
 
 ## License
 
-MIT — pi-vcc core files retain original MIT.
+MIT

package/extensions/main.ts

@@ -6,14 +6,20 @@
 
 import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
 import { scaffoldSettings } from "./vcc-core/core/settings";
+import { migrateStalePluginEntries } from "./vcc-core/core/migrate-stale";
+import { loadAllMessages } from "./vcc-core/core/load-messages";
 import {
   registerBeforeCompactHook,
   PI_VCC_COMPACT_INSTRUCTION,
   OMP_VCC_COMPACT_INSTRUCTION,
   getLastCompactionStats,
+  getCompactionHistory,
+  formatLastStatsDetail,
+  formatStatsTable,
   scheduleCompactionStatsNotify,
+  registerVccStatsTool as registerVccStatsToolHook,
+  registerVccStatsCommand as registerVccStatsCommandHook,
 } from "./vcc-core/hook";
-import { loadAllMessages } from "./vcc-core/core/load-messages";
 import { searchEntriesDetailed, getTouchedFiles } from "./vcc-core/core/search-entries";
 import { formatRecallOutput, formatTouchedOutput } from "./vcc-core/core/format-recall";
 import { getActiveLineageEntryIds } from "./vcc-core/core/lineage";
@@ -40,9 +46,11 @@ const parseRecallCommandArgs = (
 
 const DEFAULT_RECENT = 25;
 const PAGE_SIZE = 5;
-
 export default function (pi: ExtensionAPI): void {
   scaffoldSettings();
+  try {
+    migrateStalePluginEntries();
+  } catch {}
   registerBeforeCompactHook(pi);
 
   // ── vcc_recall tool — implements VCC V_adapt via rho predicate (paper §2.1 eq.2) ──
@@ -152,27 +160,27 @@ export default function (pi: ExtensionAPI): void {
       return { content: [{ type: "text", text: output }], details: undefined };
     },
   } as unknown as Parameters<ExtensionAPI["registerTool"]>[0]);
+  // ── vcc_stats tool — stats surface for savings (paper § verification) ──
+  registerVccStatsToolHook(pi);
 
-  // ── /omp-vcc command — manual algorithmic compaction (V_ui) ──
   pi.registerCommand("omp-vcc", {
     description: "Compact conversation with omp-vcc structured summary (keep:N + optional focus)",
     handler: async (args: string, ctx: unknown) => {
       const c = ctx as {
         compact: (instructions?: string) => Promise<void>;
         ui: { notify: (msg: string, level?: string) => void };
+        sessionManager?: { getSessionFile?: () => string | undefined };
       };
       const parsed = parseKeepAndPrompt(args);
       const keep = parsed.keepUserTurns;
       const followUpPrompt = parsed.followUpPrompt;
       const customInstructions = buildOmpCustomInstructions(keep);
-      // Also accept pi sentinel for legacy: map keep via buildPiVcc if needed? Use omp.
-      // Notify before compact for UX parity with pi-vcc
       try {
         c.ui.notify(`omp-vcc: compacting with keep:${keep ?? 1}${followUpPrompt ? ` + focus` : ""}...`, "info");
       } catch {}
       try {
         await c.compact(customInstructions);
-        const stats = getLastCompactionStats();
+        const stats = getLastCompactionStats(pi);
         if (stats) {
           scheduleCompactionStatsNotify(c as unknown as { ui: { notify: (msg: string, level?: string) => void } }, stats);
         } else {
@@ -209,7 +217,7 @@ export default function (pi: ExtensionAPI): void {
       const customInstructions = buildPiVccCustomInstructions(keep);
       try {
         await c.compact(customInstructions);
-        const stats = getLastCompactionStats();
+        const stats = getLastCompactionStats(pi);
         if (stats) scheduleCompactionStatsNotify(c as unknown as { ui: { notify: (msg: string, level?: string) => void } }, stats);
         else try { c.ui.notify("Compacted with pi-vcc (via omp-vcc)", "info"); } catch {}
         if (followUpPrompt) {
@@ -309,11 +317,15 @@ export default function (pi: ExtensionAPI): void {
       const header = totalPages > 1 ? `Page ${page}/${totalPages} (${hits.length} total matches${scopeSuffix}${truncationNote})` : `${hits.length} matches${scopeSuffix}${truncationNote}`;
       const footer = page < totalPages ? `\n--- /pi-vcc-recall ${query}${scopeArg} page:${page + 1} ---` : "";
       const output = formatRecallOutput(pageResults, query, header) + footer;
+
       try { piAny.sendMessage?.({ customType: "vcc-recall", content: output, display: true }, { triggerTurn: false }); } catch {}
     },
   });
+  // ── /vcc-stats commands — show savings table (PR3) ──
+  registerVccStatsCommandHook(pi);
+
 }
 // ── Re-exports for pi-vcc test compatibility (not dead: tests import via hook directly,
 // but external consumers and the `vcc-recall` shim may import via main) ──
-export { registerBeforeCompactHook, PI_VCC_COMPACT_INSTRUCTION, OMP_VCC_COMPACT_INSTRUCTION, getLastCompactionStats, scheduleCompactionStatsNotify, formatCompactionStats, AUTO_CONTINUE_CUSTOM_TYPE, LEGACY_AUTO_CONTINUE_CUSTOM_TYPE, invalidExpandIndices, registerRecallTool, registerVccRecallCommand, registerPiVccCommand } from "./vcc-core/hook";
+export { registerBeforeCompactHook, PI_VCC_COMPACT_INSTRUCTION, OMP_VCC_COMPACT_INSTRUCTION, getLastCompactionStats, getCompactionHistory, formatCompactionStats, formatStatsTable, formatLastStatsDetail, scheduleCompactionStatsNotify, AUTO_CONTINUE_CUSTOM_TYPE, LEGACY_AUTO_CONTINUE_CUSTOM_TYPE, invalidExpandIndices, registerRecallTool, registerVccRecallCommand, registerPiVccCommand, registerVccStatsTool, registerVccStatsCommand, clearCompactionHistoryForTests } from "./vcc-core/hook";
 export { buildPiVccCustomInstructions, parseKeepAndPrompt } from "./vcc-core/core/compact-args";

package/extensions/vcc-core/core/migrate-stale.ts

@@ -0,0 +1,162 @@
+// @ts-nocheck
+// One-time migration: remove stale @zhu/omp-vcc lock+symlink left by renames.
+// correctly installed `omp-vcc` or npm `dependencies` entries (real dirs).
+// Mirrors scripts/uninstall-reset.js:cleanupStalePluginEntries.
+
+import * as fsSync from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const HISTORIC = ["@zhu/omp-vcc", "@zhulinchng/omp-vcc"];
+const CURRENT = "omp-vcc";
+
+function readJson(p: string): unknown | null {
+  try {
+    return JSON.parse(fsSync.readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function isSymlink(p: string): boolean {
+  try {
+    return fsSync.lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+export function migrateStalePluginEntries(home?: string): string {
+  const baseHome = home || homedir();
+  const pluginsDir = join(baseHome, ".omp", "plugins");
+  const lockPath = join(pluginsDir, "omp-plugins.lock.json");
+  const pkgPath = join(pluginsDir, "package.json");
+  const nm = join(pluginsDir, "node_modules");
+
+  const lockRaw = readJson(lockPath) as { plugins?: Record<string, unknown>; settings?: Record<string, unknown> } | null;
+  if (!lockRaw || typeof lockRaw !== "object") return "no-lock";
+
+  const pkgRaw = readJson(pkgPath) as { dependencies?: Record<string, string> } | null;
+  const deps: Record<string, string> = (pkgRaw && typeof pkgRaw.dependencies === "object" && pkgRaw.dependencies) || {};
+
+  const pluginKeys: string[] = lockRaw.plugins ? Object.keys(lockRaw.plugins) : [];
+  const ompKeys = pluginKeys.filter((k) => k.includes("omp-vcc"));
+  const candidates = new Set([...ompKeys, ...HISTORIC, CURRENT]);
+
+  let removedLocks: string[] = [];
+  let removedLinks: string[] = [];
+
+  const getPkgName = (name: string): string | null => {
+    const j = readJson(join(nm, name, "package.json")) as { name?: string } | null;
+    return j && typeof j.name === "string" ? j.name : null;
+  };
+
+  const getReal = (name: string): string | null => {
+    const p = join(nm, name);
+    if (!isSymlink(p)) return null;
+    try {
+      return fsSync.realpathSync(p);
+    } catch {
+      return null;
+    }
+  };
+
+  const realToKeys = new Map<string, string[]>();
+  for (const k of ompKeys) {
+    const rp = getReal(k);
+    if (!rp) continue;
+    const list = realToKeys.get(rp) || [];
+    list.push(k);
+    realToKeys.set(rp, list);
+  }
+
+  for (const k of [...ompKeys]) {
+    if (k in deps) continue;
+    const pkgName = getPkgName(k);
+    if (pkgName && pkgName !== k) {
+      const isHistoric = HISTORIC.includes(k) || k !== CURRENT;
+      if (isHistoric) {
+        const p = join(nm, k);
+        if (isSymlink(p)) {
+          try {
+            fsSync.rmSync(p, { force: true });
+            removedLinks.push(k);
+            if (k.startsWith("@")) {
+              const scopeDir = join(nm, k.split("/")[0]!);
+              try {
+                if (fsSync.readdirSync(scopeDir).length === 0) fsSync.rmSync(scopeDir, { force: true });
+              } catch {}
+            }
+          } catch {}
+        }
+        if (lockRaw.plugins && (lockRaw.plugins as Record<string, unknown>)[k]) {
+          delete (lockRaw.plugins as Record<string, unknown>)[k];
+          removedLocks.push(k);
+        }
+        if (lockRaw.settings && (lockRaw.settings as Record<string, unknown>)[k]) delete (lockRaw.settings as Record<string, unknown>)[k];
+      }
+    }
+  }
+
+  for (const [, keys] of realToKeys) {
+    if (keys.length <= 1) continue;
+    let keeper: string | null = null;
+    for (const k of keys) {
+      if (getPkgName(k) === k) {
+        keeper = k;
+        break;
+      }
+    }
+    if (!keeper) keeper = keys.includes(CURRENT) ? CURRENT : keys[0]!;
+    for (const k of keys) {
+      if (k === keeper) continue;
+      if (k in deps) continue;
+      const p = join(nm, k);
+      if (isSymlink(p)) {
+        try {
+          fsSync.rmSync(p, { force: true });
+          if (!removedLinks.includes(k)) removedLinks.push(k);
+          if (k.startsWith("@")) {
+            const scopeDir = join(nm, k.split("/")[0]!);
+            try {
+              if (fsSync.readdirSync(scopeDir).length === 0) fsSync.rmSync(scopeDir, { force: true });
+            } catch {}
+          }
+        } catch {}
+      }
+      if (lockRaw.plugins && (lockRaw.plugins as Record<string, unknown>)[k]) {
+        delete (lockRaw.plugins as Record<string, unknown>)[k];
+        if (!removedLocks.includes(k)) removedLocks.push(k);
+      }
+      if (lockRaw.settings && (lockRaw.settings as Record<string, unknown>)[k]) delete (lockRaw.settings as Record<string, unknown>)[k];
+    }
+  }
+
+  for (const cand of candidates) {
+    const p = join(nm, cand);
+    if (!isSymlink(p)) continue;
+    const hasLock = !!(lockRaw.plugins && (lockRaw.plugins as Record<string, unknown>)[cand]);
+    if (hasLock) continue;
+    const pkgName = getPkgName(cand);
+    if (pkgName === CURRENT || pkgName === "@zhu/omp-vcc" || pkgName === "@zhulinchng/omp-vcc") {
+      try {
+        fsSync.rmSync(p, { force: true });
+        if (!removedLinks.includes(cand)) removedLinks.push(cand);
+        if (cand.startsWith("@")) {
+          const scopeDir = join(nm, cand.split("/")[0]!);
+          try {
+            if (fsSync.readdirSync(scopeDir).length === 0) fsSync.rmSync(scopeDir, { force: true });
+          } catch {}
+        }
+      } catch {}
+    }
+  }
+
+  if (removedLocks.length > 0 || removedLinks.length > 0) {
+    try {
+      fsSync.writeFileSync(lockPath, JSON.stringify(lockRaw, null, 2));
+    } catch {}
+    return `migrated locks:${removedLocks.join(",") || "none"} links:${removedLinks.join(",") || "none"}`;
+  }
+  return "no-stale";
+}

package/extensions/vcc-core/core/settings.ts

@@ -56,6 +56,16 @@ export interface PiVccSettings {
   continueAfterThresholdCompact: boolean;
   /** Write debug snapshot to /tmp/omp-vcc-debug.json on each compaction. */
   debug: boolean;
+  /**
+   * When true, after a successful VCC threshold/overflow compaction, eagerly
+   * trigger a follow-up shake via ctx.compact when the host rescue would not.
+   * Default false: host's #rescueCompactionDeadEnd already runs shake elide
+   * automatically when VCC didn't create enough headroom, and leaving shake in
+   * methodOrder covers that case without a second entry. Set true only if you
+   * want a chained shake even when VCC already made headroom (costs a second
+   * CompactionEntry).
+   */
+  chainShakeHint: boolean;
 }
 
 export const DEFAULT_SETTINGS: PiVccSettings = {
@@ -64,6 +74,7 @@ export const DEFAULT_SETTINGS: PiVccSettings = {
   smartKeepTail: true,
   continueAfterThresholdCompact: true,
   debug: false,
+  chainShakeHint: false,
 };
 
 const readJson = (path: string): Record<string, unknown> | null => {

package/extensions/vcc-core/details.ts

@@ -2,11 +2,20 @@
 import type { CompactionReason } from "./types";
 
 export interface PiVccCompactionDetails {
-  compactor: "pi-vcc";
+  compactor: "pi-vcc" | "omp-vcc";
   version: number;
   sections: string[];
   sourceMessageCount: number;
   previousSummaryUsed: boolean;
   reason?: CompactionReason;
   willRetry?: boolean;
+  savings?: {
+    tokensBefore: number;
+    summaryChars: number;
+    summaryTokensEst: number;
+    keptTokensEst: number;
+    tokensAfterEst: number;
+    tokensSavedEst: number;
+    savedPercentEst: number;
+  };
 }