@pi-unipi/compactor 0.1.1

package/src/compaction/content.ts

@@ -0,0 +1,47 @@
+/**
+ * Content helpers for compaction pipeline
+ */
+
+/** Extract plain text from message content */
+export function textOf(content: unknown): string {
+  if (typeof content === "string") return content;
+  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");
+  }
+  return "";
+}
+
+/** Clip text to max length, adding ellipsis */
+export function clip(text: string, max: number): string {
+  if (text.length <= max) return text;
+  return text.slice(0, max - 3) + "...";
+}
+
+/** Clip to first sentence within max length */
+export function clipSentence(text: string, max: number): string {
+  const trimmed = text.trim();
+  const sentenceEnd = trimmed.search(/[.!?](?:\s|$)/);
+  if (sentenceEnd > 0 && sentenceEnd < max) {
+    return trimmed.slice(0, sentenceEnd + 1);
+  }
+  return clip(trimmed, max);
+}
+
+/** First non-empty line, clipped */
+export function firstLine(text: string, max: number): string {
+  const line = text.split(/\r?\n/).find((l) => l.trim()) ?? "";
+  return clip(line.trim(), max);
+}
+
+/** Non-empty lines from text */
+export function nonEmptyLines(text: string): string[] {
+  return text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+}

package/src/compaction/cut.ts

@@ -0,0 +1,80 @@
+/**
+ * Cut logic — buildOwnCut for determining compaction boundaries
+ */
+
+export type OwnCutCancelReason =
+  | "no_live_messages"
+  | "too_few_live_messages"
+  | "no_user_message";
+
+export type OwnCutResult =
+  | { ok: true; messages: any[]; firstKeptEntryId: string; compactAll: boolean }
+  | { ok: false; reason: OwnCutCancelReason };
+
+interface EntryWithMessage {
+  entry: { id: string; type: string };
+  message: { role: string; content: unknown };
+}
+
+export function buildOwnCut(branchEntries: any[]): OwnCutResult {
+  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;
+    }
+  }
+
+  const hasPriorCompaction = lastCompactionIdx >= 0;
+  const hasValidKeptId = !!lastKeptId && branchEntries.some((e: any) => e.id === lastKeptId);
+  const orphanRecovery = hasPriorCompaction && !hasValidKeptId;
+
+  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;
+    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" };
+
+  let cutIdx = liveMessages.length - 1;
+  while (cutIdx > 0 && liveMessages[cutIdx].message.role !== "user") {
+    cutIdx--;
+  }
+
+  if (cutIdx <= 0) {
+    const hasUser = liveMessages.some((m) => m.message.role === "user");
+    if (!hasUser) return { ok: false, reason: "no_user_message" };
+    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,
+  };
+}

package/src/compaction/extract/commits.ts

@@ -0,0 +1,52 @@
+/**
+ * Commit extraction — git commit parsing, hash pairing, last 8
+ */
+
+import type { NormalizedBlock } from "../../types.js";
+
+const COMMIT_HASH_RE = /\b[0-9a-f]{7,40}\b/gi;
+const COMMIT_MSG_RE = /(?:commit|committed|git\s+(?:commit|push|merge|rebase))[^.]*?["']([^"']+)["']/i;
+
+export interface CommitInfo {
+  hash?: string;
+  message: string;
+}
+
+export function extractCommits(blocks: NormalizedBlock[]): CommitInfo[] {
+  const commits: CommitInfo[] = [];
+  const seen = new Set<string>();
+
+  for (const b of blocks) {
+    if (b.kind !== "user" && b.kind !== "assistant" && b.kind !== "tool_result") continue;
+    const text = b.text;
+    const hashes = text.match(COMMIT_HASH_RE) ?? [];
+    const msgMatch = text.match(COMMIT_MSG_RE);
+    const message = msgMatch?.[1]?.trim();
+
+    for (const hash of hashes) {
+      const key = hash.toLowerCase();
+      if (seen.has(key)) continue;
+      seen.add(key);
+      commits.push({ hash: hash.slice(0, 8), message: message || "" });
+    }
+
+    // Also catch "committed: message" without hash
+    if (!hashes.length && message && message.length > 5) {
+      const key = message.toLowerCase().slice(0, 60);
+      if (!seen.has(key)) {
+        seen.add(key);
+        commits.push({ message });
+      }
+    }
+  }
+
+  return commits.slice(-8);
+}
+
+export function formatCommits(commits: CommitInfo[]): string[] {
+  return commits.map((c) => {
+    if (c.hash && c.message) return `${c.hash} — ${c.message}`;
+    if (c.hash) return c.hash;
+    return c.message;
+  });
+}

package/src/compaction/extract/files.ts

@@ -0,0 +1,58 @@
+/**
+ * File tracking — Modified/Created/Read, dedup, path trimming
+ */
+
+import type { NormalizedBlock } from "../../types.js";
+
+const PATH_RE = /(?:[\w\-]+\/)+[\w\-]+(?:\.[\w\-]+)?/g;
+const EDIT_RE = /\b(edit|modify|update|change|patch|rewrite|refactor)\b/i;
+const CREATE_RE = /\b(create|write|add|new|generate|make)\b/i;
+const READ_RE = /\b(read|view|show|inspect|check|look|open|cat|head|tail|grep|find|ls)\b/i;
+
+export interface FileActivity {
+  modified: Set<string>;
+  created: Set<string>;
+  read: Set<string>;
+}
+
+export function extractFiles(blocks: NormalizedBlock[]): FileActivity {
+  const activity: FileActivity = {
+    modified: new Set(),
+    created: new Set(),
+    read: new Set(),
+  };
+
+  for (const b of blocks) {
+    if (b.kind === "tool_call") {
+      const path = extractPath(b.args);
+      if (!path) continue;
+      if (b.name === "edit" || b.name === "Edit") activity.modified.add(path);
+      else if (b.name === "write" || b.name === "Write") activity.created.add(path);
+      else if (b.name === "read" || b.name === "Read") activity.read.add(path);
+      continue;
+    }
+
+    if (b.kind !== "user" && b.kind !== "assistant") continue;
+    const text = b.text;
+    const paths = text.match(PATH_RE) ?? [];
+    for (const p of paths) {
+      if (p.split("/").length < 2) continue; // require at least one directory
+      const context = text.slice(Math.max(0, text.indexOf(p) - 40), text.indexOf(p) + p.length + 40);
+      if (EDIT_RE.test(context)) activity.modified.add(p);
+      else if (CREATE_RE.test(context)) activity.created.add(p);
+      else if (READ_RE.test(context)) activity.read.add(p);
+    }
+  }
+
+  return activity;
+}
+
+/** Extract a file path from tool args */
+export function extractPath(args: Record<string, unknown>): string | undefined {
+  const candidates = ["file_path", "path", "filePath", "filepath", "file"];
+  for (const key of candidates) {
+    const val = args[key];
+    if (typeof val === "string" && val.length > 0) return val;
+  }
+  return undefined;
+}

package/src/compaction/extract/goals.ts

@@ -0,0 +1,36 @@
+/**
+ * Goal extraction — regex-based, scope changes, task verbs
+ */
+
+import type { NormalizedBlock } from "../../types.js";
+import { nonEmptyLines } from "../content.js";
+
+const SCOPE_CHANGE_RE = /\b(scope|focus|switch|move|now|instead|rather than|change|shift|pivot|let's|let us)\b/i;
+const TASK_VERB_RE = /\b(add|create|build|implement|fix|refactor|update|remove|delete|rename|extract|merge|split|convert|migrate|optimize|test|write|generate|setup|configure|install|deploy|release|publish|document|review|audit|analyze|debug|resolve|handle|support|enable|disable|integrate|connect|sync|import|export|validate|verify|check|ensure|make|set|get|put|post|patch|delete)\b/i;
+const GOAL_PREFIX_RE = /^(?:Goal|Objective|Task|Plan|Target|Aim|Intent|Purpose|Mission|Action item|To-do|TODO|FIXME|NOTE|IDEA|HACK|BUG|FEATURE|STORY|EPIC):?\s*/i;
+
+export function extractGoals(blocks: NormalizedBlock[]): string[] {
+  const goals: string[] = [];
+  const seen = new Set<string>();
+
+  for (const b of blocks) {
+    if (b.kind !== "user" && b.kind !== "assistant") continue;
+    for (const line of nonEmptyLines(b.text)) {
+      let candidate = line;
+      // Strip goal prefix
+      candidate = candidate.replace(GOAL_PREFIX_RE, "").trim();
+      if (candidate.length < 10) continue;
+      // Must contain a task verb or scope change
+      if (!TASK_VERB_RE.test(candidate) && !SCOPE_CHANGE_RE.test(candidate)) continue;
+      // Deduplicate
+      const key = candidate.toLowerCase().slice(0, 80);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      goals.push(candidate);
+      if (goals.length >= 6) break;
+    }
+    if (goals.length >= 6) break;
+  }
+
+  return goals;
+}

package/src/compaction/extract/preferences.ts

@@ -0,0 +1,40 @@
+/**
+ * User preference extraction — track explicit preferences and constraints
+ */
+
+import type { NormalizedBlock } from "../../types.js";
+import { nonEmptyLines } from "../content.js";
+
+const PREF_RE = /\b(prefer|preference|want|would like|should|must|need to|important|critical|avoid|don't|do not|never|always|only|make sure|ensure|remember|keep in mind|note that)\b/i;
+const PREF_PREFIX_RE = /^(?:Preference|Note|Remember|Keep in mind|Important|Critical|Constraint|Rule|Guideline|Style|Format):?\s*/i;
+
+export function extractPreferences(blocks: NormalizedBlock[]): string[] {
+  const prefs: string[] = [];
+  const seen = new Set<string>();
+
+  for (const b of blocks) {
+    if (b.kind !== "user") continue;
+    for (const line of nonEmptyLines(b.text)) {
+      let candidate = line.replace(PREF_PREFIX_RE, "").trim();
+      if (candidate.length < 10) continue;
+      if (!PREF_RE.test(candidate)) continue;
+      const key = candidate.toLowerCase().slice(0, 80);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      prefs.push(candidate);
+      if (prefs.length >= 10) break;
+    }
+    if (prefs.length >= 10) break;
+  }
+
+  return prefs;
+}
+
+/** Remove preferences that overlap with goals */
+export function dedupPreferencesAgainstGoals(prefs: string[], goals: string[]): string[] {
+  const goalSet = new Set(goals.map((g) => g.toLowerCase().slice(0, 60)));
+  return prefs.filter((p) => {
+    const key = p.toLowerCase().slice(0, 60);
+    return !goalSet.has(key);
+  });
+}

package/src/compaction/filter-noise.ts

@@ -0,0 +1,46 @@
+/**
+ * Stage 2: Filter Noise — Remove thinking blocks, noise tools, XML wrappers, stop words
+ */
+
+import type { NormalizedBlock } from "../types.js";
+
+const NOISE_TOOLS = new Set([
+  "TodoWrite", "TodoRead", "ToolSearch", "WebSearch",
+  "AskUser", "ExitSpecMode", "GenerateDroid",
+]);
+
+const NOISE_STRINGS = [
+  "Continue from where you left off.",
+  "No response requested.",
+  "IMPORTANT: TodoWrite was not called yet.",
+];
+
+const XML_WRAPPER_RE = /<(system-reminder|ide_opened_file|command-message|context-window-usage)[^>]*>[\s\S]*?<\/\1>/g;
+
+const isNoiseUserBlock = (text: string): boolean => {
+  const trimmed = text.trim();
+  if (NOISE_STRINGS.some((s) => trimmed.includes(s))) return true;
+  const stripped = trimmed.replace(XML_WRAPPER_RE, "").trim();
+  return stripped.length === 0;
+};
+
+const cleanUserText = (text: string): string =>
+  text.replace(XML_WRAPPER_RE, "").trim();
+
+export const filterNoise = (blocks: NormalizedBlock[]): NormalizedBlock[] => {
+  const out: NormalizedBlock[] = [];
+  for (const b of blocks) {
+    if (b.kind === "thinking") continue;
+    if (b.kind === "tool_call" && NOISE_TOOLS.has(b.name)) continue;
+    if (b.kind === "tool_result" && NOISE_TOOLS.has(b.name)) continue;
+    if (b.kind === "user") {
+      if (isNoiseUserBlock(b.text)) continue;
+      const cleaned = cleanUserText(b.text);
+      if (!cleaned) continue;
+      out.push({ kind: "user", text: cleaned });
+      continue;
+    }
+    out.push(b);
+  }
+  return out;
+};

package/src/compaction/format.ts

@@ -0,0 +1,48 @@
+/**
+ * Stage 5: Format — Render sections with separators
+ */
+
+import type { SectionData } from "./sections.js";
+
+const section = (title: string, items: string[]): string => {
+  if (items.length === 0) return "";
+  const body = items.map((i) => `- ${i}`).join("\n");
+  return `[${title}]\n${body}`;
+};
+
+const BRIEF_MAX_LINES = 120;
+
+export const capBrief = (text: string): string => {
+  const lines = text.split("\n");
+  if (lines.length <= BRIEF_MAX_LINES) return text;
+  const omitted = lines.length - BRIEF_MAX_LINES;
+  const kept = lines.slice(-BRIEF_MAX_LINES);
+  const firstHeader = kept.findIndex((l) => /^\[.+\]/.test(l));
+  const clean = firstHeader > 0 ? kept.slice(firstHeader) : kept;
+  return `...(${omitted} earlier lines omitted)\n\n${clean.join("\n")}`;
+};
+
+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 => {
+  const headerParts = [
+    section("Session Goal", data.sessionGoal),
+    section("Files And Changes", data.filesAndChanges),
+    section("Commits", data.commits),
+    section("Outstanding Context", data.outstandingContext),
+    section("User Preferences", data.userPreferences),
+  ].filter(Boolean);
+
+  const parts: string[] = [];
+  if (headerParts.length > 0) {
+    parts.push(headerParts.join("\n\n"));
+  }
+  if (data.briefTranscript) {
+    parts.push(capBrief(data.briefTranscript));
+  }
+
+  if (parts.length === 0) return "";
+  return parts.join("\n\n---\n\n");
+};

package/src/compaction/hooks.ts

@@ -0,0 +1,145 @@
+/**
+ * Hook integration — session_before_compact + session_compact
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { convertToLlm } from "@mariozechner/pi-coding-agent";
+import { writeFileSync } from "node:fs";
+import { compile } from "./summarize.js";
+import { loadConfig } from "../config/manager.js";
+import { buildOwnCut } from "./cut.js";
+import type { CompactionStats } from "../types.js";
+
+export const COMPACTOR_INSTRUCTION = "__compactor__";
+
+let lastStats: CompactionStats | null = null;
+let lastCompactWasCompactor = false;
+export const getLastCompactionStats = () => lastStats;
+
+const formatTokens = (n: number): string => {
+  if (n >= 1000) return `${(n / 1000).toFixed(1)}k`;
+  return String(n);
+};
+
+const dbg = (debug: boolean, data: Record<string, unknown>) => {
+  if (!debug) return;
+  try { writeFileSync("/tmp/compactor-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 "";
+};
+
+const REASON_MESSAGES: Record<import("./cut.js").OwnCutCancelReason, 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",
+};
+
+export function registerCompactionHooks(pi: ExtensionAPI): void {
+  pi.on("session_before_compact", (event, ctx) => {
+    const { preparation, branchEntries, customInstructions } = event;
+    const config = loadConfig();
+
+    const isCompactor = customInstructions === COMPACTOR_INSTRUCTION;
+    if (!isCompactor && !config.overrideDefaultCompaction) return;
+
+    const ownCut = buildOwnCut(branchEntries as any[]);
+    if (!ownCut.ok) {
+      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);
+
+    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 summary = compile({
+      messages,
+      previousSummary: preparation.previousSummary,
+      fileOps: {
+        readFiles: [...preparation.fileOps.read],
+        modifiedFiles: [...preparation.fileOps.written, ...preparation.fileOps.edited],
+      },
+    });
+
+    dbg(config.debug, {
+      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),
+    };
+
+    lastCompactWasCompactor = isCompactor;
+
+    return {
+      compaction: {
+        summary,
+        details,
+        tokensBefore: preparation.tokensBefore,
+        firstKeptEntryId,
+      },
+    };
+  });
+
+  pi.on("session_compact", (event, ctx) => {
+    if (!event.fromExtension) return;
+    if (lastCompactWasCompactor) return;
+    const stats = lastStats;
+    if (!stats) return;
+    setTimeout(() => {
+      try {
+        ctx?.ui?.notify?.(
+          `compactor: ${stats.summarized} source entries processed; tail kept ${stats.kept} (~${formatTokens(stats.keptTokensEst)} tok).`,
+          "info",
+        );
+      } catch {}
+    }, 500);
+  });
+}

package/src/compaction/merge.ts

@@ -0,0 +1,113 @@
+/**
+ * Stage 6: Merge — Merge with previous summary, dedup, rolling window
+ */
+
+import { capBrief } from "./format.js";
+
+const HEADER_NAMES = ["Session Goal", "Files And Changes", "Commits", "Outstanding Context", "User Preferences"];
+const SEPARATOR = "\n\n---\n\n";
+
+const sectionOf = (text: string, header: string): string => {
+  const tag = `[${header}]`;
+  const start = text.indexOf(tag);
+  if (start < 0) return "";
+  const after = text.slice(start);
+  const nextSection = HEADER_NAMES
+    .filter((h) => h !== header)
+    .map((h) => after.indexOf(`[${h}]`))
+    .filter((n) => n > 0);
+  const nextSep = after.indexOf("\n\n---\n\n");
+  const candidates = [...nextSection, ...(nextSep > 0 ? [nextSep] : [])].sort((a, b) => a - b);
+  const end = candidates[0];
+  return (end ? after.slice(0, end) : after).trim();
+};
+
+const briefOf = (text: string): string => {
+  const idx = text.indexOf(SEPARATOR);
+  if (idx < 0) return "";
+  return text.slice(idx + SEPARATOR.length).trim();
+};
+
+const mergeHeaderSection = (header: string, prev: string, fresh: string): string => {
+  if (header === "Outstanding Context") return fresh;
+  if (!prev) return fresh;
+  if (!fresh) return prev;
+
+  if (header === "Files And Changes") {
+    return mergeFileLines(prev, fresh);
+  }
+
+  const isClean = (l: string) => l.startsWith("- ") && !l.includes("<skill") && !l.includes("</skill");
+  const prevLines = prev.split("\n").filter(isClean);
+  const freshLines = fresh.split("\n").filter(isClean);
+  const combined = [...new Set([...prevLines, ...freshLines])];
+  const CAP = header === "Session Goal" ? 8 : header === "Commits" ? 8 : 15;
+  const capped = combined.length > CAP ? combined.slice(-CAP) : combined;
+  if (capped.length === 0) return "";
+  return `[${header}]\n${capped.join("\n")}`;
+};
+
+const mergeFileLines = (prev: string, fresh: string): string => {
+  const categories = ["Modified", "Created", "Read"] as const;
+  const merged: Record<string, Set<string>> = {};
+  for (const cat of categories) merged[cat] = new Set();
+
+  for (const text of [prev, fresh]) {
+    for (const line of text.split("\n")) {
+      for (const cat of categories) {
+        const prefix = `- ${cat}: `;
+        if (!line.startsWith(prefix)) continue;
+        let rest = line.slice(prefix.length).replace(/\s*\(\+\d+ more\)\s*$/, "");
+        for (const p of rest.split(",")) {
+          const trimmed = p.trim();
+          if (trimmed) merged[cat].add(trimmed);
+        }
+      }
+    }
+  }
+
+  for (const p of merged.Modified) merged.Created.delete(p);
+
+  const cap = (set: Set<string>, limit: number) => {
+    const arr = [...set];
+    if (arr.length <= limit) return arr.join(", ");
+    return arr.slice(0, limit).join(", ") + ` (+${arr.length - limit} more)`;
+  };
+
+  const lines: string[] = [];
+  if (merged.Modified.size > 0) lines.push(`- Modified: ${cap(merged.Modified, 10)}`);
+  if (merged.Created.size > 0) lines.push(`- Created: ${cap(merged.Created, 10)}`);
+  if (merged.Read.size > 0) lines.push(`- Read: ${cap(merged.Read, 10)}`);
+  if (lines.length === 0) return "";
+  return `[Files And Changes]\n${lines.join("\n")}`;
+};
+
+const mergeBriefTranscript = (prev: string, fresh: string): string => {
+  if (!prev) return fresh;
+  if (!fresh) return prev;
+  return prev + "\n\n" + fresh;
+};
+
+export const mergePrevious = (prev: string, fresh: string): string => {
+  const headers = HEADER_NAMES
+    .map((header) => {
+      const freshSec = sectionOf(fresh, header);
+      const prevSec = sectionOf(prev, header);
+      return mergeHeaderSection(header, prevSec, freshSec);
+    })
+    .filter(Boolean);
+
+  const prevBrief = briefOf(prev);
+  const freshBrief = briefOf(fresh);
+  const mergedBrief = mergeBriefTranscript(prevBrief, freshBrief);
+
+  const parts: string[] = [];
+  if (headers.length > 0) {
+    parts.push(headers.join("\n\n"));
+  }
+  if (mergedBrief) {
+    parts.push(capBrief(mergedBrief));
+  }
+
+  return parts.join(SEPARATOR);
+};