ultimate-pi 0.4.0 → 0.5.0

package/vendor/pi-vcc/src/hooks/before-compact.ts

@@ -0,0 +1,314 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { convertToLlm } from "@mariozechner/pi-coding-agent";
+import { writeFileSync } from "fs";
+import { compile } from "../core/summarize";
+import { loadSettings, type PiVccSettings } from "../core/settings";
+import type { PiVccCompactionDetails } from "../details";
+
+export const PI_VCC_COMPACT_INSTRUCTION = "__pi_vcc__";
+
+export interface CompactionStats {
+  summarized: number;
+  kept: number;
+  keptTokensEst: number;
+}
+
+let lastStats: CompactionStats | null = null;
+let lastCompactWasPiVcc = false;
+export const getLastCompactionStats = () => lastStats;
+
+const formatTokens = (n: number): string => {
+  if (n >= 1000) return `${(n / 1000).toFixed(1)}k`;
+  return String(n);
+};
+
+const dbg = (settings: PiVccSettings, data: Record<string, unknown>) => {
+  if (!settings.debug) return;
+  try { writeFileSync("/tmp/pi-vcc-debug.json", JSON.stringify(data, null, 2)); } catch {}
+};
+
+const previewContent = (content: unknown): string => {
+  if (typeof content === "string") return content.slice(0, 300);
+  if (Array.isArray(content)) {
+    return content
+      .map((c: any) => {
+        if (c?.type === "text") return c.text ?? "";
+        if (c?.type === "toolCall") return `[toolCall:${c.name}]`;
+        if (c?.type === "thinking") return `[thinking]`;
+        if (c?.type === "image") return `[image:${c.mimeType}]`;
+        return `[${c?.type ?? "unknown"}]`;
+      })
+      .join("\n")
+      .slice(0, 300);
+  }
+  return "";
+};
+
+interface EntryWithMessage {
+  entry: { id: string; type: string };
+  message: { role: string; content: unknown };
+}
+
+export type OwnCutCancelReason =
+  | "no_live_messages"
+  | "too_few_live_messages";
+
+export type OwnCutResult =
+  | { ok: true; messages: any[]; firstKeptEntryId: string; compactAll: boolean }
+  | { ok: false; reason: OwnCutCancelReason };
+
+export function buildOwnCut(branchEntries: any[]): OwnCutResult {
+  // Find the last compaction entry and its firstKeptEntryId
+  let lastCompactionIdx = -1;
+  let lastKeptId: string | undefined;
+  for (let i = branchEntries.length - 1; i >= 0; i--) {
+    if (branchEntries[i].type === "compaction") {
+      lastCompactionIdx = i;
+      lastKeptId = branchEntries[i].firstKeptEntryId;
+      break;
+    }
+  }
+
+  // Orphan recovery: triggers when lastKeptId is set to "" (sentinel from prior
+  // compact-all) OR set to an id that no longer exists in the branch. In both cases,
+  // start collecting from right after the last compaction entry.
+  const hasPriorCompaction = lastCompactionIdx >= 0;
+  const hasValidKeptId = !!lastKeptId && branchEntries.some((e: any) => e.id === lastKeptId);
+  const orphanRecovery = hasPriorCompaction && !hasValidKeptId;
+
+  // Collect live messages
+  const liveMessages: EntryWithMessage[] = [];
+  if (orphanRecovery) {
+    for (let i = lastCompactionIdx + 1; i < branchEntries.length; i++) {
+      const e = branchEntries[i];
+      if (e.type === "compaction") continue;
+      if (e.type === "message" && e.message) {
+        liveMessages.push({ entry: e, message: e.message });
+      }
+    }
+  } else {
+    let foundKept = !lastKeptId; // if no prior compaction, start collecting immediately
+    for (const e of branchEntries) {
+      if (!foundKept && e.id === lastKeptId) foundKept = true;
+      if (!foundKept) continue;
+      if (e.type === "compaction") continue;
+      if (e.type === "message" && e.message) {
+        liveMessages.push({ entry: e, message: e.message });
+      }
+    }
+  }
+
+  if (liveMessages.length === 0) return { ok: false, reason: "no_live_messages" };
+  if (liveMessages.length <= 2) return { ok: false, reason: "too_few_live_messages" };
+
+  // Summarize all messages, keep only the last user message as context
+  let cutIdx = liveMessages.length - 1;
+  while (cutIdx > 0 && liveMessages[cutIdx].message.role !== "user") {
+    cutIdx--;
+  }
+
+  if (cutIdx <= 0) {
+    // Single user prompt scenario (or no user at all).
+    // Compact EVERYTHING and keep no tail. This handles both:
+    //  - Single user prompt at index 0: compact all, fresh start after summary
+    //  - No user message at all (e.g., long assistant/tool chain): still compact
+    //    to recover from context overflow rather than cancelling and leaving
+    //    the session unrecoverable.
+    // firstKeptEntryId="" is a sentinel: pi-core's buildSessionContext won't match it
+    // (so 0 kept from pre-compaction), and next buildOwnCut triggers orphan recovery.
+    return {
+      ok: true,
+      messages: liveMessages.map((e) => e.message),
+      firstKeptEntryId: "",
+      compactAll: true,
+    };
+  }
+
+  return {
+    ok: true,
+    messages: liveMessages.slice(0, cutIdx).map((e) => e.message),
+    firstKeptEntryId: liveMessages[cutIdx].entry.id,
+    compactAll: false,
+  };
+}
+
+const REASON_MESSAGES: Record<OwnCutCancelReason, string> = {
+  no_live_messages: "pi-vcc: Nothing to compact (no live messages)",
+  too_few_live_messages: "pi-vcc: Too few messages to compact",
+};
+
+export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
+  pi.on("session_before_compact", (event, ctx) => {
+    const { preparation, branchEntries, customInstructions } = event;
+    const settings = loadSettings();
+
+    // Always handle explicit /pi-vcc marker.
+    // Otherwise, only handle when user opted in via settings.
+    const isPiVcc = customInstructions === PI_VCC_COMPACT_INSTRUCTION;
+    if (!isPiVcc && !settings.overrideDefaultCompaction) return;
+
+    const ownCut = buildOwnCut(branchEntries as any[]);
+    if (!ownCut.ok) {
+      const lastComp = [...branchEntries].reverse().find((e: any) => e.type === "compaction");
+      const lastCompIdx = lastComp ? (branchEntries as any[]).indexOf(lastComp) : -1;
+
+      // Recompute liveMessages view (same logic as buildOwnCut) for diagnostic
+      const lastKeptId: string | undefined = lastComp?.firstKeptEntryId;
+      const hasPriorCompaction = lastCompIdx >= 0;
+      const hasValidKeptId = !!lastKeptId && (branchEntries as any[]).some((e: any) => e.id === lastKeptId);
+      const diagOrphan = hasPriorCompaction && !hasValidKeptId;
+      const liveRoles: string[] = [];
+      if (diagOrphan) {
+        for (let i = lastCompIdx + 1; i < branchEntries.length; i++) {
+          const e = (branchEntries as any[])[i];
+          if (e.type === "compaction") continue;
+          if (e.type === "message" && e.message) liveRoles.push(e.message.role);
+        }
+      } else {
+        let foundKept = !lastKeptId;
+        for (const e of branchEntries as any[]) {
+          if (!foundKept && e.id === lastKeptId) foundKept = true;
+          if (!foundKept) continue;
+          if (e.type === "compaction") continue;
+          if (e.type === "message" && e.message) liveRoles.push(e.message.role);
+        }
+      }
+      const userIndices = liveRoles.reduce<number[]>((acc, r, i) => (r === "user" ? (acc.push(i), acc) : acc), []);
+
+      dbg(settings, {
+        cancelled: true,
+        reason: ownCut.reason,
+        isPiVcc,
+        counts: {
+          total: branchEntries.length,
+          messages: (branchEntries as any[]).filter((e: any) => e.type === "message").length,
+          compactions: (branchEntries as any[]).filter((e: any) => e.type === "compaction").length,
+          entriesAfterLastCompaction: lastCompIdx >= 0 ? branchEntries.length - lastCompIdx - 1 : null,
+        },
+        liveMessages: {
+          count: liveRoles.length,
+          userCount: userIndices.length,
+          firstUserIdx: userIndices[0] ?? null,
+          lastUserIdx: userIndices[userIndices.length - 1] ?? null,
+          roleSequence: liveRoles.length <= 30
+            ? liveRoles
+            : [...liveRoles.slice(0, 10), "...", ...liveRoles.slice(-10)],
+        },
+        lastCompaction: lastComp ? {
+          hasFirstKeptEntryId: !!lastComp.firstKeptEntryId,
+          foundInBranch: lastComp.firstKeptEntryId
+            ? (branchEntries as any[]).some((e: any) => e.id === lastComp.firstKeptEntryId)
+            : null,
+        } : null,
+        tail: (branchEntries as any[]).slice(-5).map((e: any) => ({
+          type: e.type,
+          role: e.type === "message" ? e.message?.role : undefined,
+          hasContent: e.type === "message" ? e.message?.content != null : undefined,
+        })),
+      });
+
+      try {
+        ctx?.ui?.notify?.(REASON_MESSAGES[ownCut.reason], "warning");
+      } catch {}
+      return { cancel: true };
+    }
+
+    const agentMessages = ownCut.messages;
+    const firstKeptEntryId = ownCut.firstKeptEntryId;
+    const messages = convertToLlm(agentMessages);
+
+    // Count kept messages and estimate tokens
+    const keptIdx = (branchEntries as any[]).findIndex((e: any) => e.id === firstKeptEntryId);
+    const keptEntries = keptIdx >= 0
+      ? (branchEntries as any[]).slice(keptIdx).filter((e: any) => e.type === "message")
+      : [];
+    const keptChars = keptEntries.reduce((sum: number, e: any) => {
+      const c = e.message?.content;
+      if (typeof c === "string") return sum + c.length;
+      if (Array.isArray(c)) return sum + c.reduce((s: number, p: any) => {
+        if (p.text) return s + p.text.length;
+        if (p.type === "toolCall") return s + (p.name?.length ?? 0) + (typeof p.input === "string" ? p.input.length : JSON.stringify(p.input ?? "").length);
+        if (p.type === "toolResult") return s + (typeof p.content === "string" ? p.content.length : JSON.stringify(p.content ?? "").length);
+        return s;
+      }, 0);
+      return sum;
+    }, 0);
+    lastStats = {
+      summarized: agentMessages.length,
+      kept: keptEntries.length,
+      keptTokensEst: Math.round(keptChars / 4),
+    };
+
+    const config = settings;
+
+    const summary = compile({
+      messages,
+      previousSummary: preparation.previousSummary,
+      fileOps: {
+        readFiles: [...preparation.fileOps.read],
+        modifiedFiles: [...preparation.fileOps.written, ...preparation.fileOps.edited],
+      },
+    });
+
+    const branchIds = branchEntries.map((e: any) => e.id);
+    const cutIdx = branchIds.indexOf(firstKeptEntryId);
+    const cutWindow = cutIdx >= 0
+      ? branchEntries.slice(Math.max(0, cutIdx - 3), Math.min(branchEntries.length, cutIdx + 3)).map((e: any) => ({
+          id: e.id,
+          type: e.type,
+          role: e.type === "message" ? e.message?.role : undefined,
+          preview: e.type === "message" ? previewContent(e.message?.content) : undefined,
+        }))
+      : [];
+
+    dbg(config, {
+      usedOwnCut: true,
+      messagesToSummarize: agentMessages.length,
+      messagesPreviewHead: agentMessages.slice(0, 3).map((m: any) => ({ role: m.role, preview: previewContent(m.content) })),
+      messagesPreviewTail: agentMessages.slice(-3).map((m: any) => ({ role: m.role, preview: previewContent(m.content) })),
+      convertedMessages: messages.length,
+      firstKeptEntryId,
+      cutWindow,
+      tokensBefore: preparation.tokensBefore,
+      summaryLength: summary.length,
+      summaryPreview: summary.slice(0, 500),
+      sections: [...summary.matchAll(/^\[(.+?)\]/gm)].map((m) => m[1]),
+    });
+
+    const details: PiVccCompactionDetails = {
+      compactor: "ultimate-pi-vcc",
+      version: 1,
+      sections: [...summary.matchAll(/^\[(.+?)\]/gm)].map((m) => m[1]),
+      sourceMessageCount: agentMessages.length,
+      previousSummaryUsed: Boolean(preparation.previousSummary),
+    };
+
+    lastCompactWasPiVcc = isPiVcc;
+
+    return {
+      compaction: {
+        summary,
+        details,
+        tokensBefore: preparation.tokensBefore,
+        firstKeptEntryId,
+      },
+    };
+  });
+
+  // Fire success toast for /compact path only (delayed to let UI settle).
+  // /pi-vcc path uses its own onComplete callback in the command handler.
+  pi.on("session_compact", (event, ctx) => {
+    if (!event.fromExtension) return;
+    if (lastCompactWasPiVcc) return; // /pi-vcc handles its own toast via onComplete
+    const stats = lastStats;
+    if (!stats) return;
+    setTimeout(() => {
+      try {
+        ctx?.ui?.notify?.(
+          `pi-vcc: ${stats.summarized} source entries processed; tail kept ${stats.kept} (~${formatTokens(stats.keptTokensEst)} tok).`,
+          "info",
+        );
+      } catch {}
+    }, 500);
+  });
+};

package/vendor/pi-vcc/src/sections.ts

@@ -0,0 +1,12 @@
+import type { TranscriptEntry } from "./core/brief";
+
+export interface SectionData {
+  sessionGoal: string[];
+  outstandingContext: string[];
+  filesAndChanges: string[];
+  commits: string[];
+  userPreferences: string[];
+  briefTranscript: string;
+  /** Structured transcript entries (verbose object format) */
+  transcriptEntries: TranscriptEntry[];
+}

package/vendor/pi-vcc/src/tools/recall.ts

@@ -0,0 +1,109 @@
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { loadAllMessages } from "../core/load-messages";
+import { searchEntries } from "../core/search-entries";
+import { formatRecallOutput } from "../core/format-recall";
+import { getActiveLineageEntryIds } from "../core/lineage";
+import { normalizeRecallScope } from "../core/recall-scope";
+
+const DEFAULT_RECENT = 25;
+const PAGE_SIZE = 5;
+
+export const invalidExpandIndices = (requested: number[], available: Set<number>): number[] =>
+  requested.filter((i) => !Number.isInteger(i) || !available.has(i));
+
+export const registerRecallTool = (pi: ExtensionAPI) => {
+  pi.registerTool({
+    name: "vcc_recall",
+    label: "VCC Recall",
+    description:
+      "Search session history. Defaults to active lineage; use scope:'all' to include off-lineage branches." +
+      " Supports regex queries, paging, and expand indices.",
+    promptSnippet:
+      "vcc_recall: Search history; default scope is active lineage. Use scope:'all' for off-lineage branches.",
+    parameters: Type.Object({
+      query: Type.Optional(
+        Type.String({ description: "Search terms or regex pattern (e.g. 'hook|inject', 'fail.*build'). Multi-word = OR ranked by relevance." }),
+      ),
+      expand: Type.Optional(
+        Type.Array(Type.Number(), { description: "Entry indices to return full untruncated content for" }),
+      ),
+      page: Type.Optional(
+        Type.Number({ description: "Page number (1-based) for paginated search results. Default: 1." }),
+      ),
+      scope: Type.Optional(
+        Type.Union([
+          Type.Literal("lineage"),
+          Type.Literal("all"),
+        ], { description: "Search scope. Default: lineage; all includes off-lineage branches." }),
+      ),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const sessionFile = ctx.sessionManager.getSessionFile();
+      if (!sessionFile) {
+        return {
+          content: [{ type: "text", text: "No session file available." }],
+          details: undefined,
+        };
+      }
+
+      const scope = normalizeRecallScope(params.scope);
+      const lineageEntryIds = scope === "lineage"
+        ? getActiveLineageEntryIds(ctx.sessionManager)
+        : undefined;
+      const expandSet = new Set(params.expand ?? []);
+      const hasExpand = expandSet.size > 0;
+
+      if (hasExpand && !params.query) {
+        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(", ")}` }],
+            details: undefined,
+          };
+        }
+
+        const expanded = requested.map((i) => byIndex.get(i)).filter((m): m is NonNullable<typeof m> => Boolean(m));
+        const output = (scope === "all" ? "Scope: all\n\n" : "") + formatRecallOutput(expanded);
+        return {
+          content: [{ type: "text", text: output }],
+          details: undefined,
+        };
+      }
+
+      const { rendered: msgs, rawMessages } = loadAllMessages(sessionFile, false, lineageEntryIds);
+      const allResults = params.query?.trim()
+        ? searchEntries(msgs, rawMessages, params.query)
+        : msgs.slice(-DEFAULT_RECENT);
+
+      if (params.query?.trim()) {
+        const page = Math.max(1, params.page ?? 1);
+        const start = (page - 1) * PAGE_SIZE;
+        const pageResults = allResults.slice(start, start + PAGE_SIZE);
+        const totalPages = Math.ceil(allResults.length / PAGE_SIZE);
+        const scopeSuffix = scope === "all" ? " (scope: all)" : "";
+        const header = totalPages > 1
+          ? `Page ${page}/${totalPages} (${allResults.length} total matches${scopeSuffix})`
+          : `${allResults.length} matches${scopeSuffix}`;
+        const footer = page < totalPages
+          ? `\n--- Use page:${page + 1}${scope === "all" ? " with scope:'all'" : ""} for more results ---`
+          : "";
+        const output = formatRecallOutput(pageResults, params.query, header) + footer;
+        return {
+          content: [{ type: "text", text: output }],
+          details: undefined,
+        };
+      }
+
+      const output = (scope === "all" ? "Scope: all\n\n" : "") + formatRecallOutput(allResults, params.query);
+      return {
+        content: [{ type: "text", text: output }],
+        details: undefined,
+      };
+    },
+  });
+};
+

package/vendor/pi-vcc/src/types.ts

@@ -0,0 +1,14 @@
+import type { Message } from "@mariozechner/pi-ai";
+
+export interface FileOps {
+  readFiles?: string[];
+  modifiedFiles?: string[];
+  createdFiles?: string[];
+}
+
+export type NormalizedBlock =
+  | { kind: "user"; text: string; sourceIndex?: number }
+  | { kind: "assistant"; text: string; sourceIndex?: number }
+  | { kind: "tool_call"; name: string; args: Record<string, unknown>; sourceIndex?: number }
+  | { kind: "tool_result"; name: string; text: string; isError: boolean; sourceIndex?: number }
+  | { kind: "thinking"; text: string; redacted: boolean; sourceIndex?: number };

package/vendor/pi-vcc/tests/before-compact-hook.test.ts

@@ -0,0 +1,204 @@
+import { describe, test, expect, beforeEach, afterEach, beforeAll, afterAll } from "bun:test";
+import { existsSync, unlinkSync, readFileSync } from "fs";
+import { registerBeforeCompactHook, PI_VCC_COMPACT_INSTRUCTION } from "../src/hooks/before-compact";
+
+const DEBUG_PATH = "/tmp/pi-vcc-debug.json";
+
+let compactionEnvBackup: string | undefined;
+let debugEnvBackup: string | undefined;
+
+beforeAll(() => {
+	compactionEnvBackup = process.env.HARNESS_VCC_COMPACTION;
+	debugEnvBackup = process.env.HARNESS_VCC_DEBUG;
+});
+
+afterAll(() => {
+	if (compactionEnvBackup === undefined) {
+		delete process.env.HARNESS_VCC_COMPACTION;
+	} else {
+		process.env.HARNESS_VCC_COMPACTION = compactionEnvBackup;
+	}
+	if (debugEnvBackup === undefined) {
+		delete process.env.HARNESS_VCC_DEBUG;
+	} else {
+		process.env.HARNESS_VCC_DEBUG = debugEnvBackup;
+	}
+});
+
+function setHarnessEnv(opts: {
+	overrideDefaultCompaction: boolean;
+	debug: boolean;
+}) {
+	process.env.HARNESS_VCC_COMPACTION = opts.overrideDefaultCompaction
+		? "true"
+		: "false";
+	process.env.HARNESS_VCC_DEBUG = opts.debug ? "true" : "false";
+}
+
+// Minimal ExtensionAPI stub: capture handler + provide ctx with mocked ui.notify
+function createMockPi() {
+	let handler: ((event: any, ctx: any) => any) | undefined;
+	const notifyCalls: Array<{ msg: string; level: string }> = [];
+	const ctx = {
+		hasUI: true,
+		ui: {
+			notify: (msg: string, level: string) => {
+				notifyCalls.push({ msg, level });
+			},
+		},
+	};
+	return {
+		pi: {
+			on: (eventName: string, h: (e: any, c: any) => any) => {
+				if (eventName === "session_before_compact") handler = h;
+			},
+		} as any,
+		invoke: (event: any) => handler!(event, ctx),
+		notifyCalls,
+	};
+}
+
+function makeEvent(branchEntries: any[], customInstructions?: string) {
+	return {
+		type: "session_before_compact",
+		customInstructions,
+		branchEntries,
+		preparation: {
+			previousSummary: undefined,
+			fileOps: { read: [], written: [], edited: [] },
+			tokensBefore: 1000,
+		},
+		signal: new AbortController().signal,
+	};
+}
+
+const msg = (id: string, role: "user" | "assistant" | "toolResult", content = "x") => ({
+	id,
+	type: "message",
+	message: { role, content },
+});
+const comp = (id: string, firstKeptEntryId?: string) => ({
+	id,
+	type: "compaction",
+	firstKeptEntryId,
+});
+
+describe("registerBeforeCompactHook: cancel paths", () => {
+	beforeEach(() => {
+		if (existsSync(DEBUG_PATH)) unlinkSync(DEBUG_PATH);
+	});
+	afterEach(() => {
+		if (existsSync(DEBUG_PATH)) unlinkSync(DEBUG_PATH);
+	});
+
+	test("/pi-vcc with too few live messages cancels and notifies warning", () => {
+		setHarnessEnv({ debug: false, overrideDefaultCompaction: false });
+		const { pi, invoke, notifyCalls } = createMockPi();
+		registerBeforeCompactHook(pi);
+
+		const entries = [msg("m1", "user"), msg("m2", "assistant")];
+		expect(invoke(makeEvent(entries, PI_VCC_COMPACT_INSTRUCTION))).toEqual({
+			cancel: true,
+		});
+		expect(notifyCalls).toHaveLength(1);
+		expect(notifyCalls[0].level).toBe("warning");
+		expect(notifyCalls[0].msg).toContain("Too few messages");
+	});
+
+	test("/pi-vcc with no user message compacts all instead of cancelling", () => {
+		setHarnessEnv({ debug: false, overrideDefaultCompaction: false });
+		const { pi, invoke, notifyCalls } = createMockPi();
+		registerBeforeCompactHook(pi);
+
+		const entries = [
+			msg("m1", "assistant"),
+			msg("m2", "assistant"),
+			msg("m3", "assistant"),
+		];
+		const result = invoke(makeEvent(entries, PI_VCC_COMPACT_INSTRUCTION));
+		expect(result.cancel).toBeUndefined();
+		expect(result.compaction).toBeDefined();
+		expect(result.compaction.firstKeptEntryId).toBe("");
+	});
+
+	test("/compact with override=true cancels and notifies (NEW: was silent before)", () => {
+		setHarnessEnv({ debug: false, overrideDefaultCompaction: true });
+		const { pi, invoke, notifyCalls } = createMockPi();
+		registerBeforeCompactHook(pi);
+
+		const entries = [msg("m1", "user"), msg("m2", "assistant")];
+		expect(invoke(makeEvent(entries, undefined))).toEqual({ cancel: true });
+		expect(notifyCalls).toHaveLength(1);
+		expect(notifyCalls[0].level).toBe("warning");
+	});
+
+	test("/compact with override=false short-circuits (no notify, returns undefined)", () => {
+		setHarnessEnv({ debug: false, overrideDefaultCompaction: false });
+		const { pi, invoke, notifyCalls } = createMockPi();
+		registerBeforeCompactHook(pi);
+
+		const entries = [msg("m1", "user"), msg("m2", "assistant")];
+		expect(invoke(makeEvent(entries, undefined))).toBeUndefined();
+		expect(notifyCalls).toHaveLength(0);
+	});
+
+	test("debug:true writes metrics-only snapshot on cancel with no content leakage", () => {
+		setHarnessEnv({ debug: true, overrideDefaultCompaction: false });
+		const { pi, invoke } = createMockPi();
+		registerBeforeCompactHook(pi);
+
+		const entries = [
+			msg("m1", "user", "SECRET_TOKEN_abc123"),
+			msg("m2", "assistant", "sensitive response"),
+		];
+		expect(invoke(makeEvent(entries, PI_VCC_COMPACT_INSTRUCTION))).toEqual({
+			cancel: true,
+		});
+
+		expect(existsSync(DEBUG_PATH)).toBe(true);
+		const snapshot = JSON.parse(readFileSync(DEBUG_PATH, "utf-8"));
+		expect(snapshot.cancelled).toBe(true);
+		expect(snapshot.reason).toBe("too_few_live_messages");
+
+		const serialized = JSON.stringify(snapshot);
+		expect(serialized).not.toContain("SECRET_TOKEN_abc123");
+		expect(serialized).not.toContain("sensitive response");
+	});
+
+	test("debug:false does NOT write snapshot", () => {
+		setHarnessEnv({ debug: false, overrideDefaultCompaction: false });
+		const { pi, invoke } = createMockPi();
+		registerBeforeCompactHook(pi);
+		const entries = [msg("m1", "user"), msg("m2", "assistant")];
+		expect(invoke(makeEvent(entries, PI_VCC_COMPACT_INSTRUCTION))).toEqual({
+			cancel: true,
+		});
+		expect(existsSync(DEBUG_PATH)).toBe(false);
+	});
+});
+
+describe("registerBeforeCompactHook: compact-all path", () => {
+	beforeEach(() => {
+		if (existsSync(DEBUG_PATH)) unlinkSync(DEBUG_PATH);
+	});
+	afterEach(() => {
+		if (existsSync(DEBUG_PATH)) unlinkSync(DEBUG_PATH);
+	});
+
+	test("single-user + autonomous tail → returns compaction with empty firstKeptEntryId", () => {
+		setHarnessEnv({ debug: false, overrideDefaultCompaction: false });
+		const { pi, invoke, notifyCalls } = createMockPi();
+		registerBeforeCompactHook(pi);
+
+		const entries = [
+			msg("m1", "user", "go"),
+			msg("m2", "assistant", "calling tool"),
+			msg("m3", "toolResult", "result"),
+			msg("m4", "assistant", "done"),
+		];
+		const result = invoke(makeEvent(entries, PI_VCC_COMPACT_INSTRUCTION));
+		expect(result.compaction).toBeDefined();
+		expect(result.compaction.firstKeptEntryId).toBe("");
+		expect(notifyCalls).toHaveLength(0);
+	});
+});