omp-vcc 0.1.11 → 0.1.13

package/README.md

@@ -90,7 +90,7 @@ Additive VCC+shake is automatic. Eager chain: `chainShakeHint:true`. Explicit mo
 
 ```sh
 bunx tsc --noEmit
-bun test                  # 800 tests, 61 files, 2396 expects, 0 fail
+bun test                  # 870 tests, 66 files, 2907 expects, 0 fail
 bun test tests/e2e --timeout 120000  # 124 E2E
 bun run smoke             # 13 checks: 3 hooks + 6 cmds + 2 tools + dedup (+ pipeline)
 omp plugin link . && omp plugin doctor

package/extensions/main.ts

@@ -20,6 +20,8 @@ import {
   registerVccStatsTool as registerVccStatsToolHook,
   registerVccStatsCommand as registerVccStatsCommandHook,
   registerVccConfigCommand as registerVccConfigCommandHook,
+  invalidExpandIndices,
+  getCompactForm,
 } from "./vcc-core/hook";
 import { searchEntriesDetailed, getTouchedFiles } from "./vcc-core/core/search-entries";
 import { formatRecallOutput, formatTouchedOutput } from "./vcc-core/core/format-recall";
@@ -141,7 +143,7 @@ export default function (pi: ExtensionAPI): void {
         const { rendered: fullMsgs } = loadAllMessages(sessionFile, true, lineageEntryIds);
         const requested = [...expandSet];
         const byIndex = new Map(fullMsgs.map((m) => [m.index, m]));
-        const invalid = requested.filter((i) => !Number.isInteger(i) || !byIndex.has(i));
+        const invalid = invalidExpandIndices(requested, new Set(byIndex.keys()));
         if (invalid.length > 0) {
           return {
             content: [{ type: "text", text: `Cannot expand indices outside ${scope === "all" ? "session history" : "active lineage"}: ${invalid.join(", ")}` }],
@@ -179,43 +181,91 @@ 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)",
-    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);
+  // Shared /omp-vcc + /pi-vcc runner. The two hosts expose incompatible
+  // ctx.compact shapes, so the call form branches per live ctx:
+  // - omp: compact(string | CompactOptions) => Promise<void>; instructions
+  //   ride the string (the host splits string|object and drops instructions
+  //   from the object form), completion = awaited resolution, errors throw
+  //   ("Compaction cancelled" / "Already compacted" / "Nothing to compact…").
+  // - pi: compact(CompactOptions) => void; instructions ONLY via
+  //   options.customInstructions (a bare string reads as undefined), outcome
+  //   arrives via onComplete/onError. `settled` keeps one outcome.
+  // Form detection is layered (explicit test override → getSystemPrompt
+  // shape → module scope → legacy omp default) so bundled runtimes without
+  // module scope still decide correctly off the live ctx.
+  const runCompactCommand = async (
+    args: string,
+    c: {
+      compact: (arg?: unknown) => Promise<void> | void;
+      ui: { notify: (msg: string, level?: string) => void };
+    },
+    buildInstructions: (keep: number | null) => string,
+    fallbackToast: string,
+    preNotify: boolean,
+    compactForm: "object" | "string",
+  ): Promise<void> => {
+    const parsed = parseKeepAndPrompt(args);
+    const keep = parsed.keepUserTurns;
+    const followUpPrompt = parsed.followUpPrompt;
+    const customInstructions = buildInstructions(keep);
+    if (preNotify) {
       try {
         c.ui.notify(`omp-vcc: compacting with keep:${keep ?? 1}${followUpPrompt ? ` + focus` : ""}...`, "info");
       } catch {}
+    }
+    let settled = false;
+    const finishOk = (): void => {
+      if (settled) return;
+      settled = true;
+      const stats = getLastCompactionStats(pi);
+      if (stats) {
+        scheduleCompactionStatsNotify(c as unknown as { ui: { notify: (msg: string, level?: string) => void } }, stats);
+      } else {
+        try { c.ui.notify(fallbackToast, "info"); } catch {}
+      }
+      if (followUpPrompt) {
+        try {
+          const piAny = pi as unknown as { sendUserMessage?: (content: string) => unknown };
+          const sent = piAny.sendUserMessage?.(followUpPrompt) as Promise<void> | undefined;
+          if (sent && typeof sent.catch === "function") sent.catch(() => {});
+        } catch {}
+      }
+    };
+    const finishErr = (err: unknown): void => {
+      if (settled) return;
+      settled = true;
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg === "Compaction cancelled" || msg === "Already compacted" || msg.startsWith("Nothing to compact")) {
+        try { c.ui.notify("Nothing to compact", "warning"); } catch {}
+      } else {
+        try { c.ui.notify(`Compaction failed: ${msg}`, "error"); } catch {}
+      }
+    };
+    if (compactForm === "object") {
       try {
-        await c.compact(customInstructions);
-        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 omp-vcc", "info"); } catch {}
-        }
-        if (followUpPrompt) {
-          try {
-            const piAny = pi as unknown as { sendUserMessage?: (content: string) => Promise<void> | void };
-            if (piAny.sendUserMessage) await piAny.sendUserMessage(followUpPrompt);
-          } catch {}
-        }
+        c.compact({ customInstructions, onComplete: finishOk, onError: finishErr });
       } catch (err: unknown) {
-        const msg = err instanceof Error ? err.message : String(err);
-        if (msg === "Compaction cancelled" || msg === "Already compacted") {
-          try { c.ui.notify("Nothing to compact", "warning"); } catch {}
-        } else {
-          try { c.ui.notify(`Compaction failed: ${msg}`, "error"); } catch {}
-        }
+        finishErr(err);
       }
+      return;
+    }
+    try {
+      await c.compact(customInstructions);
+      finishOk();
+    } catch (err: unknown) {
+      finishErr(err);
+    }
+  };
+
+  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: (options?: unknown) => Promise<void> | void;
+        ui: { notify: (msg: string, level?: string) => void };
+        getSystemPrompt?: () => unknown;
+      };
+      await runCompactCommand(args, c, buildOmpCustomInstructions, "Compacted with omp-vcc", true, getCompactForm(() => c.getSystemPrompt?.()));
     },
   });
 
@@ -224,30 +274,11 @@ export default function (pi: ExtensionAPI): void {
     description: "Alias for /omp-vcc (pi-vcc compat)",
     handler: async (args: string, ctx: unknown) => {
       const c = ctx as {
-        compact: (instructions?: string) => Promise<void>;
+        compact: (options?: unknown) => Promise<void> | void;
         ui: { notify: (msg: string, level?: string) => void };
+        getSystemPrompt?: () => unknown;
       };
-      const parsed = parseKeepAndPrompt(args);
-      const keep = parsed.keepUserTurns;
-      const followUpPrompt = parsed.followUpPrompt;
-      const customInstructions = buildPiVccCustomInstructions(keep);
-      try {
-        await c.compact(customInstructions);
-        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) {
-          try {
-            const piAny = pi as unknown as { sendUserMessage?: (content: string) => Promise<void> | void };
-            if (piAny.sendUserMessage) await piAny.sendUserMessage(followUpPrompt);
-          } catch {}
-        }
-      } catch (err: unknown) {
-        const msg = err instanceof Error ? err.message : String(err);
-        const cancelled = msg === "Compaction cancelled" || msg === "Already compacted";
-        const note = cancelled ? "Nothing to compact" : `Compaction failed: ${msg}`;
-        try { c.ui.notify(note, cancelled ? "warning" : "error"); } catch {}
-      }
+      await runCompactCommand(args, c, buildPiVccCustomInstructions, "Compacted with pi-vcc (via omp-vcc)", false, getCompactForm(() => c.getSystemPrompt?.()));
     },
   });
 
@@ -315,8 +346,7 @@ export default function (pi: ExtensionAPI): void {
       const piAny = pi as unknown as { sendMessage?: (msg: unknown, opts?: unknown) => void };
       const { rendered, rawMessages } = loadAllMessages(sessionFile, false, lineageEntryIds);
       if (!query) {
-        const { rendered: r } = loadAllMessages(sessionFile, false, lineageEntryIds);
-        const recent = r.slice(-DEFAULT_RECENT);
+        const recent = rendered.slice(-DEFAULT_RECENT);
         const output = (scope === "all" ? "Scope: all\n\n" : "") + formatRecallOutput(recent);
         try { piAny.sendMessage?.({ customType: "vcc-recall", content: output, display: true }, { triggerTurn: false }); } catch {}
         return;
@@ -326,6 +356,12 @@ export default function (pi: ExtensionAPI): void {
       const scopeSuffix = scope === "all" ? " (scope: all)" : "";
       const scopeArg = scope === "all" ? " scope:all" : "";
       const truncationNote = truncated ? ` — showing ${hits.length} of ${totalBeforeCap} matches, refine your query for more precise results` : "";
+      if (hits.length > 0 && page > totalPages) {
+        const guidance = truncated ? `Use /pi-vcc-recall ${query}${scopeArg} page:N with N between 1 and ${totalPages}.` : `Use /pi-vcc-recall ${query}${scopeArg} page:N with N between 1 and ${totalPages}, or refine your query.`;
+        const text = `Page ${page} is outside the available range 1-${totalPages} (${hits.length} matches${scopeSuffix}${truncationNote}). ${guidance}`;
+        try { piAny.sendMessage?.({ customType: "vcc-recall", content: text, display: true }, { triggerTurn: false }); } catch {}
+        return;
+      }
       const start = (page - 1) * PAGE_SIZE;
       const pageResults = hits.slice(start, start + PAGE_SIZE);
       const header = totalPages > 1 ? `Page ${page}/${totalPages} (${hits.length} total matches${scopeSuffix}${truncationNote})` : `${hits.length} matches${scopeSuffix}${truncationNote}`;
@@ -340,7 +376,7 @@ export default function (pi: ExtensionAPI): void {
   registerVccConfigCommandHook(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, getCompactionHistory, formatCompactionStats, formatStatsTable, formatLastStatsDetail, scheduleCompactionStatsNotify, AUTO_CONTINUE_CUSTOM_TYPE, LEGACY_AUTO_CONTINUE_CUSTOM_TYPE, invalidExpandIndices, registerRecallTool, registerVccRecallCommand, registerPiVccCommand, registerVccStatsTool, registerVccStatsCommand, registerVccConfigCommand, clearCompactionHistoryForTests } from "./vcc-core/hook";
+// ── Re-exports for test compatibility (hook-owned API only; the duplicate
+// recall/pi-vcc registrars were deleted — the factory is the single source) ──
+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, registerVccStatsTool, registerVccStatsCommand, registerVccConfigCommand, clearCompactionHistoryForTests } from "./vcc-core/hook";
 export { buildPiVccCustomInstructions, parseKeepAndPrompt } from "./vcc-core/core/compact-args";

package/extensions/vcc-core/core/search-entries.ts

@@ -126,10 +126,8 @@ const looksLikeRegex = (query: string): boolean =>
   /[|*+?{}()[\]\\^$.]/.test(query);
 
 /** Build a regex for snippet highlighting — matches first available term. */
-const snippetRegex = (terms: string[]): RegExp => {
-  const alts = terms.map((t) => safeRegex(t).source);
-  return new RegExp(alts.join("|"), "i");
-};
+const snippetRegex = (sources: string[]): RegExp =>
+  new RegExp(sources.join("|"), "i");
 
 // ── Stopwords for natural language queries ──
 const STOPWORDS = new Set([
@@ -153,15 +151,29 @@ const filterStopwords = (terms: string[]): string[] => {
   return meaningful.length > 0 ? meaningful : terms;
 };
 
+/** One query term with its matchers compiled once per search: `re` (/i/) for
+ *  boolean tests, `freqRe` (/gi/) for occurrence counts via String.match
+ *  (which resets lastIndex, so reuse across docs is state-safe). */
+interface CompiledTerm {
+  term: string;
+  re: RegExp;
+  freqRe: RegExp;
+}
+
+const compileTerms = (terms: string[]): CompiledTerm[] =>
+  terms.map((t) => {
+    const re = safeRegex(t);
+    return { term: t, re, freqRe: new RegExp(re.source, "gi") };
+  });
+
 /** Count how many distinct terms match the haystack. */
-const countMatches = (hay: string, terms: string[]): number => {
+const countMatches = (hay: string, compiled: CompiledTerm[]): number => {
   let count = 0;
-  for (const t of terms) {
-    if (safeRegex(t).test(hay)) count++;
+  for (const c of compiled) {
+    if (c.re.test(hay)) count++;
   }
   return count;
 };
-
 // ── BM25-lite scoring ──
 const BM25_K = 1.2;
 const BM25_B = 0.75;
@@ -178,18 +190,21 @@ interface BM25Context {
   df: Map<string, number>; // term -> number of docs containing it
 }
 
-/** Precompute IDF and avgDl across all docs. */
-const buildBM25Context = (docs: string[], terms: string[], checkBudget: () => void): BM25Context => {
+/** Precompute IDF and avgDl across all docs. Word counts are measured once
+ *  by the caller (`wordLens`, parallel to `docs`) instead of re-splitting
+ *  every doc here and again in `bm25Score`. */
+const buildBM25Context = (docs: string[], compiled: CompiledTerm[], wordLens: number[], checkBudget: () => void): BM25Context => {
   const n = docs.length;
   const df = new Map<string, number>();
   let totalLen = 0;
 
-  for (const doc of docs) {
+  for (let d = 0; d < docs.length; d++) {
     checkBudget();
-    totalLen += doc.split(/\s+/).length;
-    for (const t of terms) {
-      if (safeRegex(t).test(doc)) {
-        df.set(t, (df.get(t) ?? 0) + 1);
+    const doc = docs[d];
+    totalLen += wordLens[d];
+    for (const c of compiled) {
+      if (c.re.test(doc)) {
+        df.set(c.term, (df.get(c.term) ?? 0) + 1);
       }
     }
   }
@@ -198,22 +213,20 @@ const buildBM25Context = (docs: string[], terms: string[], checkBudget: () => vo
 };
 
 /** BM25 score for a single doc against query terms, plus the calibration
- *  inputs the Bayesian posterior needs: total term frequency across terms,
- *  distinct normalized matched terms (coverage parity), and the doc-length
- *  ratio. Same pass — no re-scanning. */
-const bm25Score = (doc: string, terms: string[], ctx: BM25Context): { score: number; tf: number; distinctTerms: number; docLenRatio: number } => {
-  const dl = doc.split(/\s+/).length;
+ *  inputs the Bayesian posterior needs. `dl` is the doc's word count,
+ *  measured once by the caller alongside `wordLens` — no re-splitting. */
+const bm25Score = (doc: string, compiled: CompiledTerm[], ctx: BM25Context, dl: number): { score: number; tf: number; distinctTerms: number; docLenRatio: number } => {
   let score = 0;
   let totalTf = 0;
   const seenTerms = new Set<string>();
 
-  for (const t of terms) {
-    const termTf = termFreq(doc, safeRegex(t));
+  for (const c of compiled) {
+    const termTf = termFreq(doc, c.freqRe);
     if (termTf === 0) continue;
     totalTf += termTf;
-    seenTerms.add(t.toLowerCase());
+    seenTerms.add(c.term.toLowerCase());
 
-    const docFreq = ctx.df.get(t) ?? 0;
+    const docFreq = ctx.df.get(c.term) ?? 0;
     // IDF: log((N - df + 0.5) / (df + 0.5) + 1)
     const idf = Math.log((ctx.n - docFreq + 0.5) / (docFreq + 0.5) + 1);
     const tfNorm = (termTf * (BM25_K + 1)) / (termTf + BM25_K * (1 - BM25_B + BM25_B * dl / ctx.avgDl));
@@ -532,30 +545,37 @@ export const searchEntriesDetailed = (
   // Natural language / multi-word query: BM25 scoring
   const rawTerms = rawQuery.split(/\s+/);
   const terms = filterStopwords(rawTerms);
-  const snipRe = snippetRegex(terms);
+  const compiled = compileTerms(terms);
+  const snipRe = snippetRegex(compiled.map((c) => c.re.source));
 
-  // Build all docs for BM25 context
+  // Build all docs for BM25 context. Each message's searchable text is
+  // extracted once here (`texts`) and reused for snippets below; word
+  // counts (`wordLens`) are measured once for both context and scoring.
   const docs: string[] = [];
+  const texts: string[] = [];
+  const wordLens: number[] = [];
   for (let i = 0; i < entries.length; i++) {
     const e = entries[i];
     const msg = messages[i];
     const text = msg ? fullText(msg) : e.summary;
     const filePart = e.files?.join(" ") ?? "";
-    docs.push(`${e.role} ${text} ${filePart}`);
+    const hay = `${e.role} ${text} ${filePart}`;
+    docs.push(hay);
+    texts.push(text);
+    wordLens.push(hay.split(/\s+/).length);
   }
 
-  const ctx = buildBM25Context(docs, terms, checkBudget);
+  const ctx = buildBM25Context(docs, compiled, wordLens, checkBudget);
 
   const scored: Array<{ hit: SearchHit; score: number; tf: number; distinctTerms: number; docLenRatio: number }> = [];
   for (let i = 0; i < entries.length; i++) {
     checkBudget();
     const e = entries[i];
     const hay = docs[i];
-    const mc = countMatches(hay, terms);
+    const mc = countMatches(hay, compiled);
     if (mc === 0) continue;
-    const { score, tf, distinctTerms, docLenRatio } = bm25Score(hay, terms, ctx);
-    const text = messages[i] ? fullText(messages[i]) : e.summary;
-    const snip = lineSnippet(text, snipRe);
+    const { score, tf, distinctTerms, docLenRatio } = bm25Score(hay, compiled, ctx, wordLens[i]);
+    const snip = lineSnippet(texts[i], snipRe);
     scored.push({
       hit: { ...e, snippet: snip, matchCount: mc },
       score,

package/extensions/vcc-core/core/token-estimate.ts

@@ -2,6 +2,21 @@
 export const DEFAULT_CHARS_PER_TOKEN = 4;
 export const MIN_CHARS_PER_TOKEN = 2;
 export const MAX_CHARS_PER_TOKEN = 6;
+// Prior for dense machine-generated content (tool dumps, hex/uuid streams:
+// measured ~2.1-2.7 cpt on cl100k_base vs ~4.4-5.2 for code/prose). Used when
+// the slice/tokens ratio contradicts the Latin prior AND the content looks
+// dense — forcing 4 there underestimates dense tails by up to ~1.9x.
+export const DENSE_CONTENT_CHARS_PER_TOKEN = 3;
+// A sample counts as dense when fewer than this fraction of its chars are
+// letters/spaces (measured: dense 0.43, tool output 0.66, code 0.82, prose
+// 0.97 — 0.7 separates machine output from human text).
+export const DENSE_CONTENT_PROSE_FRACTION = 0.7;
+
+export const isDenseContent = (text: string | undefined): boolean => {
+  if (!text) return false;
+  const letters = (text.match(/[A-Za-z ]/g) ?? []).length;
+  return letters / text.length < DENSE_CONTENT_PROSE_FRACTION;
+};
 
 export type TokenEstimateMode = "heuristic" | "calibrated";
 
@@ -20,6 +35,7 @@ export const calibrateCharsPerToken = (
   sourceChars: number,
   sourceTokens: number | undefined,
   sampleText?: string,
+  tailSampleText?: string,
 ): TokenEstimateCalibration => {
   if (!sourceTokens || sourceTokens <= 0 || sourceChars <= 0) {
     return { mode: "heuristic", charsPerToken: DEFAULT_CHARS_PER_TOKEN };
@@ -36,12 +52,18 @@ export const calibrateCharsPerToken = (
   // for Latin text — trusting it inflates every token estimate and the
   // pipeline over-trims. Conversely a high raw on CJK text means the token
   // count under-describes the slice. When the ratio contradicts the
-  // content-class prior, fall back to that prior (reported as heuristic).
   if (sampleText) {
     const cjkChars = (sampleText.match(/[\u2E80-\u9FFF\uAC00-\uD7FF\u3000-\u303F]/g) ?? []).length;
     const cjk = sampleText.length > 0 && cjkChars / sampleText.length >= 0.2;
     if (!cjk && rawCharsPerToken < 2.5) {
-      return { mode: "heuristic", charsPerToken: DEFAULT_CHARS_PER_TOKEN, sourceChars, sourceTokens, rawCharsPerToken };
+      // Dense machine-generated content tokenizes near ~2-2.7 cpt, so a low
+      // raw can be truth (not system-prompt inflation). The head sample alone
+      // cannot tell them apart — a prose head with a dense tail is the exact
+      // shape that under-reported kept tails — so either end being dense
+      // selects the dense prior (3) over the prose prior (4).
+      const dense = isDenseContent(sampleText) || isDenseContent(tailSampleText);
+      const prior = dense ? DENSE_CONTENT_CHARS_PER_TOKEN : DEFAULT_CHARS_PER_TOKEN;
+      return { mode: "heuristic", charsPerToken: prior, sourceChars, sourceTokens, rawCharsPerToken };
     }
     if (cjk && rawCharsPerToken > 3) {
       return { mode: "heuristic", charsPerToken: MIN_CHARS_PER_TOKEN, sourceChars, sourceTokens, rawCharsPerToken };
@@ -140,6 +162,32 @@ export interface UsageStats {
  * against summed provider usage when present, heuristic fallback otherwise.
  */
 export const collectUsageStats = (messages: any[]): UsageStats => {
+  // Bounded content samples for the calibration slice/tokens guards
+  // (classification only needs a fraction of the text): head sample plus a
+  // tail sample, since a prose head with a dense tail selects the dense prior.
+  const head = { text: "" };
+  const tail = { text: "" };
+  const takeInto = (store: { text: string }, text: unknown) => {
+    if (store.text.length >= 8000 || typeof text !== "string" || !text) return;
+    store.text += (store.text ? "\n" : "") + text.slice(0, 8000 - store.text.length);
+  };
+  const samplePartsInto = (store: { text: string }, content: unknown) => {
+    if (typeof content === "string") takeInto(store, content);
+    else if (Array.isArray(content)) {
+      for (const part of content) {
+        if (part?.type === "text" && typeof part.text === "string") takeInto(store, part.text);
+      }
+    }
+  };
+  const sampleMessageInto = (store: { text: string }, m: any) => {
+    const role = typeof m?.role === "string" ? m.role : "unknown";
+    if (role === "bashExecution") {
+      takeInto(store, m?.command);
+      takeInto(store, m?.output);
+    } else {
+      samplePartsInto(store, m?.content);
+    }
+  };
   const byRole: Record<string, number> = {};
   const models = new Set<string>();
   let toolCallCount = 0;
@@ -147,21 +195,6 @@ export const collectUsageStats = (messages: any[]): UsageStats => {
   let outputChars = 0;
   let minTs = Infinity;
   let maxTs = -Infinity;
-  // Bounded content sample for the calibration slice/tokens guards
-  // (classification only needs a fraction of the text).
-  let sample = "";
-  const takeSample = (text: unknown) => {
-    if (sample.length >= 8000 || typeof text !== "string" || !text) return;
-    sample += (sample ? "\n" : "") + text.slice(0, 8000 - sample.length);
-  };
-  const sampleParts = (content: unknown) => {
-    if (typeof content === "string") takeSample(content);
-    else if (Array.isArray(content)) {
-      for (const part of content) {
-        if (part?.type === "text" && typeof part.text === "string") takeSample(part.text);
-      }
-    }
-  };
   const usageTotals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
   let sawUsage = false;
   for (const m of messages ?? []) {
@@ -181,23 +214,27 @@ export const collectUsageStats = (messages: any[]): UsageStats => {
     }
     if (role === "assistant") {
       outputChars += estimateMessageContentChars(m?.content);
-      sampleParts(m?.content);
+      sampleMessageInto(head, m);
       if (Array.isArray(m?.content)) {
         for (const part of m.content) if (part?.type === "toolCall") toolCallCount++;
       }
     } else if (role === "bashExecution") {
       inputChars += (typeof m?.command === "string" ? m.command.length : 0) + 1
         + (typeof m?.output === "string" ? m.output.length : 0);
-      takeSample(m?.command);
-      takeSample(m?.output);
+      sampleMessageInto(head, m);
     } else {
       inputChars += estimateMessageContentChars(m?.content);
-      sampleParts(m?.content);
+      sampleMessageInto(head, m);
     }
   }
+  // Tail sample in reverse: the last messages dominate kept-tail estimates.
+  const list = messages ?? [];
+  for (let i = list.length - 1; i >= 0 && tail.text.length < 8000; i--) {
+    sampleMessageInto(tail, list[i]);
+  }
   const totalChars = inputChars + outputChars;
   const sourceTokens = sawUsage ? usageTotals.input + usageTotals.output : undefined;
-  const calibration = calibrateCharsPerToken(totalChars, sourceTokens, sample || undefined);
+  const calibration = calibrateCharsPerToken(totalChars, sourceTokens, head.text || undefined, tail.text || undefined);
   return {
     messageCount: messages?.length ?? 0,
     byRole,

package/extensions/vcc-core/hook.ts

@@ -8,27 +8,100 @@ import { loadSettings, loadSettingsWithSources, DEFAULT_SETTINGS, type PiVccSett
 import { calibrateCharsPerToken, estimateMessageContentChars, estimateMessageContentTokens, estimateTokensFromChars, collectUsageStats } from "./core/token-estimate";
 import type { PiVccCompactionDetails } from "./details";
 import type { CompactionReason } from "./types";
-import { loadAllMessages as _loadAllMessages } from "./core/load-messages";
-import { searchEntriesDetailed as _searchEntriesDetailed, getTouchedFiles as _getTouchedFiles } from "./core/search-entries";
-import { formatRecallOutput as _formatRecallOutput, formatTouchedOutput as _formatTouchedOutput } from "./core/format-recall";
-import { getActiveLineageEntryIds as _getActiveLineageEntryIds } from "./core/lineage";
-import { normalizeRecallScope as _normalizeRecallScope, normalizeRecallMode as _normalizeRecallMode, parseRecallScope as _parseRecallScope } from "./core/recall-scope";
-import { parseDrillDown as _parseDrillDown, expandEntryFile as _expandEntryFile, parseEntryRef as _parseEntryRef, expandEntry as _expandEntry } from "./core/drill-down";
-
-// convertToLlm shim: try host export, fallback to identity (preserves AgentMessage for omp compileRanked)
+
+// convertToLlm shim: resolve the host export, fallback to identity (identity
+// is fine for bashExecution/custom, which the pipeline renders natively, but
+// it leaks !!-excluded spans and drops branchSummary entries — so the
+// @earendil-works root (pi's canonical export path) is tried first.
+const CONVERT_TO_LLM_CANDIDATES = [
+  "@earendil-works/pi-coding-agent",
+  "@oh-my-pi/pi-coding-agent",
+  "@oh-my-pi/pi-coding-agent/session/messages",
+] as const;
+// Pure loader-driven resolver: first candidate whose module exports a
+// convertToLlm function wins, else null (caller keeps identity).
+export const resolveConvertToLlm = (
+  load: (id: string) => any,
+): ((messages: any[]) => any[]) | null => {
+  for (const id of CONVERT_TO_LLM_CANDIDATES) {
+    try {
+      const mod = load(id);
+      if (mod && typeof mod.convertToLlm === "function") return mod.convertToLlm;
+    } catch {}
+  }
+  return null;
+};
 let convertToLlm: (messages: any[]) => any[] = (m) => m;
 try {
   const req = createRequire(import.meta.url);
-  const mod = req("@oh-my-pi/pi-coding-agent/session/messages") as any;
-  if (mod?.convertToLlm) convertToLlm = mod.convertToLlm;
+  convertToLlm = resolveConvertToLlm((id) => req(id)) ?? convertToLlm;
 } catch {}
-try {
-  if (convertToLlm.length === 0 || (convertToLlm as any).toString().includes("=> m")) {
-    const req2 = createRequire(import.meta.url);
-    const mod2 = req2("@oh-my-pi/pi-coding-agent") as any;
-    if (mod2?.convertToLlm) convertToLlm = mod2.convertToLlm;
+// Test-only override for the module-level binding (mirrors
+// clearCompactionHistoryForTests): lets suites pin convertToLlm wiring without
+// stubbing node module resolution. Null resets to the identity fallback.
+export const __setConvertToLlmForTests = (fn: ((messages: Array<unknown>) => Array<unknown>) | null): void => {
+  convertToLlm = fn ?? ((m) => m);
+};
+// Host-kind detection: omp and pi expose incompatible ctx.compact shapes
+// (omp: (string|CompactOptions)=>Promise<void> with instructions on the
+// string; pi: (CompactOptions)=>void with instructions only via
+// options.customInstructions). Three layers, first hit wins:
+// 1. Explicit test override (__setHostKindForTests).
+// 2. Observable ctx shape — works in bundled runtimes where module
+//    resolution misses: pi's getSystemPrompt() returns a string, omp's
+//    returns string[]. Pure getters, safe to call.
+// 3. Module scope — works in dev/source runtimes: @earendil-works is
+//    pi-exclusive (same mechanism as the convertToLlm shim above).
+// Default "omp" preserves the legacy string-form call when host-free.
+const HOST_KIND_CANDIDATES = ["@earendil-works/pi-coding-agent", "@oh-my-pi/pi-coding-agent"] as const;
+export type VccHostKind = "pi" | "omp";
+export type VccCompactForm = "object" | "string";
+// Pure loader-driven resolver: first resolvable scope wins (@earendil-works
+// first, mirroring CONVERT_TO_LLM_CANDIDATES), else "omp".
+export const resolveHostKind = (load: (id: string) => unknown): VccHostKind => {
+  for (const id of HOST_KIND_CANDIDATES) {
+    try {
+      if (load(id)) return id.startsWith("@earendil-works") ? "pi" : "omp";
+    } catch {}
   }
+  return "omp";
+};
+let defaultHostKind: VccHostKind = "omp";
+try {
+  defaultHostKind = resolveHostKind((id) => createRequire(import.meta.url)(id));
 } catch {}
+let hostKindOverride: VccHostKind | null = null;
+export const getHostKind = (): VccHostKind => hostKindOverride ?? defaultHostKind;
+// Test-only override (mirrors __setConvertToLlmForTests). Null restores the
+// detected default.
+export const __setHostKindForTests = (kind: VccHostKind | null): void => {
+  hostKindOverride = kind;
+};
+// Layered compact-form decision for a live ctx. getSystemPrompt is read off
+// the calling ctx (command or event); absent (host-free mocks) falls through
+// to module scope, then the legacy default.
+export const resolveCompactForm = (
+  load: (id: string) => unknown,
+  getSystemPrompt?: () => unknown,
+): VccCompactForm => {
+  if (hostKindOverride) return hostKindOverride === "pi" ? "object" : "string";
+  try {
+    const sp = getSystemPrompt?.();
+    if (typeof sp === "string") return "object";
+    if (Array.isArray(sp)) return "string";
+  } catch {}
+  return resolveHostKind(load) === "pi" ? "object" : "string";
+};
+export const getCompactForm = (getSystemPrompt?: () => unknown): VccCompactForm => {
+  let load: (id: string) => unknown = () => {
+    throw new Error("no loader");
+  };
+  try {
+    const req = createRequire(import.meta.url);
+    load = (id) => req(id);
+  } catch {}
+  return resolveCompactForm(load, getSystemPrompt);
+};
 
 export { PI_VCC_COMPACT_INSTRUCTION } from "./core/compact-args";
 export const OMP_VCC_COMPACT_INSTRUCTION = "__omp_vcc__";
@@ -76,6 +149,38 @@ export interface CompactionStats {
 
 export type BudgetCutKind = "no_anchor" | "oversized_tail";
 export const OVERSIZED_TAIL_FACTOR = 2.5;
+// Growth-guard tolerance: compacting removes N messages (freeing their
+// per-message framing) and adds one summary entry (framing + details JSON).
+// Char-diff is otherwise exact, but host token accounting has noise both
+// ways, so the guard only fires on MATERIAL growth: the net-new summary
+// content must exceed the removed prefix by more than a fixed framing
+// allowance (one entry, ~128 tok) or 25% of the prefix (per-message
+// overhead share) — or exceed the absolute cap (~1k tok) at any ratio, so
+// large-scale drift cannot hide behind a big denominator.
+export const COMPACTION_GROWTH_FIXED_MARGIN_CHARS = 512;
+export const COMPACTION_GROWTH_RELATIVE_MARGIN = 0.25;
+export const COMPACTION_GROWTH_ABSOLUTE_CAP_CHARS = 4096;
+
+export interface GrowthGuardVerdict {
+  trip: boolean;
+  netGrowthChars: number;
+  toleranceChars: number;
+}
+
+// Pure growth-guard predicate (calibration-free). Table-driven unit tests in
+// tests/compaction-growth-guard.test.ts pin every arm and edge.
+export const evaluateGrowthGuard = (prefixChars: number, netNewSummaryChars: number): GrowthGuardVerdict => {
+  const netGrowthChars = netNewSummaryChars - prefixChars;
+  const toleranceChars = Math.max(
+    COMPACTION_GROWTH_FIXED_MARGIN_CHARS,
+    Math.round(prefixChars * COMPACTION_GROWTH_RELATIVE_MARGIN),
+  );
+  return {
+    trip: netGrowthChars > toleranceChars || netGrowthChars > COMPACTION_GROWTH_ABSOLUTE_CAP_CHARS,
+    netGrowthChars,
+    toleranceChars,
+  };
+}
 
 let lastStats: CompactionStats | null = null;
 let lastCompactWasPiVcc = false;
@@ -368,6 +473,27 @@ const previewContent = (content: unknown): string => {
   return "";
 };
 
+/** Join parts with "\n" truncated to `bound` chars — byte-identical to
+ *  `parts.join("\n").slice(0, bound)` without materializing the full
+ *  joined string (calibration samples join up to 50 message contents,
+ *  any one of which can be megabytes). */
+export const joinBounded = (parts: string[], bound: number): string => {
+  let out = "";
+  let rem = bound;
+  for (let i = 0; i < parts.length; i++) {
+    if (rem <= 0) break;
+    if (i > 0) {
+      out += "\n";
+      rem--;
+      if (rem <= 0) break;
+    }
+    const take = parts[i].slice(0, rem);
+    out += take;
+    rem -= take.length;
+  }
+  return out;
+};
+
 interface EntryWithMessage {
   entry: { id: string; type: string };
   message: { role: string; content: unknown };
@@ -739,18 +865,26 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
     // Always handle explicit /pi-vcc or /omp-vcc marker.
     // 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.
+    // via an event field, let the host walker handle it even though
+    // overrideDefaultCompaction is true. This enables sequential VCC →
+    // snapcompact/shake combinations. No shipped host exposes such a field
+    // today — omp carries the mode in the compact() options (never the event)
+    // and pi has no modes (its /compact text is raw focus instructions, so
+    // lone mode words must NEVER bypass: on pi `/compact shake` means
+    // "focus on shake"). The branch stays as the contract for the optional
+    // native patch / future hosts; unpatched, override:true serves explicit
+    // omp modes via VCC (use override:false for native modes).
     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;
     }
+    // Chain-shake yield: while a {mode:"shake"} chain is in flight (see
+    // session_compact below), let the host run it — otherwise VCC would
+    // swallow the modeless call into a second VCC pass. Sentinel compactions
+    // still handled (isPiVcc path falls through below).
+    if (!isPiVcc && pendingChainShake.has(pi as unknown as object)) return;
     if (!isPiVcc && !settings.overrideDefaultCompaction) return;
 
     const calibrationCut = buildOwnCut(branchEntries as any[], 0);
@@ -763,20 +897,29 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
     const calibrationSummaryChars = typeof preparation.previousSummary === "string"
       ? preparation.previousSummary.length
       : 0;
-    // Content sample for the slice/tokens mismatch guards: slice text when the
-    // calibration cut has any, else the previous summary. Bounded (first 50
-    // string contents, 8k chars) — classification only needs a fraction.
-    const calibrationSample = calibrationCut.ok
-      ? calibrationCut.messages
-          .slice(0, 50)
-          .map((message: any) => (typeof message.content === "string" ? message.content : ""))
-          .join("\n")
-          .slice(0, 8000)
-      : "";
+    // Content samples for the mismatch guards: head text (first 50 mapped
+    // contents — string content or "" per message) plus tail text (last 50).
+    // A prose head with a dense tail is the exact shape that under-reported
+    // kept tails, so density is checked on both ends. Bounded (8k chars each):
+    // only the sampled windows are joined, never the whole transcript.
+    const calibrationMsgs = calibrationCut.ok ? calibrationCut.messages : [];
+    const headContents: string[] = [];
+    for (let i = 0; i < calibrationMsgs.length && headContents.length < 50; i++) {
+      const c = (calibrationMsgs[i] as any).content;
+      headContents.push(typeof c === "string" ? c : "");
+    }
+    const tailContents: string[] = [];
+    for (let i = Math.max(0, calibrationMsgs.length - 50); i < calibrationMsgs.length; i++) {
+      const c = (calibrationMsgs[i] as any).content;
+      tailContents.push(typeof c === "string" ? c : "");
+    }
+    const calibrationSample = joinBounded(headContents, 8000);
+    const calibrationTailSample = joinBounded(tailContents, 8000);
     const tokenEstimate = calibrateCharsPerToken(
       calibrationMessageChars + calibrationSummaryChars,
       preparation.tokensBefore,
       calibrationSample || (typeof preparation.previousSummary === "string" ? preparation.previousSummary.slice(0, 8000) : undefined),
+      calibrationTailSample || undefined,
     );
 
     // Smart keep-tail: boost default keep when the tail is small.
@@ -951,8 +1094,53 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
       return { cancel: true };
     }
 
-    const tokensBefore = typeof preparation.tokensBefore === "number" ? preparation.tokensBefore : 0;
+    // Growth guard: never emit a summary that materially adds more than it
+    // removes. tokensAfter - tokensBefore ≈ (netNew - prefix) / cpt: the kept
+    // tail cancels out, so the comparison is calibration-independent and
+    // exact in chars (plan-mode "compact and execute" grew 85K→87K: a 2-msg
+    // prefix replaced by a fixed-cost summary + brief floor). Compare the
+    // net-new content (summary minus carried-forward previous summary, which
+    // is already counted in the live context) against the removed prefix.
+    // Fires only on material growth — a fixed framing allowance or 25% of the
+    // prefix (host accounting noise), or the absolute cap (~1k tok) at any
+    // ratio. On overflow/willRetry the window is exhausted and SOME compaction
+    // must happen: abstain (host default proceeds) instead of cancelling.
     const summaryChars = summary.length;
+    const prefixChars = agentMessages.reduce(
+      (sum: number, message: any) => sum + estimateMessageContentChars(message.content),
+      0,
+    );
+    const prevSummaryChars = typeof preparation.previousSummary === "string"
+      ? preparation.previousSummary.length
+      : 0;
+    const netNewSummaryChars = summaryChars - Math.min(summaryChars, prevSummaryChars);
+    const guard = evaluateGrowthGuard(prefixChars, netNewSummaryChars);
+    const { netGrowthChars, toleranceChars } = guard;
+    if (guard.trip) {
+      const prefixTok = estimateTokensFromChars(prefixChars, tokenEstimate.charsPerToken);
+      const netNewTok = estimateTokensFromChars(netNewSummaryChars, tokenEstimate.charsPerToken);
+      dbg(settings, {
+        growthGuard: true,
+        cancelled: reason !== "overflow" && !willRetry,
+        fallbackToCore: reason === "overflow" || willRetry,
+        compaction: { reason, willRetry },
+        prefixChars,
+        prevSummaryChars,
+        netNewSummaryChars,
+        netGrowthChars,
+        toleranceChars,
+      });
+      try {
+        ctx?.ui?.notify?.(
+          `omp-vcc: compaction would grow context (prefix ~${formatTokens(prefixTok)} tok, summary adds ~${formatTokens(netNewTok)} tok) — ${reason === "overflow" || willRetry ? "deferring to host compaction" : "cancelled"}`,
+          "info",
+        );
+      } catch {}
+      if (reason === "overflow" || willRetry) return;
+      return { cancel: true };
+    }
+
+    const tokensBefore = typeof preparation.tokensBefore === "number" ? preparation.tokensBefore : 0;
     const summaryTokensEst = estimateTokensFromChars(summaryChars, tokenEstimate.charsPerToken);
     const tokensAfterEst = summaryTokensEst + keptTokensEst;
     const tokensSavedEst = tokensBefore > 0 ? Math.max(0, tokensBefore - tokensAfterEst) : 0;
@@ -1102,13 +1290,21 @@ 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.
+    // Eager post-VCC shake chain (chainShakeHint, omp only). {mode:"shake"}
+    // is the omp native spelling; the before handler above yields while
+    // pendingChainShake is set so the host actually runs shake instead of
+    // VCC swallowing the modeless call. pi's CompactOptions has no mode key
+    // (the call would trigger a spurious default compaction), so pi never
+    // chains — host rescue remains the only shake path there.
     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) {
+      const promptOf = ctxMaybe["getSystemPrompt"] as ((this: unknown) => unknown) | undefined;
+      // Form is detected off the live ctx so bundled runtimes (no module
+      // scope) still decide correctly.
+      const chainForm = getCompactForm(() => promptOf?.call(ctx));
+      if (cfgChain.chainShakeHint && chainForm === "string" && 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;
@@ -1122,8 +1318,12 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
       }
     } catch {}
     if (followUpPrompt) {
+      // Fire-and-forget: pi's sendUserMessage returns void, omp's returns a
+      // promise — never await either, but swallow async rejections so a
+      // failed redelivery cannot surface as an unhandled rejection.
       try {
-        await pi.sendUserMessage(followUpPrompt);
+        const sent = (pi as any).sendUserMessage?.(followUpPrompt) as Promise<void> | undefined;
+        if (sent && typeof sent.catch === "function") sent.catch(() => {});
       } catch {}
     } else if (shouldContinueAfterAutoCompact) {
       scheduleAutoContinueForPi(pi);
@@ -1136,172 +1336,6 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
 export const invalidExpandIndices = (requested: number[], available: Set<number>): number[] =>
   requested.filter((i) => !Number.isInteger(i) || !available.has(i));
 
-const DEFAULT_RECENT = 25;
-const PAGE_SIZE = 5;
-
-export const registerRecallTool = (pi: any) => {
-  const schema = pi?.zod?.object
-    ? pi.zod.object({
-        query: pi.zod.string().optional(),
-        expand: pi.zod.array(pi.zod.number()).optional(),
-        page: pi.zod.number().optional(),
-        scope: pi.zod.enum(["lineage", "all", "active"]).optional(),
-        mode: pi.zod.enum(["hybrid", "touched"]).optional(),
-      })
-    : {};
-  pi.registerTool({
-    name: "vcc_recall",
-    label: "VCC Recall",
-    description: "Recall earlier parts of the current session",
-    approval: "read",
-    parameters: schema,
-    async execute(_toolCallId: string, params: any, _signal: unknown, _onUpdate: unknown, ctx: any) {
-      const sessionFile = ctx?.sessionManager?.getSessionFile?.();
-      if (!sessionFile) return { content: [{ type: "text", text: "No session file available." }] };
-      const scope = _normalizeRecallScope(params.scope === "active" ? "lineage" : params.scope);
-      const lineageEntryIds = scope === "lineage" ? _getActiveLineageEntryIds(ctx.sessionManager) : undefined;
-      const q = params.query?.trim();
-      if (q && _parseEntryRef(q)) {
-        const ref = _parseEntryRef(q)!;
-        if (lineageEntryIds) {
-          const { rendered } = _loadAllMessages(sessionFile, false, lineageEntryIds);
-          if (!rendered.some((m) => m.index === ref.index)) {
-            return { content: [{ type: "text", text: `Cannot expand indices outside active lineage: ${ref.index}. Use scope:'all' to reach other branches.` }] };
-          }
-        }
-        const text = _expandEntry(sessionFile, ref.index, ref.full, ref.offset, ref.limit);
-        return { content: [{ type: "text", text }] };
-      }
-      if (q && _parseDrillDown(q)) {
-        const parsed = _parseDrillDown(q)!;
-        if (lineageEntryIds) {
-          const { rendered } = _loadAllMessages(sessionFile, false, lineageEntryIds);
-          if (!rendered.some((m) => m.index === parsed.index)) {
-            return { content: [{ type: "text", text: `Cannot expand indices outside active lineage: ${parsed.index}. Use scope:'all' to reach other branches.` }] };
-          }
-        }
-        const text = _expandEntryFile(sessionFile, parsed.index, parsed.pathPattern, parsed.full, parsed.offset, parsed.limit);
-        return { content: [{ type: "text", text }] };
-      }
-      if (_normalizeRecallMode(params.mode) === "touched") {
-        const { rendered, rawMessages } = _loadAllMessages(sessionFile, false, lineageEntryIds);
-        const touched = _getTouchedFiles(rawMessages as any, rendered);
-        const text = _formatTouchedOutput(touched, params.page);
-        return { content: [{ type: "text", text }] };
-      }
-      const expandSet = new Set(params.expand ?? []);
-      if (expandSet.size > 0) {
-        const { rendered: fullMsgs } = _loadAllMessages(sessionFile, true, lineageEntryIds);
-        const requested = [...expandSet];
-        const byIndex = new Map(fullMsgs.map((m) => [m.index, m]));
-        const invalid = invalidExpandIndices(requested, new Set(byIndex.keys()));
-        if (invalid.length > 0) return { content: [{ type: "text", text: `Cannot expand indices outside ${scope === "all" ? "session history" : "active lineage"}: ${invalid.join(", ")}` }] };
-        const expanded = requested.map((i) => byIndex.get(i)).filter(Boolean) as any[];
-        const output = (scope === "all" ? "Scope: all\n\n" : "") + _formatRecallOutput(expanded);
-        return { content: [{ type: "text", text: output }] };
-      }
-      const { rendered: msgs, rawMessages } = _loadAllMessages(sessionFile, false, lineageEntryIds);
-      if (q) {
-        const { hits, totalBeforeCap, truncated } = _searchEntriesDetailed(msgs, rawMessages as any, q);
-        const page = Math.max(1, params.page ?? 1);
-        const totalPages = Math.ceil(hits.length / PAGE_SIZE);
-        const scopeSuffix = scope === "all" ? " (scope: all)" : "";
-        const truncationNote = truncated ? ` — showing ${hits.length} of ${totalBeforeCap} matches, refine your query for more precise results` : "";
-        if (hits.length > 0 && page > totalPages) {
-          const guidance = truncated ? `Use a page between 1 and ${totalPages}.` : `Use a page between 1 and ${totalPages}, or refine your query.`;
-          const text = `Page ${page} is outside the available range 1-${totalPages} (${hits.length} matches${scopeSuffix}${truncationNote}). ${guidance}`;
-          return { content: [{ type: "text", text }] };
-        }
-        const start = (page - 1) * PAGE_SIZE;
-        const pageResults = hits.slice(start, start + PAGE_SIZE);
-        const header = totalPages > 1 ? `Page ${page}/${totalPages} (${hits.length} total matches${scopeSuffix}${truncationNote})` : `${hits.length} matches${scopeSuffix}${truncationNote}`;
-        const footer = page < totalPages ? `\n--- Use page:${page + 1}${scope === "all" ? " with scope:'all'" : ""} for more results ---` : "";
-        const output = _formatRecallOutput(pageResults, q, header, { truncated, totalBeforeCap }) + footer;
-        return { content: [{ type: "text", text: output }] };
-      }
-      const output = (scope === "all" ? "Scope: all\n\n" : "") + _formatRecallOutput(msgs.slice(-DEFAULT_RECENT), q);
-      return { content: [{ type: "text", text: output }] };
-    },
-  });
-};
-
-export const registerVccRecallCommand = (pi: any) => {
-  pi.registerCommand("pi-vcc-recall", {
-    description: "Recall earlier parts of this session",
-    handler: async (args: string, ctx: any) => {
-      const sessionFile = ctx?.sessionManager?.getSessionFile?.();
-      if (!sessionFile) { try { ctx.ui.notify("No session file available.", "error"); } catch {} return; }
-      const raw = args.trim();
-      const parsed = _parseRecallScope(raw);
-      const lineageEntryIds = parsed.scope === "lineage" ? _getActiveLineageEntryIds(ctx.sessionManager) : undefined;
-      if (!parsed.text) {
-        const { rendered } = _loadAllMessages(sessionFile, false, lineageEntryIds);
-        const recent = rendered.slice(-DEFAULT_RECENT);
-        const output = (parsed.scope === "all" ? "Scope: all\n\n" : "") + _formatRecallOutput(recent);
-        try { pi.sendMessage?.({ customType: "vcc-recall", content: output, display: true }, { triggerTurn: false }); } catch {}
-        return;
-      }
-      const pageMatch = parsed.text.match(/\bpage:(\d+)\b/i);
-      const page = pageMatch ? Math.max(1, parseInt(pageMatch[1], 10)) : 1;
-      const query = parsed.text.replace(/\bpage:\d+\b/i, "").trim();
-      if (!query) {
-        const { rendered } = _loadAllMessages(sessionFile, false, lineageEntryIds);
-        const recent = rendered.slice(-DEFAULT_RECENT);
-        const output = (parsed.scope === "all" ? "Scope: all\n\n" : "") + _formatRecallOutput(recent);
-        try { pi.sendMessage?.({ customType: "vcc-recall", content: output, display: true }, { triggerTurn: false }); } catch {}
-        return;
-      }
-      const { rendered, rawMessages } = _loadAllMessages(sessionFile, false, lineageEntryIds);
-      const { hits, totalBeforeCap, truncated } = _searchEntriesDetailed(rendered, rawMessages as any, query);
-      const totalPages = Math.ceil(hits.length / PAGE_SIZE);
-      const scopeSuffix = parsed.scope === "all" ? " (scope: all)" : "";
-      const scopeArg = parsed.scope === "all" ? " scope:all" : "";
-      const truncationNote = truncated ? ` — showing ${hits.length} of ${totalBeforeCap} matches, refine your query for more precise results` : "";
-      if (hits.length > 0 && page > totalPages) {
-        const guidance = truncated ? `Use /pi-vcc-recall ${query}${scopeArg} page:N with N between 1 and ${totalPages}.` : `Use /pi-vcc-recall ${query}${scopeArg} page:N with N between 1 and ${totalPages}, or refine your query.`;
-        const text = `Page ${page} is outside the available range 1-${totalPages} (${hits.length} matches${scopeSuffix}${truncationNote}). ${guidance}`;
-        try { pi.sendMessage?.({ customType: "vcc-recall", content: text, display: true }, { triggerTurn: false }); } catch {}
-        return;
-      }
-      const start = (page - 1) * PAGE_SIZE;
-      const pageResults = hits.slice(start, start + PAGE_SIZE);
-      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, { truncated, totalBeforeCap }) + footer;
-      try { pi.sendMessage?.({ customType: "vcc-recall", content: output, display: true }, { triggerTurn: false }); } catch {}
-    },
-  });
-};
-
-export const registerPiVccCommand = (pi: any) => {
-  pi.registerCommand("pi-vcc", {
-    description: "Compact conversation with pi-vcc structured summary",
-    handler: async (args: string, ctx: any) => {
-      const { followUpPrompt, keepUserTurns } = parseKeepAndPrompt(args);
-      ctx.compact({
-        customInstructions: buildPiVccCustomInstructions(keepUserTurns),
-        onComplete: () => {
-          const stats = getLastCompactionStats(pi);
-          if (stats) {
-            scheduleCompactionStatsNotify(ctx, stats);
-          } else {
-            ctx.ui.notify("Compacted with pi-vcc", "info");
-          }
-          if (followUpPrompt) {
-            try {
-              void Promise.resolve(pi.sendUserMessage(followUpPrompt)).catch(() => {});
-            } catch {}
-          }
-        },
-        onError: (err) => {
-          const cancelled = err.message === "Compaction cancelled" || err.message === "Already compacted";
-          const msg = cancelled ? "Nothing to compact" : `Compaction failed: ${err.message}`;
-          ctx.ui.notify(msg, cancelled ? "warning" : "error");
-        },
-      });
-    },
-  });
-};
 export const registerVccStatsTool = (pi: any) => {
   const hasBoolean = typeof pi?.zod?.boolean === "function";
   const schema = pi?.zod?.object && hasBoolean

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-vcc",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "type": "module",
   "description": "Algorithmic VCC compaction for omp - fast lossless no-LLM",
   "author": "Zhu Lin <zhulin@czl.my>",

package/scripts/smoke.ts

@@ -59,6 +59,14 @@ try {
     "vcc_stats registered",
     tools.some((t) => t.name === "vcc_stats"),
   );
+  check(
+    "vcc_recall schema has query/expand/page/scope/mode",
+    (() => {
+      const t = tools.find((t) => t.name === "vcc_recall");
+      const keys = t?.parameters ? Object.keys(t.parameters) : [];
+      return ["query", "expand", "page", "scope", "mode"].every((k) => keys.includes(k));
+    })(),
+  );
   check(
     "omp-vcc command registered",
     commands.some((c) => c.name === "omp-vcc"),

package/types.d.ts

@@ -14,13 +14,13 @@ declare module "@oh-my-pi/pi-coding-agent" {
       getBranch(fromId?: string): any[];
       getEntries(): any[];
     };
-    compact(instructionsOrOptions?: string | any): Promise<void>;
+    compact(instructionsOrOptions?: string | any): Promise<void> | void;
     sendMessage?: any;
     sendUserMessage?: any;
     [key: string]: unknown;
   }
   export interface ExtensionCommandContext extends ExtensionContext {
-    compact(instructionsOrOptions?: string | any): Promise<void>;
+    compact(instructionsOrOptions?: string | any): Promise<void> | void;
   }
   export interface ExtensionAPI {
     registerTool(tool: unknown): void;

package/extensions/vcc-core/commands/vcc-recall.ts

@@ -1,2 +0,0 @@
-// @ts-nocheck
-export { registerVccRecallCommand } from "../hook";