omp-vcc 0.1.11 → 0.1.12

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,7 @@ import {
   registerVccStatsTool as registerVccStatsToolHook,
   registerVccStatsCommand as registerVccStatsCommandHook,
   registerVccConfigCommand as registerVccConfigCommandHook,
+  invalidExpandIndices,
 } from "./vcc-core/hook";
 import { searchEntriesDetailed, getTouchedFiles } from "./vcc-core/core/search-entries";
 import { formatRecallOutput, formatTouchedOutput } from "./vcc-core/core/format-recall";
@@ -141,7 +142,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(", ")}` }],
@@ -315,8 +316,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 +326,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 +346,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,12 +8,6 @@ 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)
 let convertToLlm: (messages: any[]) => any[] = (m) => m;
@@ -76,6 +70,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 +394,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 };
@@ -763,20 +810,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 +1007,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;
@@ -1136,172 +1237,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.12",
   "type": "module",
   "description": "Algorithmic VCC compaction for omp - fast lossless no-LLM",
   "author": "Zhu Lin <zhulin@czl.my>",

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

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