omp-vcc 0.1.4 → 0.1.6

package/README.md

@@ -1,48 +1,37 @@
-# @zhulinchng/omp-vcc — Algorithmic VCC Compaction for oh-my-pi
+# Algorithmic VCC Compaction for oh-my-pi
 
-> Fast, deterministic, lossless compaction with 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)
-
 ```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.
-- **Savings observability** — toast `90.0k→22.0k (76% saved, ~68.0k)`, divider `── compacted · 90K→22K ·`, `vcc_stats` tool + `/vcc-stats` table + `details.savings` + `/tmp/omp-vcc-debug.json` (authoritative `tokensAfter` from host).
+## 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. Add `--stats` / `stats` to show last savings without compacting. |
-| `/pi-vcc` | Alias for migration |
-| `/vcc-recall [query] [scope:all] [page:N]` | Search compacted history (V_adapt). Plain keywords best. |
-| `/pi-vcc-recall` | Alias |
-| `/vcc-stats [history\|all]` | Show last compaction `Before→After/Saved/Kept` + history table (from `CompactionStats` 50-capped). |
-| `/omp-vcc-stats` | Alias for `/vcc-stats` |
+| `/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) |
+
+Tools: `vcc_recall`, `vcc_stats` (approval `read`). Extension-only — no `commands/*.md` file slash commands (avoids duplicate `/omp-vcc`).
 
-Tool `vcc_recall` mirrors the command, plus `expand:[indices]` and `mode:'touched'` for file index. Tool `vcc_stats({history:true})` mirrors `/vcc-stats` (approval `read`), same 50-capped table.
 ## 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
 {
@@ -50,170 +39,74 @@ File `~/.omp/omp-vcc/config.json` (XDG-aware: `$OMP_VCC_CONFIG_PATH` > `$PI_VCC_
   "overrideDefaultCompaction": true,
   "smartKeepTail": true,
   "continueAfterThresholdCompact": true,
-  "debug": false
+  "debug": false,
+  "chainShakeHint": false
 }
 ```
 
-## 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:
-
-- `V_full` identity — every message verbatim, defines coordinates `L`
-- `V_ui` one-line tool summaries with stable 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)
-
-`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.
-
-### VCC algorithm (30–470 ms)
-
-Traditional compaction ships the whole history to a remote LLM and waits seconds. `omp-vcc` never calls a model: it reuses `branchEntries` already in memory, calibrates token size, cuts, normalizes, and ranks locally.
-
-```mermaid
-flowchart TB
-  subgraph VCC["omp-vcc — local, deterministic"]
-    A["branchEntries\nin memory"] --> B["calibrate\ncpt = chars / tokensBefore"]
-    B --> C["buildOwnCut + smartKeep\nkeep tailored to tail size"]
-    C --> D["normalize + filter\nstrip ANSI, 123 arrow, harness XML"]
-    D --> E["rank TF-IDF\n5 sections + brief transcript"]
-    E --> F["summary 1.1k tok\n+ kept tail\n30-470 ms, zero cost"]
-  end
-  subgraph LLM["native remote LLM compaction"]
-    L1["branchEntries"] --> L2["serialize history\nHTTP to LLM"]
-    L2 --> L3["wait seconds\n+ token cost\n+ nondeterministic"]
-  end
-  F -. "next turn sees only F" .-> A
-  classDef vcc fill:#e8f5e9,stroke:#2e7d32
-  class F vcc
-  classDef llm fill:#fce4ec,stroke:#c2185b
-  class L3 llm
-```
-
-What `omp-vcc` adds vs intercepts in the harness (hooks, tools, commands, settings) and why — see [`docs/harness.md`](docs/harness.md) §§2–3.
-
-**Example** — a 80-turn session at 90k tokens, `keep:1` tail is only 3k (wastes budget):
-
-- raw tail `3k` → `smartKeepTail` grows to `keep:4` with tail `21k` (still ≤ 25k cap)
-- older 76 turns are compiled into `V_ui`:
-
-```txt
-[Session Goal] Fix auth token refresh
-[Files And Changes] src/auth.ts, src/app.ts
-[Brief transcript] (ranked, TF-IDF, 78 lines)
-  (#12) Read src/auth.ts — missing refresh on expiry
-  (#18) Edit src/auth.ts:12-34 — add refreshToken()
-  (#33) Test auth flow — 2 failed, 1 passed
----
-Recall is the same idea: `vcc_recall` runs local regex → TF-IDF `rank.ts` and preserves skeleton. `query: "hook|inject"` returns 5 hits with `(#N)` pointers like `(#33) hook registration`; `query: "#18:src/auth.ts"` drills to `V_full[18:e]` verbatim.
-
-Docs: [`architecture`](docs/architecture.md) · [`configuration`](docs/configuration.md) · [`verification`](docs/verification.md) · [`harness`](docs/harness.md) · [`paper-notes`](docs/paper-notes.md) · [`setup`](docs/setup.md) · [`PUBLISHING`](docs/PUBLISHING.md) · pinned [`omp-compaction`](docs/omp-compaction.md) / [`omp-snapcompact`](docs/omp-snapcompact.md).
-
-- **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
-
-## Best practices
+| 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. |
 
-> Goal: keep context small enough to stay fast and cheap, but large enough that the agent doesn't lose what you're working on.
+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.
 
-### 1) Let auto do its job
-
-- Keep `overrideDefaultCompaction:true` (default) — threshold/overflow compaction becomes deterministic and instant. Only set `false` if you explicitly want the remote LLM summarizer for `handoff` or you installed the optional native `vcc` dropdown patch and want to toggle per-session in `/settings`.
-- Keep `smartKeepTail:true` and `continueAfterThresholdCompact:true` — the plugin grows `keep:1` to `keep:2…4` when the tail is tiny (5 k → 25 k) and auto-continues after a threshold compact so the agent doesn't stall mid-task.
-- Don't spam `/omp-vcc` every few turns. Auto threshold (derived from your model's context window) already fires at the right moment. Manual compacts are for deliberate boundaries: finishing a sub-task, before a risky refactor, or when you feel the context getting noisy.
-
-### 2) Pick the right `keep:N`
-
-| Situation | Command | Why |
-| --- | --- | --- |
-| Default, happy path | `/omp-vcc` or `keep:1` | Smallest tail, max savings. `smartKeepTail` will still grow to `keep:3` if the last turn is only 3 k tok so you don't waste budget. |
-| Actively iterating on last edits/tests | `/omp-vcc keep:2` or `keep:3` | Preserves the last 2–3 user turns verbatim (e.g. failing test output + fix). Costs more tokens but avoids recall. |
-| Need maximal reduction (e.g. before context overflow) | `/omp-vcc keep:0` | Summarizes everything, no tail. Next turn starts from pure `V_ui`. Useful before pasting a huge spec. |
-| With a focus prompt | `/omp-vcc keep:2 focus on auth refresh only` | Preserved tail + an injected follow-up prompt so the agent continues with the narrowed scope. |
-
-Explicit `keep:N` always wins — smart-keep never overrides it.
-
-### 3) Use recall instead of keeping more
-
-Keeping a huge tail is the expensive alternative to recall. Prefer a small keep and search when you need history:
+## How it works
 
-- Plain keywords first: `/vcc-recall redis cache` or `vcc_recall({query:"redis cache"})` — multi-word is OR + TF-IDF ranked (rare terms rank higher).
-- Regex when you know the pattern: `/vcc-recall hook|inject`, `/vcc-recall fail.*build`.
-- Pagination: `page:2` (5 hits/page): `/vcc-recall auth scope:all page:2`.
-- Scope: default is active lineage (what the current branch actually saw). Add `scope:all` to search abandoned branches/edits/retries.
-- Drill-down: `/vcc-recall #18:src/auth.ts` expands that turn's file slice verbatim from `V_full` — fastest way to rehydrate an edit.
-- Index mode: `vcc_recall({query:"", mode:"touched"})` lists touched files across the session.
+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.
 
-```mermaid
-flowchart LR
-  KEEP["keep small\nkeep:1 + smartKeep"] --> RECALL["need history?\n/vcc-recall keywords"]
-  RECALL --> DRILL["#N:path drill\nrehydrate file"]
-  KEEP --> FORGET["keep huge tail\nwastes 10-20k tok"]
-  style FORGET stroke-dasharray: 3 3
+```
+Calibrate cpt → SmartKeep → BuildOwnCut → Normalize → FilterNoise → BuildSections → Brief (1100→2000 tok, 120 lines) → Merge
 ```
 
-### 4) Help the extractor help you
-
-The 5 sections (`[Session Goal]`, `[Files And Changes]`, `[Commits]`, `[Outstanding Context]`, `[User Preferences]`) are regex/heuristics, not an LLM. Make them work better:
-
-- State the goal once, plainly, in the first user message: `Goal: fix auth token refresh in src/auth.ts`. That seeds `[Session Goal]` reliably.
-- Declare preferences explicitly with cue words: `always run tests before committing`, `prefer concise diffs`, `never edit src/generated/`. Those go to `[User Preferences]`.
-- Commit frequently — commits populate `[Commits]` and survive compaction better than bare edits.
-- Mark outstanding items as questions/errors (`TODO:`, `failing:`, `why does …?`) so they land in `[Outstanding Context]` until resolved.
-
-### 5) Know the difference: compact vs clear
-
-- `/omp-vcc` (or `/compact`) **summarizes** — history becomes `V_ui` + searchable `V_full`. The divider `── compacted · 90k→22k · ctrl+o ──` stays in the transcript (expand with `ctrl+o`).
-- `/clear` **erases** — inserts a `reset_boundary` after which even `V_full` is no longer compacted. Previous history stays on disk for `/vcc-recall scope:all` but the live context starts empty. Use `/clear` when you truly want a fresh session; use `/omp-vcc` when you want to keep the story.
+See [`docs/harness.md`](docs/harness.md) for host impact and [`docs/architecture.md`](docs/architecture.md) for pipeline.
 
-### 6) Debug/verify habits
+## Combining with shake and snapcompact
 
-- One-shot verification after install: `/omp-vcc keep:1 test` → expect toast `omp-vcc: kept …` and an inline `[Session Goal]` block. No toast = `overrideDefaultCompaction:false` or a competing compactor.
-- To tune: set `debug:true` in `~/.omp/omp-vcc/config.json`, run `/omp-vcc`, then `cat /tmp/omp-vcc-debug.json` — check `usedOwnCut`, `tokensBefore`, `tokenEstimate {charsPerToken, mode}`, `summaryLength`, `sections`. Remember to flip `debug:false` after — the file is overwritten every compact.
-- For overflow: if you hit `tokensBefore > 50k` and nothing happens, check `omp plugin doctor` and that `vccEnabled:true`.
+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.
 
-### 7) Team / long-session hygiene
+| 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 |
 
-- One compaction covers 30–100 turns; repeated compactions merge bounded (transcript caps at ~120 lines, sections dedup). Long-running sessions (200+ turns) stay healthy — don't fear auto.
-- `snapcompact`/`shake`/`handoff` in `compaction.methodOrder` are orthogonal — `omp-vcc` only intercepts `context-full`. Leave them in the order if you use them; they run when `omp-vcc` explicitly defers (e.g. `vccEnabled:false`).
-- Pin the plugin version in CI or shared dots: `omp plugin install github:zhulinchng/omp-vcc#v0.1.x` so the team shares the same `RANKED_BRIEF_BUDGET_TOKENS=1100` behavior.
+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).
 
 ## 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          # 378 tests across 36 files, 1007 expects
-bun run smoke     # 9 checks: 3 hooks + 4 commands + 2 tools (vcc_recall, vcc_stats)
-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]` with toast `omp-vcc: 90.0k→22.0k (76% saved, ~68.0k) · kept 1/5 turns, ~2.1k tok` (fallback `omp-vcc: kept 1/5 turns…` when `tokensBefore` unavailable) + divider `── compacted · 90K→22K · ctrl+o ──`; with `debug:true` check `/tmp/omp-vcc-debug.json` (`savings` + `authoritativeSavings`). `/vcc-stats` / `/omp-vcc --stats` / `vcc_stats({history:true})` show the 50-capped `Before→After/Saved/Kept/Summarized/When` table. Full proof matrix and mermaid flows in [`docs/verification.md`](docs/verification.md); harness impact (adds vs intercepts) in [`docs/harness.md`](docs/harness.md). Smoke checks map to the re-runnable truth table in [`docs/harness.md` §9](docs/harness.md#9-verification-map-claim--evidence).
-
-Docs: [`architecture`](docs/architecture.md) · [`configuration`](docs/configuration.md) · [`verification`](docs/verification.md) · [`harness`](docs/harness.md) · [`paper-notes`](docs/paper-notes.md) · [`setup`](docs/setup.md) · [`PUBLISHING`](docs/PUBLISHING.md) · pinned [`omp-compaction`](docs/omp-compaction.md) / [`omp-snapcompact`](docs/omp-snapcompact.md).
-
-See [`docs/PUBLISHING.md`](docs/PUBLISHING.md) for the full checklist (package shape, gates, dual `omp-vcc` / `@zhulinchng/omp-vcc` flow, verification, deployment matrix, and troubleshooting). TL;DR:
+Full matrix: [`docs/verification.md`](docs/verification.md). Harness map: [`docs/harness.md §9`](docs/harness.md#9-verification-map-claim--evidence).
 
-- npmjs (unscoped): `npm publish --access public` (package `omp-vcc`, 2FA `auth-and-writes` → browser or `--otp`)
-- GitHub Packages (scoped): `gh release create vX.Y.Z` triggers `.github/workflows/publish-gpr.yml` → `@zhulinchng/omp-vcc` via `GITHUB_TOKEN` (`read:packages, write:packages`); manual fallback `npm pkg set name=@zhulinchng/omp-vcc && GITHUB_TOKEN=$(gh auth token) npm publish --userconfig /tmp/gpr-npmrc --access public` (see guide for the scoped-registry `/tmp/gpr-npmrc` pitfall)
-- Consumer GPR auth: add to `~/.npmrc`:
+## Docs
 
-  ```
-  @zhulinchng:registry=https://npm.pkg.github.com
-  //npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT
-  ```
+[`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)
 
-- 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
 

package/extensions/main.ts

@@ -6,6 +6,7 @@
 
 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,
@@ -45,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) ──
@@ -160,40 +163,18 @@ export default function (pi: ExtensionAPI): void {
   // ── vcc_stats tool — stats surface for savings (paper § verification) ──
   registerVccStatsToolHook(pi);
 
-
   pi.registerCommand("omp-vcc", {
-    description: "Compact conversation with omp-vcc structured summary (keep:N + optional focus) — add --stats to show savings",
+    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 trimmed = (args || "").trim();
-      const lower = trimmed.toLowerCase();
-      if (lower === "--stats" || lower === "stats" || lower.startsWith("--stats ") || lower.startsWith("stats ")) {
-        const wantHistory = lower.includes("history") || lower.includes("all");
-        const history = getCompactionHistory(pi);
-        const last = getLastCompactionStats(pi);
-        const piAny = pi as unknown as { sendMessage?: (msg: unknown, opts?: unknown) => void };
-        if (!last && history.length === 0) {
-          try { piAny.sendMessage?.({ customType: "vcc-stats", content: "No compactions yet. Run /omp-vcc to compact first.", display: true }, { triggerTurn: false }); } catch {}
-          try { c.ui.notify("No compactions yet.", "info"); } catch {}
-          return;
-        }
-        const output = wantHistory
-          ? `${formatStatsTable(history)}\n\n${last ? formatLastStatsDetail(last) : ""}`
-          : `${last ? formatLastStatsDetail(last) : "No last stats"}${history.length > 1 ? `\n\nHistory:\n${formatStatsTable(history)}` : ""}`;
-        try { piAny.sendMessage?.({ customType: "vcc-stats", content: output, display: true }, { triggerTurn: false }); } catch {}
-        try { c.ui.notify(`vcc_stats: ${history.length} compaction(s)`, "info"); } catch {}
-        return;
-      }
       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 {}

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

@@ -16,10 +16,16 @@ const settingsPath = (): string =>
 /** Backwards-compat export. Resolves at access time, not import time. */
 export const SETTINGS_PATH = settingsPath();
 // For migration: if omp config missing but legacy pi config exists, we read legacy but write to new
+// Also handles concurrent-test env shadowing: if OMP path is set by another test but file missing,
+// fall back to PI path before default.
 const fallbackReadPath = (): string | null => {
-  const primary = settingsPath();
-  if (existsSync(primary)) return primary;
-  if (existsSync(legacyPiPath)) return legacyPiPath;
+  const candidates: string[] = [];
+  if (process.env.OMP_VCC_CONFIG_PATH) candidates.push(process.env.OMP_VCC_CONFIG_PATH);
+  if (process.env.PI_VCC_CONFIG_PATH) candidates.push(process.env.PI_VCC_CONFIG_PATH);
+  candidates.push(SETTINGS_PATH_DEFAULT);
+  if (!candidates.includes(legacyPiPath)) candidates.push(legacyPiPath);
+  for (const p of candidates) if (existsSync(p)) return p;
+  // No candidate exists — return primary for creation path (used by scaffold)
   return null;
 };
 
@@ -56,6 +62,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 +80,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/hook.ts

@@ -89,6 +89,8 @@ const perPi = new WeakMap<any, { lastStats: CompactionStats | null; lastCompactW
 // Track strong refs for test helper clearCompactionHistoryForTests: WeakMap keys
 // cannot be enumerated, so keep a Set for test-only cleanup.
 const perPiKeys = new Set<any>();
+// Guard eager chainShakeHint to avoid recursion: tracks pis currently chaining.
+const pendingChainShake = new WeakSet<object>();
 const getPerPi = (pi: any) => {
   if (!pi || typeof pi !== "object") return null;
   let s = perPi.get(pi);
@@ -730,6 +732,17 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
     // Otherwise, only handle when user opted in via settings.
     const { isPiVcc, keepUserTurns, keepUserTurnsExplicit, followUpPrompt } = parseCompactionInstructions(customInstructions);
     setPendingFollowUpPrompt(pi, null);
+    // Explicit host mode bypass: when the host signals an explicit compact mode
+    // (e.g. /compact snapcompact or --mode shake), let the host walker handle it
+    // even though overrideDefaultCompaction is true. This enables sequential
+    // VCC → snapcompact/shake combinations. The event field is only present when
+    // the optional native vcc patch is applied or a future host exposes it; when
+    // absent this branch is no-op and the existing override semantics remain.
+    const explicitMode = (event as any).compactMode ?? (event as any).explicitMode ?? (event as any).mode;
+    if (!isPiVcc && typeof explicitMode === "string" && explicitMode) {
+      const m = explicitMode.toLowerCase();
+      if (m === "snapcompact" || m === "shake" || m === "soft" || m === "remote" || m === "handoff") return;
+    }
     if (!isPiVcc && !settings.overrideDefaultCompaction) return;
 
     const calibrationCut = buildOwnCut(branchEntries as any[], 0);
@@ -1058,6 +1071,25 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
     const isLargeCompaction = (stats.summarized > 10) || (stats.kept > 5) || (stats.keptTokensEst > 2000);
     const shouldContinueAfterAutoCompact = (reason === "threshold" || reason === "overflow" || (reason == null && isLargeCompaction)) && loadSettings(ctx).continueAfterThresholdCompact;
     scheduleCompactionStatsNotify(ctx, stats);
+    // Eager post-VCC shake chain (chainShakeHint). Host rescue already handles
+    // dead-end; this forces a second shake entry even when headroom was made.
+    try {
+      const cfgChain = loadSettings(ctx);
+      const ctxMaybe = ctx as unknown as Record<string, unknown>;
+      const compactFn = ctxMaybe["compact"];
+      if (cfgChain.chainShakeHint && typeof compactFn === "function" && !pendingChainShake.has(pi as unknown as object) && !willRetry && !isPiVccLast) {
+        pendingChainShake.add(pi as unknown as object);
+        const maybePromise = (compactFn as unknown as (o: unknown) => Promise<void>).call(ctx, { mode: "shake" } as unknown);
+        const asPromise = maybePromise as unknown as Promise<void> | void;
+        if (asPromise && typeof (asPromise as unknown as Promise<void>).catch === "function") {
+          (asPromise as unknown as Promise<void>).catch(() => {}).finally(() => {
+            setTimeout(() => { try { pendingChainShake.delete(pi as unknown as object); } catch {} }, 2000);
+          });
+        } else {
+          setTimeout(() => { try { pendingChainShake.delete(pi as unknown as object); } catch {} }, 2000);
+        }
+      }
+    } catch {}
     if (followUpPrompt) {
       try {
         await pi.sendUserMessage(followUpPrompt);
@@ -1288,5 +1320,4 @@ export const registerVccStatsCommand = (pi: any) => {
     try { ctx?.ui?.notify?.(`vcc_stats: ${history.length} compaction(s)`, "info"); } catch {}
   };
   pi.registerCommand("vcc-stats", { description: "Show omp-vcc compaction savings (last + history)", handler });
-  pi.registerCommand("omp-vcc-stats", { description: "Alias for /vcc-stats", handler });
 };

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "omp-vcc",
-  "version": "0.1.4",
+  "version": "0.1.6",
+  "type": "module",
   "description": "Algorithmic VCC compaction for omp - fast lossless no-LLM",
   "author": "Zhu Lin <zhulin@czl.my>",
   "repository": {
@@ -25,7 +26,6 @@
   "files": [
     "extensions",
     "skills",
-    "commands",
     "scripts",
     "types.d.ts"
   ],
@@ -34,10 +34,6 @@
     "extensions": [
       "./extensions/main.ts"
     ],
-    "commands": [
-      "./commands/omp-vcc.md",
-      "./commands/vcc-recall.md"
-    ],
     "settings": {
       "vccEnabled": {
         "type": "boolean",
@@ -63,6 +59,11 @@
         "type": "boolean",
         "default": false,
         "description": "Write debug snapshot to /tmp/omp-vcc-debug.json"
+      },
+      "chainShakeHint": {
+        "type": "boolean",
+        "default": false,
+        "description": "Eager post-VCC shake chain (host rescue is automatic; this forces a second shake even when VCC created headroom)"
       }
     }
   },
@@ -71,10 +72,6 @@
     "extensions": [
       "./extensions/main.ts"
     ],
-    "commands": [
-      "./commands/omp-vcc.md",
-      "./commands/vcc-recall.md"
-    ],
     "settings": {
       "vccEnabled": {
         "type": "boolean",
@@ -100,6 +97,11 @@
         "type": "boolean",
         "default": false,
         "description": "Write debug snapshot to /tmp/omp-vcc-debug.json"
+      },
+      "chainShakeHint": {
+        "type": "boolean",
+        "default": false,
+        "description": "Eager post-VCC shake chain (host rescue is automatic; this forces a second shake even when VCC created headroom)"
       }
     }
   },
@@ -107,6 +109,8 @@
     "typecheck": "bunx tsc --noEmit",
     "test": "bun test",
     "smoke": "bun run scripts/smoke.ts",
+    "e2e": "bun run scripts/e2e.ts",
+    "e2e:direct": "bun test tests/e2e --timeout 120000",
     "postuninstall": "node scripts/uninstall-reset.js || true",
     "prepublishOnly": "npm run typecheck && npm test && npm run smoke"
   }

package/scripts/e2e.ts

@@ -0,0 +1,131 @@
+#!/usr/bin/env bun
+// @ts-nocheck
+// Usage: bun run e2e   or   bun run scripts/e2e.ts [--timeout 120000]
+
+import { mkdtempSync, existsSync, mkdirSync, cpSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+const timeoutArg = process.argv.find((a) => a.startsWith("--timeout"));
+const timeout = timeoutArg ? Number(timeoutArg.split("=")[1] ?? 120000) : 120000;
+const verbose = process.argv.includes("--verbose");
+
+console.log("== omp-vcc E2E runner ==");
+
+const ompDir = mkdtempSync(join(tmpdir(), "omp-vcc-e2e-runner-"));
+const configPath = join(ompDir, "config.json");
+console.log(`OMP_DIR=${ompDir}`);
+console.log(`OMP_VCC_CONFIG_PATH=${configPath}`);
+
+let failures = 0;
+
+async function probeOmp(): Promise<void> {
+  try {
+    const proc = Bun.spawn(["omp", "--help"], { stdout: "pipe", stderr: "pipe" });
+    await proc.exited;
+    const out = await new Response(proc.stdout).text().catch(() => "");
+    const err = await new Response(proc.stderr).text().catch(() => "");
+    const help = out + err;
+    if (verbose) console.log(help.slice(0, 2000));
+    const hasPrint = /--print\b/.test(help);
+    const hasExtension = /--extension\b|-e\b/.test(help);
+    const hasPlugin = /\bplugin\b/.test(help);
+    console.log(`probe omp --help: hasPrint=${hasPrint} hasExtension=${hasExtension} hasPlugin=${hasPlugin}`);
+    if (!hasPlugin) console.log("note: omp plugin subcommand not found — isolated plugin link test will be skipped");
+  } catch (e) {
+    console.log(`probe failed (omp not on PATH?): ${e}`);
+  }
+}
+
+await probeOmp();
+
+// Try plugin link in isolated dir (best effort, skip if omp missing)
+try {
+  const linkProc = Bun.spawn(["omp", "plugin", "link", process.cwd()], {
+    env: { ...process.env, OMP_DIR: ompDir, PI_CODING_AGENT_DIR: ompDir, OMP_VCC_CONFIG_PATH: configPath, PI_VCC_CONFIG_PATH: configPath },
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  await linkProc.exited;
+  const code = linkProc.exitCode ?? 0;
+  if (code === 0) {
+    console.log("omp plugin link ok (isolated)");
+    const doctor = Bun.spawn(["omp", "plugin", "doctor"], {
+      env: { ...process.env, OMP_DIR: ompDir, PI_CODING_AGENT_DIR: ompDir, OMP_VCC_CONFIG_PATH: configPath },
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    await doctor.exited;
+    const out = await new Response(doctor.stdout).text().catch(() => "");
+    console.log(out.slice(0, 1500));
+  } else {
+    const err = await new Response(linkProc.stderr).text().catch(() => "");
+    console.log(`omp plugin link skipped or failed (code ${code}): ${err.slice(0, 500)}`);
+  }
+} catch (e) {
+  console.log(`omp plugin link probe skipped: ${e}`);
+}
+
+console.log(`\n== running bun test tests/e2e --timeout ${timeout} ==`);
+const env = {
+  ...process.env,
+  OMP_DIR: ompDir,
+  PI_CODING_AGENT_DIR: ompDir,
+  OMP_VCC_CONFIG_PATH: configPath,
+  PI_VCC_CONFIG_PATH: configPath,
+};
+const testProc = Bun.spawn(["bun", "test", "tests/e2e", "--timeout", String(timeout)], {
+  env,
+  stdout: "pipe",
+  stderr: "pipe",
+});
+const stdoutChunks: string[] = [];
+const stderrChunks: string[] = [];
+// Stream
+const outReader = testProc.stdout.getReader();
+const errReader = testProc.stderr.getReader();
+async function drain(reader: ReadableStreamDefaultReader<Uint8Array>, store: string[], isErr: boolean) {
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      const text = new TextDecoder().decode(value);
+      store.push(text);
+      if (isErr) process.stderr.write(text);
+      else process.stdout.write(text);
+    }
+  } catch {}
+}
+await Promise.all([drain(outReader as any, stdoutChunks, false), drain(errReader as any, stderrChunks, true)]);
+const exitCode = await testProc.exited;
+
+console.log(`\n== bun test exit code: ${exitCode} ==`);
+
+// collect debug artifacts
+const artifactsDir = join(process.cwd(), "artifacts", "e2e-debug");
+try {
+  mkdirSync(artifactsDir, { recursive: true });
+  for (const p of ["/tmp/omp-vcc-debug.json", "/tmp/pi-vcc-debug.json"]) {
+    if (existsSync(p)) {
+      const dest = join(artifactsDir, p.split("/").pop()!);
+      cpSync(p, dest);
+      console.log(`artifact collected: ${p} -> ${dest}`);
+    }
+  }
+  if (existsSync(configPath)) {
+    cpSync(configPath, join(artifactsDir, "isolated-config.json"));
+  }
+} catch (e) {
+  console.log(`artifact collection warning: ${e}`);
+}
+
+// cleanup isolated dir (keep artifacts)
+try { rmSync(ompDir, { recursive: true, force: true }); } catch {}
+console.log(`isolated OMP_DIR removed: ${ompDir}`);
+
+if (exitCode !== 0) {
+  console.log("\nE2E FAILED");
+  process.exit(exitCode ?? 1);
+} else {
+  console.log("\nAll E2E checks passed.");
+}

package/scripts/smoke.ts

@@ -76,8 +76,16 @@ try {
     commands.some((c) => c.name === "vcc-stats"),
   );
   check(
-    "omp-vcc-stats alias registered",
-    commands.some((c) => c.name === "omp-vcc-stats"),
+    "no omp-vcc-stats duplicate",
+    !commands.some((c) => c.name === "omp-vcc-stats"),
+  );
+  check(
+    "pi-vcc-recall alias registered",
+    commands.some((c) => c.name === "pi-vcc-recall"),
+  );
+  check(
+    "no file slash command duplication (only extension commands)",
+    commands.filter((c) => c.name === "omp-vcc").length === 1,
   );
   } catch (e) {
   check("extension loads", false, String(e));

package/scripts/uninstall-reset.js

@@ -1,73 +1,302 @@
 #!/usr/bin/env node
 /**
- * postuninstall hook: reset ownership marker if this plugin owned global state.
- * Generic postuninstall reset for ownership marker
- * Marker: ~/.config/@zhulinchng/omp-vcc/.ownership.json with { state: "owned", previous: boolean }
+ * postuninstall hook: reset ownership marker and clean stale plugin entries.
+ *
+ * 1. Marker: ~/.config/@zhulinchng/omp-vcc/.ownership.json with { state: "owned" }
+ *    When the plugin set `startup.quiet: true` in the global config, restore.
+ *    No-op when marker missing or not owned.
+ *
+ * 2. Stale plugin entries: historic `package.json:name` renames left
+ *    `@zhu/omp-vcc` → `@zhulinchng/omp-vcc` → `omp-vcc`. `omp plugin link .`
+ *    under an old name creates a symlink+lock entry that survives the rename
+ *    (host `PluginManager.link` did not clean same-realpath stale keys, and
+ *    `PluginManager.uninstall` for linked plugins left the symlink behind).
+ *    This script removes those stale symlinks+lock entries without touching
+ *    correctly installed `omp-vcc` (or npm `dependencies` entries which are
+ *    real directories, not symlinks).
+ *    Safe to run repeatedly; also runs on extension activation (see
+ *    extensions/vcc-core/core/migrate-stale.ts).
  */
-import { readFileSync, rmSync, writeFileSync } from "node:fs";
+import { readFileSync, rmSync, writeFileSync, existsSync, lstatSync, readdirSync, realpathSync } from "node:fs";
+import { readFile, lstat, readdir, realpath, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, resolve, dirname } from "node:path";
 import { pathToFileURL } from "node:url";
 
+const HISTORIC_NAMES = ["@zhu/omp-vcc", "@zhulinchng/omp-vcc"];
+const CURRENT_NAME = "omp-vcc";
+
 export function resetOwnedQuiet(home) {
-  const markerPath = join(
-    home,
-    ".config",
-    "@zhulinchng/omp-vcc",
-    ".ownership.json",
-  );
-  const configPath = join(home, ".omp", "agent", "config.yml");
+  const baseHome = home || homedir();
+  const markerPath = join(baseHome, ".config", "@zhulinchng/omp-vcc", ".ownership.json");
+  const configCandidates = [
+    join(baseHome, ".omp", "agent", "config.yml"),
+    join(baseHome, ".omp", "config.yml"),
+  ];
+
   let marker;
   try {
     marker = JSON.parse(readFileSync(markerPath, "utf8"));
   } catch {
     return "no-marker";
   }
+
   const clearMarker = () => {
     try {
       rmSync(markerPath, { force: true });
     } catch {}
   };
+
   if (marker?.state !== "owned") {
     clearMarker();
     return "not-owned";
   }
+
   let content;
-  try {
-    content = readFileSync(configPath, "utf8");
-  } catch {
+  let configPath;
+  for (const p of configCandidates) {
+    try {
+      content = readFileSync(p, "utf8");
+      configPath = p;
+      break;
+    } catch {}
+  }
+  if (!configPath || content === undefined) {
     clearMarker();
     return "config-missing";
   }
+
   const lines = content.split("\n");
   let inStartup = false;
   let changed = false;
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i] ?? "";
     if (/^startup:\s*$/.test(line)) inStartup = true;
-    else if (inStartup && /^[^ \t]/.test(line) && line.trim() !== "")
-      inStartup = false;
+    else if (inStartup && /^[^ \t]/.test(line) && line.trim() !== "") inStartup = false;
     if (inStartup && /quiet:\s*true/.test(line)) {
       lines[i] = line.replace("true", "false");
       changed = true;
       break;
     }
   }
+
   if (changed) {
     try {
       writeFileSync(configPath, lines.join("\n"), "utf8");
     } catch {
+      clearMarker();
       return "write-failed";
     }
   }
+
   clearMarker();
   return changed ? "restored" : "already-default";
 }
 
-if (
+// --- stale plugin cleanup (in-plugin, no host changes) ---
+
+function isSymlinkSync(p) {
+  try {
+    return lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function readJsonSync(p, fallback = null) {
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Remove stale `omp-vcc` plugin entries left by historic package.json renames
+ * and by `omp plugin uninstall` for linked plugins (which left the symlink
+ * behind on old hosts).
+ *
+ * - Only touches lockfile-only entries (not in `package.json:dependencies`)
+ *   where `package.json:name` mismatches the lock key, or where two keys
+ *   point at the same realpath.
+ * - Only removes symlinks, never real directories (npm installs).
+ * - Returns a summary string for logging.
+ */
+export function cleanupStalePluginEntries(home) {
+  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 lock = readJsonSync(lockPath, null);
+  if (!lock || typeof lock !== "object") return "no-lock";
+
+  const pkg = readJsonSync(pkgPath, { dependencies: {} });
+  const deps = (pkg && typeof pkg.dependencies === "object" && pkg.dependencies) || {};
+
+  const pluginKeys = lock.plugins && typeof lock.plugins === "object" ? Object.keys(lock.plugins) : [];
+  const ompKeys = pluginKeys.filter((k) => k.includes("omp-vcc"));
+
+  // If no omp-vcc keys at all, still check for orphaned symlinks at historic
+  // paths that may remain after `omp plugin uninstall` (old host left symlink).
+  const candidates = new Set([...ompKeys, ...HISTORIC_NAMES, CURRENT_NAME]);
+
+  let removedLocks = [];
+  let removedLinks = [];
+
+  // Helper to get package.json:name for a node_modules entry, without throwing
+  const getPkgName = (name) => {
+    try {
+      const jp = readJsonSync(join(nm, name, "package.json"), null);
+      return jp && typeof jp.name === "string" ? jp.name : null;
+    } catch {
+      return null;
+    }
+  };
+
+  // Helper to get realpath for dedup, null if not exists or not symlink
+  const getReal = (name) => {
+    const p = join(nm, name);
+    if (!isSymlinkSync(p)) return null;
+    try {
+      return realpathSync(p);
+    } catch {
+      return null;
+    }
+  };
+
+  // Map realpath -> list of lock keys that resolve to it (for dedup)
+  const realToKeys = new Map();
+  for (const k of ompKeys) {
+    const rp = getReal(k);
+    if (!rp) continue;
+    const list = realToKeys.get(rp) || [];
+    list.push(k);
+    realToKeys.set(rp, list);
+  }
+
+  // 1. lock-only mismatch: lock key !== pkg name -> stale (e.g. @zhu/omp-vcc -> omp-vcc)
+  for (const k of [...ompKeys]) {
+    if (k in deps) continue; // npm-declared, keep even if name mismatches (dual publish)
+    const pkgName = getPkgName(k);
+    if (pkgName && pkgName !== k) {
+      // Historic rename leftover: lock key is old name, package is new name
+      const isHistoric = HISTORIC_NAMES.includes(k) || k !== CURRENT_NAME;
+      if (isHistoric) {
+        // Remove symlink if it exists
+        const p = join(nm, k);
+        if (isSymlinkSync(p)) {
+          try {
+            rmSync(p, { force: true });
+            removedLinks.push(k);
+            // try to remove empty scope dir e.g. .../node_modules/@zhu
+            if (k.startsWith("@")) {
+              const scopeDir = join(nm, k.split("/")[0]);
+              try {
+                if (readdirSync(scopeDir).length === 0) rmSync(scopeDir, { force: true });
+              } catch {}
+            }
+          } catch {}
+        }
+        // Remove lock entry
+        if (lock.plugins[k]) {
+          delete lock.plugins[k];
+          removedLocks.push(k);
+        }
+        if (lock.settings && lock.settings[k]) delete lock.settings[k];
+      }
+    }
+  }
+
+  // 2. duplicate realpath: two lock keys point at same directory -> keep the
+  //    one where lock key === pkg name, remove the other(s)
+  for (const [, keys] of realToKeys) {
+    if (keys.length <= 1) continue;
+    // Determine keeper: prefer CURRENT_NAME or key that matches pkg name
+    let keeper = null;
+    for (const k of keys) {
+      const pkgName = getPkgName(k);
+      if (pkgName === k) {
+        keeper = k;
+        break;
+      }
+    }
+    if (!keeper) keeper = keys.includes(CURRENT_NAME) ? CURRENT_NAME : keys[0];
+    for (const k of keys) {
+      if (k === keeper) continue;
+      // Only remove if lock-only (not deps) and symlink
+      if (k in deps) continue;
+      const p = join(nm, k);
+      if (isSymlinkSync(p)) {
+        try {
+          rmSync(p, { force: true });
+          if (!removedLinks.includes(k)) removedLinks.push(k);
+          if (k.startsWith("@")) {
+            const scopeDir = join(nm, k.split("/")[0]);
+            try {
+              if (readdirSync(scopeDir).length === 0) rmSync(scopeDir, { force: true });
+            } catch {}
+          }
+        } catch {}
+      }
+      if (lock.plugins[k]) {
+        delete lock.plugins[k];
+        if (!removedLocks.includes(k)) removedLocks.push(k);
+      }
+      if (lock.settings && lock.settings[k]) delete lock.settings[k];
+    }
+  }
+
+  // 3. orphaned symlinks at candidate paths that have no lock entry (old
+  //    host left symlink after uninstall). Remove them if they are symlinks
+  //    and their package name is omp-vcc (so we don't delete unrelated).
+  for (const cand of candidates) {
+    const p = join(nm, cand);
+    if (!isSymlinkSync(p)) continue;
+    const hasLock = !!lock.plugins[cand];
+    if (hasLock) continue; // already handled
+    const pkgName = getPkgName(cand);
+    // Only remove orphaned omp-vcc symlinks, not other plugins
+    if (pkgName === CURRENT_NAME || pkgName === "@zhu/omp-vcc" || pkgName === "@zhulinchng/omp-vcc") {
+      try {
+        rmSync(p, { force: true });
+        if (!removedLinks.includes(cand)) removedLinks.push(cand);
+        if (cand.startsWith("@")) {
+          const scopeDir = join(nm, cand.split("/")[0]);
+          try {
+            if (readdirSync(scopeDir).length === 0) rmSync(scopeDir, { force: true });
+          } catch {}
+        }
+      } catch {}
+    }
+  }
+
+  if (removedLocks.length > 0 || removedLinks.length > 0) {
+    try {
+      writeFileSync(lockPath, JSON.stringify(lock, null, 2));
+    } catch {}
+    return `cleaned locks:${removedLocks.join(",") || "none"} links:${removedLinks.join(",") || "none"}`;
+  }
+  return "no-stale";
+}
+
+const isDirectRun =
   process.argv[1] &&
-  import.meta.url === pathToFileURL(process.argv[1]).href
-) {
-  const result = resetOwnedQuiet(homedir());
-  console.log(`uninstall-reset: ${result}`);
+  (() => {
+    try {
+      return import.meta.url === pathToFileURL(resolve(process.argv[1])).href;
+    } catch {
+      return false;
+    }
+  })();
+
+if (isDirectRun) {
+  try {
+    const r1 = resetOwnedQuiet(homedir());
+    const r2 = cleanupStalePluginEntries(homedir());
+    console.log(`uninstall-reset: ${r1} ${r2}`);
+  } catch (err) {
+    console.log(`uninstall-reset: error ${err?.message ?? err}`);
+  }
 }

package/skills/omp-vcc/SKILL.md

@@ -48,8 +48,7 @@ Use `vcc_recall` to search for prior work … Do not redo work already completed
 
 | Task | How | Notes |
 |---|---|---|
-| **Force compaction** | `/omp-vcc` or `/omp-vcc keep:2 fix auth` · alias `/pi-vcc` | `keep:1` is default. Explicit `keep:N` always wins. Default `keep:1` may keep 2–4 turns if tail is tiny (smart-keep ≤5k→≤25k). `keep:0` = compact all, next turn from pure `V_ui`. Focus text after `keep:N` becomes the next user message. |
-| **Check savings** | `/omp-vcc --stats` · `/vcc-stats` · `/omp-vcc-stats`  · `vcc_stats({history:true})` | Last + history table (50-capped). Use to confirm headroom before long edits. |
+| **Check savings** | `/vcc-stats` · `vcc_stats({history:true})` | Last + history table (50-capped, no `omp-vcc-stats` alias). `/omp-vcc` toast is single line only; detailed savings via `/vcc-stats`. Use to confirm headroom before long edits. |
 | **Recall search** | `/vcc-recall <query> [scope:all] [page:2]` · alias `/pi-vcc-recall` · tool `vcc_recall({query, scope, mode, page, expand})` | 5 hits/page, up to 50 total. See cookbook below. |
 | **Stats tool** | `vcc_stats({history?: boolean})` | Same as `/vcc-stats`. `history:true` = full 50-row table. |
 

package/commands/omp-vcc.md

@@ -1,19 +0,0 @@
----
-description: Compact conversation with omp-vcc structured summary (keep:N + optional focus)
----
-
-# /omp-vcc
-
-Algorithmic VCC compaction — fast lossless no-LLM. Registered by `@zhulinchng/omp-vcc` extension.
-
-Usage:
-
-- `/omp-vcc` — compact with default keep:1 (smart-keep may boost to keep:N up to 25k tokens)
-- `/omp-vcc keep:2` — keep last 2 user turns, summarize the rest
-- `/omp-vcc keep:0` — compact all (no tail, sentinel firstKeptEntryId="")
-- `/omp-vcc some prompt text` — compact with additional prompt/focus for the summary
-- `/omp-vcc keep:2 some prompt text` — both keep and prompt
-
-This command is handled by the `omp-vcc` extension (`extensions/main.ts`). It delegates to the VCC pipeline (calibrate → smart-keep → budget-cut → normalize → filter-noise → build-sections → brief transcript → format → merge) and writes a structured summary with `[Session Goal]` / `[Files And Changes]` / `[Brief transcript]` sections.
-
-Arguments: `$ARGUMENTS`

package/commands/vcc-recall.md

@@ -1,21 +0,0 @@
----
-description: Recall earlier parts of this session via ranked search (V_adapt)
----
-
-# /vcc-recall
-
-Search compacted history — implements VCC `V_adapt` with rho predicate (regex or BM25-like ranked OR).
-
-Registered by `@zhulinchng/omp-vcc` extension.
-
-Usage:
-
-- `/vcc-recall` — show 25 most recent entries
-- `/vcc-recall auth token` — keyword search (OR-ranked, TF-IDF)
-- `/vcc-recall "hook|inject" scope:all` — regex search across all branches
-- `/vcc-recall cache page:2` — paginated results (5 per page)
-- `vcc_recall` tool: `{"query":"redis cache","scope":"all","page":1}` — same engine, also supports `mode:'touched'` for file index and `expand:[12,34]` or `#12:path` drill-down
-
-The tool preserves VCC invariants: role tags, line range pointers `(#N)`, and progressive disclosure `V_ui → V_adapt → V_full[s:e]`.
-
-Arguments: `$ARGUMENTS`