@pi-unipi/compactor 2.6.1 → 2.9.0

package/src/compaction/format-recall.ts

@@ -0,0 +1,96 @@
+/** Recall output formatting (pi-vcc parity) */
+
+import type { TouchedFile } from "./touched-files.js";
+import type { RecallHit } from "./search-entries.js";
+
+// ── Path shortening ───────────────────────────────────────────────────────
+
+const CWD = process.cwd();
+
+/**
+ * Shorten an absolute file path for display:
+ * - If within cwd, return `./relative/path`
+ * - Otherwise, show last 3 path components with `.../` prefix
+ * - Short paths (≤3 components) returned as-is
+ */
+export function shortPath(fullPath: string): string {
+  const normalized = fullPath.replace(/\\/g, "/");
+  const cwdNormalized = CWD.replace(/\\/g, "/");
+  if (normalized.startsWith(cwdNormalized + "/")) {
+    return "." + normalized.slice(cwdNormalized.length);
+  }
+  const parts = normalized.split("/");
+  if (parts.length > 3) {
+    return ".../" + parts.slice(-3).join("/");
+  }
+  return normalized;
+}
+
+// ── Touched file output ───────────────────────────────────────────────────
+
+export const TOUCHED_PAGE_SIZE = 5;
+
+export function formatTouchedOutput(
+  touched: TouchedFile[],
+  page?: number,
+  pageSize?: number,
+): string {
+  if (touched.length === 0) {
+    return "No file operations found in session history.";
+  }
+
+  const ps = pageSize ?? TOUCHED_PAGE_SIZE;
+  const totalPages = Math.ceil(touched.length / ps);
+  const currentPage = Math.max(1, page ?? 1);
+  const start = (currentPage - 1) * ps;
+  const pageFiles = touched.slice(start, start + ps);
+
+  const header =
+    totalPages > 1
+      ? `Page ${currentPage}/${totalPages} (${touched.length} total files)`
+      : `${touched.length} files touched`;
+
+  const lines = pageFiles.map((tf) => {
+    const displayPath = shortPath(tf.path);
+    const indices = tf.entries
+      .map((e) => `#${e.index} (${e.toolName})`)
+      .join(", ");
+    return `  ${displayPath}    ${indices}`;
+  });
+
+  let result = `${header}:\n\n${lines.join("\n")}`;
+
+  if (currentPage < totalPages) {
+    result += `\n\n--- Use page:${currentPage + 1} for more results ---`;
+  }
+
+  return result;
+}
+
+export const RECALL_PAGE_SIZE = 5;
+
+export const formatRecallOutput = (
+  hits: RecallHit[],
+  query?: string,
+  headerOverride?: string,
+): string => {
+  if (hits.length === 0) {
+    return query
+      ? `No matches for "${query}" in session history.`
+      : "No entries in session history.";
+  }
+
+  const header = headerOverride
+    ? `${headerOverride} for "${query}":`
+    : query
+      ? `Found ${hits.length} matches for "${query}":`
+      : `Session history (${hits.length} entries):`;
+
+  const lines = hits.map((h) => {
+    const fileSuffix = h.files?.length ? ` files:[${h.files.join(", ")}]` : "";
+    const body = h.snippet ?? h.text;
+    return `#${h.index} [${h.kind}]${fileSuffix} ${body}`;
+  });
+
+  return `${header}\n\n${lines.join("\n\n")}`;
+};

package/src/compaction/format.ts

@@ -10,7 +10,7 @@ const section = (title: string, items: string[]): string => {
   return `[${title}]\n${body}`;
 };
 
-const BRIEF_MAX_LINES = 120;
+export const BRIEF_MAX_LINES = 120;
 
 export const capBrief = (text: string): string => {
   const lines = text.split("\n");
@@ -26,7 +26,12 @@ export const RECALL_NOTE =
   "Use `vcc_recall` to search for prior work, decisions, and context from before this summary. " +
   "Do not redo work already completed.";
 
-export const formatSummary = (data: SectionData): string => {
+export interface FormatSummaryOptions {
+  capBriefTranscript?: boolean;
+}
+
+export const formatSummary = (data: SectionData, options: FormatSummaryOptions = {}): string => {
+  const capBriefTranscript = options.capBriefTranscript ?? true;
   const headerParts = [
     section("Session Goal", data.sessionGoal),
     section("Files And Changes", data.filesAndChanges),
@@ -40,7 +45,7 @@ export const formatSummary = (data: SectionData): string => {
     parts.push(headerParts.join("\n\n"));
   }
   if (data.briefTranscript) {
-    parts.push(capBrief(data.briefTranscript));
+    parts.push(capBriefTranscript ? capBrief(data.briefTranscript) : data.briefTranscript);
   }
 
   if (parts.length === 0) return "";

package/src/compaction/hooks.ts

@@ -1,5 +1,7 @@
 /**
  * Hook integration — session_before_compact + session_compact
+ * (parity-aligned with pi-vcc before-compact.ts: token calibration, smart keep,
+ * budget-cut rescue, keep:N parsing, invisible auto-continue)
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -10,46 +12,131 @@ import type {
   SessionBeforeCompactEvent,
   SessionCompactEvent,
 } from "@earendil-works/pi-coding-agent";
-import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import { compile } from "./summarize.js";
+import { compileRanked } from "./summarize.js";
 import { loadConfig } from "../config/manager.js";
-import { buildOwnCut, type OwnCutResult } from "./cut.js";
+import {
+  buildOwnCut,
+  resolveSmartKeepUserTurns,
+  applyTailBudget,
+  MAX_SMART_TAIL_TOKENS,
+} from "./cut.js";
+import { parseCompactionInstructions } from "./compact-args.js";
+import {
+  calibrateCharsPerToken,
+  estimateMessageContentChars,
+  estimateTokensFromChars,
+} from "./token-estimate.js";
 import type { CompactionStats } from "../types.js";
 import type { SessionDB } from "../session/db.js";
 
-import { COMPACTOR_INSTRUCTION } from "@pi-unipi/core";
+import { COMPACTOR_INSTRUCTION, formatTokens } from "@pi-unipi/core";
 
 let lastStats: CompactionStats | null = null;
 let lastCompactWasCompactor = false;
+let pendingFollowUpPrompt: string | null = null;
+let pendingAutoContinueTimer: ReturnType<typeof setTimeout> | null = null;
 export const getLastCompactionStats = () => lastStats;
+export const consumePendingFollowUpPrompt = (): string | null => {
+  const p = pendingFollowUpPrompt;
+  pendingFollowUpPrompt = null;
+  return p;
+};
+
+// ── Invisible auto-continue (pi-vcc parity) ──────────────────────────────
+// Resume the agent after threshold/overflow compaction without polluting the
+// LLM context: send a custom message marked with a dedicated customType
+// (content:[], display:false, triggerTurn:true, deliverAs:'followUp') so Pi's
+// queue/busy-state stays coherent; the on('context') filter registered below
+// removes that message (by customType ONLY) from the LLM payload — the model
+// simply continues from the compaction summary.
+export const AUTO_CONTINUE_CUSTOM_TYPE = "compactor-auto-continue";
+
+const clearPendingAutoContinue = () => {
+  if (pendingAutoContinueTimer) {
+    clearTimeout(pendingAutoContinueTimer);
+    pendingAutoContinueTimer = null;
+  }
+};
 
-const formatTokens = (n: number): string => {
-  if (n >= 1000) return `${(n / 1000).toFixed(1)}k`;
-  return String(n);
+export const triggerInvisibleContinue = (pi: ExtensionAPI): void => {
+  pi.sendMessage(
+    {
+      customType: AUTO_CONTINUE_CUSTOM_TYPE,
+      content: [],
+      display: false,
+      details: undefined,
+    },
+    {
+      triggerTurn: true,
+      deliverAs: "followUp",
+    },
+  );
 };
 
-const dbg = (_debug: boolean, _event: string, _data?: Record<string, unknown>) => {
-  // Debug logging disabled — was writing to stdout causing TUI rendering issues.
-  return;
+const scheduleAutoContinue = (pi: ExtensionAPI) => {
+  clearPendingAutoContinue();
+  pendingAutoContinueTimer = setTimeout(() => {
+    pendingAutoContinueTimer = null;
+    try {
+      triggerInvisibleContinue(pi);
+    } catch {}
+  }, 0);
 };
 
-const REASON_MESSAGES: Record<import("./cut.js").OwnCutCancelReason, string> = {
+const REASON_MESSAGES: Record<string, string> = {
   no_live_messages: "compactor: Nothing to compact (no live messages)",
   too_few_live_messages: "compactor: Too few messages to compact",
-  no_user_message: "compactor: Cannot compact — no user message found",
 };
 
-/** Count chars in a content part array (TextContent, ToolCall, ToolResult, etc.) */
+const dbg = (debug: boolean, data: Record<string, unknown>) => {
+  if (!debug) return;
+  try {
+    // Lazy import so the debug path never loads node:fs in hot paths.
+    import("node:fs").then(({ writeFileSync }) =>
+      writeFileSync("/tmp/compactor-debug.json", JSON.stringify(data, null, 2)),
+    ).catch(() => {});
+  } 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 "";
+};
+
+/** Format the post-compaction toast (pi-vcc formatCompactionStats parity). */
+export const formatCompactionStats = (stats: CompactionStats): string => {
+  if (stats.budgetCut) {
+    const reason = stats.budgetCut === "no_anchor" ? "no user anchor" : "oversized tail";
+    return `compactor: kept ~${formatTokens(stats.keptTokensEst)} tok tail (mid-turn cut, ${reason}), summarized ${stats.summarized}.`;
+  }
+  const notes: string[] = [`summarized ${stats.summarized}`];
+  if (stats.smartKeepAdjusted) {
+    notes.push("smart-keep");
+  }
+  return `compactor: kept ${stats.keptUserTurns}/${stats.totalUserTurns} turns, ~${formatTokens(stats.keptTokensEst)} tok (${notes.join(", ")}).`;
+};
+
+/** Count chars in a content part array (legacy helper, kept for stats parity). */
 function contentPartsChars(parts: Array<{ text?: string; name?: string; input?: unknown; content?: unknown }>): number {
   return parts.reduce((s: number, p) => {
     if (p.text) return s + p.text.length;
     if (p.name) {
-      // ToolCall
       const inputStr = typeof p.input === "string" ? p.input : JSON.stringify(p.input ?? "");
       return s + p.name.length + inputStr.length;
     }
     if (p.content !== undefined) {
-      // ToolResult
       const contentStr = typeof p.content === "string" ? p.content : JSON.stringify(p.content ?? "");
       return s + contentStr.length;
     }
@@ -58,80 +145,135 @@ function contentPartsChars(parts: Array<{ text?: string; name?: string; input?:
 }
 
 /** Estimate char count for an AgentMessage (unwrapped — has role + content directly) */
-function messageChars(msg: AgentMessage): number {
-  const c = (msg as { content: unknown }).content;
+export function messageChars(msg: { content: unknown }): number {
+  const c = msg.content;
   if (typeof c === "string") return c.length;
   if (Array.isArray(c)) return contentPartsChars(c as Array<{ text?: string; name?: string; input?: unknown; content?: unknown }>);
   return 0;
 }
 
-/** Estimate char count for a SessionMessageEntry's message */
-function entryMessageChars(entry: SessionMessageEntry): number {
-  return messageChars(entry.message);
-}
-
 /** Filter entries to only SessionMessageEntry */
 function filterMessageEntries(entries: SessionEntry[]): SessionMessageEntry[] {
   return entries.filter((e): e is SessionMessageEntry => e.type === "message");
 }
 
+const readCompactionEventContext = (event: unknown): { reason?: "manual" | "threshold" | "overflow"; willRetry: boolean } => {
+  const raw = event as { reason?: unknown; willRetry?: unknown };
+  const reason = raw.reason === "manual" || raw.reason === "threshold" || raw.reason === "overflow"
+    ? raw.reason
+    : undefined;
+  return { reason, willRetry: raw.willRetry === true };
+};
+
 export function registerCompactionHooks(
   pi: ExtensionAPI,
   deps?: { getSessionDB?: () => SessionDB | null; getSessionId?: () => string },
 ): void {
+  // Filter our invisible-continue marker out of the LLM context payload so the
+  // model just continues from the compaction summary (matched by customType ONLY).
+  // This replaces the old dead sanitizer branch that read a nonexistent
+  // event.context string (prefix-cache audit finding).
+  pi.on("context", (event) => {
+    const messages = (event as { messages: Array<{ role?: string; customType?: string }> }).messages.filter((message) => {
+      if (message.role !== "custom") return true;
+      return message.customType !== AUTO_CONTINUE_CUSTOM_TYPE;
+    });
+    if (messages.length !== (event as { messages: unknown[] }).messages.length) {
+      return { messages } as any;
+    }
+  });
+
+  pi.on("before_agent_start", () => {
+    clearPendingAutoContinue();
+  });
+
   pi.on("session_before_compact", (event: SessionBeforeCompactEvent, ctx) => {
     const { preparation, branchEntries, customInstructions } = event;
     const config = loadConfig();
-    const isCompactor = customInstructions?.startsWith(COMPACTOR_INSTRUCTION) ?? false;
-    dbg(config.debug, "session_before_compact:enter", {
-      entryCount: branchEntries.length,
-      hasPrevSummary: !!preparation?.previousSummary,
-      isCompactor,
-    });
+    const { isCompactor, keepUserTurns, keepUserTurnsExplicit, followUpPrompt } =
+      parseCompactionInstructions(customInstructions);
 
+    // Always handle explicit compactor marker.
+    // Otherwise, only handle when user opted in via settings.
     if (!isCompactor && !config.overrideDefaultCompaction) {
-      dbg(config.debug, "session_before_compact:skip", { reason: "not_compactor_and_no_override" });
       return;
     }
 
-    const ownCut: OwnCutResult = buildOwnCut(branchEntries);
-    dbg(config.debug, "buildOwnCut", {
-      ok: ownCut.ok,
-      reason: !ownCut.ok ? (ownCut as { ok: false; reason: string }).reason : undefined,
+    pendingFollowUpPrompt = null;
+
+    // Calibrate chars/token from Pi's real token count vs actual message chars.
+    const calibrationCut = buildOwnCut(branchEntries as any[], 0);
+    const calibrationMessageChars = calibrationCut.ok
+      ? calibrationCut.messages.reduce(
+          (sum: number, message) => sum + estimateMessageContentChars((message as any).content),
+          0,
+        )
+      : 0;
+    const calibrationSummaryChars = typeof preparation.previousSummary === "string"
+      ? preparation.previousSummary.length
+      : 0;
+    const tokenEstimate = calibrateCharsPerToken(
+      calibrationMessageChars + calibrationSummaryChars,
+      preparation.tokensBefore,
+    );
+
+    // Smart keep-tail: boost default keep when the tail is small.
+    // Explicit keep:N from the user is always respected (resolver no-ops).
+    const smartKeep = resolveSmartKeepUserTurns({
+      branchEntries: branchEntries as any[],
+      requestedKeepUserTurns: keepUserTurnsExplicit ? keepUserTurns : null,
+      explicit: keepUserTurnsExplicit,
+      smartKeepTail: config.smartKeepTail,
+      charsPerToken: tokenEstimate.charsPerToken,
     });
+    let ownCut = buildOwnCut(branchEntries as any[], smartKeep.keepUserTurns);
+    // Default path only: rescue autonomous / oversized-tail sessions with a
+    // token-budget cut. Explicit keep:N is respected absolutely (no-op here).
+    if (ownCut.ok && !keepUserTurnsExplicit) {
+      ownCut = applyTailBudget(branchEntries as any[], ownCut, { charsPerToken: tokenEstimate.charsPerToken });
+    }
     if (!ownCut.ok) {
+      if (!isCompactor && (readCompactionEventContext(event).reason === "overflow")) {
+        return; // let pi core retry
+      }
       try {
-        ctx?.ui?.notify?.(REASON_MESSAGES[(ownCut as { ok: false; reason: import("./cut.js").OwnCutCancelReason }).reason], "warning");
+        ctx?.ui?.notify?.(REASON_MESSAGES[ownCut.reason] ?? ownCut.reason, "warning");
       } catch {}
+      dbg(config.debug, { cancelled: true, reason: ownCut.reason });
       return { cancel: true };
     }
 
-    const { messages: agentMessages, firstKeptEntryId } = ownCut;
-    const messages = convertToLlm(agentMessages);
+    pendingFollowUpPrompt = followUpPrompt;
+    const agentMessages = ownCut.messages;
+    const firstKeptEntryId = ownCut.firstKeptEntryId;
+    const messages = convertToLlm(agentMessages as any);
 
-    // Find kept entries (from cut point onward)
-    const keptIdx = branchEntries.findIndex((e: SessionEntry) => e.id === firstKeptEntryId);
+    // Count kept messages and estimate tokens
+    const keptIdx = (branchEntries as SessionEntry[]).findIndex((e: SessionEntry) => e.id === firstKeptEntryId);
     const keptMessageEntries: SessionMessageEntry[] = keptIdx >= 0
-      ? filterMessageEntries(branchEntries.slice(keptIdx))
+      ? filterMessageEntries((branchEntries as SessionEntry[]).slice(keptIdx))
       : [];
+    const keptChars = keptMessageEntries.reduce(
+      (sum: number, e: SessionMessageEntry) => sum + estimateMessageContentChars((e.message as any)?.content),
+      0,
+    );
 
-    // Compute char estimates for proportional token estimation
-    const summarizedChars = agentMessages.reduce((sum, msg) => sum + messageChars(msg), 0);
-    const keptChars = keptMessageEntries.reduce((sum, e) => sum + entryMessageChars(e), 0);
-    const totalChars = summarizedChars + keptChars;
-
-    // Use Pi's real token count for "before", estimate "after" proportionally
     const tokensBefore = preparation.tokensBefore;
-    const tokensAfterEst = totalChars > 0
-      ? Math.round(tokensBefore * keptChars / totalChars)
-      : 0;
-
     lastStats = {
       summarized: agentMessages.length,
       kept: keptMessageEntries.length,
       totalMessages: agentMessages.length + keptMessageEntries.length,
       tokensBefore,
-      tokensAfterEst,
+      tokensAfterEst: estimateTokensFromChars(keptChars, tokenEstimate.charsPerToken),
+      keptUserTurns: ownCut.keptUserTurns,
+      totalUserTurns: ownCut.totalUserTurns,
+      requestedKeepUserTurns: ownCut.requestedKeepUserTurns,
+      keepUserTurnsExplicit,
+      keepFallbackToCompactAll: ownCut.keepFallbackToCompactAll,
+      keptTokensEst: estimateTokensFromChars(keptChars, tokenEstimate.charsPerToken),
+      smartKeepAdjusted: smartKeep.smartAdjusted,
+      smartFromKeep: smartKeep.fromKeep,
+      budgetCut: ownCut.budgetCut,
     };
 
     // Persist cumulative compaction stats
@@ -139,41 +281,64 @@ export function registerCompactionHooks(
     if (sessionDB && deps?.getSessionId) {
       try {
         const sessionId = deps.getSessionId();
+        const summarizedChars = agentMessages.reduce((sum, msg) => sum + messageChars(msg as any), 0);
         sessionDB.addCompactionStats(sessionId, summarizedChars, keptChars, agentMessages.length);
       } catch {
         // non-fatal
       }
     }
 
-    dbg(config.debug, "compile", { messageCount: messages.length, hasPrevSummary: !!preparation.previousSummary });
-    const summary = compile({
-      messages,
+    // Ranked compaction: keep the highest-signal blocks under a token budget
+    // instead of the old unranked compile() (fixed 120-line cap). The token
+    // budget is converted to a char budget via the session's calibrated
+    // charsPerToken so the summary targets ~RANKED_BRIEF_BUDGET_TOKENS tokens
+    // regardless of content density. The budget is SIZE-RELATIVE: it scales
+    // with transcript length between a floor and a ceiling at
+    // RANKED_BRIEF_CHARS_PER_BLOCK per normalized block (pi-vcc parity).
+    const RANKED_BRIEF_BUDGET_TOKENS = 1100;
+    const RANKED_BRIEF_CEILING_TOKENS = 2000;
+    const RANKED_BRIEF_TOKENS_PER_BLOCK = 15;
+    const summary = compileRanked({
+      messages: messages as any,
       previousSummary: preparation.previousSummary,
-      fileOps: {
-        readFiles: [...preparation.fileOps.read],
-        modifiedFiles: [...preparation.fileOps.written, ...preparation.fileOps.edited],
+      fileOps: preparation.fileOps
+        ? {
+            readFiles: [...preparation.fileOps.read],
+            modifiedFiles: [...preparation.fileOps.written, ...preparation.fileOps.edited],
+          }
+        : undefined,
+      ranking: {
+        maxBriefChars: Math.round(RANKED_BRIEF_BUDGET_TOKENS * tokenEstimate.charsPerToken),
+        maxBriefCharsCeiling: Math.round(RANKED_BRIEF_CEILING_TOKENS * tokenEstimate.charsPerToken),
+        briefCharsPerBlock: Math.round(RANKED_BRIEF_TOKENS_PER_BLOCK * tokenEstimate.charsPerToken),
       },
     });
 
-    dbg(config.debug, "compaction_pipeline", {
-      usedOwnCut: true,
-      messagesToSummarize: agentMessages.length,
-      firstKeptEntryId,
-      tokensBefore: preparation.tokensBefore,
-      summaryLength: summary.length,
-      sections: [...summary.matchAll(/^\[(.+?)\]/gm)].map((m) => m[1]),
-    });
-
     const details = {
       compactor: "@pi-unipi/compactor",
       version: 1,
       sections: [...summary.matchAll(/^\[(.+?)\]/gm)].map((m) => m[1]),
       sourceMessageCount: agentMessages.length,
       previousSummaryUsed: Boolean(preparation.previousSummary),
+      reason: readCompactionEventContext(event).reason,
+      budgetCut: ownCut.budgetCut,
     };
 
     lastCompactWasCompactor = isCompactor;
 
+    dbg(config.debug, {
+      usedOwnCut: true,
+      budgetCut: ownCut.budgetCut,
+      messagesToSummarize: agentMessages.length,
+      firstKeptEntryId,
+      tokensBefore,
+      tokenEstimate,
+      smartKeep,
+      summaryLength: summary.length,
+      summaryPreview: summary.slice(0, 500),
+      sections: details.sections,
+    });
+
     return {
       compaction: {
         summary,
@@ -185,19 +350,30 @@ export function registerCompactionHooks(
   });
 
   pi.on("session_compact", (event: SessionCompactEvent, ctx) => {
-    const config = loadConfig();
-    dbg(config.debug, "session_compact", { fromExtension: event.fromExtension, lastCompactWasCompactor });
     if (!event.fromExtension) return;
-    if (lastCompactWasCompactor) return;
+    if (lastCompactWasCompactor) return; // /unipi:compact handles its own toast
     const stats = lastStats;
     if (!stats) return;
+    const { reason, willRetry } = readCompactionEventContext(event);
+    if (willRetry) return;
+    const followUpPrompt = consumePendingFollowUpPrompt();
+    const shouldContinueAfterAutoCompact =
+      (reason === "threshold" || reason === "overflow") && loadConfig().continueAfterThresholdCompact;
     setTimeout(() => {
       try {
-        ctx?.ui?.notify?.(
-          `Compacted ${stats.totalMessages} messages (~${formatTokens(stats.tokensBefore)} tokens) → ${stats.kept} messages (~${formatTokens(stats.tokensAfterEst)} tokens)`,
-          "info",
-        );
+        ctx?.ui?.notify?.(formatCompactionStats(stats), "info");
       } catch {}
     }, 500);
+    if (followUpPrompt) {
+      setTimeout(() => {
+        try {
+          void pi.sendUserMessage(followUpPrompt);
+        } catch {}
+      }, 0);
+    } else if (shouldContinueAfterAutoCompact) {
+      scheduleAutoContinue(pi);
+    }
   });
 }
+
+export { MAX_SMART_TAIL_TOKENS };

package/src/compaction/merge.ts

@@ -2,7 +2,7 @@
  * Stage 6: Merge — Merge with previous summary, dedup, rolling window
  */
 
-import { capBrief } from "./format.js";
+import { capBrief, BRIEF_MAX_LINES } from "./format.js";
 
 const HEADER_NAMES = ["Session Goal", "Files And Changes", "Commits", "Outstanding Context", "User Preferences"];
 const SEPARATOR = "\n\n---\n\n";
@@ -88,7 +88,35 @@ const mergeBriefTranscript = (prev: string, fresh: string): string => {
   return prev + "\n\n" + fresh;
 };
 
-export const mergePrevious = (prev: string, fresh: string): string => {
+const briefLineCount = (text: string): number =>
+  text ? text.split("\n").length : 0;
+
+const capBriefToLineBudget = (text: string, maxLines: number): string => {
+  if (!text || maxLines <= 0) return "";
+  const lines = text.split("\n");
+  if (lines.length <= maxLines) return text;
+  const kept = lines.slice(-maxLines);
+  const firstHeader = kept.findIndex((l) => /^\[.+\]/.test(l));
+  const clean = firstHeader > 0 ? kept.slice(firstHeader) : kept;
+  const omitted = lines.length - clean.length;
+  return `...(${omitted} earlier lines omitted)\n\n${clean.join("\n")}`;
+};
+
+/** Fresh brief gets the line budget; previous brief fills the remainder (pi-vcc parity) */
+export const mergeBriefTranscriptWithFreshBudget = (prev: string, fresh: string): string => {
+  if (!prev) return fresh;
+  if (!fresh) return capBrief(prev);
+  const freshLines = briefLineCount(fresh);
+  const remainingPrevLines = Math.max(0, BRIEF_MAX_LINES - freshLines);
+  const prevTail = capBriefToLineBudget(prev, remainingPrevLines);
+  return prevTail ? `${prevTail}\n\n${fresh}` : fresh;
+};
+
+export const mergePrevious = (
+  prev: string,
+  fresh: string,
+  options: { preserveFreshBrief?: boolean } = {},
+): string => {
   const headers = HEADER_NAMES
     .map((header) => {
       const freshSec = sectionOf(fresh, header);
@@ -99,14 +127,16 @@ export const mergePrevious = (prev: string, fresh: string): string => {
 
   const prevBrief = briefOf(prev);
   const freshBrief = briefOf(fresh);
-  const mergedBrief = mergeBriefTranscript(prevBrief, freshBrief);
+  const mergedBrief = options.preserveFreshBrief
+    ? mergeBriefTranscriptWithFreshBudget(prevBrief, freshBrief)
+    : mergeBriefTranscript(prevBrief, freshBrief);
 
   const parts: string[] = [];
   if (headers.length > 0) {
     parts.push(headers.join("\n\n"));
   }
   if (mergedBrief) {
-    parts.push(capBrief(mergedBrief));
+    parts.push(options.preserveFreshBrief ? mergedBrief : capBrief(mergedBrief));
   }
 
   return parts.join(SEPARATOR);